diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml
index 5741d63..b302001 100644
--- a/.github/workflows/claude-review.yml
+++ b/.github/workflows/claude-review.yml
@@ -1,32 +1,32 @@
-name: Claude Code Review
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  contents: read
-  pull-requests: write
-  issues: write
-
-jobs:
-  claude-review:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Claude Code Review
-        uses: anthropics/claude-code-action@v1
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          review_comment_prefix: "evm-cortex-review"
-          direct_prompt: |
-            Review this PR for:
-            1. Solidity code quality and security patterns
-            2. Smart contract vulnerabilities (reentrancy, access control, oracle manipulation)
-            3. Gas optimization opportunities
-            4. Test coverage gaps (Foundry tests)
-            5. Breaking changes to existing contracts
-
-            Use evm-cortex's code-reviewer agent standards.
-            Provide VERDICT: PASS | WARN | FAIL
+name: Claude Code Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  claude-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Claude Code Review
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Review this PR for:
+            1. Solidity code quality and security patterns
+            2. Smart contract vulnerabilities (reentrancy, access control, oracle manipulation)
+            3. Gas optimization opportunities
+            4. Test coverage gaps (Foundry tests)
+            5. Breaking changes to existing contracts
+
+            Use evm-cortex's code-reviewer agent standards.
+            Provide VERDICT: PASS | WARN | FAIL
diff --git a/CLAUDE.md b/CLAUDE.md
index 405c87d..73b40ca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -113,7 +113,7 @@ Full analysis with PoC verification for Medium+ findings. Mix of opus and sonnet
 Complete audit with invariant fuzzing, formal properties, multi-iteration depth analysis, and skeptic review for High/Critical findings.
 
 ### Pashov 12-Agent Pipeline
-For comprehensive security review, use the `pashov-audit-pipeline` skill which runs 12 specialized attacker agents in parallel. Nine work a single lens — math precision, access control, economic security, execution trace, invariant, periphery, first principles, asymmetry, boundary — and three are gap-hunters (numerical, trust, flow) that report only bugs living at the seam between lenses. Findings are deduplicated, run through four judging gates, confidence-scored, and severity-classified with PoCs for Critical/High.
+For comprehensive security review, use the `pashov-audit-pipeline` skill which runs 12 specialized attacker agents in parallel. Nine work a single lens — math precision, access control, economic security, execution trace, invariant, periphery, first principles, asymmetry, boundary — and three are gap-hunters (numerical, trust, flow) that report only bugs living at the seam between lenses. Findings are deduplicated, run through four judging gates, confidence-scored, and assembled by shell into one report, with an EVM Cortex severity annex and PoCs for Critical/High. Supports loop mode (`--loop N` passes per scan, each told what earlier passes found) and a findings ledger across scans (`--memory`).
 
 ### 0xSimao Accounting-First Pipeline
 For accounting-heavy protocols (vaults, lending, staking, yield, AMMs, bridges), use the `simao-audit-pipeline` skill. It reverse-engineers 0xSimao's 869 published findings: the orchestrator first writes a **money map** — assets, tracked totals, an asymmetry table, invariants, lifecycles, and actor cohorts — then hands it to 12 parallel single-specialty lenses (accounting-desync, share-exchange-rate, temporal-cohort, liquidation-solvency, cross-chain-state, rounding-precision, ordering-mev, dos-griefing, access-trust, integration-assumptions, edge-states, flow-completeness). His signature class: a tracked total that desyncs from reality, letting early actors over-withdraw and leaving the last user out insolvent. Findings are deduplicated through four hard gates, judged, and severity-classified with Foundry PoCs for High findings. Complements `pashov-audit-pipeline` — run both and treat overlap as signal.
diff --git a/UPGRADING.md b/UPGRADING.md
index 0221604..a9df67d 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -63,7 +63,9 @@ These are user data:
 
 ## Version History
 
-### Unreleased
+### v1.1.0 (2026-09-29)
+
+Minor release. Installers gain a real upgrade mode, the Pashov audit pipeline moves to solidity-auditor v4 with loop mode and scan memory, `simao-audit-pipeline` and the `fizz` family are new, the Uniswap skills are corrected against current Uniswap code, and the EVM facts are refreshed. `package.json`, `plugin.json`, and `evm-cortex version` now agree on the version; the latter two had stayed at 1.0.0 through 1.0.1 and 1.0.2. Skills total 95, agents 50.
 
 **Installers now support upgrading.** Previously the default mode skipped every existing file and reported the result as "Skipped: N (already existed)", which made an upgrade a silent no-op — the documented `git pull && ./install.sh` flow updated nothing. Default mode now distinguishes *already current* from *out of date*, lists the stale files, and points at `--update`. `install-cursor.sh` gained overwrite support, which it previously lacked entirely.
 
@@ -73,6 +75,12 @@ These three skills now ship `references/`, `scripts/`, and `templates/` subdirec
 
 **Added `simao-audit-pipeline`.** An accounting-first audit skill vendored from [0xSimao AI](https://github.com/0xsimao/0xsimao-ai) (VERSION 1.0.0), reverse-engineered from 0xSimao's 869 published findings. The orchestrator builds a money map (assets, tracked totals, asymmetry table, invariants, lifecycles, cohorts), then runs 12 parallel single-specialty lenses over it, deduplicates through four hard gates, and emits severity-classified findings with Foundry PoCs for Highs. It ships a `references/` subdirectory (method, severity calibration, report formatting, 12 attack lenses + shared rules) carried over from upstream intact except for the repo's `onchain` spelling normalization; the EVM Cortex adaptations (agent mapping, Foundry pre-flight, PoC routing) live in `SKILL.md` only. Skills total 95.
 
+**`pashov-audit-pipeline` synced to solidity-auditor v4.** Upstream (2026-09-23) added loop mode (`--loop N` passes per scan, each pass told what earlier passes found, one combined report), a findings ledger across scans (`--memory`, on automatically when passes > 1, stored at `.solidity-auditor/memory.tsv` in the audited repo), and a shell-assembled report: each pass writes its gated findings to a run file and `references/assemble.sh` is the only thing that produces `full-report.md`, so the report can never overstate its coverage. Findings are worded in Simplified Technical English (`report-language.md`, appended to every agent bundle), the confidence threshold moved from 80 to 75, deploy scripts are now in scope, agents are READ-ONLY in the audited repo, and the upgrade warning fires only when the local `VERSION` is lower. Upstream's `SKILL.md` is vendored verbatim as `references/orchestration.md` so future syncs stay a file-by-file diff; the EVM Cortex layer (agent mapping, context package, Foundry pre-flight, a `**Severity**` line in each finding block, and a Turn 6 severity/PoC annex built by shell from the assembled report) lives in `SKILL.md`. PoCs are written under `.solidity-auditor/runs/{stamp}/poc/` and run with `FOUNDRY_TEST` overridden, never into the project's `test/`. Audited repos should gitignore `.solidity-auditor/`.
+
+**EVM current-state facts refreshed from ethskills.com (2026-09-25).** `rules/evm-current-state.md` now records Fusaka as shipped (Dec 3, 2025), Glamsterdam as in progress for Q3-Q4 2026 with FOCIL dropped, and Hegota (Q4 2026) without Verkle; adds Unichain (chain ID 130, time-priority ordering) and Robinhood Chain (chain ID 4663, Orbit L2 whose transaction filtering can censor force-included transactions); notes the Aerodrome/Velodrome merger into Aero, Base's announced Superchain exit, and Hardhat 3 as a legitimate toolchain alongside this squad's Foundry default; and pins the ERC-8004 registry and ERC-4337 EntryPoint v0.7 addresses after `cast code` verification. `agents/eip-expert.md` had Fusaka as "targeting late 2026" and Glamsterdam as "2027+"; both corrected, with a CFI/SFI/DFI (EIP-7723) guide for checking fork scope on forkcast. `agents/l2-specialist.md` gained Unichain, Robinhood Chain, chain IDs, and the dominant-DEX-per-chain note. `skills/erc8004-patterns` replaces its `0x...` placeholder with the verified registry addresses.
+
+**Uniswap skills and agents corrected against current Uniswap code and docs (2026-09-25).** The seven `uniswap-*`/`lp-analyst`/`pool-finder` skills and six matching agents were homegrown in April and had drifted. Compile-breaking fixes: `SwapParams`/`ModifyLiquidityParams` now import from `v4-core/src/types/PoolOperation.sol` instead of `IPoolManager.*`; `BaseHook` and `HookMiner` were removed from `v4-periphery` on 2026-02-06 (PR #510), so hook examples import `@openzeppelin/uniswap-hooks/src/base/BaseHook.sol` (what `Uniswap/v4-template` pins) or `Uniswap/v4-hooks-public`, and override `_beforeSwap`/`_afterSwap` internally; `uniswap-v4-testing` had the V4 swap sign convention inverted everywhere (negative `amountSpecified` is exact input), redeclared `PoolKey key` over the `Deployers` field, used a pre-V4 fork block, and carried a bad EIP-55 checksum. Fact fixes: V3 TickLens address was non-hex and wrong; V4 positions are ERC-721, not ERC-6909; protocol-fee mechanics rewritten (set by the `protocolFeeController`, charged on swap input before the LP fee, lower 12 bits zeroForOne); `sync()` is callable outside `unlock()`; `notifyBurn` has five arguments; `Actions` has 26 codes; V4 is on 19 mainnets with Blast dropped and X Layer, Robinhood Chain, and Arc added; docs moved to developers.uniswap.org. New facts: the protocol fee switch is live on V3 mainnet since UNIfication executed 2025-12-28 (`feeProtocol` 68 or 102) and on V4 static-fee pools since 2026-07-27, so fee-revenue formulas now carry `(1 - protocol_share)`; Unichain (chain ID 130) V3 and V4 addresses and Ethereum StateView/V4Quoter/ReservesLens/Permit2 added, every address `cast code`-verified and EIP-55 checksummed; `pool-finder` calls StateView instead of a non-existent `getSlot0` ABI on the PoolManager and its PoolId `cast` example now reproduces the live ETH/USDC pool id. Numeric corrections in `uniswap-math` and `lp-analyst` (sqrtPriceX96 worked examples, tick for 3e-9, `maxLiquidityPerTick` magnitudes, capital-efficiency multipliers) were recomputed with arbitrary-precision arithmetic.
+
 ### v1.0.0 (2026-04-10)
 
 **Initial release as EVM Cortex** — Ethereum protocol engineering squad.
diff --git a/agents/amm-expert.md b/agents/amm-expert.md
index 60ccc50..6d8dc27 100644
--- a/agents/amm-expert.md
+++ b/agents/amm-expert.md
@@ -46,17 +46,22 @@ L = Δy / (√(P_upper) - √(P_lower))                              // liquidit
 
 ```solidity
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.24;
+pragma solidity 0.8.26;
 
-import {BaseHook} from "v4-periphery/src/utils/BaseHook.sol";
+// BaseHook no longer ships in v4-periphery (removed 2026-02-06, PR #510). Pick one maintained base:
+import {BaseHook} from "@openzeppelin/uniswap-hooks/src/base/BaseHook.sol";   // pinned by Uniswap/v4-template
+// or: import {BaseHook} from "v4-hooks-public/src/base/BaseHook.sol";       // Uniswap Labs
 import {Hooks} from "v4-core/src/libraries/Hooks.sol";
 import {IPoolManager} from "v4-core/src/interfaces/IPoolManager.sol";
 import {PoolKey} from "v4-core/src/types/PoolKey.sol";
 import {PoolId, PoolIdLibrary} from "v4-core/src/types/PoolId.sol";
 import {BalanceDelta} from "v4-core/src/types/BalanceDelta.sol";
 import {BeforeSwapDelta, BeforeSwapDeltaLibrary} from "v4-core/src/types/BeforeSwapDelta.sol";
+import {SwapParams} from "v4-core/src/types/PoolOperation.sol";
 import {Currency} from "v4-core/src/types/Currency.sol";
 
+// BaseHook's external callbacks are non-virtual and already `onlyPoolManager`;
+// override the internal `_before*`/`_after*` functions and return the external selector.
 contract MyHook is BaseHook {
     using PoolIdLibrary for PoolKey;
 
@@ -83,35 +88,31 @@ contract MyHook is BaseHook {
         });
     }
 
-    function afterInitialize(
-        address sender,
-        PoolKey calldata key,
-        uint160 sqrtPriceX96,
-        int24 tick
-    ) external override onlyPoolManager returns (bytes4) {
+    function _afterInitialize(address, PoolKey calldata key, uint160, int24)
+        internal
+        override
+        returns (bytes4)
+    {
         swapCount[key.toId()] = 0;
-        return this.afterInitialize.selector;
+        return BaseHook.afterInitialize.selector;
     }
 
-    function beforeSwap(
-        address sender,
-        PoolKey calldata key,
-        IPoolManager.SwapParams calldata params,
-        bytes calldata hookData
-    ) external override onlyPoolManager returns (bytes4, BeforeSwapDelta, uint24) {
+    function _beforeSwap(address, PoolKey calldata, SwapParams calldata, bytes calldata)
+        internal
+        override
+        returns (bytes4, BeforeSwapDelta, uint24)
+    {
         // Custom pre-swap logic (e.g., dynamic fees, access control)
-        return (this.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, 0);
+        return (BaseHook.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, 0);
     }
 
-    function afterSwap(
-        address sender,
-        PoolKey calldata key,
-        IPoolManager.SwapParams calldata params,
-        BalanceDelta delta,
-        bytes calldata hookData
-    ) external override onlyPoolManager returns (bytes4, int128) {
+    function _afterSwap(address, PoolKey calldata key, SwapParams calldata, BalanceDelta, bytes calldata)
+        internal
+        override
+        returns (bytes4, int128)
+    {
         swapCount[key.toId()]++;
-        return (this.afterSwap.selector, 0);
+        return (BaseHook.afterSwap.selector, 0);
     }
 }
 ```
@@ -120,9 +121,13 @@ contract MyHook is BaseHook {
 
 ### Dynamic Fee Hook
 ```solidity
-function beforeSwap(...) external override returns (bytes4, BeforeSwapDelta, uint24) {
+function _beforeSwap(address, PoolKey calldata key, SwapParams calldata, bytes calldata)
+    internal
+    override
+    returns (bytes4, BeforeSwapDelta, uint24)
+{
     uint24 fee = _calculateDynamicFee(key);
-    return (this.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, fee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
+    return (BaseHook.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, fee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
 }
 
 function _calculateDynamicFee(PoolKey calldata key) internal view returns (uint24) {
@@ -157,12 +162,16 @@ function _executeTWAMMOrders(PoolKey calldata key) internal {
 ```solidity
 mapping(PoolId => mapping(int24 => mapping(bool => uint256))) public limitOrders;
 
-function afterSwap(...) external override returns (bytes4, int128) {
+function _afterSwap(address, PoolKey calldata key, SwapParams calldata params, BalanceDelta, bytes calldata)
+    internal
+    override
+    returns (bytes4, int128)
+{
     int24 currentTick = _getCurrentTick(key);
     // Check if price crossed any limit order ticks
     // Fill orders that are now in-the-money
     _fillCrossedOrders(key, currentTick, params.zeroForOne);
-    return (this.afterSwap.selector, 0);
+    return (BaseHook.afterSwap.selector, 0);
 }
 ```
 
@@ -174,8 +183,8 @@ function afterSwap(...) external override returns (bytes4, int128) {
 2. **Choose minimal permissions** — only enable the hooks you need. Each enabled hook adds gas cost to every matching operation.
 3. **Preserve pool invariants** — hooks must not break the AMM's core accounting. If your hook modifies deltas, prove conservation of value.
 4. **Consider MEV implications** — beforeSwap hooks that read onchain state can be front-run. Use commit-reveal or batch auctions for price-sensitive logic.
-5. **Test with the V4 test framework** — use `PoolManager` deployers and routers from v4-periphery for realistic testing.
-6. **Gas budget** — hooks execute on every swap. Keep gas under 50K for beforeSwap/afterSwap. Profile with `forge test --gas-report`.
+5. **Test with the V4 test framework** — use `Deployers` (`v4-core/test/utils/Deployers.sol`) and the test routers (`PoolSwapTest`, `PoolModifyLiquidityTest` from `v4-core/src/test/`) for realistic testing.
+6. **Gas budget** — hooks execute on every swap. There is no universal gas threshold; measure `beforeSwap`/`afterSwap` overhead on realistic and adversarial state with `forge test --gas-report` and track regressions with `forge snapshot --check`.
 
 ### Impermanent Loss Calculation:
 
diff --git a/agents/eip-expert.md b/agents/eip-expert.md
index 8a570c4..7e76666 100644
--- a/agents/eip-expert.md
+++ b/agents/eip-expert.md
@@ -42,18 +42,26 @@ ERCs (Ethereum Request for Comments) are a category of EIPs scoped to applicatio
 | 7918 | Blob base fee bounded | Blob base fee can't drop below execution gas cost equivalent. |
 | 7934 | RLP block size limit | Limits serialized block size. |
 
-### Fusaka (targeting late 2026)
+### Fusaka (live, December 3, 2025)
 | EIP | Title | Impact |
 |-----|-------|--------|
 | 7594 | PeerDAS | Peer Data Availability Sampling. Major L2 scaling improvement. |
 | 7892 | Blob-only hardforks | Enables blob parameter changes without full hard fork. |
 
-### Glamsterdam (targeting 2027+)
+### Glamsterdam (in progress, targeting Q3-Q4 2026 — dates slip)
 | EIP | Title | Impact |
 |-----|-------|--------|
 | 7732 | Enshrined PBS (ePBS) | Proposer-Builder Separation in protocol. Removes MEV-Boost relay dependency. |
 | 7928 | Block Access Lists | Contracts declare state access upfront. Enables parallel EVM execution. |
 
+FOCIL (fork-choice inclusion lists) was removed from Glamsterdam scope to reduce complexity. Check [forkcast.org](https://forkcast.org) for the current SFI list before quoting scope.
+
+### Hegota (targeting Q4 2026)
+Does **not** contain Verkle trees. Verkle was the statelessness candidate for years, then deprioritized in 2024-2025 over quantum-resistance and ZK-compatibility concerns. Ethereum may move to a binary state tree instead (EIP-7864, Draft as of March 2026). Check https://forkcast.org/upgrade/hegota for confirmed scope.
+
+### Checking whether a feature is actually scheduled
+Roadmap diagrams and blog posts older than six months are aspirational. The status that matters is the fork relationship on [forkcast.org](https://forkcast.org), defined in EIP-7723: **CFI** (Considered for Inclusion — being evaluated, implementation starting), **SFI** (Scheduled for Inclusion — in devnets, ships barring disasters), **DFI** (Declined for Inclusion — rejected for that fork). Only SFI means "coming in fork X". For what client teams are saying, read the public [eth-rnd-archive](https://github.com/ethereum/eth-rnd-archive); for the canonical spec, prefer [execution-specs](https://github.com/ethereum/execution-specs) and [consensus-specs](https://github.com/ethereum/consensus-specs) over EIP text, which may have been modified during implementation.
+
 ## EVM Opcodes (Developer-Critical Finals)
 
 | EIP | Opcode/Feature | Solidity Impact |
diff --git a/agents/l2-specialist.md b/agents/l2-specialist.md
index 954f0b3..2944ac1 100644
--- a/agents/l2-specialist.md
+++ b/agents/l2-specialist.md
@@ -12,20 +12,23 @@ You are the Layer 2 deployment and cross-chain specialist. You understand the op
 ## L2 Landscape (2025-2026)
 
 **OP Stack (Optimistic Rollups):**
-- **Base** — cheapest major L2, largest consumer app ecosystem, Coinbase-operated sequencer
-- **Optimism** — governance-heavy, RetroPGF ecosystem, OP token
-- **Superchain** — the shared sequencer and interop vision unifying OP Stack chains
-
-**Arbitrum:**
-- **Arbitrum One** — deepest DeFi liquidity of any L2, Stylus (Rust/C++ contracts) live
+- **Base** (chain ID 8453) — cheapest major L2, largest consumer app ecosystem, Coinbase-operated sequencer. Announced February 2026 that it is leaving the Superchain; finalizes in a future hardfork.
+- **Optimism** (10) — governance-heavy, RetroPGF ecosystem, OP token
+- **Unichain** (130) — Uniswap's L2, mainnet February 11, 2025. TEE-based block building (Flashbots Rollup-Boost): transactions are ordered by time received, not gas price, with a private encrypted mempool. Priority-fee bidding is pointless there. 1s blocks, Flashblocks sub-blocks on the roadmap.
+- **Celo** (42220) — migrated from independent L1 to OP Stack L2 on March 26, 2025. Mobile payments focus (MiniPay). Mento stablecoins rebranded December 2025: USDm (was cUSD), EURm (was cEUR), BRLm (was cREAL), same contract addresses.
+- **Superchain** — the shared upgrade-governance and interop vision unifying OP Stack chains (OP Mainnet, Unichain, Ink, Celo, Zora, World Chain, ...); members contribute 15% of sequencer revenue
+
+**Arbitrum (Nitro / Orbit):**
+- **Arbitrum One** (42161) — deepest DeFi liquidity of any L2, Stylus (Rust/C++ contracts) live
 - **Arbitrum Nova** — AnyTrust chain for gaming/social (cheaper, weaker DA guarantees)
+- **Robinhood Chain** (4663) — Orbit rollup settling **directly to Ethereum** with blob DA (an L2, not an L3; not AnyTrust). Mainnet July 1, 2026, ~100ms blocks, ETH gas. Purpose: 24/7 tokenized stocks and ETFs as plain 18-decimal ERC-20s (legally debt securities, not available to US persons). Splits and dividends adjust a `uiMultiplier()` display scalar (ERC-8056 Draft) — raw balances never rebase. **Censorship caveat:** ArbOS 61 transaction filtering lets an authorized filterer reject any tx hash, including transactions force-included via L1, so force inclusion is not an escape hatch here; L2Beat rates it Stage 0. USDG (Paxos) stablecoin has 6 decimals. Same `block.number` semantics as Arbitrum One (returns the L1 block).
 
 **zkEVMs:**
-- **Polygon zkEVM** — being wound down, migrating to AggLayer
-- **zkSync Era** — custom VM (zkEVM), different address derivation (CREATE2 differs)
-- **Linea, Scroll** — closer to EVM equivalence but with proving overhead
+- **Polygon zkEVM** — being shut down (announced June 2025). Do not start projects there; Polygon is refocusing on PoS + AggLayer
+- **zkSync Era** (324) — custom VM (zkEVM), needs `zksolc`, no `EXTCODECOPY`, native account abstraction; different address derivation (CREATE2 differs)
+- **Linea** (59144), **Scroll** (534352) — bytecode-compatible, standard `solc`, proving overhead on finality
 
-**Celo** — migrated from independent L1 to OP Stack L2 in 2025.
+**Dominant DEX per chain is NOT Uniswap by default:** Aero on Base and Optimism (Aerodrome and Velodrome merged in November 2025 under Dromos Labs), Camelot and GMX on Arbitrum, SyncSwap on zkSync. Check liquidity before routing.
 
 ## OP Stack Specifics
 
diff --git a/agents/lp-analyst.md b/agents/lp-analyst.md
index 6ddb3c9..1271296 100644
--- a/agents/lp-analyst.md
+++ b/agents/lp-analyst.md
@@ -40,20 +40,22 @@ efficiency = 1 / (1 - √(P_a / P_b))
 
 ±0.1% range → ~1000× V2 efficiency
 ±1% range   → ~100× V2 efficiency
-±10% range  → ~5× V2 efficiency
+±10% range  → ~10.5× V2 efficiency
+±25% range  → ~4.4× V2 efficiency
 Full range  → 1× V2 efficiency
 ```
 
 ### Fee APR
 ```
-fee_APR = (daily_volume × fee_tier × position_share) / position_value × 365
+fee_APR = (daily_volume × fee_tier × (1 - protocol_share) × position_share) / position_value × 365
 position_share = position_liquidity / total_active_liquidity
 breakeven_APR = |IL| × 365 / holding_period_days
 ```
+`protocol_share` is nonzero on Ethereum mainnet. V3: since UNIfication executed 2025-12-28, `slot0().feeProtocol` reads `68` on the 0.01%/0.05% tiers (protocol takes 1/4 of LP fees) and `102` on the 0.30% tier (1/6); decode `token0 = feeProtocol % 16`, `token1 = feeProtocol >> 4`, share `= 1/N`. V4: static-fee pools charge a protocol fee since 2026-07-27 (mainnet ETH/USDC 500/10: `protocolFee = 512125` → 125 pips per direction), taken from swap input ahead of the LP fee, so `protocol_share ≈ protocolFee / 1e6`.
 
-### IL Sensitivity (for small price changes)
+### Expected IL from Volatility (small-move approximation)
 ```
-dIL/dP ≈ -σ²t/8   (continuous approximation)
+E[IL] ≈ -σ²t/8   (expected V2 IL under geometric Brownian motion; second-order expansion, not a derivative)
 For 50% ETH volatility over 1 year: IL ≈ -0.5² × 1/8 = -3.125%
 ```
 
@@ -90,7 +92,7 @@ cast call <pool_address> "slot0()" --rpc-url $ETH_RPC
 |-----------|------------------|------------|----------------|
 | Stable/Stable (USDC/USDT) | ±0.1% ($0.999–$1.001) | ~1000× | Rare |
 | Correlated (ETH/stETH) | ±1% | ~100× | Weekly |
-| Major pair (ETH/USDC) | ±15–25% | ~3–5× | Daily–Weekly |
+| Major pair (ETH/USDC) | ±15–25% | ~4.4–7.1× | Daily–Weekly |
 | Volatile pair | ±50%+ or full range | ~1.5–2× | Infrequent |
 
 ## Rebalancing Strategies
@@ -127,7 +129,8 @@ rebalance IFF rebalance_benefit > rebalance_cost × safety_margin
 
 ### V4 Auto-Compound Hook
 ```solidity
-function afterSwap(...) external override returns (bytes4, int128) {
+// BaseHook (OpenZeppelin uniswap-hooks / Uniswap v4-hooks-public) keeps afterSwap non-virtual; override _afterSwap
+function _afterSwap(...) internal override returns (bytes4, int128) {
     // Collect accrued fees and re-deposit into the same position
     // Only compound if fees exceed gas threshold
 }
diff --git a/agents/pool-finder.md b/agents/pool-finder.md
index 277e92e..2d1e0cc 100644
--- a/agents/pool-finder.md
+++ b/agents/pool-finder.md
@@ -23,10 +23,12 @@ You are a specialist in discovering and analyzing Uniswap pools across V3 and V4
 
 ### Factories & Routers
 ```
-V3 Factory (Ethereum):       0x1F98431c8aD98523631AE4a59f267346ea31F984
-V4 PoolManager (Ethereum):   0x000000000004444c5dc75cb358380d2e3de08a90
-QuoterV2 (Ethereum):         0x61fFE014bA17989E743c5F6cB21bF9697530B21e
-UniversalRouter (Ethereum):  0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+V3 Factory (Ethereum):              0x1F98431c8aD98523631AE4a59f267346ea31F984
+V4 PoolManager (Ethereum):          0x000000000004444c5dc75cB358380D2e3dE08A90
+V4 StateView (Ethereum):            0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227
+QuoterV2 (Ethereum):                0x61fFE014bA17989E743c5F6cB21bF9697530B21e
+UniversalRouter V2 (Ethereum):      0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+UniversalRouter V2.1.2 (Ethereum):  0x23617e59A5925b2A4Bf75d73ff6711cD0b29De85
 ```
 
 ### Common Tokens (Ethereum)
@@ -83,11 +85,16 @@ cast call <pool> "ticks(int24)(uint128,int128,uint256,uint256,int56,uint160,uint
 
 ### V4 — Read Pool State
 ```bash
-# Pool state via StateLibrary's extsload pattern
-cast call 0x000000000004444c5dc75cb358380d2e3de08a90 \
+# Read through the StateView lens. StateLibrary is a Solidity library of *internal* extsload
+# helpers, not an onchain ABI — calling getSlot0/getLiquidity on the PoolManager itself reverts.
+# Ethereum address below; per-chain StateView addresses:
+# https://developers.uniswap.org/docs/protocols/v4/deployments
+STATE_VIEW=0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227
+
+cast call $STATE_VIEW \
   "getSlot0(bytes32)(uint160,int24,uint24,uint24)" <pool_id> --rpc-url $ETH_RPC
 
-cast call 0x000000000004444c5dc75cb358380d2e3de08a90 \
+cast call $STATE_VIEW \
   "getLiquidity(bytes32)(uint128)" <pool_id> --rpc-url $ETH_RPC
 ```
 
diff --git a/agents/uniswap-math-expert.md b/agents/uniswap-math-expert.md
index a4387ec..55b2c7a 100644
--- a/agents/uniswap-math-expert.md
+++ b/agents/uniswap-math-expert.md
@@ -128,20 +128,20 @@ fees0 = (feeGrowthInside0X128 - position.feeGrowthInside0LastX128) × position.l
 
 ### Worked Example: WETH/USDC Price Conversion
 ```
-WETH = 18 decimals (token0, lower address on mainnet pools)
-USDC = 6 decimals (token1)
-Price of 1 ETH = 3000 USDC
+USDC = 6 decimals  (token0 — 0xA0b8... sorts below 0xC02a..., so USDC is token0 on every mainnet WETH/USDC pool)
+WETH = 18 decimals (token1)
+Price of 1 ETH = 3000 USDC  →  1 USDC = 1/3000 ETH
 
-In pool terms (token1/token0):
-price_raw = 3000 × 10^6 / 10^18 = 3000 × 10^(-12) = 3e-9
+In pool terms (token1/token0, raw units):
+price_raw = (1/3000) × 10^18 / 10^6 = 10^12 / 3000 ≈ 3.3333e8
 
-sqrtPrice = √(3e-9) ≈ 5.477e-5
-sqrtPriceX96 = 5.477e-5 × 2^96 ≈ 4_339_505_179_874_779_xxx
+sqrtPrice = √(3.3333e8) ≈ 18257.4186
+sqrtPriceX96 = 18257.4186 × 2^96 ≈ 1_446_501_726_624_926_496_477_173_928_747_177  (≈ 1.4465e33)
 
-tick = log(3e-9) / log(1.0001) ≈ -196237
+tick = floor(log(3.3333e8) / log(1.0001)) = floor(196256.35) = 196256
 ```
 
-**Note:** Token ordering matters! On Ethereum mainnet, WETH (0xC02a...) > USDC (0xA0b8...) numerically, so USDC is token0 and WETH is token1 in the WETH/USDC pool. This inverts the price representation.
+**Note:** Token ordering matters! Had WETH been token0 (as many tutorials assume), price_raw would be 3000 × 10^6 / 10^18 = 3e-9, sqrtPriceX96 ≈ 4_339_505_179_874_779_489_431_521 and tick = floor(-196256.35) = -196257 — the mirror image of the real mainnet pool. Always read `token0()` / `currency0` before interpreting `sqrtPriceX96`.
 
 ## Output Format
 
diff --git a/agents/uniswap-v3-expert.md b/agents/uniswap-v3-expert.md
index 784e68f..753d686 100644
--- a/agents/uniswap-v3-expert.md
+++ b/agents/uniswap-v3-expert.md
@@ -27,13 +27,14 @@ You are the definitive authority on Uniswap V3 protocol architecture, concentrat
 ```
 UniswapV3Factory:                0x1F98431c8aD98523631AE4a59f267346ea31F984
 NonfungiblePositionManager:      0xC36442b4a4522E871399CD717aBDD847Ab11FE88
-SwapRouter (v1):                 0xE592427A0AEce92De3Edee1F18E0157C05861564
+SwapRouter (v1, legacy):         0xE592427A0AEce92De3Edee1F18E0157C05861564
 SwapRouter02:                    0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45
 QuoterV2:                        0x61fFE014bA17989E743c5F6cB21bF9697530B21e
-UniversalRouter:                 0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+UniversalRouter V2:              0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+UniversalRouter V2.1.2:          0x23617e59A5925b2A4Bf75d73ff6711cD0b29De85
 ```
 
-**CRITICAL**: Addresses vary by chain. Base, BNB, Avalanche, and Celo use different addresses. Always verify with `cast code`.
+**CRITICAL**: Addresses vary by chain. Base, BNB, Avalanche, Celo and Unichain use different addresses (Unichain: Factory `0x1F98400000000000000000000000000000000003`, NPM `0x943e6e07a7E8E791dAFC44083e54041D743C46E9`). The legacy SwapRouter v1 exists only on Ethereum, Arbitrum One, Optimism and Polygon — use SwapRouter02 or UniversalRouter elsewhere. Always verify with `cast code`.
 
 ### Key V3 Pools (Ethereum)
 ```
@@ -55,6 +56,8 @@ DAI/USDC 0.01%:   0x5777d92f208679DB4b9778590Fa3CAB3aC9e2168
 | 30        | 0.30%   | 60          | Standard pairs (ETH/USDC, ETH/DAI) |
 | 100       | 1.00%   | 200         | Exotic/volatile pairs |
 
+**Protocol fee is on.** Since UNIfication executed on 2025-12-28, Ethereum mainnet V3 pools carry a protocol fee: `slot0().feeProtocol` reads `68` on the 0.01%/0.05% tiers (protocol takes 1/4 of LP fees, LPs keep 75%) and `102` on the 0.30% tier (1/6, LPs keep 83.3%). Decode as `token0 = feeProtocol % 16`, `token1 = feeProtocol >> 4`, share `= 1/N`, and multiply any volume-based fee-APR estimate by `(1 - protocol_share)`.
+
 ### Price-Tick Relationship
 ```
 price = 1.0001^tick
@@ -70,7 +73,8 @@ L = amount1 / (√P_upper - √P_lower)
 
 ## Core Integration Patterns
 
-### Swap via SwapRouter
+### Swap via SwapRouter (legacy v1)
+Prefer `SwapRouter02` (`IV3SwapRouter` — no `deadline` in the params struct; use `multicall(deadline, data)`) or `UniversalRouter`. SwapRouter v1 is absent on Base, Unichain, BNB, Avalanche and Celo.
 ```solidity
 ISwapRouter.ExactInputSingleParams memory params = ISwapRouter.ExactInputSingleParams({
     tokenIn: WETH,
@@ -132,7 +136,7 @@ secondsAgos[0] = 1800; // 30 minutes ago
 secondsAgos[1] = 0;    // now
 (int56[] memory tickCumulatives,) = pool.observe(secondsAgos);
 int24 twapTick = int24((tickCumulatives[1] - tickCumulatives[0]) / int56(int32(1800)));
-uint160 twapSqrtPriceX96 = TickMath.getSqrtPriceAtTick(twapTick);
+uint160 twapSqrtPriceX96 = TickMath.getSqrtRatioAtTick(twapTick); // V3 name; getSqrtPriceAtTick is V4
 ```
 
 ### Callback Verification
diff --git a/agents/uniswap-v4-expert.md b/agents/uniswap-v4-expert.md
index 265f4e2..0a4ff5f 100644
--- a/agents/uniswap-v4-expert.md
+++ b/agents/uniswap-v4-expert.md
@@ -14,24 +14,36 @@ You are the definitive authority on Uniswap V4 protocol architecture, integratio
 - **PoolManager singleton** — all pool state in one contract, pool identification via PoolKey/PoolId
 - **Flash accounting** — EIP-1153 transient storage, delta tracking, settle/take pattern, unlock/unlockCallback flow
 - **Hook system** — all 14 permission flags, 10 callback functions, return-delta mechanics, address mining via CREATE2
-- **PositionManager** — ERC-721 position NFTs, modifyLiquidities entry point, 24 action codes, subscriber notifications
+- **PositionManager** — ERC-721 position NFTs, modifyLiquidities entry point, 26 action codes (incl. 2 deprecated `*_FROM_DELTAS`), subscriber notifications
 - **Currency type** — address(0) for native ETH, no WETH wrapping required
 - **Fee system** — static fees (hundredths of bps), dynamic fees via LPFeeLibrary, OVERRIDE_FEE_FLAG, protocol fees
 - **Custom accounting** — hooks that modify swap/liquidity deltas, custom curves, hook-collected fees
-- **Production deployments** — addresses across 17+ chains, chain-specific verification
+- **Production deployments** — addresses across 19 mainnets, chain-specific verification
 - **UniversalRouter** — V4 swap routing, multi-protocol batching (V3+V4), permit2 integration
 
 ## Production Deployment Addresses
 
 ```
-Ethereum PoolManager:     0x000000000004444c5dc75cb358380d2e3de08a90
-Ethereum UniversalRouter: 0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+Ethereum PoolManager:            0x000000000004444c5dc75cB358380D2e3dE08A90
+Ethereum StateView:              0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227
+Ethereum V4Quoter:               0x52F0E24D1c21C8A0cB1e5a5dD6198556BD9E1203
+Ethereum Permit2:                0x000000000022D473030F116dDEE9F6B43aC78BA3
+Ethereum UniversalRouter (V2):   0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
+Ethereum UniversalRouter 2.1.1:  0x4C82D1fBFe28C977cBB58D8C7FF8FCF9F70a2cCA
+Ethereum UniversalRouter 2.1.2:  0x23617e59A5925b2A4Bf75d73ff6711cD0b29De85
+
+Unichain PoolManager:            0x1F98400000000000000000000000000000000004
+Unichain PositionManager:        0x4529A01c7A0410167c5740C487A8DE60232617bf
+Unichain StateView:              0x86e8631A016F9068C3f085fAF484Ee3F5fDee8f2
+Unichain UniversalRouter (V2):   0xEf740bf23aCaE26f6492B10de645D6B98dC8Eaf3
 ```
 
-Deployed on: Ethereum, Unichain, Optimism, Base, Arbitrum One, Polygon, Blast, Zora, Worldchain, Ink, Soneium, Avalanche, BNB, Celo, Monad, MegaETH, Tempo.
+Deployed on 19 mainnets: Ethereum, Unichain, Optimism, Base, Arbitrum One, Polygon, Zora, Worldchain, X Layer, Ink, Soneium, Avalanche, BNB Smart Chain, Celo, Monad, MegaETH, Tempo, Robinhood Chain, Arc. Blast was dropped from the official list. Per-chain addresses: https://developers.uniswap.org/docs/protocols/v4/deployments.
 
 **CRITICAL**: Addresses differ per chain. Always verify with `cast code <address> --rpc-url <chain_rpc>`.
 
+V4 protocol fees are active (governance proposal executed 2026-07-27): `protocolFeeController()` is set on Ethereum and Base, and still `address(0)` on Unichain. Read `protocolFee` from `getSlot0` before modelling fee revenue.
+
 ## Core Architecture
 
 ### Singleton + Flash Accounting Flow
@@ -68,7 +80,11 @@ struct PoolKey {
 
 ### Router with Swap + Settle/Take
 ```solidity
+import {SwapParams} from "v4-core/src/types/PoolOperation.sol"; // top-level struct; not a member of IPoolManager
+
 contract V4Router is IUnlockCallback {
+    using CurrencyLibrary for Currency;
+
     IPoolManager public immutable pm;
 
     function swap(PoolKey calldata key, bool zeroForOne, int256 amount) external {
@@ -80,7 +96,7 @@ contract V4Router is IUnlockCallback {
         (PoolKey memory key, bool zf1, int256 amt, address user) =
             abi.decode(data, (PoolKey, bool, int256, address));
 
-        BalanceDelta delta = pm.swap(key, IPoolManager.SwapParams({
+        BalanceDelta delta = pm.swap(key, SwapParams({
             zeroForOne: zf1,
             amountSpecified: amt,
             sqrtPriceLimitX96: zf1
@@ -97,8 +113,15 @@ contract V4Router is IUnlockCallback {
         if (delta < 0) {
             // Caller owes PM
             uint256 owed = uint256(uint128(-delta));
-            IERC20(Currency.unwrap(currency)).transferFrom(user, address(pm), owed);
-            pm.settle();
+            if (currency.isAddressZero()) {
+                pm.settle{value: owed}();
+            } else {
+                // settle() credits the diff against the synced balance; without sync() it
+                // treats the currency as native and credits msg.value (0) -> CurrencyNotSettled()
+                pm.sync(currency);
+                IERC20(Currency.unwrap(currency)).transferFrom(user, address(pm), owed);
+                pm.settle();
+            }
         } else if (delta > 0) {
             pm.take(currency, user, uint256(uint128(delta)));
         }
@@ -135,8 +158,8 @@ contract V4Router is IUnlockCallback {
 | TickMath | Tick ↔ sqrtPriceX96 conversion | v4-core/src/libraries/TickMath.sol |
 | LPFeeLibrary | Fee flags and validation | v4-core/src/libraries/LPFeeLibrary.sol |
 | Actions | PositionManager action codes | v4-periphery/src/libraries/Actions.sol |
-| BaseHook | Hook base class | v4-periphery/src/utils/BaseHook.sol |
-| HookMiner | Address mining for hooks | v4-periphery/src/utils/HookMiner.sol |
+| BaseHook | Hook base class (removed from v4-periphery 2026-02-06) | @openzeppelin/uniswap-hooks/src/base/BaseHook.sol (v4-template default) or v4-hooks-public/src/base/BaseHook.sol |
+| HookMiner | Address mining for hooks | v4-periphery/test/shared/HookMiner.sol or v4-hooks-public/src/utils/HookMiner.sol (byte-identical) |
 
 ## Output Format
 
diff --git a/bin/cli.mjs b/bin/cli.mjs
index ce4c7fe..1c36c9a 100755
--- a/bin/cli.mjs
+++ b/bin/cli.mjs
@@ -13,7 +13,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const REPO_DIR = join(__dirname, '..');
 const CLAUDE_DIR = join(homedir(), '.claude');
-const VERSION = '1.0.0';
+const VERSION = '1.1.0';
 
 const COLORS = {
   reset: '\x1b[0m',
diff --git a/package.json b/package.json
index d51ff4e..27ea787 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "evm-cortex",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Ethereum protocol engineering squad for Solidity development, security auditing, DeFi, and smart contract testing",
   "type": "module",
   "bin": {
diff --git a/plugin.json b/plugin.json
index 1b64936..6ea26ee 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "evm-cortex",
   "description": "Ethereum protocol engineering squad for Solidity development, security auditing, DeFi integration, and smart contract testing with Foundry",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "ccashwell",
     "url": "https://github.com/ccashwell"
diff --git a/rules/evm-current-state.md b/rules/evm-current-state.md
index 9a87e13..58840da 100644
--- a/rules/evm-current-state.md
+++ b/rules/evm-current-state.md
@@ -2,8 +2,10 @@
 
 ## Your Training Data is Stale — Use These Facts
 
+Source of record: [ethskills.com](https://ethskills.com/SKILL.md) (fetched 2026-09-25) and [forkcast.org](https://forkcast.org). Re-fetch before quoting a number in a report.
+
 ### Gas Costs
-- Mainnet base fee: under 1 gwei (was 10-30 gwei in training data)
+- Mainnet base fee: under 1 gwei, typically 0.1-0.5 gwei (was 10-30 gwei in training data)
 - ETH transfer: ~$0.004 (was $1-5)
 - ERC-20 transfer: ~$0.01
 - Swap: ~$0.04 (was $5-50)
@@ -14,35 +16,41 @@
 - "Ethereum is expensive" was true 2021-2023. It is false in 2026.
 
 ### Recent Upgrades
-- **Pectra** (May 2025): EIP-7702 (EOA smart accounts), EIP-7691 (blob throughput), EIP-7623 (calldata cost increase)
-- **Fusaka** (Dec 2025): PeerDAS, 2x gas limit increase
-- **Glamsterdam** (planned mid-2026): ePBS (EIP-7732), Block Access Lists (EIP-7928)
-- Verkle trees were deprioritized — may shift to binary state tree (EIP-7864)
+- **Pectra** (May 7, 2025): EIP-7702 (EOA smart accounts), EIP-7691 (blob throughput), EIP-7623 (calldata cost increase), BLS12-381 precompiles
+- **Fusaka** (Dec 3, 2025): PeerDAS (EIP-7594), gas limit 30M → 60M, blob-only hardforks (EIP-7892)
+- **Glamsterdam** (in progress, targeting Q3-Q4 2026 — dates slip): ePBS (EIP-7732), Block Access Lists (EIP-7928). FOCIL was removed from scope.
+- **Hegota** (targeting Q4 2026): does NOT contain Verkle trees. Verkle was deprioritized over quantum-resistance and ZK-compatibility concerns; Ethereum may shift to a binary state tree (EIP-7864, Draft as of March 2026).
+- Upgrade cadence: roughly twice a year. A feature is scheduled only when forkcast shows it **SFI** for a named fork (CFI = under consideration, DFI = declined; definitions in EIP-7723). Roadmap diagrams and blog posts older than 6 months are aspirational, not commitments.
 
 ### EIP-7702 is Live
-EOAs can now have smart contract functionality without migration. Authorization tuples enable batched transactions, sponsored gas, session keys.
+EOAs can now have smart contract functionality without migration. Authorization tuples enable batched transactions, sponsored gas, session keys. ERC-4337 remains the bundler-based path; EntryPoint v0.7 is `0x0000000071727De22E5E9d8BAf0edAc6f37da032` (verified with `cast code`, 2026-09-25).
 
 ### Toolchain
-- **Foundry** is the default for new projects in 2026, not Hardhat
-- Forge, Cast, Anvil, Chisel are the standard toolset
-- Slither remains the primary static analysis tool
-- Aderyn (by Cyfrin) gaining adoption
+- **Foundry** is this squad's default (see CLAUDE.md): Forge, Cast, Anvil, Chisel
+- **Hardhat 3** (Aug 2025) shipped Solidity tests, fuzzing, and Rust internals; it is a legitimate TypeScript-first choice, not a dead one. Do not describe Hardhat as obsolete.
+- **Truffle** is deprecated. **Goerli and Rinkeby** are deprecated; Sepolia (chain ID 11155111) is the testnet.
+- Slither remains the primary static analysis tool; Aderyn (by Cyfrin) gaining adoption
+- Blockscout MCP (`https://mcp.blockscout.com/mcp`) gives agents structured onchain data; abi.ninja for zero-setup contract interaction
 
 ### New Standards
-- **ERC-8004**: Onchain agent identity registry, deployed January 2026 on 20+ chains
-- **x402**: HTTP 402 payment protocol for machine-to-machine commerce (production-ready)
+- **ERC-8004**: Onchain agent identity registry, deployed January 29, 2026 on 20+ chains. Mainnet IdentityRegistry `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`, ReputationRegistry `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` (both verified with `cast code`, 2026-09-25)
+- **x402**: HTTP 402 payment protocol for machine-to-machine commerce (production-ready; SDKs `@x402/fetch`, `x402` Python, Go)
 - **EIP-3009**: Gasless token transfers (what makes x402 work, USDC implements it)
+- **ERC-8056** "Scaled UI Amount" (Draft, Oct 2025): a `uiMultiplier()` display scalar for tokenized stocks — raw balances never rebase, so index raw amounts
 
 ### L2 Landscape
-- Base: cheapest major L2, Coinbase distribution
-- Arbitrum: deepest DeFi liquidity
-- Optimism: Superchain ecosystem, retroPGF
-- Celo: migrated to OP Stack L2 in March 2025 (NOT an L1 anymore)
-- Polygon zkEVM: being shut down — do NOT build on it
-- Dominant DEX per L2: Aerodrome (Base), Velodrome (Optimism), Camelot (Arbitrum) — NOT Uniswap
+- **Base**: cheapest major L2, Coinbase distribution. Announced in February 2026 that it is leaving the Superchain (finalizes in a future hardfork)
+- **Arbitrum One**: deepest DeFi liquidity, Stylus (Rust/C++ contracts). `block.number` is the L1 block number
+- **Optimism**: Superchain ecosystem, retroPGF
+- **Unichain**: Uniswap's OP Stack L2, chain ID 130, mainnet February 11, 2025. TEE-based block building orders transactions by time received, not gas price — priority-fee bidding is pointless there
+- **Celo**: migrated to OP Stack L2 on March 26, 2025 (NOT an L1 anymore). Mento stablecoins rebranded Dec 2025: USDm (was cUSD), EURm, BRLm — same addresses
+- **Robinhood Chain**: Arbitrum Orbit L2 settling directly to Ethereum with blob DA, chain ID 4663, mainnet July 1, 2026. Tokenized stocks as ERC-20s (not available to US persons). ArbOS 61 transaction filtering can censor even L1 force-included transactions; L2Beat Stage 0. USDG stablecoin has 6 decimals
+- **Polygon zkEVM**: being shut down — do NOT build on it
+- **Dominant DEX per L2 is NOT Uniswap by default**: Aero (Aerodrome and Velodrome merged in November 2025 under Dromos Labs) on Base and Optimism, Camelot and GMX on Arbitrum, SyncSwap on zkSync
 
 ### ETH Price
-~$2,000 (early 2026). Volatile — always verify before economic calculations.
+~$2,000 (early 2026). Volatile — always verify before economic calculations (Chainlink ETH/USD feed or CoinGecko).
 
 ### Reference
-Track upcoming changes: https://forkcast.org
+- Track upcoming changes: https://forkcast.org
+- Knowledge corrections for agents: https://ethskills.com/SKILL.md (sub-skills: `why/`, `gas/`, `l2s/`, `protocol/`, `standards/`, `tools/`, `security/`, `audit/`, `crops/`)
diff --git a/skills/erc8004-patterns/SKILL.md b/skills/erc8004-patterns/SKILL.md
index e803f37..f4a8569 100644
--- a/skills/erc8004-patterns/SKILL.md
+++ b/skills/erc8004-patterns/SKILL.md
@@ -7,7 +7,7 @@ description: Use when integrating ERC-8004 onchain agent identity. Covers agent
 
 ## Overview
 
-ERC-8004 establishes a standard for AI agent identity onchain. Deployed in January 2026 across 20+ chains, it provides a registry for agents to declare their identity, capabilities, and trust relationships. This enables verifiable agent-to-agent and agent-to-protocol interactions.
+ERC-8004 establishes a standard for AI agent identity onchain. Deployed on January 29, 2026 across 20+ chains, it provides a registry for agents to declare their identity, capabilities, and trust relationships. This enables verifiable agent-to-agent and agent-to-protocol interactions.
 
 ## Core Interface
 
@@ -201,7 +201,12 @@ ERC-8004 is deployed at the same address on 20+ chains. Query the registry on an
 import { createPublicClient, http } from 'viem';
 import { base, optimism, arbitrum } from 'viem/chains';
 
-const ERC8004_REGISTRY = '0x...'; // Same address on all chains
+// ERC-8004 registries (same addresses on 20+ chains). Verified with `cast code` on
+// Ethereum mainnet and Base, 2026-09-25 — re-verify on any other chain before use.
+// Source: https://ethskills.com/why/SKILL.md, https://www.8004.org
+const ERC8004_IDENTITY_REGISTRY = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432';
+const ERC8004_REPUTATION_REGISTRY = '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63';
+const ERC8004_REGISTRY = ERC8004_IDENTITY_REGISTRY;
 
 async function checkAgentOnChain(agentAddress: `0x${string}`, chain: any) {
   const client = createPublicClient({ chain, transport: http() });
diff --git a/skills/lp-analyst/SKILL.md b/skills/lp-analyst/SKILL.md
index 897fe4a..d7e0a14 100644
--- a/skills/lp-analyst/SKILL.md
+++ b/skills/lp-analyst/SKILL.md
@@ -148,16 +148,18 @@ Compare with V2 full-range IL at the same price move (r = 3500/3000 ≈ 1.167):
 IL_v2 = 2√1.167 / (1 + 1.167) - 1 = 2 × 1.0801 / 2.167 - 1 ≈ -0.28%
 ```
 
-The concentrated position suffers ~14x more IL — consistent with the capital efficiency multiplier for this range.
+The concentrated position suffers ~13-14x more IL on this move — more than the ~6.5x capital-efficiency multiplier for the 2500-3500 range. IL amplification is not a constant factor: it grows as price approaches a range edge, so the multiplier understates downside near the bounds.
 
 ## Fee Revenue Estimation
 
 ### Fee Accrual Model
 
 ```
-fee_revenue = volume_in_range × fee_tier × (position_liquidity / total_liquidity_in_range)
+fee_revenue = volume_in_range × fee_tier × (1 - protocol_share) × (position_liquidity / total_liquidity_in_range)
 ```
 
+`protocol_share` is no longer zero. Since the UNIfication proposal executed on 2025-12-28, Ethereum mainnet V3 pools set `slot0().feeProtocol` to `68` on the 0.01%/0.05% tiers (protocol takes 1/4 of LP fees) and `102` on the 0.30% tier (1/6) — decode as `token0 = feeProtocol % 16`, `token1 = feeProtocol >> 4`, share `= 1/N`. V4 static-fee pools have charged a protocol fee since governance activated it on 2026-07-27 (mainnet ETH/USDC 500/10: `protocolFee = 512125`, i.e. 125 pips per direction); it is taken from the swap input ahead of the LP fee, so for V4 `protocol_share ≈ protocolFee / 1e6` per direction.
+
 Annualized:
 
 ```
@@ -234,10 +236,10 @@ efficiency = 1 / (1 - √(Pa / Pb))
 |-------|-------|-----------|
 | ±0.1% (stables) | 0.998 | ~1000x |
 | ±1% | 0.980 | ~100x |
-| ±5% | 0.905 | ~19x |
-| ±10% | 0.818 | ~5.2x |
-| ±25% | 0.600 | ~3.8x |
-| ±50% | 0.333 | ~2.2x |
+| ±5% | 0.905 | ~20.5x |
+| ±10% | 0.818 | ~10.5x |
+| ±25% | 0.600 | ~4.4x |
+| ±50% | 0.333 | ~2.4x |
 | Full range | 0→∞ | 1x |
 
 Higher efficiency means more fees earned per dollar of capital, but also more IL per dollar and more frequent out-of-range events.
@@ -461,7 +463,7 @@ function collectFees(
 
 ### V4 Fee Collection
 
-V4 positions collect fees through the `PositionManager.collect` action inside a multicall/modifyLiquidities batch. Fees settle through the PoolManager's transient accounting.
+V4 has no `collect`. Encode `[Actions.DECREASE_LIQUIDITY (liquidity = 0), Actions.TAKE_PAIR]` in `modifyLiquidities`; the zero-liquidity decrease pokes the position and its `feesAccrued` are taken via `TAKE_PAIR` (or `CLOSE_CURRENCY`). Fees settle through the PoolManager's transient accounting.
 
 ## Rebalancing Strategies
 
@@ -583,13 +585,15 @@ abstract contract LPKeeper is AutomationCompatibleInterface {
 A V4 hook can auto-compound fees into the position on every swap:
 
 ```solidity
-function afterSwap(
+// SwapParams lives in v4-core/src/types/PoolOperation.sol. BaseHook (OpenZeppelin uniswap-hooks or
+// Uniswap/v4-hooks-public) keeps the external callbacks non-virtual; override the internal _afterSwap.
+function _afterSwap(
     address,
     PoolKey calldata key,
-    IPoolManager.SwapParams calldata,
+    SwapParams calldata,
     BalanceDelta delta,
     bytes calldata
-) external override returns (bytes4, int128) {
+) internal override returns (bytes4, int128) {
     // Collect fees generated by the swap and re-add as liquidity
     // This is possible because V4 hooks execute within the PoolManager's
     // unlock context, allowing atomic fee collection + liquidity addition
@@ -683,7 +687,7 @@ Key considerations:
 ```
 daily_fees_usd = sum(feesUSD over 24h for ticks in [tickLower, tickUpper])
 position_share = position_liquidity / total_liquidity_in_tick_range
-my_daily_fees = daily_fees_usd × position_share
+my_daily_fees = daily_fees_usd × (1 - protocol_share) × position_share   # subgraph feesUSD is gross of the protocol fee
 fee_APR = (my_daily_fees / position_value_usd) × 365
 ```
 
@@ -693,7 +697,7 @@ Higher V/L ratio means more fee revenue per unit of liquidity:
 
 ```
 VL_ratio = volume_24h / TVL_in_range
-expected_daily_yield = VL_ratio × fee_tier
+expected_daily_yield = VL_ratio × fee_tier × (1 - protocol_share)
 ```
 
 ## Risk Metrics
diff --git a/skills/pashov-audit-pipeline/SKILL.md b/skills/pashov-audit-pipeline/SKILL.md
index 0288f9a..c48ecf7 100644
--- a/skills/pashov-audit-pipeline/SKILL.md
+++ b/skills/pashov-audit-pipeline/SKILL.md
@@ -1,36 +1,54 @@
 ---
 name: pashov-audit-pipeline
-description: Use when performing a comprehensive smart contract security audit. Implements the Pashov Audit Group's parallelized 12-agent attacker-framing methodology — nine single-specialty lenses (math precision, access control, economic security, execution trace, invariant, periphery, first principles, asymmetry, boundary) plus three gap-hunters that find bugs living at the seams between lenses. Produces deduplicated, confidence-scored, severity-classified findings with PoC verification.
+description: Use when performing a comprehensive smart contract security audit. Implements the Pashov Audit Group's parallelized 12-agent attacker-framing methodology (solidity-auditor v4) — nine single-specialty lenses (math precision, access control, economic security, execution trace, invariant, periphery, first principles, asymmetry, boundary) plus three gap-hunters that find bugs living at the seams between lenses. Supports loop mode (N passes per scan, each told what earlier passes found) and a findings ledger that remembers results across scans. Produces a shell-assembled, deduplicated, confidence-scored report plus an EVM Cortex severity and PoC annex. Trigger on "pashov audit", "run the auditor in loop mode", "run 3 passes".
 ---
 
 # Pashov Audit Pipeline
 
 You are the orchestrator of a parallelized smart contract security audit.
 
-Twelve specialized agents attack the same codebase at once, then their output is deduplicated and gated into a single report. Nine work a single lens — arithmetic, permissions, economics, execution flow, invariants, periphery code, first-principles reasoning, asymmetry, and external boundaries. Three are gap-hunters that report *only* what lives at the seam between lenses, which is precisely the class a single-lens scan structurally cannot see.
+Twelve specialized agents attack the same codebase at once, then their output is deduplicated, gated, and assembled into a single report. Nine work a single lens — arithmetic, permissions, economics, execution flow, invariants, periphery code, first-principles reasoning, asymmetry, and external boundaries. Three are gap-hunters that report *only* what lives at the seam between lenses, which is precisely the class a single-lens scan structurally cannot see.
 
-Vendored from the Pashov Audit Group's open-source approach (`github.com/pashov/skills`), skill `solidity-auditor`, **VERSION 3** (see the `VERSION` file alongside this one). Everything under `references/` is upstream content carried over intact except for two documented EVM Cortex additions — the severity/PoC addendum in `references/judging.md` and the deviations section in `references/report-formatting.md`. Check for a newer upstream revision before a high-stakes audit:
+Vendored from the Pashov Audit Group's open-source approach (`github.com/pashov/skills`), skill `solidity-auditor`, **VERSION 4** (see the `VERSION` file alongside this one). Everything under `references/` is upstream content carried over intact, with four documented EVM Cortex deviations:
+
+1. `references/orchestration.md` is upstream's `SKILL.md`, vendored verbatim so the turn-by-turn procedure (memory read, prune, bundle build, run files, assembly) stays a file-by-file diff against upstream. Where any reference file says "SKILL.md Turn N", it means that file.
+2. `references/judging.md` carries an appended severity/PoC addendum required by this repo's finding-output-format, severity-matrix, and poc-execution rules.
+3. `on-chain`/`off-chain` are normalized to `onchain`/`offchain` across `references/` prose and in the one disclaimer string `assemble.sh` prints, per this repo's style rule.
+4. `assemble.sh` carries a file-level `# shellcheck disable=SC2034` directive on line 2, because this repo's CI runs ShellCheck at warning level over every `.sh` file and the assembler's `read` loops bind TSV columns it does not use. Nothing else in the script differs.
+
+Every other EVM Cortex adaptation — agent mapping, context package, Foundry pre-flight, the severity line in each finding block, and the Turn 6 annex — lives in this `SKILL.md` only, so an upstream re-sync replaces `references/` cleanly. Check for a newer upstream revision before a high-stakes audit:
 
 ```bash
 curl -sf https://raw.githubusercontent.com/pashov/skills/main/solidity-auditor/VERSION
 ```
 
-If that returns a number greater than 3, this skill is behind upstream.
+If that returns a number greater than 4, this skill is behind upstream.
+
+## What v4 changed
+
+- **Loop mode.** `--loop [N]` runs N passes of the twelve agents in one scan. Every pass after the first is handed what the earlier passes found as "ground already walked", so it hunts new ground. One combined report at the end. When the runner asks for loop mode without a number, the default is 3 passes; the reference gives measured times (about 15 minutes per pass on a 2,200-line codebase).
+- **Scan memory.** `--memory` (on automatically when passes > 1) keeps a ledger at `.solidity-auditor/memory.tsv` in the audited repo. Findings are tagged `KNOWN (n scans)` or `NEW`; records the scan did not raise again are listed under "Known from earlier scans" and explicitly marked not re-checked.
+- **Shell-assembled report.** Each pass writes its gated findings to `.solidity-auditor/runs/{stamp}/run-K.md` while it still has context to spare; `references/assemble.sh` is the only producer of `full-report.md`. The orchestrator never composes, re-words, or summarizes the report. A real 3-pass scan that produced 71 findings once printed 14 of them and claimed full coverage; the design exists to kill that defect.
+- **Simplified Technical English.** `references/report-language.md` is appended to every agent bundle and governs every title and Description: one sentence, 25 words or fewer, active voice, names who acts and what they get.
+- **Threshold 75, not 80.** A promoted lead lands at exactly 75 and must clear the line. It is set once in `judging.md`; the assembler reads it from there.
+- **Scope.** Build and dependency directories are excluded; deploy scripts (`script/`, `deploy/`, `*.s.sol`) are **in scope** because they set constructor arguments and hand over ownership; explicitly named files are always scanned wherever they live.
+- **Agents are READ-ONLY** inside the audited repository. No PoC files, no scratch notes, not even ones deleted afterwards. PoCs are written under the scan directory (Turn 6).
+- **Upgrade warning** fires only when the local `VERSION` is lower than upstream, not merely different.
 
 ## The stance: agents are attackers, not reviewers
 
-This is what changed most in v3 and it is the whole point of the pipeline. Every agent is framed as an attacker with unlimited capital and flash loans, not as a reviewer working a checklist. Three consequences worth stating up front, because they invert the instinct:
+Every agent is framed as an attacker with unlimited capital and flash loans, not as a reviewer working a checklist. Three consequences worth stating up front, because they invert the instinct:
 
 - **When an agent finds a bug it deepens the attack — it never argues itself out of one.** Chain it, find more victims, lower the precondition cost. Refutation belongs to the judging phase, not the hunting phase.
 - **A finding is not real until traced with concrete values.** No proof means LEAD, not FINDING. Leads are not failures; they are honest calibration and they get emitted.
-- **Catalog scanning is not the product.** Pattern catalogs live in the sibling skills (`reentrancy-patterns`, `flash-loan-attacks`, `oracle-manipulation`, `signature-vulnerabilities`, `economic-attack-vectors`, `denial-of-service`) — load those for reference. A pure catalog sweep was the previous generation of this pipeline; it produced volume without depth, which is why upstream dropped the dedicated vector-scan agent in v3.
+- **Catalog scanning is not the product.** Pattern catalogs live in the sibling skills (`reentrancy-patterns`, `flash-loan-attacks`, `oracle-manipulation`, `signature-vulnerabilities`, `economic-attack-vectors`, `denial-of-service`) — load those for reference. A pure catalog sweep was an earlier generation of this pipeline; it produced volume without depth, which is why upstream dropped the dedicated vector-scan agent in v3.
 
 ### When to Use
 
 - Full security audit of a protocol before mainnet deployment
-- Re-audit after significant code changes or new feature additions
+- Re-audit after significant code changes or new feature additions — run with `--memory` so the report says what is new
 - Pre-merge security review of high-risk PRs touching core accounting or token logic
-- Competitive audit participation where thoroughness and finding volume matter
+- Competitive audit participation where thoroughness and finding volume matter — use loop mode
 
 ### When NOT to Use
 
@@ -39,238 +57,198 @@ This is what changed most in v3 and it is the whole point of the pipeline. Every
 - Gas-only review — use `gas-optimizer`
 - Code quality review without security focus — use `code-reviewer`
 - Pre-audit reconnaissance and readiness assessment — run `xray-pre-audit` first, then feed its output in as the context package
+- Accounting-heavy protocols where the question is "does the tracked total match reality" — run `simao-audit-pipeline` as well and treat overlap as signal
 
 ---
 
-## Mode Selection
+## How to run this skill
 
-**Exclude pattern:** skip directories `interfaces/`, `lib/`, `mocks/`, `test/`, `script/` and files matching `*.t.sol`, `*.s.sol`, `*Test*.sol`, `*Mock*.sol`.
+Follow `references/orchestration.md` turn by turn — Mode Selection, Turn 1 through Turn 5, and its Banner — with the EVM Cortex substitutions and insertions below. The reference files it delegates to sit in the same directory: `agent-prompts.md` (Turn 3a prompts), `dedup-and-assembly.md` (Turn 4 and Turn 5 procedure), `report-formatting.md` (finding-block shape), `report-language.md` (wording), `judging.md` (gates, confidence, lead promotion, severity addendum), `senior-auditor-sop.md` and `hacking-agents/` (bundle content), and `assemble.sh` (the assembler).
 
-- **Default** (no arguments): scan all `.sol` files using the exclude pattern. Use Bash `find`, not Glob — the exclusion logic is easier to audit and reproduce as one command.
-- **`$filename ...`**: scan the specified file(s) only.
-
-**Flags:**
-
-- `--file-output` (off by default): also write the report to a markdown file, at the path in `references/report-formatting.md`. Never write a report file unless explicitly passed.
-
----
+Two upstream steps are pinned here because the runtime differs:
 
-## Orchestration
+- **`{resolved_path}`** is this skill's own `references/` directory. Do not glob for `shared-rules.md` — the installer places a copy under `~/.claude/skills/` and a repo checkout may hold another, and a glob can pick the wrong one.
+- **Version check** (Turn 1 e): compare as numbers and warn only when local is lower. Print `⚠️ Upstream solidity-auditor is at version N, this skill is vendored at 4. See https://github.com/pashov/skills`. A failed fetch is skipped silently — a network failure is not an audit finding.
 
-### Turn 1 — Discover
+### Turn 1b — Model and pass count
 
-Print the banner, then make these tool calls in parallel in one message:
+Ask both questions in one `AskUserQuestion` call exactly as the reference describes. The runner's model choice `{agent_model}` applies to agents 1–9. **The three gap-hunters (agents 10–12) run on `opus` regardless of the answer.** Cross-lens reasoning is where model tier matters most; a weaker gap-hunter collapses into restating single-lens findings, which dedup then discards as duplicates — the most expensive way to save money in this pipeline. Say so in one line when the runner picks a lower tier.
 
-1. Bash `find` for in-scope `.sol` files per mode selection
-2. `ToolSearch select:Agent`
-3. Read the local `VERSION` file in this skill's directory
-4. Bash `curl -sf https://raw.githubusercontent.com/pashov/skills/main/solidity-auditor/VERSION`
-5. Bash `mktemp -d ./.audit-XXXXXX` → store as `{bundle_dir}`
+If the audited repo's `.gitignore` does not list `.solidity-auditor/`, print a one-line reminder that the runs directory and ledger should be ignored. Do not edit `.gitignore` yourself.
 
-`{resolved_path}` is this skill's `references/` directory.
+### Turn 2b — Context package (EVM Cortex insertion, once per scan)
 
-If the remote VERSION fetch succeeds and differs from local, print: `⚠️ Upstream solidity-auditor is at version N, this skill is vendored at 3. See https://github.com/pashov/skills`. If the fetch fails, skip silently — a network failure is not an audit finding.
+After `source.md` is built and before the bundles are catted, assemble, when available: the protocol README, known issues (to avoid duplicate reports), documented design decisions, deployment context (target chains, upgrade strategy), external dependencies, and prior audit reports with resolution status. Write it to `{bundle_dir}/context.md` and append it to every bundle **after `report-language.md` and before `known-findings.md`**. Keep it under 300 lines; the agents' attention belongs to the source.
 
-### Turn 1b — Model selection
+If `xray-pre-audit` has been run, its `x-ray/x-ray.md` is the best available context package — it already carries the threat model, invariant list, and entry-point classification.
 
-Ask which model tier the twelve agents should run at, via `AskUserQuestion`, defaulting to the orchestrator's own family. Store as `{agent_model}`.
+### Turn 2c — Foundry pre-flight (EVM Cortex insertion, once per scan)
 
-Prefer opus for the three gap-hunters regardless of the answer. Cross-lens reasoning is where model tier matters most, and a weaker gap-hunter collapses into restating single-lens findings — which Phase 4 then discards as duplicates. That is the most expensive way to save money in this pipeline.
+Run in the audited repo, writing outputs only under the scan directory:
 
-### Turn 2 — Prepare bundles
-
-Read `{resolved_path}/report-formatting.md` and `{resolved_path}/judging.md` in parallel.
-
-Then build all bundles in a single Bash command using `cat` (not shell variables or heredocs):
+```bash
+forge build --deny-warnings
+forge test --summary
+slither . --filter-paths "test|script|node_modules|lib" --json .solidity-auditor/runs/{stamp}/slither-report.json
+forge tree > .solidity-auditor/runs/{stamp}/dependency-tree.txt
+```
 
-1. `{bundle_dir}/source.md` — ALL in-scope `.sol` files, each under a `### path` header inside a fenced `solidity` block.
-2. One bundle per agent: `source.md` + SOP + that agent's specialty + shared rules.
+`forge build` and `forge test` write only to `out/` and `cache/`, which the scan excludes. A build failure is not a stopper — note it in the context package and continue; the agents read source, not artifacts. If the project is not a Foundry project, skip the `forge` steps and say so.
 
-| Bundle | Appended files (relative to `{resolved_path}`) |
-|--------|-----------------------------------------------|
-| `agent-1-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/math-precision-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-2-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/access-control-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-3-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/economic-security-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-4-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/execution-trace-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-5-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/invariant-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-6-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/periphery-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-7-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/first-principles-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-8-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/asymmetry-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-9-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/boundary-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-10-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/numerical-gap-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-11-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/trust-gap-agent.md` + `hacking-agents/shared-rules.md` |
-| `agent-12-bundle.md` | `senior-auditor-sop.md` + `hacking-agents/flow-gap-agent.md` + `hacking-agents/shared-rules.md` |
+### Turn 3a — Agent mapping
 
-Print line counts for `source.md` and every bundle. An undersized bundle means a broken `cat` and must be caught before agents launch, not after twelve agents return empty.
+Use the two prompt templates in `references/agent-prompts.md` verbatim, substituting `{bundle_dir}`, the agent number, and the bundle's real line count. The READ-ONLY paragraph is unconditional; the "Known findings" paragraph appears only when memory is on and `known-findings.md` was appended. Spawn all twelve as parallel background Agent calls with these `subagent_type` values:
 
-**Never inline source code into an Agent prompt.** The prompt points at the bundle file and the agent reads it. Inlining multiplies token cost by twelve and truncates on large codebases.
+| # | Lens | `subagent_type` | Model |
+|---|------|-----------------|-------|
+| 1 | Math & Precision | `depth-token-flow` | opus |
+| 2 | Access Control | `access-control-reviewer` | sonnet |
+| 3 | Economic Security | `mev-analyst` | sonnet |
+| 4 | Execution Trace | `depth-state-trace` | opus |
+| 5 | Invariant | `invariant-analyst` | sonnet |
+| 6 | Periphery | `depth-external` | opus |
+| 7 | First Principles | `sleuth` | opus |
+| 8 | Asymmetry | `code-reviewer` | opus |
+| 9 | Boundary | `depth-edge-case` | sonnet |
+| 10 | Numerical Gap | `depth-token-flow` | opus |
+| 11 | Trust Gap | `mev-analyst` | opus |
+| 12 | Flow Gap | `sleuth` | opus |
 
-Each agent gets its own lens only. Handing all twelve specialties to every agent defeats the design — the lenses are supposed to be independent so their overlap is evidence rather than an echo.
+The `subagent_type` selects a base persona and tool set; **the specialty file in the bundle is what determines the lens.** Reused types (`depth-token-flow`, `mev-analyst`, `sleuth`) run as independent instances with different bundles and share no context. The Model column is the default when Turn 1b set no `{agent_model}`; when it did, agents 1–9 take the runner's choice and 10–12 stay on opus.
 
-### Turn 2b — Context package
+### Verifying the agents did the work
 
-Every agent also gets, when available: the protocol README, known issues (to avoid duplicate reports), documented design decisions, deployment context (target chains, upgrade strategy), external dependencies, and prior audit reports with resolution status.
+`shared-rules.md` binds every agent to three mental tools from `senior-auditor-sop.md`, each with a trigger that requires a literal marker in the agent's output: `[Feynman: <name>]` when it opens a new function, `[Socratic: <file:line> — why?]` when it stops on an unclear line, `[Inversion: <function>]` when a path reads as clean.
 
-If `xray-pre-audit` has been run, its `x-ray/x-ray.md` output is the best available context package — it already contains the threat model, invariant list, and entry-point classification.
+After each agent returns, grep its output for those markers. An agent that returns findings with no markers did not reason — it scanned. Note the shortfall as a workflow violation and weight that agent's findings accordingly. Do not respawn it: in loop mode the next pass covers the same lens for free, and on a 1-pass scan a retry costs an unbounded wait for one twelfth of the coverage.
 
-### Turn 2c — Pre-flight
+### Turn 4 — Severity line (EVM Cortex insertion, every pass)
 
-```bash
-forge build --deny-warnings           # must compile clean
-forge test --summary                  # establish a baseline
-slither . --filter-paths "test|script|node_modules" --json slither-report.json
-forge tree > dependency-tree.txt
-```
+Follow `references/dedup-and-assembly.md` Turn 4 step by step. Between step 3 (lead promotion) and step 4 (memory tag), classify every gated **FINDING** per the severity addendum in `judging.md` — impact × likelihood from the global severity matrix, assigned independently of confidence. LEADs are not classified.
 
-### Turn 3a — Spawn all twelve agents
+In step 5a, write the severity into the finding block's body as one structured line between the Description and the Fix:
 
-One message, twelve parallel background Agent calls (`run_in_background=true`), `model={agent_model}`. Single phase, no later spawns. You will be notified as each completes — do not poll or sleep.
+````markdown
+**Description**
+<one sentence>
 
-Agents 1–9 use the single-specialty prompt; agents 10–12 use the gap-hunter prompt.
+**Severity** High · Impact High · Likelihood Likely
 
-**Single-specialty prompt (agents 1–9):**
+**Fix**
+...
+````
 
-```
-You are an attacker. Your specialty, mindset, source, and output rules
-are in your bundle. Read it fully before producing findings.
+The assembler pastes the body through unchanged, so the line reaches the report without any change to `assemble.sh`. It is a structured field, not prose: `report-language.md` rule 10 (no `critical`, `severe` in sentences) governs sentences and does not reach it. Use exactly one of `Critical`, `High`, `Medium`, `Low`, `Informational`, and keep the `**Severity** ` prefix and ` · ` separators exactly — Turn 6 extracts the value by shell.
 
-Read first:
-- {bundle_dir}/agent-N-bundle.md (XXXX lines) — source + SOP + specialty + shared rules.
+### Turn 5 — Assemble, print, clean
 
-The bundle contains all in-scope source. Do NOT re-read in-scope files
-for the initial scan. Use Read/Grep only for cross-file searches or
-out-of-scope context (interfaces/, lib/, mocks/, test/).
+Follow `references/dedup-and-assembly.md` Turn 5 unchanged. Do not re-word, re-order, add to, or summarize `full-report.md`. The `--file-output` copy is named `{project-name}-pashov-ai-audit-report-{stamp}.md`.
 
-What a finding looks like:
-- file, function
-- root cause — the one-sentence code-level defect
-- minimal fix — the smallest change that eliminates the defect
-- proof — concrete numbers, a trace, or quoted code
+### Turn 6 — Severity and PoC annex (EVM Cortex, once per scan)
 
-Without concrete proof, it's a LEAD, not a finding. Leads are honest
-about what you couldn't verify — they're not failures, they're
-calibration. Emit them.
+Runs after Turn 5, at any pass count. It reads `full-report.md` and never writes to it.
 
-Don't skim. Don't trust your first read. Trust your discomfort.
+1. **Extract the severity table by shell, never by hand.** One `awk` over the assembled file; the `#` column is the finding's number in `full-report.md`:
 
-Output format: see shared-rules.md inside your bundle.
+```bash
+REPORT=.solidity-auditor/runs/{stamp}/full-report.md
+awk -v OFS='\t' '
+function rank(s){ return (s=="Critical")?0:(s=="High")?1:(s=="Medium")?2:(s=="Low")?3:(s=="Informational")?4:5 }
+function flush(){ if (want) { n++; print rank(sev), conf+0, "| " n " | " sev " | [" conf "] | " title " | `" loc "` |"; want=0 } }
+/^\[[0-9]+\] \*\*[0-9]+\. / { flush(); match($0,/^\[[0-9]+\]/); conf=substr($0,RSTART+1,RLENGTH-2)
+  t=$0; sub(/^\[[0-9]+\] \*\*[0-9]+\. /,"",t); sub(/\*\*[ \t]*$/,"",t); title=t; want=1; sev="Unclassified"; loc=""; next }
+want && loc=="" && /^`/ { match($0,/^`[^`]*`/); loc=substr($0,RSTART+1,RLENGTH-2); next }
+want && /^\*\*Severity\*\* / { s=$0; sub(/^\*\*Severity\*\* /,"",s); sub(/ ·.*$/,"",s); sev=s; next }
+/^Findings List/ { flush() }
+END { flush() }
+' "$REPORT" | sort -t$'\t' -k1,1n -k2,2nr | cut -f3 > .solidity-auditor/runs/{stamp}/severity-rows.md
+wc -l < .solidity-auditor/runs/{stamp}/severity-rows.md
 ```
 
-**Gap-hunter prompt (agents 10–12):** identical, except the finding shape adds `seam — which two or three lenses combine`, the proof must demonstrate the seam, and the closing line points at the gap-hunter-specific output fields in the specialty file.
-
-### Turn 3b — Wait
-
-Proceed only once all twelve have notified completion. Let them run to natural completion; do not start dedup early and do not poll.
+The row count must equal `F` from Turn 5 step 3. If it does not, the annex says so in words and lists what it could read — it never claims to cover more than it does. A finding whose block lacks a severity line prints as `Unclassified`; leave it so and say why, rather than editing the assembled report.
 
-### Turn 4 — Deduplicate, judge, report
+2. **Write `.solidity-auditor/runs/{stamp}/severity-annex.md`:**
 
-Single pass: dedup, gate, and produce the final report in one turn. Do not print an intermediate dedup list.
+````markdown
+# Severity annex — <project-name>
 
-1. **Dedup** per the four hard gates below.
-2. **Gate** each deduped finding through the four gates in `judging.md`, in order, no skipping and no revisiting after a verdict.
-3. **Promote or reject leads** per `judging.md`.
-4. **Classify severity** and attach PoCs per the addendum in `judging.md`.
-5. **Format and print** per `report-formatting.md`. With `--file-output`, also write the file.
-6. **Auto-clean:** `rm -rf {bundle_dir}`. It is transient build state, not an artifact. For debugging, copy it elsewhere before re-running.
+_EVM Cortex layer over `full-report.md` (same stamp). Severity is impact × likelihood per the global severity matrix and is independent of confidence. `#` is the finding's number in the report. Rows: N of F findings._
 
----
-
-## Deduplication Gates
+| # | Severity | Confidence | Title | Location |
+|---|---|---|---|---|
+<severity-rows.md, verbatim>
 
-Group findings by `group_key` (`Contract | function | bug-class`). Exact match first, then merge synonymous `bug_class` values within the same `(Contract, function)`. Keep the best item per group, number sequentially, annotate `[agents: N]`.
+## Proof of concept
 
-Four gates govern this phase. They exist because the failure mode of naive merging is silently deleting real bugs — twelve agents converging on one function is *information*, not redundancy.
+_Critical and High findings require a working Foundry PoC before they are reported at that severity. Medium findings need a PoC or a step-by-step reproduction._
 
-**Gate A — Function isolation (HARD).** NEVER merge across different `function:` values. Dedup only within `(Contract, function)`. A different function is a different bug, always.
+| # | Severity | PoC | Status |
+|---|---|---|---|
+| 3 | Critical | `.solidity-auditor/runs/{stamp}/poc/Exploit_3.t.sol` | passes · fork block 19_000_000 |
+| 7 | High | — | pending — routed to poc-writer |
+````
 
-**Gate B — Wide description.** A merged group whose constituents describe distinct mechanisms — different `fix:`, different code-level cause, or different attack path — MUST list every mechanism. One function can host several coexisting bugs at the same `group_key` and all of them must appear.
+3. **Route PoCs.** For every Critical and High finding, spawn `security-verifier` or `poc-writer` with the finding block and the source it names. PoC tests are written **only** under `.solidity-auditor/runs/{stamp}/poc/` — never into the project's `test/` — and run with the test directory overridden so the project tree stays untouched:
 
-**Gate C — Function-level second pass.** After `group_key` dedup, run a second pass at `(Contract, function)` ignoring `bug_class` entirely. Agents often tag coexisting bugs with different `bug_class` values while referencing multiple mechanisms in the body text. For every `(Contract, function)` with multiple final findings, scan the description, path, proof, and fix of every constituent for distinct mechanisms crossing `bug_class` boundaries. Every mechanism appearing in any constituent body must survive into at least one final finding. This pass stays *within* `(Contract, function)` — never across, per Gate A.
-
-**Gate D — Fix preservation (HARD).** Before writing a merged `fix:` for a `(Contract, function)` with multiple findings:
+```bash
+FOUNDRY_TEST=.solidity-auditor/runs/{stamp}/poc forge test --match-path '.solidity-auditor/runs/{stamp}/poc/*' -vvv
+```
 
-1. Collect every raw `fix:` from every agent that flagged the tuple.
-2. Group them by ADD-lines (the `+` lines, or the equivalent require/assignment).
-3. Two fixes are distinct if their ADD-lines differ in the called function or expression (`require(msg.value == amount)` vs `require(zrc20 != _ETH_ADDRESS_)`), the check direction (validate / restrict / ban), or the checked parameter.
-4. Two or more distinct fixes are presented as Option A, Option B, … — one block each, **verbatim** from the agent's text, no paraphrase.
-5. Label each intuitively: validate / restrict / allow-and-handle / ban-path.
+Pin the fork block in every fork-based PoC. A Critical or High finding whose PoC fails is downgraded in the annex with a one-line reason; the severity line in the run file is left as written — the run file is the pass's record, the annex is this turn's verdict.
 
-Before printing, count the distinct fixes in the raw output for that `(Contract, function)`. Two or more distinct but only one shown is a violation — add the alternatives.
+4. **Fix verification** for findings at or above the threshold, per the `judging.md` addendum: trace the fix against the attack path, run the side-effect checklist, and pattern-check the rest of the codebase for the same defect.
 
-**Completeness check (HARD).** Before printing the report, enumerate every unique `(Contract, function, bug-class)` in any raw FINDING or LEAD across all twelve agents. Every unique `(Contract, function)` must have at least one item in the final report; zero means a silent drop, so fix it. Multiple `bug_class` values within one `(Contract, function)` may collapse into a single wide-description item, but the `(Contract, function)` itself must survive. Print this line before the report:
+5. **Print** a five-number summary and the annex path, nothing else:
 
 ```
-Completeness: N unique (Contract, function) in raw, N covered in final.
+Severity: Critical N · High N · Medium N · Low N · Informational N — annex: .solidity-auditor/runs/{stamp}/severity-annex.md
 ```
 
-**Composite chains.** If finding A's output feeds finding B's precondition AND the combined impact exceeds either alone, add `Chain: [A] + [B]` at `confidence = min(A, B)`. Most audits produce zero to two.
-
----
-
-## Verifying the agents did the work
-
-`shared-rules.md` binds every agent to three mental tools from `senior-auditor-sop.md`, each with a trigger that requires a literal marker in the agent's output: `[Feynman: <name>]` when it opens a new function, `[Socratic: <file:line> — why?]` when it stops on an unclear line, `[Inversion: <function>]` when a path reads as clean.
-
-After each agent returns, grep its output for those markers. An agent that returns findings with no markers did not reason — it scanned. Note the shortfall as a workflow violation and weight that agent's findings accordingly; consider re-running it.
+With `--file-output`, also copy the annex to `{project-name}-pashov-ai-audit-severity-{stamp}.md` beside the report copy.
 
 ---
 
-## EVM Cortex Agent Mapping
+## Deduplication gates (summary)
 
-| # | Lens | `subagent_type` | Model |
-|---|------|-----------------|-------|
-| 1 | Math & Precision | `depth-token-flow` | opus |
-| 2 | Access Control | `access-control-reviewer` | sonnet |
-| 3 | Economic Security | `mev-analyst` | sonnet |
-| 4 | Execution Trace | `depth-state-trace` | opus |
-| 5 | Invariant | `invariant-analyst` | sonnet |
-| 6 | Periphery | `depth-external` | opus |
-| 7 | First Principles | `sleuth` | opus |
-| 8 | Asymmetry | `code-reviewer` | opus |
-| 9 | Boundary | `depth-edge-case` | sonnet |
-| 10 | Numerical Gap | `depth-token-flow` | opus |
-| 11 | Trust Gap | `mev-analyst` | opus |
-| 12 | Flow Gap | `sleuth` | opus |
+The procedure is `references/dedup-and-assembly.md` Turn 4 step 1 and is followed from there, not from here. The gates are hard, and the failure mode they exist for is silently deleting real bugs — twelve agents converging on one function is *information*, not redundancy:
 
-The `subagent_type` selects a base persona and tool set; **the specialty file in the bundle is what determines the lens.** Reused types (`depth-token-flow`, `mev-analyst`, `sleuth`) run as independent instances with different bundles and share no context.
+- **Canonicalise the bug-class label** (new in v4) — one label per (Contract, function) before grouping: the repository's own label from `known-findings.md` wins, then the majority label, then the shortest label that names the defect. Without it one bug becomes three ledger records and is never recognised again.
+- **Function isolation** — never merge across `function:` values. A different function is a different bug, always.
+- **Wide description** — a merged group with distinct mechanisms lists every mechanism.
+- **Function-level second pass** — at (Contract, function) ignoring `bug_class`, every mechanism in any constituent body survives into a final finding.
+- **Fix preservation** — distinct fixes are shown verbatim as Option A, Option B, … with intuitive labels.
+- **Completeness** — every unique (Contract, function) in raw output has at least one item in the run file; print `Completeness: N unique (Contract, function) in raw, N covered in final.`
 
-PoC construction for Critical and High findings routes to `security-verifier` or `poc-writer` after Turn 4.
+Composite chains: `Chain: [A] + [B]` at `confidence = min(A, B)` when A's output feeds B's precondition and the combined impact exceeds either alone. Most audits produce zero to two.
 
 ---
 
 ## Pre-Audit Checklist
 
-- [ ] All in-scope files identified via the exclude pattern
+- [ ] All in-scope files identified with the exact `find` command in `orchestration.md` (deploy scripts in, build and dependency dirs out)
 - [ ] `xray-pre-audit` run, or an equivalent context package assembled
-- [ ] Bundle directory created; `source.md` plus twelve agent bundles built
-- [ ] Line counts printed for `source.md` and every bundle, and none is undersized
-- [ ] Context package assembled (README, known issues, design docs, prior audits)
-- [ ] `forge build --deny-warnings` passes clean
-- [ ] `forge test` passes with no failures
-- [ ] Slither baseline report generated
-- [ ] Known issues documented to avoid duplicate findings
-- [ ] Local `VERSION` checked against upstream
+- [ ] Local `VERSION` (4) checked against upstream
+- [ ] `{stamp}` computed once; `.solidity-auditor/runs/{stamp}/scope.tsv` opened with `name`, `mode`, `files`
+- [ ] Pass count and model settled in one `AskUserQuestion`; `passes_planned` written
+- [ ] Memory on → ledger validated (`#solidity-auditor-memory v1`, 6 columns) or the scan stopped
+- [ ] `source.md` built once; twelve bundles built per pass, each ending with `report-language.md` (+ `context.md`, + `known-findings.md` when present); line counts printed and none undersized
+- [ ] Foundry pre-flight run; outputs under the scan directory only
+- [ ] `.solidity-auditor/` gitignored in the audited repo (reminder printed if not)
 
 ## Post-Audit Checklist
 
-- [ ] All twelve agents returned findings
+- [ ] All twelve agents returned; any loss recorded in the pass summary line, the run-file header, and `pass_K_agents`
 - [ ] Mental-tool marker counts verified per agent
-- [ ] Findings grouped by `group_key`; function isolation respected (Gate A)
-- [ ] Wide-description gate applied to every merged group (Gate B)
-- [ ] Function-level second pass run across `bug_class` boundaries (Gate C)
-- [ ] Distinct fixes preserved verbatim as Option A/B/… (Gate D)
-- [ ] `Completeness: N / N` line printed and reconciled
-- [ ] Composite chains identified
-- [ ] Every finding run through all four judging gates in order, one pass, no revisiting
-- [ ] Confidence scored from 100 with documented deductions
+- [ ] Bug-class labels canonicalised; function isolation, wide description, second pass, fix preservation, and the completeness line applied per pass
+- [ ] Every finding run through the four judging gates in order, one pass, no revisiting
 - [ ] LEADs promoted or rejected with justification; no deployer-intent reasoning used
-- [ ] Severity assigned per the matrix in `judging.md`
-- [ ] Foundry PoC written for every Critical and High finding
-- [ ] Fix verification completed for confidence ≥ 80 findings
-- [ ] Fix pattern-check run across the rest of the codebase
-- [ ] Report ordered by severity then confidence; sub-80 findings carry no fix block
-- [ ] Agent attribution table completed
-- [ ] Bundle directory deleted
+- [ ] Every gated FINDING carries a `**Severity**` line in its run-file block
+- [ ] Every run file uses the exact `<!--F …-->` / `<!--/F-->` markers; `assemble.sh` reported no structure break
+- [ ] `full-report.md` printed word for word (20 findings or fewer) or as the counted top-3 slice (more than 20); never re-worded
+- [ ] Memory on → `memory.tsv` written atomically via `.tmp`; `mem_after` and `mem_sha` recorded
+- [ ] Annex row count equals `F`; Foundry PoC passing for every Critical and High, under `.solidity-auditor/runs/{stamp}/poc/`
+- [ ] Fix verification and codebase pattern-check completed for findings at or above 75
+- [ ] Bundle directory deleted; nothing written outside `.solidity-auditor/` except `--file-output` copies
 
 ---
 
diff --git a/skills/pashov-audit-pipeline/VERSION b/skills/pashov-audit-pipeline/VERSION
index 00750ed..b8626c4 100644
--- a/skills/pashov-audit-pipeline/VERSION
+++ b/skills/pashov-audit-pipeline/VERSION
@@ -1 +1 @@
-3
+4
diff --git a/skills/pashov-audit-pipeline/references/agent-prompts.md b/skills/pashov-audit-pipeline/references/agent-prompts.md
new file mode 100644
index 0000000..453a356
--- /dev/null
+++ b/skills/pashov-audit-pipeline/references/agent-prompts.md
@@ -0,0 +1,119 @@
+# Agent prompt templates — Turn 3a
+
+The two prompts the orchestrator gives to the 12 agents. Agents 1–9 get the
+single-specialty prompt; agents 10–12 get the gap-hunter prompt.
+
+Both are verbatim text with values substituted in. Substitute `{bundle_dir}`,
+the agent number `N`, and the bundle's real line count. Change nothing else.
+
+The orchestrator reads this file in **Turn 2**, in the same parallel message
+that reads `report-formatting.md` and `judging.md`.
+
+---
+
+## Single-specialty prompt
+
+**Turn 3a-i — Single-specialty prompt template (agents 1–9, substitute real values):**
+
+```
+You are an attacker. Your specialty, mindset, source, and output rules
+are in your bundle. Read it fully before producing findings.
+
+Read first:
+- {bundle_dir}/agent-N-bundle.md (XXXX lines) — source + SOP + specialty + shared rules.
+
+The bundle contains all in-scope source. Do NOT re-read in-scope files
+for the initial scan. Use Read/Grep only for cross-file searches or
+out-of-scope context (interfaces/, mocks/, test/, and dependency
+sources under node_modules/ or lib/ — read a base contract when the
+behaviour it inherits matters).
+
+You are READ-ONLY inside the audited repository. Never create, edit or
+delete a file there — not a Foundry PoC, not a test, not a scratch note,
+not even one you intend to delete afterwards. An audit that changes the
+code it is measuring is not an audit. Write proof-of-concept code in your
+own scratchpad, or quote it in your finding as text.
+
+What a finding looks like:
+- file, function
+- root cause — the one-sentence code-level defect
+- minimal fix — the smallest change that eliminates the defect
+- proof — concrete numbers, a trace, or quoted code
+
+Without concrete proof, it's a LEAD, not a finding. Leads are honest
+about what you couldn't verify — they're not failures, they're
+calibration. Emit them.
+
+Don't skim. Don't trust your first read. Trust your discomfort.
+
+Write every description in Simplified Technical English — the rules are
+in your bundle, in "Report language". One sentence, 25 words or fewer,
+active voice, no metaphor, and it names who acts and what they get.
+Your bug_class label, the identifiers and any code you quote are data:
+write those exactly as the source and the output rules require.
+
+Your bundle ends with "Known findings — ground already walked". Obey it:
+spend your effort on new ground, report every bug you find in full —
+the listed ones included — and reuse its bug-class labels for the same
+class of bug in the same function.
+
+Output format: see shared-rules.md inside your bundle.
+```
+
+The "Known findings" paragraph is included **only when memory is on and `known-findings.md` was appended**. On a plain scan the prompt is byte-identical to the one it has always been — a paragraph about a section that is not there would send agents hunting for it.
+
+The READ-ONLY paragraph is **unconditional** — every agent, every mode, every pass. It is here because a real scan proved it necessary: an agent built Foundry proof-of-concept files inside the audited repository and deleted them afterwards. It left the tree clean and the stored SHA honest, and it was still wrong. A later editor must not make it conditional, and must not soften it into a preference.
+
+## Gap-hunter prompt
+
+**Turn 3a-ii — Gap-hunter prompt template (agents 10–12, substitute real values):**
+
+```
+You are an attacker. Your gap-hunter specialty, mindset, source, and
+output rules are in your bundle. Read it fully before producing findings.
+
+Read first:
+- {bundle_dir}/agent-N-bundle.md (XXXX lines) — source + SOP + gap-hunter specialty + shared rules.
+
+The bundle contains all in-scope source. Do NOT re-read in-scope files
+for the initial scan. Use Read/Grep only for cross-file searches or
+out-of-scope context (interfaces/, mocks/, test/, and dependency
+sources under node_modules/ or lib/ — read a base contract when the
+behaviour it inherits matters).
+
+You are READ-ONLY inside the audited repository. Never create, edit or
+delete a file there — not a Foundry PoC, not a test, not a scratch note,
+not even one you intend to delete afterwards. An audit that changes the
+code it is measuring is not an audit. Write proof-of-concept code in your
+own scratchpad, or quote it in your finding as text.
+
+What a finding looks like:
+- file, function
+- seam — which two or three lenses combine
+- root cause — the one-sentence code-level defect that lives at the seam
+- minimal fix — the smallest change that eliminates the defect
+- proof — concrete numbers, a trace, or quoted code showing the seam
+
+Without concrete proof of the seam, it's a LEAD, not a finding.
+Leads are honest about what you couldn't verify — they're not failures,
+they're calibration. Emit them.
+
+Don't skim. Don't trust your first read. Trust your discomfort.
+
+Write every description in Simplified Technical English — the rules are
+in your bundle, in "Report language". One sentence, 25 words or fewer,
+active voice, no metaphor, and it names who acts and what they get.
+Your bug_class label, the identifiers and any code you quote are data:
+write those exactly as the source and the output rules require.
+
+Your bundle ends with "Known findings — ground already walked". Obey it:
+spend your effort on new ground, report every bug you find in full —
+the listed ones included — and reuse its bug-class labels for the same
+class of bug in the same function.
+
+Output format: see shared-rules.md inside your bundle (gap-hunter-specific
+output fields are in your specialty file).
+```
+
+The same paragraph, under the same condition as Turn 3a-i: memory on and the file appended, or the paragraph is left out.
+
diff --git a/skills/pashov-audit-pipeline/references/assemble.sh b/skills/pashov-audit-pipeline/references/assemble.sh
new file mode 100755
index 0000000..88681c5
--- /dev/null
+++ b/skills/pashov-audit-pipeline/references/assemble.sh
@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2034  # EVM Cortex: `read` lines below bind every TSV column by name so the
+#                             # field order is visible; unused names are deliberate. Upstream file otherwise intact.
+# THE ASSEMBLER. It writes the whole solidity-auditor report. SKILL.md Turn 5 runs it.
+#
+# This is the only producer of a report in this skill. The orchestrator does not compose one,
+# and must not be re-taught to: an orchestrator under context pressure is the thing that
+# failed. Every finding this scan gated is in a run file; this script prints all of them or
+# says out loud that it could not.
+#
+#   assemble.sh --dir .solidity-auditor/runs/{stamp}
+#
+# Reads ONE directory and writes {dir}/full-report.md — the complete report, banner line down
+# to the disclaimer, ready to print word for word. No model judgment runs in here.
+#
+# reads   dir/run-K.md          the run files (ticket 01 shape), one per pass, model-written
+#         dir/scope.tsv         key <TAB> value, append-only, LAST LINE PER KEY WINS
+#         dir/memory-before.tsv the pruned photocopy — its PRESENCE is not the memory flag,
+#                               scope.tsv's `mem_before` key is
+#         dir/source-names.tsv  normalised <TAB> as spelled in the source
+# writes  dir/full-report.md
+#
+# The model types the markers, so it can mistype one. The assembler CHECKS them and prints
+# the disagreement into the Scope table. A broken run file becomes a visible line in the
+# report, never a silent loss.
+#
+# Written to .part and moved into place on exit 0, so a half-report never exists.
+set -euo pipefail
+
+dir=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) dir=$2; shift 2 ;;
+    *) echo "assemble.sh: unknown argument $1" >&2; exit 2 ;;
+  esac
+done
+[ -d "$dir" ] || { echo "assemble.sh: no such directory $dir" >&2; exit 2; }
+
+out="$dir/full-report.md"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+THRESHOLD=75   # judging.md sets it. Named there and read here; never a second opinion.
+
+# ---------------------------------------------------------------- scope.tsv, last wins
+# An absent key gives an absent row. That is what keeps a plain scan's table at four rows.
+# A missing scope.tsv is every key missing at once — the same path, no special case. It must
+# not be a non-zero exit either: `set -e` would turn one absent label into no report at all.
+scope() {
+  [ -f "$dir/scope.tsv" ] || return 0
+  awk -F'\t' -v k="$1" '$1==k { v=$2 } END { print v }' "$dir/scope.tsv"
+}
+
+name=$(scope name);            [ -n "$name" ] || name='**name missing**'
+mode=$(scope mode);            [ -n "$mode" ] || mode='**Mode missing**'
+passes_planned=$(scope passes_planned)
+mem_before=$(scope mem_before)
+mem_after=$(scope mem_after)
+mem_sha=$(scope mem_sha)
+
+memory_on=0; [ -n "$mem_before" ] && memory_on=1
+if [ "$memory_on" = 1 ] && [ ! -f "$dir/memory-before.tsv" ]; then
+  echo "assemble.sh: memory is on but $dir/memory-before.tsv is missing — Turn 5 did not copy it" >&2
+  memory_on=0
+fi
+
+# run files in PASS order. A plain glob puts run-10 before run-2, which is a real 10-pass bug.
+runs=()
+while IFS= read -r f; do runs+=("$f"); done < <(
+  ls "$dir"/run-*.md 2>/dev/null | sed 's/.*run-\([0-9]*\)\.md/\1 &/' | sort -n | cut -d' ' -f2)
+N=${#runs[@]}
+
+# ---------------------------------------------------------------- index every block
+# key conf kind agents file pass start end bodystart bodyend title loc leadbody
+#
+# A FINDING and a LEAD are NOT the same shape on disk, and one geometry read over both is what
+# produced `- **- **Title**` rows and a "Body missing" line under leads that had a body:
+#
+#   FINDING            LEAD
+#   +0  <!--F ...-->   +0  <!--F ...-->
+#   +1                 +1
+#   +2  [95] **1. T**  +2  - **T** — `loc` · TAG — smells — why not verified
+#   +3                 +3
+#   +4  `loc` · Conf   +4  <!--/F-->
+#   +5
+#   +6  body …
+#
+# Read with the finding geometry, a lead put its WHOLE formatted line in `title` (which the
+# emitter then wrapped in `- **…**` a second time), found no backticks at +4 so `loc` came out
+# empty, and had no body region at all. Each kind now gets its own reader.
+#
+# **No field is ever emitted empty** — `-` stands in. `read` below splits on IFS=$'\t', and a
+# tab is IFS *whitespace*, so bash collapses `\t\t` into one delimiter and every later field
+# shifts left by one. That is how a lead's memory tag ended up printed as its location.
+: > "$work/index.tsv"
+for f in ${runs[@]+"${runs[@]}"}; do
+  awk -v F="$f" '
+    /^<!--RUN / { line=$0; sub(/[[:space:]]*-->[[:space:]]*$/, "", line)
+                  n=split(line, a, /[[:space:]]+/)
+                  for (i=2; i<=n; i++) { eq=index(a[i],"="); if (substr(a[i],1,eq-1)=="pass") pass=substr(a[i],eq+1) } }
+    /^<!--F / {
+      key=""; conf=""; kind=""; agents=""
+      line = $0
+      sub(/[[:space:]]*-->[[:space:]]*$/, "", line)   # terminator off BEFORE splitting
+      n = split(line, a, /[[:space:]]+/)
+      for (i = 2; i <= n; i++) {
+        eq = index(a[i], "="); nm = substr(a[i], 1, eq-1); v = substr(a[i], eq+1)
+        if (nm == "key") key = v; else if (nm == "conf") conf = v
+        else if (nm == "kind") kind = v; else if (nm == "agents") agents = v
+      }
+      if (conf == "") conf = "-"        # a LEAD is not scored
+      start = NR; title = ""; loc = ""; lbody = ""
+      next
+    }
+    kind != "LEAD" && start && NR == start + 2 { t = $0; sub(/^\[[0-9]+\] /, "", t); sub(/^\*\*/, "", t); sub(/\*\*$/, "", t); title = t }
+    kind != "LEAD" && start && NR == start + 4 { l = $0; if (match(l, /`[^`]*`/)) loc = substr(l, RSTART+1, RLENGTH-2) }
+
+    # A lead is one line. Split it here, once, so the emitter formats leads and findings with
+    # the same fields instead of re-printing a line that is already formatted.
+    # `match` + RSTART/RLENGTH, never index()+a literal width: the separator is an em dash,
+    # 3 bytes and 1 character, and the two disagree across awks and locales.
+    kind == "LEAD" && start && NR == start + 2 && /^- \*\*/ {
+      l = $0
+      sub(/^- \*\*/, "", l)
+      if (match(l, /\*\* — /)) { title = substr(l, 1, RSTART-1); l = substr(l, RSTART+RLENGTH) }
+      else                     { title = l; l = "" }
+      if (match(l, /^`[^`]*`/)) { loc = substr(l, RSTART+1, RLENGTH-2); l = substr(l, RSTART+RLENGTH) }
+      # What is left is " · NEW — body" or " — body". Either way the body starts after the
+      # first " — ". The inline tag is DROPPED: the assembler derives the memory tag itself
+      # from memory-before.tsv, and two sources for one fact is how they come to disagree.
+      if (match(l, / — /)) l = substr(l, RSTART+RLENGTH); else l = ""
+      lbody = l
+    }
+    /^<!--\/F-->/ && start {
+      if (title == "") title = "-"
+      if (loc   == "") loc   = "-"
+      if (lbody == "") lbody = "-"
+      print key "\t" conf "\t" kind "\t" agents "\t" F "\t" pass "\t" start "\t" NR "\t" (start+6) "\t" (NR-1) "\t" title "\t" loc "\t" lbody
+      start = 0; kind = ""
+    }
+  ' "$f" >> "$work/index.tsv"
+done
+
+# ---------------------------------------------------------------- the structure check
+# The model typed these markers. When the counts disagree, a finding was raised and cannot be
+# read — say so IN the report. The report may print less than the scan found; it may never
+# claim to print more.
+#
+# No run file at all is the same rule at its limit: pass 1 produced nothing, so the scan
+# reviewed nothing. That is a REPORT, not an exit — SKILL.md Turn 3b routes a real scan down
+# here, and a shell error in place of a report is the one outcome this skill must never have.
+# The row is necessary because the Passes row is suppressed on a 1-pass scan, so without it
+# nothing in the report would say the pass died.
+broken=
+if [ "$N" = 0 ]; then
+  broken="⚠️ No pass produced a run file. This scan reviewed nothing."
+  echo "assemble.sh: NO RUN FILES — $broken" >&2
+else
+  opens=$(cat "${runs[@]}" | grep -c '^<!--F ' || :)
+  closes=$(cat "${runs[@]}" | grep -c '^<!--/F-->' || :)
+  indexed=$(wc -l < "$work/index.tsv" | tr -d ' ')
+  if [ "$opens" != "$closes" ] || [ "$opens" != "$indexed" ]; then
+    broken="⚠️ $opens findings marked, $indexed readable. $(( opens - indexed )) could not be read and are missing below. See the run files."
+    echo "assemble.sh: STRUCTURE BROKEN — $broken" >&2
+  fi
+fi
+
+# ---------------------------------------------------------------- dedup across runs
+# 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.
+# k counts every run that raised the key, in either section.
+sort -t $'\t' -k1,1 "$work/index.tsv" | awk -F'\t' '
+  function rank(k) { return (k == "FINDING") ? 1 : 0 }
+  {
+    if (!(($5 SUBSEP $1) in seenrun)) { seenrun[$5 SUBSEP $1]=1; k[$1]++ }
+    c = ($2 == "-") ? -1 : $2 + 0
+    if (!($1 in best) || rank($3) > br[$1] || (rank($3) == br[$1] && c > bc[$1]) \
+        || (rank($3) == br[$1] && c == bc[$1] && $6 + 0 >= bp[$1])) {
+      best[$1] = $0; br[$1] = rank($3); bc[$1] = c; bp[$1] = $6 + 0
+    }
+  }
+  END { for (key in best) print k[key] "\t" best[key] }
+' > "$work/merged.tsv"
+
+# ---------------------------------------------------------------- the memory tag
+# Derived here from memory-before.tsv, not carried in the marker. One source: the report and
+# the ledger cannot disagree because both read the same photocopy.
+#   KNOWN (n scans) — the STORED count plus one; this scan has just found it again.
+if [ "$memory_on" = 1 ]; then
+  awk -F'\t' -v OFS='\t' '
+    FILENAME==ARGV[1] { if (FNR>1) sc[$1]=$3; next }
+    { print $0, ($2 in sc) ? "KNOWN (" sc[$2]+1 " scans)" : "NEW" }
+  ' "$dir/memory-before.tsv" "$work/merged.tsv" > "$work/merged.tagged.tsv"
+else
+  awk -F'\t' -v OFS='\t' '{ print $0, "" }' "$work/merged.tsv" > "$work/merged.tagged.tsv"
+fi
+
+# columns now: 1 k · 2 key · 3 conf · 4 kind · 5 agents · 6 file · 7 pass · 8 start · 9 end
+#              10 bodystart · 11 bodyend · 12 title · 13 loc · 14 leadbody · 15 memtag
+# 12, 13 and 14 are never empty — `-` stands in, because IFS=$'\t' collapses adjacent tabs.
+sort -t $'\t' -k4,4 -k3,3nr -k2,2 "$work/merged.tagged.tsv" > "$work/sorted.tsv"
+awk -F'\t' '$4=="FINDING"' "$work/sorted.tsv" > "$work/findings.tsv"
+awk -F'\t' '$4=="LEAD"'    "$work/sorted.tsv" > "$work/leads.tsv"
+
+nfind=$(wc -l < "$work/findings.tsv" | tr -d ' ')
+nlead=$(wc -l < "$work/leads.tsv" | tr -d ' ')
+
+# ---------------------------------------------------------------- emit
+R="$work/report.md"
+: > "$R"
+say() { printf '%s\n' "$1" >> "$R"; }
+rule() { say ""; say "---"; say ""; }
+row() { printf '| %s | %s |\n' "$1" "$2" >> "$R"; }
+
+say "# 🔐 Security Review — $name"
+rule
+say "## Scope"
+say ""
+row "" ""
+row "---" "---"
+row "**Mode**" "$mode"
+
+# Files reviewed — 3 per line, in source.md order, joined with `<br>`. One `files` key holds
+# them space separated; shell does the wrapping.
+files=$(scope files | tr ' ' '\n' | awk 'NF { printf "`%s`", $0; if (++n % 3 == 0) printf "<br>"; else printf " · " }' \
+        | sed -e 's/ · $//' -e 's/<br>$//')
+row "**Files reviewed**" "$files"
+row "**Confidence threshold (1-100)**" "$THRESHOLD"
+
+# The Passes cell is COMPOSED from facts, never written as prose by a model.
+if [ -n "$passes_planned" ] && [ "$passes_planned" -gt 1 ] 2>/dev/null; then
+  short=""
+  for k in $(seq 1 "$passes_planned"); do
+    a=$(scope "pass_${k}_agents"); fail=$(scope "pass_${k}_failed")
+    if [ -n "$fail" ]; then short="${short:+$short, }pass $k failed"
+    elif [ -n "$a" ] && [ "$a" != "12/12" ]; then short="${short:+$short, }pass $k ran $a agents"; fi
+  done
+  if [ "$N" -lt "$passes_planned" ]; then cell="$N of $passes_planned"; else cell="$passes_planned"; fi
+  [ -n "$short" ] && cell="$cell ($short)"
+  row "**Passes**" "$cell"
+fi
+[ "$memory_on" = 1 ] && row "**Memory**" "$mem_before records before this scan · $mem_after after · \`$mem_sha\`"
+[ -n "$broken" ] && row "**Run files**" "$broken"
+rule
+
+say "## Findings"
+say ""
+
+emit_body() {  # file bodystart bodyend  — copied through, never re-worded
+  awk -v s="$2" -v e="$3" 'NR>=s && NR<=e' "$1" \
+    | awk '{ lines[++n] = $0 } END {
+        b=1; while (b<=n && lines[b]=="") b++
+        while (n>=b && lines[n]=="") n--
+        for (i=b; i<=n; i++) print lines[i] }'
+}
+
+i=0
+while IFS=$'\t' read -r k key conf kind agents file pass start end bstart bend title loc lbody memtag; do
+  i=$((i+1))
+  [ "$title" = "-" ] && title="**Title missing** — the block's title line could not be read"
+  if [ "$loc" = "-" ]; then meta="**location missing**"; else meta="\`$loc\`"; fi
+  say "[$conf] **$i. $title**"
+  say ""
+  meta="$meta · Confidence: $conf"
+  [ "$N" -gt 1 ] && meta="$meta · seen in $k/$N runs"
+  [ -n "$memtag" ] && meta="$meta · $memtag"
+  say "$meta"
+  say ""
+  body=$(emit_body "$file" "$bstart" "$bend")
+  if [ -z "$body" ]; then
+    say "**Body missing** — pass $pass raised this finding and wrote no description."
+  else
+    printf '%s\n' "$body" >> "$R"
+  fi
+  rule
+done < "$work/findings.tsv"
+
+if [ "$nfind" = 0 ]; then
+  # An empty table with a header row and no rows under it is not a report of nothing, it is a
+  # report that looks broken. Say it in words instead.
+  say "_None — this scan raised no findings._"
+  rule
+else
+say "Findings List"
+say ""
+say "| # | Confidence | Title |"
+say "|---|---|---|"
+i=0; sep=0
+while IFS=$'\t' read -r k key conf kind agents file pass start end bstart bend title loc lbody memtag; do
+  i=$((i+1))
+  if [ "$sep" = 0 ] && [ "$conf" -lt "$THRESHOLD" ]; then
+    say "| | | **Below Confidence Threshold** |"; sep=1
+  fi
+  say "| $i | [$conf] | $title |"
+done < "$work/findings.tsv"
+rule
+fi
+
+say "## Leads"
+say ""
+say "_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._"
+say ""
+[ "$nlead" = 0 ] && say "_None._"
+while IFS=$'\t' read -r k key conf kind agents file pass start end bstart bend title loc lbody memtag; do
+  seg=""
+  [ "$N" -gt 1 ] && seg="$seg · seen in $k/$N runs"
+  [ -n "$memtag" ] && seg="$seg · $memtag"
+  # The body was parsed out of the lead's own line by the indexer. Do NOT read it back out of
+  # the run file here: a lead has no body region, so emit_body returned nothing and every lead
+  # got the "Body missing" line whether or not it had one.
+  [ "$title" = "-" ] && title="**Title missing** — the lead's line could not be read"
+  if [ "$loc" = "-" ]; then locmd="**location missing**"; else locmd="\`$loc\`"; fi
+  [ "$lbody" = "-" ] && lbody="**Body missing** — pass $pass raised this lead and wrote no description."
+  say "- **$title** — $locmd$seg — $lbody"
+done < "$work/leads.tsv"
+
+# ---------------------------------------------------------------- Known from earlier scans
+# The keys this scan raised come from the index — the run files are the record, so no separate
+# run-keys.tsv or scan-rows.tsv has to be carried in.
+if [ "$memory_on" = 1 ]; then
+  held=$(( $(wc -l < "$dir/memory-before.tsv") - 1 ))
+  if [ "$held" -gt 0 ]; then
+    tail -n +2 "$dir/memory-before.tsv" | cut -f1 | sort -u > "$work/keys-before.txt"
+    cut -f1 "$work/index.tsv" | sort -u > "$work/keys-scan.txt"
+    comm -23 "$work/keys-before.txt" "$work/keys-scan.txt" > "$work/keys-left.txt"
+    rule
+    say "## Known from earlier scans"
+    say ""
+    say "_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. \`.solidity-auditor/memory.tsv\`._"
+    say ""
+    if [ -s "$work/keys-left.txt" ]; then
+      say "| Scans | Kind | Location | Title |"
+      say "|---|---|---|---|"
+      awk -F'\t' '
+        FILENAME==ARGV[1] { nm[$1]=$2; next }
+        FILENAME==ARGV[2] { if (FNR>1) { sc[$1]=$3; ti[$1]=$5; ki[$1]=$6 } ; next }
+        {
+          split($1, p, "|")
+          c = (p[1] in nm) ? nm[p[1]] : p[1]      # print-as-stored when the segment is not in the map
+          f = (p[2] in nm) ? nm[p[2]] : p[2]
+          print "| " sc[$1] " | " ki[$1] " | `" c "." f "` | " ti[$1] " |"
+        }
+      ' "$dir/source-names.tsv" "$dir/memory-before.tsv" "$work/keys-left.txt" >> "$R"
+    else
+      say "_None — every record in the ledger was raised again by this scan._"
+    fi
+  fi
+fi
+
+rule
+say "> ⚠️ 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 onchain monitoring are strongly recommended. For a consultation regarding your projects' security, visit [https://www.pashov.com](https://www.pashov.com)"
+
+cp "$R" "$out.part"
+mv "$out.part" "$out"
+echo "assembled $out — $nfind findings, $nlead leads, $N run files"
diff --git a/skills/pashov-audit-pipeline/references/dedup-and-assembly.md b/skills/pashov-audit-pipeline/references/dedup-and-assembly.md
new file mode 100644
index 0000000..8bab8b2
--- /dev/null
+++ b/skills/pashov-audit-pipeline/references/dedup-and-assembly.md
@@ -0,0 +1,419 @@
+# 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 `.solidity-auditor/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 — solidity-auditor
+
+   <!--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.
+   - **`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" >> .solidity-auditor/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 `.solidity-auditor/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 "#solidity-auditor-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 > .solidity-auditor/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 .solidity-auditor/memory.tsv.tmp .solidity-auditor/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 .solidity-auditor` before the first write. The user is expected to gitignore that directory; the ledger 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 < .solidity-auditor/memory.tsv) - 1 ))" \
+     >> .solidity-auditor/runs/{stamp}/scope.tsv
+   printf '%s\t%s\n' mem_sha "$(git rev-parse --short HEAD 2>/dev/null || echo none)" \
+     >> .solidity-auditor/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 `.solidity-auditor/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 .solidity-auditor/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 .solidity-auditor/runs/{stamp}
+   ```
+
+   It writes `.solidity-auditor/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 }
+   ' .solidity-auditor/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}`** — `.solidity-auditor/runs/{stamp}/full-report.md`, or, when `--file-output` was passed, the **copy** and only the copy: `{project-name}-pashov-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
+   }
+   ' .solidity-auditor/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 .solidity-auditor/runs/{stamp}/full-report.md "{project-name}-pashov-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 `.solidity-auditor/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 `.audit-*` 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.
+
diff --git a/skills/pashov-audit-pipeline/references/hacking-agents/shared-rules.md b/skills/pashov-audit-pipeline/references/hacking-agents/shared-rules.md
index 237db6f..55a1aff 100644
--- a/skills/pashov-audit-pipeline/references/hacking-agents/shared-rules.md
+++ b/skills/pashov-audit-pipeline/references/hacking-agents/shared-rules.md
@@ -2,7 +2,7 @@
 
 ## Bundle contents
 
-Your bundle is four concatenated files: all in-scope source code, the SOP (HOW to think), your specialty agent (WHAT to look for), and these shared rules (output format, dedup tags, AND mandatory mental tool protocol).
+Your bundle is five concatenated files: all in-scope source code, the SOP (HOW to think), your specialty agent (WHAT to look for), these shared rules (output format, dedup tags, AND mandatory mental tool protocol), and the report language rules (HOW to word a finding).
 
 Read the whole bundle once at the start. The bundle contains all in-scope source. Use Read/Grep only for cross-file searches or out-of-scope context (interfaces/, lib/, mocks/, test/) — do not re-read in-scope files for the initial scan.
 
@@ -64,3 +64,21 @@ description: one sentence explaining trail and what remains unverified
 ```
 
 The `group_key` enables deduplication: `ContractName | functionName | bug_class`. Agents may add custom fields.
+
+## Language — MANDATORY
+
+**Your `description:` and your `fix:` sentence are written in Simplified Technical English.** The
+rules follow these ones in your bundle, under the heading "Report language". Read them, and
+obey them in every finding and every lead you emit.
+
+Your `description:` is what the report prints. Nothing downstream rewrites it into plain
+English for you — the orchestrator pastes it into the report and the report goes to the
+developer who must fix the code. One sentence, twenty-five words or fewer, active voice, no
+`-ing` clause, no metaphor. Name who acts and what they get.
+
+The rule reaches the wording and never the data. Your `bug_class` label, your `group_key`, the
+contract and function names, and every line of code you quote are written exactly as the
+source and the dedup rules require. `report-language.md` says which is which.
+
+Your `path:` and `proof:` fields are working notes, not report text. Keep them concrete;
+concrete is already plain.
diff --git a/skills/pashov-audit-pipeline/references/judging.md b/skills/pashov-audit-pipeline/references/judging.md
index 310ef40..ed3e91c 100644
--- a/skills/pashov-audit-pipeline/references/judging.md
+++ b/skills/pashov-audit-pipeline/references/judging.md
@@ -44,7 +44,9 @@ Prove material harm to an identifiable victim.
 
 ## Confidence
 
-Start at **100**, deduct: partial attack path **-20**, bounded non-compounding impact **-15**, requires specific (but achievable) state **-10**. Confidence ≥ 80 gets description + fix. Below 80 gets description only.
+Start at **100**, deduct: partial attack path **-20**, bounded non-compounding impact **-15**, requires specific (but achievable) state **-10**. Confidence ≥ 75 gets description + fix. Below 75 gets description only.
+
+**The threshold is 75, and it is set here.** `report-formatting.md` reads it from this line and states it nowhere else. It is 75 and not 80 because the three lead-promotion rules below all land a promoted lead at exactly 75: at a threshold of 80 every cross-contract echo, every multi-agent convergence and every completed partial path would be promoted to a finding and then printed with no **Fix** block. Moving this number means moving those three, or the promotions stop being worth making.
 
 ## Safe patterns (do not flag)
 
@@ -62,7 +64,7 @@ Before finalizing leads, promote where warranted:
 
 - **Cross-contract echo.** Same root cause confirmed as FINDING in one contract → promote in every contract where the identical pattern appears.
 - **Multi-agent convergence.** 2+ agents flagged same area, lead was demoted (not rejected) → promote to FINDING at confidence 75.
-- **Partial-path completion.** Only weakness is incomplete trace but path is reachable and unguarded → promote to FINDING at confidence 75, description only.
+- **Partial-path completion.** Only weakness is incomplete trace but path is reachable and unguarded → promote to FINDING at confidence 75, **description only — a deliberate exception to the threshold**. 75 clears the line, so this finding would otherwise carry a **Fix** block; it does not, because the trace it would fix was never completed. The other two promotions above take their **Fix** block normally.
 
 ## Leads
 
@@ -101,7 +103,7 @@ Note the interaction with Gate 3: an admin-action finding that clears only via a
 
 Route PoC construction to `security-verifier` or `poc-writer`. Pin the fork block number in every fork-based PoC so it stays reproducible.
 
-### Fix verification (confidence ≥ 80)
+### Fix verification (confidence ≥ 75)
 
 Trace the proposed fix against the original attack path and confirm the path terminates, then check for side effects:
 
diff --git a/skills/pashov-audit-pipeline/references/orchestration.md b/skills/pashov-audit-pipeline/references/orchestration.md
new file mode 100644
index 0000000..454d07f
--- /dev/null
+++ b/skills/pashov-audit-pipeline/references/orchestration.md
@@ -0,0 +1,462 @@
+---
+name: solidity-auditor
+description: Security audit of Solidity code while you develop. Trigger on "audit", "check this contract", "review for security", "loop mode", "run the auditor in loop mode", "run 3 passes". Modes - default (full repo) or a specific filename. Loop mode runs several passes in one scan, each pass told what the earlier ones found, and ends in one combined report; it remembers findings between scans in a ledger.
+---
+
+# Smart Contract Security Audit
+
+You are the orchestrator of a parallelized smart contract security audit.
+
+## Mode Selection
+
+**Exclude pattern:** skip **dependency and build directories** — `node_modules/`, `lib/`, `artifacts/`, `cache/`, `out/`, `broadcast/`, `coverage/`, `typechain*/` — and **non-production code** — `interfaces/`, `mocks/`, `test/` and files matching `*.t.sol`, `*Test*.sol` or `*Mock*.sol`.
+
+**Deploy scripts stay in scope.** `script/`, `deploy/` and `*.s.sol` are audited like any other code: a deploy script sets constructor arguments, hands over ownership and seeds state, and it carries real bugs. Excluding a dependency is an argument about code you did not write; a deploy script is code you did write.
+
+- **Default** (no arguments): scan all `.sol` files using the exclude pattern. Use Bash `find` (not Glob), exactly this command:
+
+  ```bash
+  find . -type f -name '*.sol' \
+    -not -path '*/node_modules/*' -not -path '*/lib/*' -not -path '*/artifacts/*' \
+    -not -path '*/cache/*' -not -path '*/out/*' -not -path '*/broadcast/*' \
+    -not -path '*/coverage/*' -not -path '*/typechain*/*' \
+    -not -path '*/interfaces/*' -not -path '*/mocks/*' -not -path '*/test/*' \
+    -not -name '*.t.sol' -not -name '*Test*.sol' -not -name '*Mock*.sol'
+  ```
+
+  `-type f` is **required, not tidiness**: Hardhat writes each build artifact into a *directory* named `GatewayCrossChain.sol/`, so a `find` without it matches directories as if they were source files and hands them to `cat`. Do not drop it, and do not re-derive this command — paste it.
+
+- **`$filename ...`**: scan the specified file(s) only. **The exclude pattern does not apply here.** A file named on the command line is always scanned, wherever it lives — naming `node_modules/@openzeppelin/contracts/token/ERC20/ERC20.sol` scans that file. The pattern chooses what a *default* scan discovers; it never overrides an explicit request.
+
+**Flags:**
+
+- `--file-output` (off by default): **copy** the assembled report into the working directory (name per `{resolved_path}/report-formatting.md`). The flag never causes a report to be produced — every scan assembles `.solidity-auditor/runs/{stamp}/full-report.md` whether it is passed or not. It only decides whether a copy lands where the runner can see it.
+
+  > **Line 33 used to read "Never write a report file unless explicitly passed", and that is now false.** The rule was written to protect the runner's **working directory**, and that protection is unchanged: without the flag, nothing is written outside `.solidity-auditor/`. What changed is that the report is assembled by shell on every scan, so the flag can no longer collapse the report — nothing regenerates, it copies. A later editor must not read this as a mistake and revert it.
+
+- `--memory` (off by default): remember findings between scans in a ledger at `.solidity-auditor/memory.tsv` in the audited repo. Any pass count above 1 turns memory on by itself, whether or not the flag was passed.
+- `--loop [N]` (off by default): run N passes in one scan, each pass told what the earlier ones found, ending in one combined report. `--loop` with no number is **3** passes. `--loop 1` is a 1-pass scan. The flag exists for runners who prefer flags; when it is passed the picker in Turn 1b does not ask, it obeys.
+
+**Vocabulary (used throughout this file):**
+
+- **run** — one pass of the 12 agents.
+- **scan** — one invocation of this skill. A scan holds 1 or more runs.
+
+The ledger's `scans` column counts scans. The report's `seen in k/N runs` counts runs inside one scan and is never written to the ledger. Two numbers, two names — do not mix them.
+
+The pass count the scan runs is `{passes}` — settled in Turn 1b, 1 or more. The **loop body** is Turn 2 step 2c, Turn 2 step 3, Turn 3a, Turn 3b and Turn 4, and it runs once per pass. Everything before it runs once per scan, and Turn 5 closes the scan once, whatever `{passes}` is.
+
+> **HARD RULE — the plain path must stay plain.** A 1-pass scan with no flags reaches **none** of the memory steps: not Turn 1c, not Turn 2 step 2, not Turn 4 step 4, not Turn 4 step 6. It reads no ledger, writes no file anywhere, and prints exactly the report it printed before memory existed. Memory is on only when `--memory` was passed or the pass count is above 1. A later editor who is tempted to make any memory step unconditional is breaking this on purpose, not tidying up.
+
+> **A 1-pass answer reaches none of the loop or memory machinery.** No ledger is read or written. No `Passes` or `Memory` row in the Scope table. No `seen in k/N runs`. No `KNOWN` / `NEW` tag. No per-pass summary lines. **The printed report is the report this skill printed before loop mode existed.** The only trace of the picker is the question itself.
+>
+> **What it does write.** Every scan writes `.solidity-auditor/runs/{stamp}/` — one `run-1.md`, one `scope.tsv`, one `full-report.md` — because the report is assembled from those files at every pass count, and `name`, `mode`, `files` and `threshold` are needed by every report. This paragraph used to say a 1-pass answer creates no `.solidity-auditor/` directory and no `runs/` files; that is now false, and it was never what the rule was protecting.
+>
+> **What the rule protects, stated exactly:** on the plain path the scan reads no ledger, writes no `mem_` key, and prints a Scope table of exactly **three** rows — `Mode`, `Files reviewed`, `Confidence threshold (1-100)` — and no `Passes` row, no `Memory` row. Disk is not printed output. A later editor who makes a **memory** step unconditional is breaking this on purpose; writing the runs directory is not one of those steps.
+>
+> `--memory` on a 1-pass run is the single exception: memory turns on, the loop machinery stays off.
+
+## Orchestration
+
+**Turn 1 — Discover.** Print the banner, then make these parallel tool calls in one message:
+
+a. Bash `find` for in-scope `.sol` files per mode selection
+b. Glob for `**/references/hacking-agents/shared-rules.md` — extract the `references/` directory (two levels up) as `{resolved_path}`
+c. ToolSearch `select:Agent`
+d. Read the local `VERSION` file from the same directory as this skill
+e. Bash `curl -sf https://raw.githubusercontent.com/pashov/skills/main/solidity-auditor/VERSION`
+f. Bash `mktemp -d ./.audit-XXXXXX` → store as `{bundle_dir}`
+g. Bash `date +%Y%m%d-%H%M%S` → store as `{stamp}`, the scan-time stamp. **One stamp per scan, computed once, here.** The runs directory, the run files and any `--file-output` copy all carry it, so a report and the runs that produced it are tied together by eye.
+
+**Turn 1a — Open the scan directory.** After the `find` returns, in one Bash command:
+
+```bash
+mkdir -p .solidity-auditor/runs/{stamp}
+: > .solidity-auditor/runs/{stamp}/scope.tsv
+```
+
+Then write the three scope keys this turn knows. **A scope key is written with one `printf` and never any other way:**
+
+```bash
+printf '%s\t%s\n' name  "{project-name}" >> .solidity-auditor/runs/{stamp}/scope.tsv
+printf '%s\t%s\n' mode  "{mode}"         >> .solidity-auditor/runs/{stamp}/scope.tsv
+printf '%s\t%s\n' files "{file list}"    >> .solidity-auditor/runs/{stamp}/scope.tsv
+```
+
+- `{project-name}` — the repo root basename, the same one `report-formatting.md` names.
+- `{mode}` — `default` or `filename`, as Mode Selection settled it.
+- `{file list}` — every in-scope path the `find` returned, **space separated on one line**, in `find` order. The assembler wraps them 3 per row; the order it prints is the order written here.
+
+> **`scope.tsv` is `key<TAB>value`, append-only, last line per key wins.** An absent key gives an absent table row — that is what keeps the plain scan's Scope table at three rows with no special case. A tab or a newline in a value breaks the row, so values are **stripped**, not escaped: no key here has any use for either character. Six writers across four turns append to this one file, and none of them ever rewrites or deletes a line.
+>
+> `name` and `mode` are the **only two keys a model types**. Everything else is either shell knowledge or read by the assembler for itself: the threshold from the constant, `N` in `seen in k/N runs` from counting run files, the stamp from the directory's own name.
+
+If the remote VERSION fetch succeeds, compare the two as **numbers** and warn **only when the local one is lower**: print `⚠️ You are not using the latest version. Please upgrade for best security coverage. See https://github.com/pashov/skills`. If it fails, skip silently.
+
+> **Lower, not different.** A plain "differs" test warns the wrong person: somebody working on an unreleased version has a local `VERSION` **above** the published one, and gets told to upgrade to the version they are writing. Local equal to remote, or local above it, prints nothing.
+
+**Turn 1b — Model and pass count.** This turn asks **two questions in one `AskUserQuestion` call**: which model the 12 agents use, and how many passes the scan runs. The runner is interrupted once, before any work starts.
+
+> **The two questions do not fail the same way.** On a runtime without `AskUserQuestion` and an `Agent` tool that takes a `model` parameter — Codex, Gemini, Cursor's native agent — the **model** question is skipped silently, `{agent_model}` is left unset, and no prose replaces it. The **pass** question is not skipped: it falls through to the printed block in Turn 1b-ii, which stops and waits. This turn as a whole is never skipped. A later editor must not restore a blanket "SKIP this turn entirely" rule: it was true when this turn asked one question, and it is false now.
+
+**Turn 1b-i — the `AskUserQuestion` call (Claude Code).** Ask both questions in one call. Where the `Agent` tool takes no `model` parameter, ask the pass question alone.
+
+Question 1 — model:
+
+1. Read your system prompt to detect your own model **family** (Opus, Sonnet, or Haiku). Ignore the version digits — the Agent tool's `model` parameter takes the family name (`"opus"` / `"sonnet"` / `"haiku"`), and the runtime resolves to the latest version in that family.
+2. Put this question in the call:
+   - Question: `"Which Claude model should the 12 audit agents use?"`
+   - Three single-select options. Mark the orchestrator's own family as `(Recommended)` and place it first.
+   - On each option, set the `description` field to `latest`.
+   - On each option, set the `preview` field verbatim (preserve all whitespace exactly — the box widths must stay equal across all three):
+
+   Opus preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  opus  ·  highest reasoning  ·  most expensive           │
+   └──────────────────────────────────────────────────────────┘
+   ```
+
+   Sonnet preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  sonnet  ·  balanced reasoning  ·  mid cost              │
+   └──────────────────────────────────────────────────────────┘
+   ```
+
+   Haiku preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  haiku  ·  lowest reasoning  ·  cheapest                 │
+   └──────────────────────────────────────────────────────────┘
+   ```
+3. Store the runner's choice as `{agent_model}`. If no answer, default to the orchestrator's own model.
+
+Question 2 — pass count. It goes in the **same call**, second:
+
+4. Question: `"How many passes should this audit run? Each pass is a full 12-agent audit, and every pass after the first is told what the earlier ones found, so it hunts new ground. You get one combined report at the end."`
+
+   Three single-select options, `3 passes` first and marked `(Recommended)`. Each carries a `preview` box in this turn's style — the boxes are **60 characters wide, equal to the model picker's**, so two questions in one prompt look like one thing. Set `preview` verbatim, whitespace preserved:
+
+   | Label | `description` |
+   | --- | --- |
+   | `3 passes (Recommended)` | `~45 min` |
+   | `1 pass` | `~15 min` |
+   | `5 passes` | `~75 min` |
+
+   3 passes preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  3 passes  ·  each pass hunts new ground  ·  ~45 min     │
+   └──────────────────────────────────────────────────────────┘
+   ```
+
+   1 pass preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  1 pass  ·  today's audit  ·  ~15 min, nothing written   │
+   └──────────────────────────────────────────────────────────┘
+   ```
+
+   5 passes preview:
+
+   ```
+   ┌──────────────────────────────────────────────────────────┐
+   │  5 passes  ·  deepest sweep  ·  ~75 min                  │
+   └──────────────────────────────────────────────────────────┘
+   ```
+
+   > **These are measured, not guessed — and they are a floor.** A real 3-pass scan of 2,228
+   > lines of Solidity across 10 files, 12 agents per pass on Opus, took **43 minutes** wall
+   > clock: 11 minutes for pass 1 and about 16 for each of passes 2 and 3, which run slower
+   > because the growing `known-findings.md` is appended to all twelve bundles. Individual
+   > agents ran 3.5–11 minutes. A larger codebase takes longer; a smaller model is faster.
+   > Quote minutes rather than multipliers — "~3x time" told the runner nothing about whether
+   > to wait or come back after lunch. If these numbers are ever re-measured, correct them
+   > here rather than adding a second estimate somewhere else.
+
+5. **Any other number needs no option of its own.** `AskUserQuestion` always adds an **Other** choice with a free-text box, and the runner types their number there. Do NOT add a fourth option reading "your own number" — options are fixed choices, so it could not collect the number and would dead-end.
+
+   Parse the Other answer for the first integer. Below 1 or above 10 → ask once more. A second unusable answer → **1 pass**.
+
+6. Store the answer as `{passes}`. No answer at all → 1 pass.
+
+**Turn 1b-ii — the printed fallback (every runtime without `AskUserQuestion`).** Print this exactly:
+
+```
+How many passes should this audit run?
+
+Each pass is a full 12-agent audit. Every pass after the first is told what the
+earlier passes found, so it hunts new ground. You get one combined report at the end.
+
+  1) 1 pass    — today's audit, about 15 minutes. Nothing is written to disk.
+  2) 3 passes  — recommended. About 45 minutes.
+  3) 5 passes  — deepest sweep. About 75 minutes.
+
+Answer with 1, 2, 3, or any pass count you want.
+```
+
+> **STOP here and wait for the runner's answer.** Do NOT choose for them. Do NOT continue to Turn 2 with an assumed pass count. Do NOT start the scan and ask later.
+>
+> This is the one place in this skill where a question is emitted as prose. Turn 1b forbids prose questions because the model picker has a safe default — the orchestrator's own model. A pass count has no safe default: 1 and 5 differ by 5x in time and in cost, and that is the runner's money. A later editor must not "fix" this by deleting the prose block or by picking a default. If you are reading this and it looks like an inconsistency, it is deliberate.
+
+Answers `1`, `2` and `3` are the three listed choices; any other integer is that many passes. Apply the same bounds as Turn 1b-i step 5 — below 1 or above 10, ask once more, then 1 pass.
+
+**Turn 1b-iii — when the runner already said.** Ask nothing that has already been answered:
+
+| What arrived | What the picker does |
+| --- | --- |
+| `--loop 5` | Skip the pass question, silently. 5 passes. |
+| `--loop` with no number | Skip the pass question, silently. 3 passes. |
+| "run 4 passes", "audit this four times" | Skip the pass question, silently. 4 passes. |
+| "loop mode", "run it a few times" — a request with no number | **Ask.** They asked for the feature, not for a count. |
+| Nothing | Ask. |
+
+Skipping is silent in the first three rows — printing `using 5 passes` back at somebody who just typed `--loop 5` is noise. Skipping the pass question never skips the model question, and the reverse holds too.
+
+**Turn 1b-iv — record the pass count.** However `{passes}` was settled — asked, typed in the prose fallback, or read off a flag — write it once, here:
+
+```bash
+printf '%s\t%s\n' passes_planned "{passes}" >> .solidity-auditor/runs/{stamp}/scope.tsv
+```
+
+This is the `P` in the Scope table's `Passes` row. The `R` — how many passes actually produced a run file — is counted by the assembler from the run files themselves, so a pass that dies before it can record anything still lowers the count. The row is printed only when `P` is above 1, so writing the key on a 1-pass scan is harmless: `passes_planned` `1` prints no row.
+
+**Turn 1c — Memory read.** **SKIP this turn entirely when memory is off.** It is a turn of its own, and not a step of Turn 2, because two of its outcomes stop or downgrade the whole scan — they have to be reached before any expensive work starts.
+
+1. **Shell check.** Memory is merged by `awk`. Run `command -v awk >/dev/null` once. If it fails, print `memory needs a bash shell — on Windows install Git for Windows`, turn memory **off** for this scan, scan as a plain 1-run scan, and touch no file. There is no second implementation of the merge; the rule that must never break lives in one language only.
+
+2. **Stale temporary file.** If `.solidity-auditor/memory.tsv.tmp` exists, a previous scan did not finish. Print `warning: .solidity-auditor/memory.tsv.tmp left by an unfinished scan — overwriting`, then carry on. It is overwritten by this scan's merge.
+
+3. **Read the ledger.** If `.solidity-auditor/memory.tsv` does not exist, this is a first-ever scan: memory is empty, every finding is `NEW`, the file is written at the end. Otherwise read it and **validate it before using it**:
+   - the first line's first tab-separated field is exactly `#solidity-auditor-memory v1`
+   - every later line has exactly **6** tab-separated fields
+
+   On any failure print the path and the problem and **STOP the scan**. No agents, no report, no write. The user fixes or deletes the file. Do NOT start fresh and do NOT continue with a warning — a single bad row must never destroy real memory.
+
+4. **Photocopy it.** `mkdir -p {bundle_dir}` is already done; copy the ledger as it was **before this scan started**:
+
+   ```bash
+   cp .solidity-auditor/memory.tsv {bundle_dir}/memory-before.tsv 2>/dev/null || : > {bundle_dir}/memory-before.tsv
+   ```
+
+   Every merge this scan performs reads this photocopy, never the live file. Create it empty when no ledger exists, so the merge command below needs no special case.
+
+5. **Create the scan's row file**, empty: `: > {bundle_dir}/scan-rows.tsv`. Each run appends its gated rows to it.
+
+6. **Hold the key list** — column 1 of every row of the photocopy (after the prune in Turn 2, if one runs).
+
+   The **per-function bug-class vocabulary** — for each `contract|function` prefix, the bug-class labels the ledger already holds — is not held in the orchestrator's head. Turn 2 step 2c writes it to `{bundle_dir}/known-findings.md`, where the agents read it inside their bundles and Turn 4 reads it back from disk. It is a file and not a memory because the two readers are a long scan apart, and because the same labels must reach both.
+
+   The vocabulary is what keeps exact key matching honest: a bug class is a label written in words, so the same bug re-labelled is a second record and memory fails silently. Handing the existing labels back is how the same bug keeps the same key.
+
+**Turn 2 — Prepare.** In one message, make parallel tool calls: (a) Read `{resolved_path}/report-formatting.md`, (b) Read `{resolved_path}/judging.md`, (c) Read `{resolved_path}/agent-prompts.md`, (d) Read `{resolved_path}/report-language.md`.
+
+> **Why `report-formatting.md` is still read, now that nothing here composes a report.** It is the shape Turn 4 step 5a writes each finding in — title line, location line, Description, diff Fix block — and the assembler pastes those bytes straight through. Read it as the contract the finding blocks meet, not as a template to imitate at the end.
+
+> **`report-language.md` is read for the same reason, one level down.** `report-formatting.md` settles the **shape** of a finding block; `report-language.md` settles the **words inside it**. Turn 4 step 5a writes the title and the Description, the assembler pastes them through unchanged, so those bytes are the last chance to write a sentence a developer can act on. It is Simplified Technical English (ASD-STE100), and it is not optional styling: a finding the developer cannot read is a finding they do not fix. The same file is in every agent bundle, so the sentence the pass writes and the sentence the agent handed it obey one rule.
+
+Then build `source.md`, run the memory step, and only then cat the bundles — in that order, because the bundles carry a file the memory step writes:
+
+> **Turn 2 is split across the loop.** Step 1 runs **once per scan**: `source.md` provably cannot change between passes — one git SHA for the whole loop, no pruning between them — and it is the expensive half of the build. Step 2c and step 3 run **once per pass**, because only they carry the knowns, and re-catting twelve bundles from files already on disk is one Bash command. Steps 2a and 2b run once per scan with step 1, since both read that frozen source.
+>
+> **One `{bundle_dir}`, reused, everything overwritten.** `source.md` is written once and never touched again; `known-findings.md` and the twelve `agent-N-bundle.md` files are overwritten each pass. Disk stays flat whether the runner picked 1 pass or 10 — a directory per pass would hold 12 × N copies of the whole repo. This is safe because Turn 3b is a hard barrier: no pass-K agent is still reading a bundle when pass K+1 overwrites it. The cost, accepted: after the loop you cannot see what pass 2 told its agents. The durable record is the run files and the ledger.
+
+1. **Once per scan.** `{bundle_dir}/source.md` — ALL in-scope `.sol` files, each with a `### path` header and fenced code block.
+2. **Turn 2 step 2 — Name map, prune and known findings** (below). SKIPPED whole when memory is off. Parts a and b run once per scan; part c runs **every pass**, because the ledger it reads grows as the loop learns.
+3. **Every pass.** Agent bundles, in a single Bash command using `cat` (not shell variables or heredocs) = `source.md` + agent-specific files:
+
+| Bundle                | Appended files (relative to `{resolved_path}`)                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-1-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/math-precision-agent.md` + `hacking-agents/shared-rules.md`                            |
+| `agent-2-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/access-control-agent.md` + `hacking-agents/shared-rules.md`                            |
+| `agent-3-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/economic-security-agent.md` + `hacking-agents/shared-rules.md`                         |
+| `agent-4-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/execution-trace-agent.md` + `hacking-agents/shared-rules.md`                           |
+| `agent-5-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/invariant-agent.md` + `hacking-agents/shared-rules.md`                                 |
+| `agent-6-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/periphery-agent.md` + `hacking-agents/shared-rules.md`                                 |
+| `agent-7-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/first-principles-agent.md` + `hacking-agents/shared-rules.md`                          |
+| `agent-8-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/asymmetry-agent.md` + `hacking-agents/shared-rules.md`                                 |
+| `agent-9-bundle.md`   | `source.md` + `senior-auditor-sop.md` + `hacking-agents/boundary-agent.md` + `hacking-agents/shared-rules.md`                                  |
+| `agent-10-bundle.md`  | `source.md` + `senior-auditor-sop.md` + `hacking-agents/numerical-gap-agent.md` + `hacking-agents/shared-rules.md`                             |
+| `agent-11-bundle.md`  | `source.md` + `senior-auditor-sop.md` + `hacking-agents/trust-gap-agent.md` + `hacking-agents/shared-rules.md`                                 |
+| `agent-12-bundle.md`  | `source.md` + `senior-auditor-sop.md` + `hacking-agents/flow-gap-agent.md` + `hacking-agents/shared-rules.md`                                  |
+| **every one of the 12** | **+ `report-language.md`, appended after `shared-rules.md`** — unconditional, every mode, every pass. The agent's `description:` is the seed of the report's Description, so the language rule has to reach the writer and not only the editor. |
+| **every one of the 12** | **+ `{bundle_dir}/known-findings.md`, appended last** — only when memory is on **and** step 2 wrote that file. Never appended on a plain scan, and never appended when the ledger holds no record. |
+
+Each bundle = source.md + SOP + specialty + shared-rules + report-language (+ known findings, when there are any). Agents read the bundle; no Read/Grep needed for the initial scan. Targeted Read/Grep allowed for cross-file investigation.
+
+**Turn 2 step 2 — Name map, prune and known findings.** **SKIP this step entirely when memory is off.** It lives in Turn 2 and not in a turn of its own because all three parts read `source.md`, which Turn 2 has just built — a separate turn would only carry that file across a boundary. It is numbered **2**, ahead of the bundle cat, because part c writes a file every bundle carries; a pruned record must never reach an agent.
+
+a. **Build the name map, always** — once per scan, with step 1 (both the prune and the report need it, and the source it reads is frozen for the whole scan):
+
+```bash
+grep -ohE '(contract|library|interface)[[:space:]]+[A-Za-z0-9_]+|function[[:space:]]+[A-Za-z0-9_]+' {bundle_dir}/source.md \
+  | awk '{ n=$2; k=tolower(n); gsub(/[^a-z0-9]+/, "-", k); print k "\t" n }' \
+  | sort -u > {bundle_dir}/source-names.tsv
+```
+
+Column 1 is the identifier normalised the same way a key segment is (lower case, every run of non-alphanumeric characters to one hyphen); column 2 is how it is spelled in the source. Normalising **both sides the same way** is what makes the comparison exact — a key segment can never be matched against raw source text, because `withdrawAll` is stored as `withdrawall`.
+
+b. **Prune — once per scan, and only after a whole-repo scan.** Run it **only** in default mode. Never on a named-file scan (a file that was not scanned proves nothing about the records it holds), and never a second time inside one scan — the loop's later passes read the same frozen source, so there is nothing new for a second prune to learn.
+
+The prune edits the **photocopy**, not the live ledger. The live file inherits the prune when the first merge writes it. Pruning the live file instead would be undone by the next rebuild.
+
+```bash
+awk -F'\t' -v OFS='\t' '
+FILENAME==ARGV[1] { names[$1]=1; next }
+FNR==1 { print; next }
+{
+  split($1, p, "|")
+  keep = (p[1] in names) && (p[2] in names)
+  if (p[2]=="constructor" || p[2]=="receive" || p[2]=="fallback") keep = (p[1] in names)
+  if (keep) print; else print "pruned: " $6 "\t" $1 "\t" $5 > "/dev/stderr"
+}
+' {bundle_dir}/source-names.tsv {bundle_dir}/memory-before.tsv > {bundle_dir}/memory-before.tsv.tmp \
+  && mv {bundle_dir}/memory-before.tsv.tmp {bundle_dir}/memory-before.tsv
+```
+
+A record is dropped when its contract or its function can no longer be found in the assembled source. `constructor`, `receive` and `fallback` are never written as `function <name>`, so a record on one of them is kept whenever its contract survives.
+
+**The prune deletes Leads as well as findings.** A Lead is a full ledger record, so the same rule reaches it — and a pruned Lead leaves no trace anywhere else in the output. That is why the command prints every dropped row to the runner: `kind`, key and title, one line each. Print them under `Pruned N records (contract or function no longer in scope):`. Never drop a record silently.
+
+After the prune, re-read the photocopy for the key list of Turn 1c step 6. A pruned record must not reach the agents, the merge, or the "Known from earlier scans" section.
+
+
+c. **Write `mem_before`, then build `{bundle_dir}/known-findings.md`.**
+
+**`mem_before` first** — the row count of the photocopy **as the merge will read it**, which is the count *after* the prune. It is written here and nowhere else, and it is written in every mode memory is on, whether or not part b's prune ran (it does not run on a named-file scan):
+
+```bash
+printf '%s\t%s\n' mem_before "$(( $(wc -l < {bundle_dir}/memory-before.tsv) - 1 ))" \
+  >> .solidity-auditor/runs/{stamp}/scope.tsv
+```
+
+The `- 1` drops the header line. An empty photocopy has no header and would give `-1`; write `0` instead. The **pre**-prune number would make the `Memory` row's own arithmetic wrong — `12 records before this scan · 14 after` has to describe the same set the merge worked on.
+
+**This key is the memory flag the assembler reads.** Its presence is what makes the `Memory` row appear and the "Known from earlier scans" section exist — the presence of `memory-before.tsv` is not. Nothing writes a `mem_` key when memory is off, and this whole step is skipped when it is, so the flag cannot get out of step with the scan.
+
+It is written before the early exit below, so an empty ledger still gets a `Memory` row reading `0 records before this scan`.
+
+**Then `{bundle_dir}/known-findings.md`** — the ledger as the agents and Turn 4 read it. It is built from the **pruned** photocopy and from `source-names.tsv`, so it never names a record the prune has just dropped and never prints a normalised key at a human.
+
+```bash
+awk -F'\t' '
+FILENAME==ARGV[1] { nm[$1]=$2; next }
+FNR==1 { next }
+{
+  split($1, p, "|")
+  c = (p[1] in nm) ? nm[p[1]] : p[1]
+  f = (p[2] in nm) ? nm[p[2]] : p[2]
+  h = c "." f
+  if (!(h in seen)) { seen[h]=1; ord[++n]=h }
+  body[h] = body[h] "- `" p[3] "` — " $6 ", seen in " $3 ($3==1 ? " scan" : " scans") " — " $5 "\n"
+}
+END { for (i=1; i<=n; i++) printf "## %s\n\n%s\n", ord[i], body[ord[i]] }
+' {bundle_dir}/source-names.tsv {bundle_dir}/memory-before.tsv > {bundle_dir}/known-findings.body.md
+```
+
+**If that file is empty, stop here** — delete it, write no `known-findings.md`, and append nothing to the bundles. An empty ledger (a first-ever scan, or a scan whose every record the prune removed) must not hand twelve agents an empty heading.
+
+Otherwise write `{bundle_dir}/known-findings.md` as this exact prose followed by the body, unchanged:
+
+````markdown
+# Known findings — ground already walked
+
+Earlier scans of this repository recorded the findings below, grouped by the contract and
+function they sit in. Each line is `bug class` — kind, scans, title.
+
+**They are not false positives, and they are not off limits.** Put your **effort** into new
+ground: functions, flows and mechanisms this list does not name. That is a rule about where
+your reading time goes. It is **not** a rule about what you report.
+
+**Report every bug you find in full, listed or not.** A listed bug you reach again is a bug
+that is still there, and the report has to say so. Write it up exactly as you would write up
+anything new — the same path, proof and fix — whether you reached it by the mechanism it is
+listed with or by a different one. Silence is read as "nobody found this": a finding no agent
+raises drops out of the report into a table of records nobody re-checked, so a repository
+scanned twice would show fewer bugs than the same repository scanned once.
+
+**Reuse the bug-class label.** The backticked label on each line is the word this repository
+already uses for that class of bug in that function. When you report a finding or a lead
+whose bug class is one of the classes listed for that same contract and function, write
+**that exact label**. Invent a new label only when none of them is the same class of bug.
+Memory matches these labels as plain text, so the same bug under a new word is remembered
+twice and recognised never.
+
+<body — one `## Contract.function` section per function, as generated above>
+````
+
+The label-reuse rule is written here, once, for **both** readers of this file: the 12 agents,
+who write the bug class in a finding, and Turn 4 step 4, which writes it into a key.
+
+**The builder takes any 6-column ledger file.** On a single-run scan that file is the pruned
+photocopy, as above. A multi-pass scan rebuilds `known-findings.md` from the freshly merged
+`.solidity-auditor/memory.tsv` after every pass, before it re-cats the bundles, so the agents
+of pass K+1 read what pass K found as ground already walked. That is the whole point of
+passing memory down a loop; the command does not change, only the file it is pointed at.
+
+Print line counts for every bundle and `source.md`. Do NOT inline source code into the Agent call prompt itself.
+
+**Turn 3a — Spawn all 12 agents.** Runs **every pass**. In one message, spawn all 12 agents as **parallel BACKGROUND Agent calls** (`run_in_background=true`). If Turn 1b set `{agent_model}`, pass `model={agent_model}` on every Agent call. If `{agent_model}` is unset (Turn 1b skipped — Codex, Gemini, others), omit the `model` parameter entirely — do NOT substitute any default. The orchestrator will receive a notification when each agent completes — do NOT poll or sleep. Single phase, no later spawns. Proceed to Turn 3b only after all 12 have notified completion.
+
+Agents 1–9 use the **single-specialty prompt** (Turn 3a-i). Agents 10–12 use the **gap-hunter prompt** (Turn 3a-ii).
+
+**Turn 3a-i — Single-specialty prompt (agents 1–9).** Use the template under "Single-specialty prompt" in `{resolved_path}/agent-prompts.md`, substituting `{bundle_dir}`, the agent number and the bundle line count.
+
+**Turn 3a-ii — Gap-hunter prompt (agents 10–12).** Use the template under "Gap-hunter prompt" in the same file.
+
+Two rules that file carries, repeated here because they are conditions and not text:
+
+- The **"Known findings"** paragraph is included **only when memory is on and `known-findings.md` was appended**. On a plain scan the prompt is byte-identical to the one it has always been — a paragraph about a section that is not there would send agents hunting for it.
+- The **READ-ONLY** paragraph is **unconditional** — every agent, every mode, every pass. A real scan proved it necessary: an agent built Foundry proof-of-concept files inside the audited repository and deleted them afterwards. It left the tree clean and the stored SHA honest, and it was still wrong. A later editor must not make it conditional, and must not soften it into a preference.
+
+**Turn 3b — Wait for all 12 agents to complete.** Runs **every pass**. Once every one of the 12 spawned agents has notified completion, proceed to Turn 4. Do NOT proceed to dedup until every agent has finished — let them run to natural completion. Do NOT poll or sleep; act only on completion notifications.
+
+**While you wait, on the first pass only, Read `{resolved_path}/dedup-and-assembly.md`.** It holds the whole of Turn 4 and Turn 5. This turn is the one point in the scan where the orchestrator has nothing else to do, so the read costs no wall-clock; and having it in hand before Turn 4 starts is what keeps Turn 4 from improvising. Later passes already hold it.
+
+**When an agent dies.** Continue the pass with the eleven that came back. **Never respawn it, in any mode.** A retry costs an unbounded wait for one twelfth of the coverage, and a loop covers it for free — the next pass runs the same twelve specialties again, knowing what this one found. Record the loss in all three places, or it is a silent coverage loss: the pass summary line (Turn 4 step 5), the `run-K.md` header, and the report's `Passes` row.
+
+**When a whole pass produces nothing** — the bundle build failed, or all twelve died:
+
+**Record the failure before doing either.** A pass that produces nothing writes no run file, so nothing else on disk knows it was ever planned:
+
+```bash
+printf '%s\t%s\n' pass_{K}_failed 1 >> .solidity-auditor/runs/{stamp}/scope.tsv
+```
+
+- **Pass 1 produces nothing:** this is not a loop failure, it is today's failure. No ledger write. Go to Turn 5, which assembles a report with no findings in it — `_None — this scan raised no findings._` — rather than printing nothing at all. The `Passes` row is suppressed on a 1-pass scan, so the assembler says it in a **Run files** row instead — `⚠️ No pass produced a run file. This scan reviewed nothing.` The runs directory stays; it holds the `scope.tsv` that says what was attempted.
+- **A later pass produces nothing:** stop the loop and go straight to Turn 5. The report is assembled from the passes that finished and its `Passes` row says which one failed. Nothing is lost — the ledger was rebuilt after every pass. Grinding on to the next pass after the machinery has broken burns the runner's money.
+
+**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.
+
+**Steps 4 and 6 are SKIPPED entirely when memory is off.** Every other step runs at any pass count.
+
+Follow `{resolved_path}/dedup-and-assembly.md`, section **"Turn 4"**, step by step.
+
+Then, after the loop body has run `{passes}` times (or stopped early), go to Turn 5 once.
+
+**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 holds no model judgment.** It copies two files, runs `assemble.sh`, counts with `awk`, and prints. `assemble.sh` 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. If this turn looks too thin to be a reporting step — that is the point, and `dedup-and-assembly.md` records why.
+
+Follow `{resolved_path}/dedup-and-assembly.md`, section **"Turn 5"**, step by step. Its step 1 is SKIPPED when memory is off; its step 4 runs only when `--file-output` was passed.
+
+## Banner
+
+Before doing anything else, print this exactly:
+
+```
+
+██████╗  █████╗ ███████╗██╗  ██╗ ██████╗ ██╗   ██╗     ███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
+██╔══██╗██╔══██╗██╔════╝██║  ██║██╔═══██╗██║   ██║     ██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
+██████╔╝███████║███████╗███████║██║   ██║██║   ██║     ███████╗█████╔╝ ██║██║     ██║     ███████╗
+██╔═══╝ ██╔══██║╚════██║██╔══██║██║   ██║╚██╗ ██╔╝     ╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
+██║     ██║  ██║███████║██║  ██║╚██████╔╝ ╚████╔╝      ███████║██║  ██╗██║███████╗███████╗███████║
+╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝   ╚═══╝       ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝
+
+```
diff --git a/skills/pashov-audit-pipeline/references/report-formatting.md b/skills/pashov-audit-pipeline/references/report-formatting.md
index 03a8ecf..384a86d 100644
--- a/skills/pashov-audit-pipeline/references/report-formatting.md
+++ b/skills/pashov-audit-pipeline/references/report-formatting.md
@@ -1,20 +1,57 @@
 # Report Formatting
 
-## Report Path
+## 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.
 
-Save the report to `{project-name}-pashov-ai-audit-report-{timestamp}.md` in the current working directory, where `{project-name}` is the repo root basename and `{timestamp}` is `YYYYMMDD-HHMMSS` at scan time.
+**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.
 
-## EVM Cortex deviations from upstream
+**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.
 
-Two changes, both required by the repo's global finding-output-format rules. They are already folded into the template below — this section only explains *why* it differs from upstream's.
+## Report Path
+
+**Every scan assembles `.solidity-auditor/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.
 
-1. **Findings carry a severity as well as a confidence.** Upstream orders findings by confidence alone. Here, findings are grouped into severity bands (Critical → High → Medium → Low → Informational) and ordered by confidence descending *within* each band, numbered per band (`C-01`, `H-01`, `M-01`, `L-01`, `I-01`). See `judging.md` for how severity is assigned and why it is independent of confidence.
-2. **Critical and High findings include a Proof of Concept block** referencing the Foundry test that demonstrates the exploit. A Critical or High finding with no PoC is not ready to report.
+`--file-output` makes a **copy** of that file into the current working directory as
+`{project-name}-pashov-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.
 
-Unchanged from upstream: the scope table, the description-then-fix shape, the sub-threshold rule (findings below confidence 80 get a description but no **Fix** block), the leads section, and the disclaimer.
+The `run-K.md` files stay in `.solidity-auditor/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>
 
@@ -22,47 +59,26 @@ Unchanged from upstream: the scope table, the description-then-fix shape, the su
 
 ## Scope
 
-|                                  |                                                        |
-| -------------------------------- | ------------------------------------------------------ |
-| **Mode**                         | ALL / default / filename                               |
-| **Files reviewed**               | `File1.sol` · `File2.sol`<br>`File3.sol` · `File4.sol` | <!-- list every file, 3 per line -->
-| **nSLOC**                        | N                                                      |
-| **Commit**                       | <hash>                                                 |
-| **Methodology**                  | Pashov 12-agent parallel audit (solidity-auditor v3)   |
-| **Confidence threshold (1-100)** | N                                                      |
-
-| Severity | Count |
-|----------|-------|
-| Critical | X |
-| High | Y |
-| Medium | Z |
-| Low | W |
-| Informational | V |
-
-### Key Observations
-
-- <the most important findings, in 1-3 sentences>
-- <overall assessment of code quality and security posture>
+|  |  |
+| --- | --- |
+| **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 -->
 
 ---
 
-## Critical Findings
+## Findings
 
-### [C-01] <Title>
+[95] **1. <Title>**
 
-**Severity:** Critical · **Confidence:** 95 · **Agents:** [3]
-`ContractName.functionName` · `src/Contract.sol:L42-L58`
-**Status:** Confirmed
+`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>
 
-**Impact**
-<What an attacker gains, quantified>
-
-**Proof of Concept**
-<Foundry test reference plus the traced exploit path — mandatory for Critical/High>
-
 **Fix**
 
 ```diff
@@ -72,24 +88,12 @@ Unchanged from upstream: the scope table, the description-then-fix shape, the su
 
 ---
 
-< ... remaining Critical findings, confidence descending >
-
-## High Findings
-
-### [H-01] <Title>
+[82] **2. <Title>**
 
-**Severity:** High · **Confidence:** 82 · **Agents:** [2]
-`ContractName.functionName` · `src/Contract.sol:L88-L94`
-**Status:** Confirmed
+`ContractName.functionName` · Confidence: 82
 
 **Description**
-<...>
-
-**Impact**
-<...>
-
-**Proof of Concept**
-<mandatory for High>
+<The vulnerable code pattern and why it is exploitable, in 1 short sentence>
 
 **Fix**
 
@@ -100,39 +104,32 @@ Unchanged from upstream: the scope table, the description-then-fix shape, the su
 
 ---
 
-## Medium Findings
+< ... all above-threshold findings >
 
-### [M-01] <Title>
+---
 
-**Severity:** Medium · **Confidence:** 75
-`ContractName.functionName` · `src/Contract.sol:L120`
+[60] **3. <Title>**
 
-**Description**
-<...>
+`ContractName.functionName` · Confidence: 60
 
-<!-- confidence < 80: description only, no Fix block -->
+**Description**
+<The vulnerable code pattern and why it is exploitable, in 1 short sentence>
 
 ---
 
-## Low Findings
-
-### [L-01] <Title>
-<...>
-
-## Informational
-
-### [I-01] <Title>
-<...>
+< ... all below-threshold findings (description only, no Fix block) >
 
 ---
 
 Findings List
 
-| # | Severity | Confidence | Title |
-|---|---|---|---|
-| C-01 | Critical | [95] | <title> |
-| H-01 | High | [82] | <title> |
-| M-01 | Medium | [75] | <title> |
+| # | Confidence | Title |
+|---|---|---|
+| 1 | [95] | <title> |
+| 2 | [82] | <title> |
+| 3 | [75] | <title> |
+| | | **Below Confidence Threshold** |
+| 4 | [60] | <title> |
 
 ---
 
@@ -140,22 +137,21 @@ Findings List
 
 _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` — Code smells: <missing guard, unsafe arithmetic, etc.> — <1-2 sentence description of the trail and what remains unverified>
-- **<Title>** — `Contract.function` — Code smells: <...> — <1-2 sentence description>
+- **<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 -->
 
 ---
 
-## Appendix
+## Known from earlier scans
 
-### A. Scope Table
-### B. Methodology — 12-agent parallel audit with deduplication, four-gate judging, and PoC verification
-### C. Tools — Foundry, Slither, Aderyn, manual review by 12 specialized agents
-### D. Agent Attribution
+<!-- only when memory is on AND the ledger held at least one record — see Memory in the report -->
 
-| Finding | Agents That Flagged |
-|---------|---------------------|
-| C-01 | Math & Precision, Numerical Gap, Execution Trace |
-| H-01 | Access Control, Trust Gap |
+_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. `.solidity-auditor/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 |
 
 ---
 
@@ -163,4 +159,227 @@ _Vulnerability trails with concrete code smells where the full exploit path coul
 
 ````
 
-**Rules:** Follow the template above exactly. Group findings into severity bands, then sort by confidence (highest first) within each band. Findings below the confidence threshold get a description but no **Fix** block. Critical and High findings must carry a Proof of Concept. Draft findings directly in report format — do not re-generate.
+**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 `.solidity-auditor/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
+`.solidity-auditor/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.`
diff --git a/skills/pashov-audit-pipeline/references/report-language.md b/skills/pashov-audit-pipeline/references/report-language.md
new file mode 100644
index 0000000..b383c72
--- /dev/null
+++ b/skills/pashov-audit-pipeline/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?
diff --git a/skills/pool-finder/SKILL.md b/skills/pool-finder/SKILL.md
index 7dccffd..01b0bb5 100644
--- a/skills/pool-finder/SKILL.md
+++ b/skills/pool-finder/SKILL.md
@@ -13,7 +13,8 @@ description: Use when discovering Uniswap pools, querying pool state, analyzing
 | V3 QuoterV2 | `0x61fFE014bA17989E743c5F6cB21bF9697530B21e` |
 | V3 SwapRouter02 | `0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45` |
 | V3 NonfungiblePositionManager | `0xC36442b4a4522E871399CD717aBDD847Ab11FE88` |
-| V4 PoolManager | `0x000000000004444c5dc75cb358380d2e3de08a90` |
+| V4 PoolManager | `0x000000000004444c5dc75cB358380D2e3dE08A90` |
+| V4 StateView | `0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227` |
 
 ## V3 Pool Discovery
 
@@ -131,36 +132,48 @@ function orderCurrencies(address a, address b) pure returns (Currency c0, Curren
 ### Reading V4 Pool State with cast
 
 ```bash
-POOL_MANAGER=0x000000000004444c5dc75cb358380d2e3de08a90
+# Read through the StateView lens, NOT the PoolManager. getSlot0/getLiquidity/... are
+# StateLibrary *internal* helpers built on extsload; the PoolManager exposes no such ABI
+# and `cast call $POOL_MANAGER "getSlot0(bytes32)..."` reverts. Ethereum address below;
+# per-chain StateView addresses: https://developers.uniswap.org/docs/protocols/v4/deployments
+STATE_VIEW=0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227
 
 # Get slot0: (sqrtPriceX96, tick, protocolFee, lpFee)
-cast call $POOL_MANAGER \
+cast call $STATE_VIEW \
   "getSlot0(bytes32)(uint160,int24,uint24,uint24)" \
   <pool_id>
 
 # Get active liquidity
-cast call $POOL_MANAGER \
+cast call $STATE_VIEW \
   "getLiquidity(bytes32)(uint128)" \
   <pool_id>
 
 # Get liquidity at a specific tick
-cast call $POOL_MANAGER \
+cast call $STATE_VIEW \
   "getTickLiquidity(bytes32,int24)(uint128,int128)" \
   <pool_id> <tick>
 
 # Get tick bitmap word
-cast call $POOL_MANAGER \
+cast call $STATE_VIEW \
   "getTickBitmap(bytes32,int16)(uint256)" \
   <pool_id> <word_position>
+
+# IStateView also exposes getTickInfo, getFeeGrowthGlobals, getPositionInfo, getFeeGrowthInside
 ```
 
 ### Computing a PoolId Offchain
 
 ```bash
-# Encode the PoolKey struct and hash it
+# abi.encode the PoolKey fields (cast needs a function-style signature) and hash them
 cast keccak $(cast abi-encode \
-  "(address,address,uint24,int24,address)" \
+  "f(address,address,uint24,int24,address)" \
   <currency0> <currency1> <fee> <tickSpacing> <hooks>)
+
+# Example — mainnet native ETH/USDC 0.05% pool (currency0 = address(0), fee 500, tickSpacing 10, no hook):
+cast keccak $(cast abi-encode "f(address,address,uint24,int24,address)" \
+  0x0000000000000000000000000000000000000000 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 500 10 \
+  0x0000000000000000000000000000000000000000)
+# → 0x21c67e77068de97969ba93d4aab21826d33ca12bb9f565d8496e8fda8a82ca27
 ```
 
 ## Subgraph Queries
@@ -360,6 +373,9 @@ uint256 impactBps   = (priceBefore - priceAfter) * 10_000 / priceBefore;
 | Fee revenue vs IL | LP profitability | Negative = LPs losing money, expect exits |
 | Oracle cardinality | V3 observation buffer size (slot0 field 4) | Default 1 = no TWAP history |
 | Tick crossing frequency | How often price moves through tick boundaries | Very high = volatile, may deter LPs |
+| Protocol fee share | Portion of swap fees diverted from LPs (V3 `slot0.feeProtocol`, V4 `slot0.protocolFee`) | Nonzero on Ethereum mainnet: V3 `68`/`102` (1/4 or 1/6 of LP fees) since 2025-12-28, V4 static-fee pools since 2026-07-27 — subtract from LP fee-revenue estimates |
+
+Decode V3 `feeProtocol` as `token0 = feeProtocol % 16`, `token1 = feeProtocol >> 4`, protocol share `= 1/N` (68 → 1/4 on the 0.01%/0.05% tiers, 102 → 1/6 on the 0.30% tier). V4 `protocolFee` packs two pips fees — lower 12 bits zeroForOne, upper 12 bits oneForZero — charged on swap input before the LP fee (mainnet ETH/USDC 500/10 reads `512125`, i.e. 125 pips each way).
 
 ### Reading Oracle Cardinality
 
@@ -383,7 +399,7 @@ address pool = factory.createPool(tokenA, tokenB, fee);
 // Initialize with starting price (sqrtPriceX96 format)
 // For 1 token0 = 2000 token1 (e.g., 1 ETH = 2000 USDC with 18/6 decimals):
 // sqrtPriceX96 = sqrt(2000 * 1e6 / 1e18) * 2^96
-uint160 sqrtPriceX96 = 3543191142285914205922034323215; // example
+uint160 sqrtPriceX96 = 3543191142285914205922034; // sqrt(2e-9) * 2^96 ≈ 3.54e24 (with equal decimals it would be sqrt(2000) * 2^96 ≈ 3.54e30)
 IUniswapV3Pool(pool).initialize(sqrtPriceX96);
 ```
 
@@ -392,7 +408,7 @@ IUniswapV3Pool(pool).initialize(sqrtPriceX96);
 ```solidity
 import {IPoolManager} from "v4-core/src/interfaces/IPoolManager.sol";
 
-IPoolManager poolManager = IPoolManager(0x000000000004444c5dc75cb358380d2e3de08a90);
+IPoolManager poolManager = IPoolManager(0x000000000004444c5dc75cB358380D2e3dE08A90);
 
 PoolKey memory key = PoolKey({
     currency0: Currency.wrap(token0),
@@ -408,6 +424,9 @@ poolManager.initialize(key, sqrtPriceX96);
 ### sqrtPriceX96 Calculator
 
 ```solidity
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {FullMath} from "v4-core/src/libraries/FullMath.sol";
+
 /// @notice Computes sqrtPriceX96 from a human-readable price ratio
 /// @param price The price of token0 in terms of token1 (e.g., 2000 for 1 ETH = 2000 USDC)
 /// @param decimals0 Decimals of token0
@@ -417,11 +436,12 @@ function computeSqrtPriceX96(
     uint8 decimals0,
     uint8 decimals1
 ) pure returns (uint160) {
-    // adjustedPrice = price * 10^decimals0 / 10^decimals1
-    // sqrtPriceX96 = sqrt(adjustedPrice) * 2^96
-    uint256 adjustedPrice = price * (10 ** decimals1) / (10 ** decimals0);
-    uint256 sqrtPrice = Math.sqrt(adjustedPrice);
-    return uint160(sqrtPrice << 96);
+    // rawPrice = price * 10^decimals1 / 10^decimals0   (raw token1 units per raw token0 unit)
+    // sqrtPriceX96 = sqrt(rawPrice) * 2^96 = sqrt(rawPrice * 2^192)
+    // Scale by 2^192 BEFORE dividing so a sub-1 rawPrice (2000e6 / 1e18 = 2e-9) does not truncate to 0;
+    // FullMath.mulDiv keeps the 512-bit intermediate product from overflowing.
+    uint256 priceX192 = FullMath.mulDiv(price * (10 ** decimals1), 1 << 192, 10 ** decimals0);
+    return uint160(Math.sqrt(priceX192));
 }
 ```
 
diff --git a/skills/uniswap-math/SKILL.md b/skills/uniswap-math/SKILL.md
index 73d2b73..5ef9d25 100644
--- a/skills/uniswap-math/SKILL.md
+++ b/skills/uniswap-math/SKILL.md
@@ -37,7 +37,7 @@ Human-readable price: 1 ETH = 3000 USDC
 Raw price (token1/token0) = 3000 × 10⁶ / 10¹⁸ = 3000 × 10⁻¹²
 
 sqrtPrice = √(3000 × 10⁻¹²) = √(3 × 10⁻⁹) ≈ 5.47722558 × 10⁻⁵
-sqrtPriceX96 = 5.47722558 × 10⁻⁵ × 2⁹⁶ ≈ 4_339_505_179_874_779_489_878_115
+sqrtPriceX96 = 5.47722558 × 10⁻⁵ × 2⁹⁶ ≈ 4_339_505_179_874_779_489_431_521
 ```
 
 For a pair where both tokens have 18 decimals (e.g., WETH/DAI at price 3000):
@@ -45,7 +45,7 @@ For a pair where both tokens have 18 decimals (e.g., WETH/DAI at price 3000):
 ```
 Raw price = 3000 (decimals cancel)
 sqrtPrice = √3000 ≈ 54.7722558
-sqrtPriceX96 = 54.7722558 × 2⁹⁶ ≈ 4_339_505_179_874_779_163_484_739_850_572_800
+sqrtPriceX96 = 54.7722558 × 2⁹⁶ ≈ 4_339_505_179_874_779_489_431_521_786_241
 ```
 
 ### Converting sqrtPriceX96 to Human Price
@@ -64,8 +64,8 @@ def sqrtPriceX96_to_price(sqrtPriceX96, decimals0, decimals1):
     adjusted = price * 10 ** (decimals0 - decimals1)
     return adjusted
 
-# ETH/USDC: sqrtPriceX96 = 4_339_505_179_874_779_489_878_115
-sqrtPriceX96_to_price(4_339_505_179_874_779_489_878_115, 18, 6)
+# ETH/USDC: sqrtPriceX96 = 4_339_505_179_874_779_489_431_521
+sqrtPriceX96_to_price(4_339_505_179_874_779_489_431_521, 18, 6)
 # ≈ 3000.0
 ```
 
@@ -674,12 +674,12 @@ Step 2: Square root
 
 Step 3: Scale by 2⁹⁶
   sqrtPriceX96 = 5.47722558 × 10⁻⁵ × 79228162514264337593543950336
-               ≈ 4_339_505_179_874_779_489_878_115
+               ≈ 4_339_505_179_874_779_489_431_521
 
 Step 4: Corresponding tick
-  tick = log(3 × 10⁻⁹) / log(1.0001) ≈ -196222
+  tick = floor(log(3 × 10⁻⁹) / log(1.0001)) = floor(-196256.35) = -196257
 
-Verification: TickMath.getSqrtPriceAtTick(-196222) should be ≈ sqrtPriceX96 above
+Verification: TickMath.getSqrtPriceAtTick(-196257) should be ≈ sqrtPriceX96 above (slightly below it, since the tick is floored)
 ```
 
 ### Example 2: Liquidity from Token Amounts
@@ -691,13 +691,13 @@ Scenario:
   Deposit: 1 ETH + 3000 USDC
 
 Step 1: Convert price bounds to ticks
-  tickLower ≈ -198242  (corresponding to ~$2500)
-  tickUpper ≈ -194626  (corresponding to ~$3500)
+  tickLower ≈ -198080  (corresponding to ~$2500)
+  tickUpper ≈ -194715  (corresponding to ~$3500)
 
 Step 2: Get sqrtPrices
   √P       = √(3000 × 10⁻¹²) × 2⁹⁶  (current, from Example 1)
-  √P_lower = √(2500 × 10⁻¹²) × 2⁹⁶ ≈ 3_961_408_831_915_985_491_200_000
-  √P_upper = √(3500 × 10⁻¹²) × 2⁹⁶ ≈ 4_689_982_010_565_498_048_200_000
+  √P_lower = √(2500 × 10⁻¹²) × 2⁹⁶ ≈ 3_961_408_125_713_216_879_677_197
+  √P_upper = √(3500 × 10⁻¹²) × 2⁹⁶ ≈ 4_687_201_305_027_700_927_646_043
 
 Step 3: Compute L from each token
   L_from_ETH = amount0 × √P × √P_upper / (√P_upper - √P)
@@ -740,10 +740,10 @@ Step 4: If √P_new crosses a tick boundary, split the computation:
 ### Example 4: Tick to Human-Readable Price
 
 ```
-Given: tick = -196222, token0 = WETH (18 dec), token1 = USDC (6 dec)
+Given: tick = -196257, token0 = WETH (18 dec), token1 = USDC (6 dec)
 
 Step 1: Raw price
-  rawPrice = 1.0001^(-196222) ≈ 3.000 × 10⁻⁹
+  rawPrice = 1.0001^(-196257) ≈ 3.000 × 10⁻⁹
 
 Step 2: Adjust for decimals
   humanPrice = rawPrice × 10^(decimals0 - decimals1)
@@ -751,7 +751,7 @@ Step 2: Adjust for decimals
              = 3.000 × 10⁻⁹ × 10¹²
              = 3000
 
-So tick -196222 ≈ $3000 ETH/USDC
+So tick -196257 ≈ $3000 ETH/USDC
 ```
 
 ```python
@@ -908,9 +908,9 @@ require(tickLower < tickUpper, "tickLower must be < tickUpper");
 
 ```solidity
 // From Pool.tickSpacingToMaxLiquidityPerTick:
-// tickSpacing=1   → maxLiq ≈ 1.91 × 10³⁷
-// tickSpacing=60  → maxLiq ≈ 1.15 × 10³⁹
-// tickSpacing=200 → maxLiq ≈ 3.83 × 10³⁹
+// tickSpacing=1   → maxLiq ≈ 1.918 × 10³²  ((2¹²⁸−1) / 1_774_545 ticks)
+// tickSpacing=60  → maxLiq ≈ 1.151 × 10³⁴  ((2¹²⁸−1) / 29_575 ticks)
+// tickSpacing=200 → maxLiq ≈ 3.835 × 10³⁴  ((2¹²⁸−1) / 8_873 ticks)
 ```
 
 ### 7. Fee Growth Wrapping
diff --git a/skills/uniswap-v3-expert/SKILL.md b/skills/uniswap-v3-expert/SKILL.md
index 9b0535a..984512d 100644
--- a/skills/uniswap-v3-expert/SKILL.md
+++ b/skills/uniswap-v3-expert/SKILL.md
@@ -19,10 +19,10 @@ UniswapV3Factory (singleton)
 │
 Periphery contracts (stateless routers / managers):
 ├── NonfungiblePositionManager — wraps LP positions as ERC-721 NFTs
-├── SwapRouter — single and multi-hop exact-input / exact-output swaps
+├── SwapRouter (legacy v1) — single and multi-hop exact-input / exact-output swaps; Ethereum, Arbitrum, Optimism, Polygon only
 ├── SwapRouter02 — v2+v3 unified router with multicall
 ├── UniversalRouter — command-based router supporting v2, v3, permits, NFTs
-├── Quoter — off-chain swap simulation (reverts internally to return amounts)
+├── Quoter — offchain swap simulation (reverts internally to return amounts)
 ├── QuoterV2 — returns sqrtPriceX96After, initializedTicksCrossed, gasEstimate
 └── TickLens — batch read initialized ticks for a pool
 ```
@@ -97,6 +97,8 @@ Boundary values:
 
 Tick spacing means LPs can only place range boundaries at ticks divisible by the spacing. The 1 bps tier was added via governance (not in original deployment).
 
+**Protocol fee is live on Ethereum mainnet.** Since the UNIfication governance proposal executed on 2025-12-28, mainnet V3 pools carry a protocol fee: `slot0().feeProtocol` is `68` on the 0.01% and 0.05% tiers (protocol takes 1/4 of LP fees) and `102` on the 0.30% tier (1/6). Decode it as `token0 = feeProtocol % 16`, `token1 = feeProtocol >> 4`, protocol share `= 1/N`; the `feeGrowthGlobal*X128` accumulators already accrue net of that share, so volume-based LP fee-revenue estimates must be multiplied by `(1 - protocol_share)`.
+
 ### Liquidity Math
 
 Within a single tick range, the V3 pool behaves like a constant-product AMM scaled by liquidity `L`:
@@ -461,7 +463,9 @@ positionManager.burn(tokenId);
 
 ## SwapRouter Integration
 
-### SwapRouter (original)
+### SwapRouter (legacy v1)
+
+The original `SwapRouter` (`0xE592427A0AEce92De3Edee1F18E0157C05861564`) is a legacy contract: it is deployed only on Ethereum, Arbitrum One, Optimism and Polygon and is absent from Base, Unichain, BNB, Avalanche and Celo (on Base and Unichain that address holds an unrelated contract). The official docs name `UniversalRouter` as the preferred swap entrypoint, with `SwapRouter02` as the V3-native alternative; the interface below is kept for reference and for reading existing integrations.
 
 ```solidity
 interface ISwapRouter {
@@ -717,37 +721,40 @@ function _verifyCallback(address tokenA, address tokenB, uint24 fee) internal vi
 |----------|---------|
 | UniswapV3Factory | `0x1F98431c8aD98523631AE4a59f267346ea31F984` |
 | NonfungiblePositionManager | `0xC36442b4a4522E871399CD717aBDD847Ab11FE88` |
-| SwapRouter | `0xE592427A0AEce92De3Edee1F18E0157C05861564` |
+| SwapRouter (legacy v1) | `0xE592427A0AEce92De3Edee1F18E0157C05861564` |
 | SwapRouter02 | `0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45` |
 | Quoter | `0xb27308f9F90D607463bb33eA1BeBb41C27CE5AB6` |
 | QuoterV2 | `0x61fFE014bA17989E743c5F6cB21bF9697530B21e` |
-| UniversalRouter (current) | `0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af` |
-| TickLens | `0xbfd8137f7d1516D3fe7e20F7doA5099eEc6856aF` |
+| UniversalRouter V2 | `0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af` |
+| UniversalRouter V2.1.1 | `0x4C82D1fBFe28C977cBB58D8C7FF8FCF9F70a2cCA` |
+| UniversalRouter V2.1.2 | `0x23617e59A5925b2A4Bf75d73ff6711cD0b29De85` |
+| TickLens | `0xbfd8137f7d1516D3ea5cA83523914859ec47F573` |
 
 ### Cross-Chain Deployments
 
-V3 core contracts (Factory, NPM, SwapRouter, Quoter) are deployed to the same addresses across all supported chains via CREATE2:
+The original CREATE2 set (Factory `0x1F98…F984`, NPM `0xC364…FE88`, SwapRouter `0xE592…1564`, SwapRouter02 `0x68b3…Fc45`, QuoterV2 `0x61fF…B21e`) is shared only by Ethereum, Arbitrum One, Optimism and Polygon (verified by `cast code`); every later chain has its own addresses:
 
-| Chain | Factory | NPM | SwapRouter |
-|-------|---------|-----|------------|
-| Arbitrum | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0xE592427A...1564` |
-| Optimism | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0xE592427A...1564` |
-| Polygon | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0xE592427A...1564` |
-| Base | `0x33128a8fC17869897dcE68Ed026d694621f6FDfD` | `0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1` | varies |
-| BNB Chain | `0xdB1d10011AD0Ff90774D0C6Bb92e5C5c8b4461F7` | `0x7b8A01B39D58278b5DE7e48c8449c9f4F5170613` | varies |
-| Avalanche | `0x740b1c1de25031C31FF4fC9A62f554A55cdC1baD` | varies | varies |
-| Celo | `0xAfE208a311B21f13EF87E33A90049fC17A7acDEc` | varies | varies |
+| Chain | Factory | NPM | SwapRouter02 | QuoterV2 |
+|-------|---------|-----|--------------|----------|
+| Arbitrum | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0x68b34658...Fc45` | `0x61fFE014...B21e` |
+| Optimism | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0x68b34658...Fc45` | `0x61fFE014...B21e` |
+| Polygon | `0x1F98431c...F984` | `0xC36442b4...FE88` | `0x68b34658...Fc45` | `0x61fFE014...B21e` |
+| Base | `0x33128a8fC17869897dcE68Ed026d694621f6FDfD` | `0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1` | `0x2626664c2603336E57B271c5C0b26F421741e481` | `0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a` |
+| Unichain | `0x1F98400000000000000000000000000000000003` | `0x943e6e07a7E8E791dAFC44083e54041D743C46E9` | `0x73855d06DE49d0fe4A9c42636Ba96c62da12FF9C` | `0x385A5cf5F83e99f7BB2852b6A19C3538b9FA7658` |
+| BNB Chain | `0xdB1d10011AD0Ff90774D0C6Bb92e5C5c8b4461F7` | `0x7b8A01B39D58278b5DE7e48c8449c9f4F5170613` | `0xB971eF87ede563556b2ED4b1C0b0019111Dd85d2` | `0x78D78E420Da98ad378D7799bE8f4AF69033EB077` |
+| Avalanche | `0x740b1c1de25031C31FF4fC9A62f554A55cdC1baD` | `0x655C406EBFa14EE2006250925e54ec43AD184f8B` | `0xbb00FF08d01D300023C629E8fFfFcb65A5a578cE` | `0xbe0F5544EC67e9B3b2D979aaA43f18Fd87E6257F` |
+| Celo | `0xAfE208a311B21f13EF87E33A90049fC17A7acDEc` | `0x3d79EdAaBC0EaB6F08ED885C05Fc0B014290D95A` | `0x5615CDAb10dc425a742d643d949a7F474C01abc4` | `0x82825d0554fA07f7FC52Ab63c961F330fdEFa8E8` |
 
-**CRITICAL**: Addresses on Base, BNB, Avalanche, Celo, and newer chains differ from the canonical set. Always verify with `cast code <address> --rpc-url <chain>` or check the Uniswap Labs deployment repository before integrating.
+**CRITICAL**: Addresses on Base, BNB, Avalanche, Celo, and newer chains differ from the canonical set. Always verify with `cast code <address> --rpc-url <chain>` or check the official per-chain deployment pages at `https://developers.uniswap.org/docs/protocols/v3/deployments/<chain>` (the former `docs.uniswap.org` URLs redirect there) before integrating.
 
 ## Foundry Setup
 
 ### Install Dependencies
 
 ```bash
-forge install Uniswap/v3-core --no-commit
-forge install Uniswap/v3-periphery --no-commit
-forge install OpenZeppelin/openzeppelin-contracts --no-commit
+forge install Uniswap/v3-core
+forge install Uniswap/v3-periphery
+forge install OpenZeppelin/openzeppelin-contracts
 ```
 
 ### Remappings (foundry.toml or remappings.txt)
@@ -760,6 +767,8 @@ forge install OpenZeppelin/openzeppelin-contracts --no-commit
 
 ### Fork Testing Against Mainnet Pools
 
+This test targets the legacy `SwapRouter` v1, so it only works on Ethereum, Arbitrum One, Optimism and Polygon forks. To target `SwapRouter02` instead (`0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45` on Ethereum; per-chain addresses in the table above), use `IV3SwapRouter` from `Uniswap/swap-router-contracts` — its `ExactInputSingleParams` has no `deadline` field, so drop that line and wrap the call in `multicall(uint256 deadline, bytes[] data)` if you need a deadline.
+
 ```solidity
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.24;
@@ -876,7 +885,7 @@ This is profitable because concentrated liquidity in a tiny range captures nearl
 | Pool architecture | One contract per pool | Singleton `PoolManager` |
 | Pool creation | `factory.createPool()` | `poolManager.initialize()` |
 | Token transfers | Callbacks (pull pattern) | Flash accounting with `settle()` / `take()` |
-| LP positions | `NonfungiblePositionManager` (ERC-721) | `PositionManager` (ERC-6909) |
+| LP positions | `NonfungiblePositionManager` (ERC-721) | `PositionManager` (ERC-721, Permit2, action-batched) |
 | Swap routing | `SwapRouter` / `SwapRouter02` | `UniversalRouter` or custom routers |
 | Extensibility | None | Hooks at every lifecycle point |
 | Fee model | Fixed fee tiers | Dynamic fees via hooks |
@@ -888,7 +897,7 @@ This is profitable because concentrated liquidity in a tiny range captures nearl
 ### Key Migration Considerations
 
 1. **Oracle removal**: V4 removed built-in oracles. If you depend on V3 TWAPs, either keep using V3 pools or implement an oracle hook in V4.
-2. **ERC-721 → ERC-6909**: V4 positions use semi-fungible ERC-6909 tokens instead of NFTs. This changes how positions are tracked and transferred.
+2. **Positions stay ERC-721**: V4 `PositionManager` mints ERC-721 NFTs ("Uniswap v4 Positions NFT") but is driven by batched `Actions` via `modifyLiquidities`; ERC-6909 in V4 is the PoolManager's claim-token standard (`mint`/`burn`), not LP positions.
 3. **Callback → flash accounting**: V3 callbacks that push tokens to the pool are replaced by V4's `settle()` and `take()` within an `unlock()` context.
 4. **Fee tiers → dynamic**: V3 fixed fee tiers become fully configurable via hooks in V4. Custom fee logic (volatility-based, time-based) is possible.
 
diff --git a/skills/uniswap-v4-expert/SKILL.md b/skills/uniswap-v4-expert/SKILL.md
index 7adb07c..7edcac3 100644
--- a/skills/uniswap-v4-expert/SKILL.md
+++ b/skills/uniswap-v4-expert/SKILL.md
@@ -40,11 +40,13 @@ This means multi-hop swaps (e.g., A→B→C) only require net token movements fo
 
 ### Functions Callable Outside unlock()
 
-Only two functions do NOT require the unlock context:
+Functions callable outside `unlock()`:
 - `initialize()` — creates a new pool (no balance changes)
+- `sync(currency)` — snapshots reserves into transient storage; harmless outside a lock
 - `updateDynamicLPFee()` — called by hook contracts to set the current dynamic fee
+- the `IProtocolFees` admin functions (`setProtocolFeeController`, `setProtocolFee`, `collectProtocolFees`)
 
-Everything else (`swap`, `modifyLiquidity`, `donate`, `take`, `settle`, `mint`, `burn`, `sync`, `clear`) requires being inside an active `unlockCallback`.
+`swap`, `modifyLiquidity`, `donate`, `take`, `settle`, `settleFor`, `clear`, `mint`, `burn` are all `onlyWhenUnlocked` and must run inside an active `unlockCallback`.
 
 ## Core Types
 
@@ -320,19 +322,24 @@ Two mechanisms for dynamic fee updates:
 2. **Per-swap override**: `beforeSwap` returns a fee with the override flag set in the third return value (`uint24`). The returned fee is `desiredFee | LPFeeLibrary.OVERRIDE_FEE_FLAG`. This overrides the stored fee for that single swap only.
 
 ```solidity
-function beforeSwap(address, PoolKey calldata, IPoolManager.SwapParams calldata, bytes calldata)
-    external
+import {SwapParams} from "v4-core/src/types/PoolOperation.sol";
+
+// Inside a BaseHook subclass: override the internal _beforeSwap, not the external entry point
+function _beforeSwap(address, PoolKey calldata, SwapParams calldata, bytes calldata)
+    internal
     override
     returns (bytes4, BeforeSwapDelta, uint24)
 {
     uint24 dynamicFee = _computeFee();
-    return (this.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, dynamicFee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
+    return (BaseHook.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, dynamicFee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
 }
 ```
 
 ### Protocol Fees
 
-Set by the PoolManager owner via `IProtocolFees.setProtocolFee(PoolKey, uint24)`. Protocol fees are taken as a percentage of LP fees. The protocol fee is a `uint24` where the upper 12 bits are the fee for token0 and the lower 12 bits are the fee for token1.
+Set by the `protocolFeeController` (appointed by the PoolManager owner via `setProtocolFeeController`) through `IProtocolFees.setProtocolFee(PoolKey, uint24)`. The `uint24` packs two direction-specific fees in pips: lower 12 bits = zeroForOne, upper 12 bits = oneForZero, each `<= ProtocolFeeLibrary.MAX_PROTOCOL_FEE` (1000 pips = 0.1%). The protocol fee is charged on the swap input first; the LP fee applies to the remainder (`swapFee = protocolFee + lpFee - protocolFee * lpFee / 1e6`).
+
+Protocol fees are live on mainnet V4 pools since the governance proposal "Activate v4 Protocol Fees (Part 1/2)" executed on 2026-07-27. On Ethereum, `PoolManager.owner()` is the governance timelock `0x1a9C8182C09F50C8318d769245beA52c32BE35BC` and `protocolFeeController()` is `0x89A5D5bF00a27D55c02951E49078a5C5771051dB`; the native ETH/USDC 500/10 pool reports `protocolFee = 512125` (125 pips in each direction). Fee-revenue models for hooks and LPs must account for this cut.
 
 ## PositionManager (Periphery)
 
@@ -377,6 +384,7 @@ library Actions {
     uint256 internal constant SWAP_EXACT_IN               = 0x07;
     uint256 internal constant SWAP_EXACT_OUT_SINGLE       = 0x08;
     uint256 internal constant SWAP_EXACT_OUT              = 0x09;
+    uint256 internal constant DONATE                      = 0x0a; // not supported by PositionManager or V4Router
     uint256 internal constant SETTLE                      = 0x0b;
     uint256 internal constant SETTLE_ALL                  = 0x0c;
     uint256 internal constant SETTLE_PAIR                 = 0x0d;
@@ -389,9 +397,14 @@ library Actions {
     uint256 internal constant SWEEP                       = 0x14;
     uint256 internal constant WRAP                        = 0x15;
     uint256 internal constant UNWRAP                      = 0x16;
+    uint256 internal constant MINT_6909                   = 0x17; // not supported by PositionManager or V4Router
+    uint256 internal constant BURN_6909                   = 0x18; // not supported by PositionManager or V4Router
+    uint256 internal constant UNWIND_WITH_FALLBACK        = 0x19;
 }
 ```
 
+The library defines 26 constants (`0x00`–`0x19`); the two deprecated `*_FROM_DELTAS` codes are listed below.
+
 **DEPRECATED** (vulnerable to sandwich attacks — lack slippage protection):
 - `INCREASE_LIQUIDITY_FROM_DELTAS` (0x04)
 - `MINT_POSITION_FROM_DELTAS` (0x05)
@@ -423,11 +436,14 @@ Burn an empty position:
 The `Notifier` base enables position subscribers — external contracts that receive callbacks when a position is modified. Subscribers implement `ISubscriber`:
 
 ```solidity
+import {BalanceDelta} from "v4-core/src/types/BalanceDelta.sol";
+import {PositionInfo} from "v4-periphery/src/libraries/PositionInfoLibrary.sol";
+
 interface ISubscriber {
     function notifySubscribe(uint256 tokenId, bytes memory data) external;
     function notifyUnsubscribe(uint256 tokenId) external;
     function notifyModifyLiquidity(uint256 tokenId, int256 liquidityChange, BalanceDelta feesAccrued) external;
-    function notifyBurn(uint256 tokenId) external;
+    function notifyBurn(uint256 tokenId, address owner, PositionInfo info, uint256 liquidity, BalanceDelta feesAccrued) external;
 }
 ```
 
@@ -440,14 +456,34 @@ Subscribe via `positionManager.subscribe(tokenId, subscriber, data)`. The subscr
 | Contract | Address |
 |----------|---------|
 | PoolManager | `0x000000000004444c5dc75cB358380D2e3dE08A90` |
-| Universal Router | `0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af` |
+| Universal Router (V2) | `0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af` |
+| Universal Router 2.1.1 | `0x4C82D1fBFe28C977cBB58D8C7FF8FCF9F70a2cCA` |
+| Universal Router 2.1.2 | `0x23617e59A5925b2A4Bf75d73ff6711cD0b29De85` |
 | PositionManager | `0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e` |
+| PositionDescriptor | `0xd1428Ba554F4C8450b763a0B2040A4935c63f06C` |
+| StateView | `0x7fFE42C4a5DEeA5b0feC41C94C136Cf115597227` |
+| V4Quoter | `0x52F0E24D1c21C8A0cB1e5a5dD6198556BD9E1203` |
+| ReservesLens | `0x0000001b173C3bbF3984D417d8614E3eed34865B` |
+| Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` |
+
+### Unichain (Chain ID: 130)
+
+| Contract | Address |
+|----------|---------|
+| PoolManager | `0x1F98400000000000000000000000000000000004` |
+| PositionManager | `0x4529A01c7A0410167c5740C487A8DE60232617bf` |
+| StateView | `0x86e8631A016F9068C3f085fAF484Ee3F5fDee8f2` |
+| V4Quoter | `0x333E3C607B141b18fF6de9f258db6e77fE7491E0` |
+| Universal Router (V2) | `0xEf740bf23aCaE26f6492B10de645D6B98dC8Eaf3` |
+| Universal Router 2.1.2 | `0xD1b797D92d87B688193A2B976eFc8D577D204343` |
+
+RPC: `https://mainnet.unichain.org`. All Unichain addresses above were verified with `cast code`; the Ethereum PoolManager address has no code on Unichain. Unichain's `protocolFeeController()` is still `address(0)`, so protocol fees are not yet active there.
 
 ### Supported Chains
 
-V4 is deployed on: **Ethereum, Unichain, Optimism, Base, Arbitrum One, Polygon, Blast, Zora, Worldchain, Ink, Soneium, Avalanche, BNB Smart Chain, Celo, Monad, MegaETH, Tempo**
+V4 is deployed on 19 mainnets: **Ethereum, Unichain, Optimism, Base, Arbitrum One, Polygon, Zora, Worldchain, X Layer, Ink, Soneium, Avalanche, BNB Smart Chain, Celo, Monad, MegaETH, Tempo, Robinhood Chain, Arc**. Blast was removed from the official list (its onchain status is unverified).
 
-**CRITICAL**: Addresses are NOT the same across chains. Always verify per-chain at https://docs.uniswap.org/contracts/v4/deployments. Use `cast code <address> --rpc-url <rpc>` to confirm deployment before integrating.
+**CRITICAL**: Addresses are NOT the same across chains. Always verify per-chain at https://developers.uniswap.org/docs/protocols/v4/deployments. Use `cast code <address> --rpc-url <rpc>` to confirm deployment before integrating.
 
 ## Integration Patterns
 
@@ -549,6 +585,7 @@ poolManager.burn(address(this), currency.toId(), amount);
 ```bash
 forge install uniswap/v4-core
 forge install uniswap/v4-periphery
+forge install OpenZeppelin/uniswap-hooks   # BaseHook (no longer in v4-periphery)
 ```
 
 ### Remappings (foundry.toml or remappings.txt)
@@ -560,6 +597,7 @@ remappings = [
     "v4-periphery/=lib/v4-periphery/",
     "@uniswap/v4-core/=lib/v4-core/",
     "@uniswap/v4-periphery/=lib/v4-periphery/",
+    "@openzeppelin/uniswap-hooks/=lib/uniswap-hooks/",
     "permit2/=lib/v4-periphery/lib/permit2/",
     "forge-std/=lib/forge-std/src/",
 ]
@@ -588,8 +626,9 @@ import {LPFeeLibrary} from "v4-core/src/libraries/LPFeeLibrary.sol";
 import {StateLibrary} from "v4-core/src/libraries/StateLibrary.sol";
 import {TransientStateLibrary} from "v4-core/src/libraries/TransientStateLibrary.sol";
 
-// Periphery — hooks
-import {BaseHook} from "v4-periphery/src/base/hooks/BaseHook.sol";
+// Periphery — hooks (BaseHook no longer ships in v4-periphery; pick one)
+import {BaseHook} from "@openzeppelin/uniswap-hooks/src/base/BaseHook.sol";   // v4-template default
+// or: import {BaseHook} from "v4-hooks-public/src/base/BaseHook.sol";       // Uniswap Labs
 
 // Periphery — position management
 import {IPositionManager} from "v4-periphery/src/interfaces/IPositionManager.sol";
@@ -636,10 +675,10 @@ The `Deployers` helper from `v4-core/test/utils/Deployers.sol` provides `deployF
 | Token transfers | Direct transfers on every operation | Flash accounting (deltas in transient storage) |
 | Multi-hop efficiency | Transfer tokens between each pool | Net settlement — only endpoints transfer |
 | Native ETH | Must wrap to WETH first | Native ETH via `Currency.wrap(address(0))` |
-| Extensibility | No hook system | 14 hook callbacks with return-delta support |
+| Extensibility | No hook system | 10 hook callbacks (14 permission flags incl. 4 return-delta flags) |
 | Fee model | Fixed fee tiers (0.01%, 0.05%, 0.30%, 1%) | Arbitrary static fees + dynamic fees via hooks |
 | Fee distribution | Swap fees only | `donate()` for direct distribution to LPs |
-| Position NFTs | NonfungiblePositionManager (V3) | PositionManager with Permit2 + ERC-6909 |
+| Position NFTs | NonfungiblePositionManager (V3) | PositionManager (still ERC-721) with Permit2 and batched `Actions`; ERC-6909 is for PoolManager claim tokens, not positions |
 | LP fee updates | Immutable after pool creation | Dynamic via `updateDynamicLPFee()` |
 | Transient storage | Not used (pre-Cancun) | EIP-1153 for delta tracking |
 | Flash loans | Dedicated `flash()` function | Implicit via unlock — take first, settle later |
@@ -763,7 +802,7 @@ When a hook has `afterSwapReturnDelta` permission, the `int128` returned from `a
 - [ ] PoolKey fee is valid: either a static fee `<= 1_000_000` or exactly `DYNAMIC_FEE_FLAG`
 - [ ] `tickSpacing > 0` and `<= type(int16).max`
 - [ ] Pool is initialized before any swaps or liquidity operations
-- [ ] All operations (except `initialize`) are inside an `unlockCallback`
+- [ ] Every balance-changing operation (`swap`, `modifyLiquidity`, `donate`, `take`, `settle`, `settleFor`, `clear`, `mint`, `burn`) runs inside an `unlockCallback`; only `initialize`, `sync`, `updateDynamicLPFee`, and the `IProtocolFees` admin functions are callable outside
 - [ ] `unlockCallback` validates `msg.sender == address(poolManager)`
 
 ### Delta Resolution
diff --git a/skills/uniswap-v4-hooks/SKILL.md b/skills/uniswap-v4-hooks/SKILL.md
index 52df458..139943b 100644
--- a/skills/uniswap-v4-hooks/SKILL.md
+++ b/skills/uniswap-v4-hooks/SKILL.md
@@ -10,6 +10,12 @@ revision of the Uniswap V4 template or pin `v4-core`, `v4-periphery`, and the
 hook library to known-compatible revisions. Do not combine examples from
 different releases.
 
+As of 2026-02-06 `v4-periphery` no longer contains `BaseHook` or `HookMiner`
+(PR #510). Use `@openzeppelin/uniswap-hooks` (what `Uniswap/v4-template` pins)
+or `Uniswap/v4-hooks-public`; both expose the same `_before*`/`_after*`
+internal-override API. `HookMiner` also remains at
+`v4-periphery/test/shared/HookMiner.sol`.
+
 Before editing, inspect the project's `foundry.lock`, `.gitmodules`, and
 remappings. Read `Hooks.sol`, `IHooks.sol`, `PoolOperation.sol`, `BaseHook.sol`,
 and `HookMiner.sol` at those installed revisions. The links at the end are for
@@ -105,6 +111,13 @@ When the project's pinned dependency graph uses OpenZeppelin's hook library,
 override the internal `_before*` and `_after*` functions of its `BaseHook`. The
 inherited external entry points already enforce `onlyPoolManager`.
 
+The import path below assumes the `Uniswap/v4-template` remapping
+`@openzeppelin/uniswap-hooks/=lib/uniswap-hooks/`. OpenZeppelin's own README
+recommends `@openzeppelin/uniswap-hooks/=lib/uniswap-hooks/src/`, under which
+the same file is `@openzeppelin/uniswap-hooks/base/BaseHook.sol`. The path
+depends on your remapping; check it before treating a "file not found" as a
+missing dependency.
+
 ```solidity
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.26;
diff --git a/skills/uniswap-v4-testing/SKILL.md b/skills/uniswap-v4-testing/SKILL.md
index 1384fc8..f42583d 100644
--- a/skills/uniswap-v4-testing/SKILL.md
+++ b/skills/uniswap-v4-testing/SKILL.md
@@ -23,6 +23,7 @@ import {PoolKey} from "v4-core/src/types/PoolKey.sol";
 import {PoolId, PoolIdLibrary} from "v4-core/src/types/PoolId.sol";
 import {Currency, CurrencyLibrary} from "v4-core/src/types/Currency.sol";
 import {BalanceDelta} from "v4-core/src/types/BalanceDelta.sol";
+import {SwapParams, ModifyLiquidityParams} from "v4-core/src/types/PoolOperation.sol";
 import {Hooks} from "v4-core/src/libraries/Hooks.sol";
 import {TickMath} from "v4-core/src/libraries/TickMath.sol";
 import {StateLibrary} from "v4-core/src/libraries/StateLibrary.sol";
@@ -35,7 +36,7 @@ contract MyHookTest is Test, Deployers {
     using CurrencyLibrary for Currency;
 
     MyHook hook;
-    PoolKey key;
+    // `PoolKey key` is inherited from Deployers; redeclaring it is a DeclarationError
     PoolId poolId;
 
     function setUp() public {
@@ -51,7 +52,7 @@ contract MyHookTest is Test, Deployers {
 
         modifyLiquidityRouter.modifyLiquidity(
             key,
-            IPoolManager.ModifyLiquidityParams({
+            ModifyLiquidityParams({
                 tickLower: -120,
                 tickUpper: 120,
                 liquidityDelta: 10 ether,
@@ -78,7 +79,11 @@ contract MyHookTest is Test, Deployers {
 | `SQRT_PRICE_1_4` | `uint160` | sqrtPriceX96 for a 1:4 price ratio |
 | `SQRT_PRICE_4_1` | `uint160` | sqrtPriceX96 for a 4:1 price ratio |
 | `ZERO_BYTES` | `bytes` | Empty bytes constant for hookData |
-| `MAX_TICK_SPACING` | `int24` | Maximum allowed tick spacing |
+| `MIN_PRICE_LIMIT` | `uint160` | `TickMath.MIN_SQRT_PRICE + 1`, price limit for zeroForOne swaps |
+| `MAX_PRICE_LIMIT` | `uint160` | `TickMath.MAX_SQRT_PRICE - 1`, price limit for oneForZero swaps |
+| `LIQUIDITY_PARAMS` | `ModifyLiquidityParams` | Default add-liquidity params |
+| `REMOVE_LIQUIDITY_PARAMS` | `ModifyLiquidityParams` | Default remove-liquidity params |
+| `SWAP_PARAMS` | `SwapParams` | Default exact-input swap (`amountSpecified: -100`, zeroForOne) |
 
 ### Key Deployer Functions
 
@@ -98,7 +103,9 @@ deployFreshManager();
 Hook addresses encode permissions in their leading bits. `HookMiner` brute-forces a CREATE2 salt that produces an address with the correct bit pattern.
 
 ```solidity
-import {HookMiner} from "v4-periphery/src/utils/HookMiner.sol";
+// HookMiner left v4-periphery/src on 2026-02-06 (PR #510); it now lives under test/shared
+import {HookMiner} from "v4-periphery/test/shared/HookMiner.sol";
+// or: import {HookMiner} from "v4-hooks-public/src/utils/HookMiner.sol"; (byte-identical)
 
 function _deployHook() internal {
     uint160 flags = uint160(
@@ -162,9 +169,9 @@ function test_swapExactInput_zeroForOne() public {
 
     BalanceDelta delta = swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,  // positive = exact input
+            amountSpecified: -1 ether,  // negative = exact input
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({
@@ -187,17 +194,17 @@ function test_swapExactInput_zeroForOne() public {
 function test_swapExactOutput_oneForZero() public {
     BalanceDelta delta = swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: false,
-            amountSpecified: -0.5 ether,  // negative = exact output
+            amountSpecified: 0.5 ether,  // positive = exact output
             sqrtPriceLimitX96: TickMath.MAX_SQRT_PRICE - 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
         ZERO_BYTES
     );
 
-    assertEq(delta.amount0(), -0.5 ether, "should receive exactly 0.5 token0");
-    assertGt(delta.amount1(), 0, "should spend token1");
+    assertEq(delta.amount0(), 0.5 ether, "should receive exactly 0.5 token0");
+    assertLt(delta.amount1(), 0, "should spend token1");
 }
 ```
 
@@ -205,10 +212,10 @@ function test_swapExactOutput_oneForZero() public {
 
 | `zeroForOne` | `amountSpecified` | Meaning |
 |---|---|---|
-| `true` | `> 0` | Exact input of token0, receive token1 |
-| `true` | `< 0` | Receive exact output of token1, spend token0 |
-| `false` | `> 0` | Exact input of token1, receive token0 |
-| `false` | `< 0` | Receive exact output of token0, spend token1 |
+| `true` | `< 0` | Exact input of token0, receive token1 |
+| `true` | `> 0` | Receive exact output of token1, spend token0 |
+| `false` | `< 0` | Exact input of token1, receive token0 |
+| `false` | `> 0` | Receive exact output of token0, spend token1 |
 
 ### Price Limits
 
@@ -234,9 +241,9 @@ function testFuzz_swap(uint256 amountIn, bool zeroForOne) public {
 
     BalanceDelta delta = swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: zeroForOne,
-            amountSpecified: int256(amountIn),
+            amountSpecified: -int256(amountIn),  // negative = exact input
             sqrtPriceLimitX96: priceLimit
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -264,7 +271,7 @@ function test_addLiquidity() public {
 
     BalanceDelta delta = modifyLiquidityRouter.modifyLiquidity(
         key,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: -600,
             tickUpper: 600,
             liquidityDelta: 5 ether,
@@ -289,7 +296,7 @@ function test_removeLiquidity() public {
 
     BalanceDelta delta = modifyLiquidityRouter.modifyLiquidity(
         key,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: -120,
             tickUpper: 120,
             liquidityDelta: -5 ether,  // negative = remove
@@ -320,7 +327,7 @@ function test_addLiquidity_outOfRange() public {
 
     BalanceDelta delta = modifyLiquidityRouter.modifyLiquidity(
         key,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: tickLower,
             tickUpper: tickUpper,
             liquidityDelta: 1 ether,
@@ -344,9 +351,9 @@ function test_hookCalledOnSwap() public {
 
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -367,9 +374,9 @@ function test_hookReceivesCorrectParams() public {
     emit MyHook.BeforeSwapCalled(
         address(swapRouter),
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         hookData
@@ -377,9 +384,9 @@ function test_hookReceivesCorrectParams() public {
 
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -397,9 +404,9 @@ function test_hookReturnsDelta() public {
 
     BalanceDelta delta = swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -437,9 +444,9 @@ function test_poolStateAfterSwap() public {
 
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -457,7 +464,9 @@ function test_poolLiquidity() public {
     uint128 totalLiquidity = manager.getLiquidity(poolId);
     assertGt(totalLiquidity, 0, "pool should have liquidity from setUp");
 
-    uint128 positionLiquidity = manager.getPositionLiquidity(
+    // StateLibrary.getPositionLiquidity takes (poolId, bytes32 positionId); the
+    // owner/tick/salt form is getPositionInfo, which also returns fee growth
+    (uint128 positionLiquidity,,) = manager.getPositionInfo(
         poolId,
         address(modifyLiquidityRouter),
         -120,
@@ -485,7 +494,7 @@ function test_dynamicFeeHook() public {
 
     modifyLiquidityRouter.modifyLiquidity(
         dynamicKey,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: -120,
             tickUpper: 120,
             liquidityDelta: 10 ether,
@@ -497,9 +506,9 @@ function test_dynamicFeeHook() public {
     // Swap under normal conditions → expect base fee
     BalanceDelta delta1 = swapRouter.swap(
         dynamicKey,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 0.1 ether,
+            amountSpecified: -0.1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -511,9 +520,9 @@ function test_dynamicFeeHook() public {
 
     BalanceDelta delta2 = swapRouter.swap(
         dynamicKey,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 0.1 ether,
+            amountSpecified: -0.1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -531,19 +540,23 @@ function test_dynamicFeeHook() public {
 contract V4ForkTest is Test {
     using StateLibrary for IPoolManager;
 
-    IPoolManager constant PM = IPoolManager(0x000000000004444c5dc75cB358380D2e3de08A90);
+    // EIP-55 checksum matters: Solidity rejects a mixed-case literal with a wrong checksum
+    IPoolManager constant PM = IPoolManager(0x000000000004444c5dc75cB358380D2e3dE08A90);
 
     function setUp() public {
-        vm.createSelectFork(vm.envString("ETH_RPC_URL"), 21_000_000);
+        // The PoolManager first has code at block 21_688_329 (2025-01-23); fork after that
+        vm.createSelectFork(vm.envString("ETH_RPC_URL"), 23_000_000);
     }
 
     function test_productionPoolState() public view {
-        // Construct the key for an existing pool
+        // Canonical live pool: native ETH / USDC, 0.05% fee, tickSpacing 10, no hook
+        // PoolId 0x21c67e77068de97969ba93d4aab21826d33ca12bb9f565d8496e8fda8a82ca27
+        // (initialized at block 21_688_545 on 2025-01-23, so any later fork block works)
         PoolKey memory liveKey = PoolKey({
-            currency0: Currency.wrap(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48), // USDC
-            currency1: Currency.wrap(0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2), // WETH
-            fee: 3000,
-            tickSpacing: int24(60),
+            currency0: Currency.wrap(address(0)),                                  // native ETH
+            currency1: Currency.wrap(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48), // USDC
+            fee: 500,
+            tickSpacing: int24(10),
             hooks: IHooks(address(0))
         });
 
@@ -559,6 +572,18 @@ contract V4ForkTest is Test {
 }
 ```
 
+### L2 Fork (Unichain)
+
+PoolManager addresses differ per chain. On Unichain (chain ID 130, RPC `https://mainnet.unichain.org`) the PoolManager is `0x1F98400000000000000000000000000000000004` (verified with `cast code`); the Ethereum address has no code there.
+
+```solidity
+IPoolManager constant UNICHAIN_PM = IPoolManager(0x1F98400000000000000000000000000000000004);
+
+function setUp() public {
+    vm.createSelectFork(vm.envString("UNICHAIN_RPC_URL"));
+}
+```
+
 ## Gas Profiling
 
 ### CLI Commands
@@ -584,9 +609,9 @@ function test_hookGasOverhead() public {
     uint256 gasBefore = gasleft();
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -603,9 +628,9 @@ function test_compareGasWithAndWithoutHook() public {
     uint256 gasBefore = gasleft();
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 0.1 ether,
+            amountSpecified: -0.1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -620,7 +645,7 @@ function test_compareGasWithAndWithoutHook() public {
     manager.initialize(bareKey, SQRT_PRICE_1_1);
     modifyLiquidityRouter.modifyLiquidity(
         bareKey,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: -120, tickUpper: 120,
             liquidityDelta: 10 ether, salt: bytes32(0)
         }),
@@ -630,9 +655,9 @@ function test_compareGasWithAndWithoutHook() public {
     gasBefore = gasleft();
     swapRouter.swap(
         bareKey,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 0.1 ether,
+            amountSpecified: -0.1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -642,7 +667,8 @@ function test_compareGasWithAndWithoutHook() public {
 
     uint256 overhead = gasWithHook - gasWithoutHook;
     emit log_named_uint("hook overhead (gas)", overhead);
-    assertLt(overhead, 50_000, "hook gas overhead too high");
+    // There is no universal hook gas threshold: record the overhead with
+    // `forge snapshot` and review regressions with `forge snapshot --check`
 }
 ```
 
@@ -655,7 +681,7 @@ contract HookHandler is Test, Deployers {
     using PoolIdLibrary for PoolKey;
 
     MyHook public hook;
-    PoolKey public key;
+    // `key` is inherited from Deployers
 
     constructor(MyHook _hook, PoolKey memory _key) {
         hook = _hook;
@@ -671,9 +697,9 @@ contract HookHandler is Test, Deployers {
 
         try swapRouter.swap(
             key,
-            IPoolManager.SwapParams({
+            SwapParams({
                 zeroForOne: zeroForOne,
-                amountSpecified: int256(amount),
+                amountSpecified: -int256(amount),  // negative = exact input
                 sqrtPriceLimitX96: priceLimit
             }),
             PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -685,7 +711,7 @@ contract HookHandler is Test, Deployers {
         uint256 liquidity = bound(liquiditySeed, 1e16, 5 ether);
         try modifyLiquidityRouter.modifyLiquidity(
             key,
-            IPoolManager.ModifyLiquidityParams({
+            ModifyLiquidityParams({
                 tickLower: -600,
                 tickUpper: 600,
                 liquidityDelta: int256(liquidity),
@@ -705,7 +731,6 @@ contract MyHookInvariantTest is Test, Deployers {
     using PoolIdLibrary for PoolKey;
 
     MyHook hook;
-    PoolKey key;
     PoolId poolId;
     HookHandler handler;
 
@@ -720,7 +745,7 @@ contract MyHookInvariantTest is Test, Deployers {
 
         modifyLiquidityRouter.modifyLiquidity(
             key,
-            IPoolManager.ModifyLiquidityParams({
+            ModifyLiquidityParams({
                 tickLower: -600, tickUpper: 600,
                 liquidityDelta: 100 ether, salt: bytes32(0)
             }),
@@ -778,9 +803,9 @@ function test_hookDataPassedToBeforeSwap() public {
 
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -796,9 +821,9 @@ function test_emptyHookData() public {
     // Hook should handle empty hookData gracefully
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -818,9 +843,9 @@ function test_revert_uninitializedPool() public {
     vm.expectRevert();
     swapRouter.swap(
         badKey,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -832,7 +857,7 @@ function test_revert_swapZeroAmount() public {
     vm.expectRevert();
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
             amountSpecified: 0,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
@@ -848,9 +873,9 @@ function test_revert_hookCustomError() public {
     hook.setPaused(poolId, true);
     swapRouter.swap(
         key,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -874,7 +899,7 @@ function test_nativeETHPool() public {
 
     modifyLiquidityRouter.modifyLiquidity{value: 10 ether}(
         ethKey,
-        IPoolManager.ModifyLiquidityParams({
+        ModifyLiquidityParams({
             tickLower: -120,
             tickUpper: 120,
             liquidityDelta: 10 ether,
@@ -885,9 +910,9 @@ function test_nativeETHPool() public {
 
     swapRouter.swap{value: 1 ether}(
         ethKey,
-        IPoolManager.SwapParams({
+        SwapParams({
             zeroForOne: true,
-            amountSpecified: 1 ether,
+            amountSpecified: -1 ether,
             sqrtPriceLimitX96: TickMath.MIN_SQRT_PRICE + 1
         }),
         PoolSwapTest.TestSettings({takeClaims: false, settleUsingBurn: false}),
@@ -923,7 +948,6 @@ abstract contract HookTestBase is Test, Deployers {
     using StateLibrary for IPoolManager;
 
     MyHook hook;
-    PoolKey key;
     PoolId poolId;
 
     function setUp() public virtual {
@@ -951,7 +975,7 @@ abstract contract HookTestBase is Test, Deployers {
     function _seedLiquidity() internal {
         modifyLiquidityRouter.modifyLiquidity(
             key,
-            IPoolManager.ModifyLiquidityParams({
+            ModifyLiquidityParams({
                 tickLower: -600, tickUpper: 600,
                 liquidityDelta: 100 ether, salt: bytes32(0)
             }),
@@ -962,9 +986,9 @@ abstract contract HookTestBase is Test, Deployers {
     function _swapExactIn(bool zeroForOne, uint256 amount) internal returns (BalanceDelta) {
         return swapRouter.swap(
             key,
-            IPoolManager.SwapParams({
+            SwapParams({
                 zeroForOne: zeroForOne,
-                amountSpecified: int256(amount),
+                amountSpecified: -int256(amount),  // negative = exact input
                 sqrtPriceLimitX96: zeroForOne
                     ? TickMath.MIN_SQRT_PRICE + 1
                     : TickMath.MAX_SQRT_PRICE - 1
@@ -996,7 +1020,7 @@ abstract contract HookTestBase is Test, Deployers {
 - [ ] **Delta returns**: hooks with RETURNS_DELTA flags modify swap/liquidity amounts correctly
 - [ ] **Revert paths**: invalid inputs, paused states, and unauthorized access revert correctly
 - [ ] **Native ETH**: pool with `Currency.wrap(address(0))` works with hook
-- [ ] **Gas overhead**: hook callbacks measured under 50K gas each via `forge snapshot`
+- [ ] **Gas overhead**: hook callback overhead measured and documented via `forge snapshot` (no universal threshold; review regressions with `--check`)
 - [ ] **Gas comparison**: overhead vs no-hook pool documented
 - [ ] **Invariant: PM solvency**: PoolManager balances never go negative
 - [ ] **Invariant: price bounds**: sqrtPriceX96 stays within [MIN, MAX]