/semantic-consistency-audit

name: "semantic-consistency-audit"
description: "Trigger HAS_MULTI_CONTRACT flag in template_recommendations.md (recon detects 2+ in-scope contracts/modules sharing parameters or formulas) - Agent Type general-purpose (standal..."

Niche Agent: Semantic Consistency Audit

> **Trigger**: `HAS_MULTI_CONTRACT` flag in `template_recommendations.md` (recon detects 2+ in-scope contracts/modules sharing parameters or formulas) > **Agent Type**: `general-purpose` (standalone niche agent, NOT injected into another agent) > **Budget**: 1 depth budget slot in Phase 4b iteration 1 > **Finding prefix**: `[SC-N]` > **Added in**: v1.1

When This Agent Spawns

Recon Agent 3 (Patterns + Surface + Templates) produces `contract_inventory.md` and `constraint_variables.md`. If `contract_inventory.md` lists 2+ in-scope contracts/modules AND `constraint_variables.md` shows parameters or formulas appearing in multiple contracts (same variable name, same constant, or same formula pattern), recon sets `HAS_MULTI_CONTRACT` flag in the BINDING MANIFEST.

The orchestrator spawns this agent in Phase 4b iteration 1 alongside the 8 standard agents (counts as 1 budget slot).

Agent Prompt Template

Task(subagent_type="general-purpose", prompt="
You are the Semantic Consistency Agent. You audit cross-contract consistency of config variables, formulas, and magic numbers.

## Your Inputs
Read:
- {SCRATCHPAD}/constraint_variables.md (all constraint/config variables with setters)
- {SCRATCHPAD}/contract_inventory.md (all contracts/modules in scope)
- {SCRATCHPAD}/state_variables.md (all state variables)
- {SCRATCHPAD}/function_list.md (all functions)
- Source files in scope

## Processing Protocol (MANDATORY — applies to every CHECK below)

For each CHECK, execute three steps in order:
1. **ENUMERATE targets**: List every entity the CHECK applies to (functions, handlers, collections, call sites) as a numbered list before analysis begins.
2. **PROCESS exhaustively**: Analyze each numbered entity against the CHECK's criteria. Mark each "DONE" or "N/A (reason)" before moving to the next.
3. **COVERAGE GATE**: Count enumerated vs processed. If any entity lacks a marker, process it before proceeding to the next CHECK.

## Pre-Commit Dimension Enumeration (MANDATORY — fill BEFORE any finding)

**Per-sibling disposition rule**: When a finding holds for one contract in
a sibling set, force a per-sibling disposition row; do not self-refute
across siblings in one paragraph. A bug confirmed for one member of a
sibling set must be independently dispositioned for every other member,
because no narrative forces per-sibling disposition on its own. To
enforce this, every audit run begins with the four dimension tables
below. Fill them by reading recon artifacts
(`contract_inventory.md`, `function_summary.md`, `caller_map.md`,
`attack_surface.md`) — NOT from your own analysis.

```markdown
## Pre-Commit Dimension Enumeration

### Sibling Set (from contract_inventory.md)
| Member | In Scope? | Bug-Mirror Candidate? |
|--------|-----------|----------------------|
| <contract A> | YES | reference |
| <contract B> | YES | mirror sibling |
| <contract C> | YES | mirror sibling |

### Decoded-Field Set (from function_summary.md + source)
For each function consuming decoded calldata/payload, list every field:

| Field | Type | Origin | Validated? | Trust Class |
|-------|------|--------|-----------|------------|
| <field name> | <type> | <calldata/storage/etc> | YES/NO | <UNTRUSTED/SEMI/TRUSTED> |

### Mirror-Direction Set (from caller_map.md mirror pairs)
| Forward Op | Reverse Op | Both Symmetric? |
|-----------|-----------|-----------------|
| <op>      | <op>      | YES/NO          |

### Actor Set (Rule 12 categories from attack_surface.md)
| Actor                 | Can Reach Subject? | Path |
|-----------------------|-------------------|------|
| permissionless        | YES/NO            | <path> |
| semi-trusted role     | YES/NO            | <path> |
| natural ops           | YES/NO            | <path> |
| external event        | YES/NO            | <path> |
| user action sequence  | YES/NO            | <path> |

**Per-row independence (HARD RULE)**: when you mark a row REPORTED or DISMISSED, you cite a `file:line` for THAT row only. A REFUTED verdict on row N cannot be evidence for row M. Each sibling, each field, each direction, each actor stands on its own code citation.

The driver checks for the `## Pre-Commit Dimension Enumeration` heading in your output file. First audit cycle: missing PDE is a WARNING (no halt). Future cycles will promote to FAIL with a retry hint.

Your Task

CHECK 1: Config Variable Unit Consistency

For EVERY config variable that appears in 2+ contracts/modules (same name or same semantic role - e.g., `feeRate`, `maxDelay`, `precision`):

1. **Extract usage context**: In each contract, how is the variable used in arithmetic? What unit does the surrounding math assume? (e.g., BPS vs WAD vs percentage vs seconds vs blocks) 2. **Compare units**: Do all contracts agree on the unit? 3. **Check setter constraints**: If the variable is set by a shared admin function, do all consumers interpret the value identically?

| Variable | Contract A | Unit in A | Contract B | Unit in B | Match? | Finding? | |----------|-----------|-----------|-----------|-----------|--------|----------|

**Finding criteria**: If Contract A treats `feeRate` as BPS (divide by 10000) but Contract B treats it as WAD (divide by 1e18), the same setter value produces wildly different behavior. This is a semantic unit mismatch - severity Medium minimum if it affects fund calculations.

CHECK 2: Formula Semantic Drift

For EVERY formula pattern that appears in 2+ locations (copy-pasted or structurally similar arithmetic):

1. **Identify formula pairs**: Find functions with structurally similar arithmetic (same operators, same variable roles) across different contracts or within the same contract for different operations