# Simulation Evidence Store

This document defines how `simulation_acceleration` writes project-local
simulation evidence for AI agents.

## Purpose

`simulation_acceleration` is the fast verification layer in the Vivado AI MCP
tool suite. It should give agents compact pass/fail evidence before they spend
time and tokens on full Vivado/xsim or implementation flows.

It does not replace Vivado. It provides a fast path for RTL smoke tests,
cocotb-based checks, Verilator lint/simulation, and other small simulation loops.

## Output Directory

Simulation evidence is written under the project being simulated:

```text
.vivado_ai_mcp/
  simulation/
    runs/
      <timestamp>_<run_name>/
        manifest.json
        summary.json
        failures.json
        raw/
          stdout.log
          stderr.log
  evidence/
    index.json
    latest.json
```

Agents should read `summary.json` first. If the run failed, read
`failures.json` next. Raw logs should be read only when the compact summaries are
not enough.

## Generic Runner

Use `scripts/run_with_evidence.py` to wrap a simulation command:

```powershell
python scripts\run_with_evidence.py `
  --project-root path\to\project `
  --run-name smoke_counter_icarus `
  --tool cocotb_icarus `
  -- python path\to\run_icarus.py
```

The wrapper preserves the simulation command exit code and writes:

- `manifest.json`: run metadata and output paths
- `summary.json`: compact status, command, duration, stdout/stderr tails
- `failures.json`: matched failure/error/assertion lines
- `raw/stdout.log`: full stdout
- `raw/stderr.log`: full stderr
- `evidence/index.json`: project-local evidence catalog
- `evidence/latest.json`: pointer to the latest simulation summary

## Current Smoke Scripts

The following scripts use the generic evidence runner:

```powershell
scripts\run_smoke_counter.ps1
scripts\run_smoke_counter_verilator.ps1
scripts\run_smoke_counter_verilator_cpp.ps1
```

## Agent Reading Rules

Agents should:

- read `.vivado_ai_mcp/evidence/latest.json` after a run
- read the latest simulation `summary.json`
- read `failures.json` for failed runs
- read raw logs only on demand
- compare multiple run summaries before repeating expensive work

Agents should not:

- paste full logs into the conversation by default
- treat open-source simulation as authoritative for Xilinx IP or block design behavior
- run full Vivado/xsim before a smaller relevant smoke test when a fast test exists

## Relationship To Other Tools

- Use `vivado_context_mcp` first to locate the relevant RTL, testbench, IP, and top-level context.
- Use `simulation_acceleration` for fast functional feedback.
- Use `vivado_mcp` or `vivado_mcp_pro` when Vivado-authoritative behavior is required.
- Use `vivado_debug_mcp` later for ILA/VIO and board-level capture evidence.
