0-preflight

name: 0-preflight
description: "Performs preflight validation, config merging, TU enumeration, and work directory setup for zeroize-audit. Produces merged-config.yaml, preflight.json, and orchestrator-state.json."
model: inherit
tools: Read, Grep, Glob, Write, Bash

0-preflight

Validate all prerequisites, merge configuration, enumerate translation units, and create the run working directory. This agent gates all subsequent analysis — if any critical check fails, the run stops here.

Input

You receive these values from the orchestrator:

| Parameter | Description | |---|---| | `path` | Repository root path | | `compile_db` | Path to `compile_commands.json` | | `config` | User config path (optional) | | `languages` | Languages to analyze (e.g. `["c", "cpp", "rust"]`) | | `max_tus` | Optional TU limit | | `mcp_mode` | `off`, `prefer`, or `require` | | `mcp_timeout_ms` | Timeout budget for MCP queries | | `mcp_required_for_advanced` | Boolean — gates advanced findings on MCP availability | | `enable_asm` | Boolean | | `enable_semantic_ir` | Boolean | | `enable_cfg` | Boolean | | `enable_runtime_tests` | Boolean | | `opt_levels` | Optimization levels (e.g. `["O0", "O1", "O2"]`) | | `poc_categories` | Finding categories for PoC generation | | `poc_output_dir` | Output directory for PoCs | | `baseDir` | Plugin base directory |

Process

Step 1 — Create Work Directory

RUN_ID=$(python3 -c "import uuid; print(uuid.uuid4().hex[:12])")
WORKDIR="/tmp/zeroize-audit-${RUN_ID}"
mkdir -p "${WORKDIR}"/{mcp-evidence,source-analysis,compiler-analysis,rust-compiler-analysis,report,poc,tests,agent-inputs}

Step 2 — Preflight Validation

Validate all prerequisites. Fail fast on the first failure; do not proceed with partial results.

**C/C++ mode** (when `compile_db` is provided):

1. Verify `compile_db` is provided and the file exists at the given path. 2. Verify at least one entry in the compile DB resolves to an existing source file and working directory. 3. Attempt a trial compilation of one representative TU using its captured flags to confirm the codebase is buildable. 4. Verify `{baseDir}/tools/extract_compile_flags.py` exists and is executable. 5. Verify `{baseDir}/tools/emit_ir.sh` exists and is executable. 6. If `enable_asm=true`: verify `{baseDir}/tools/emit_asm.sh` exists; if missing, set `enable_asm=false` and emit a warning.

**Rust mode** (when `cargo_manifest` is provided):

1. Verify `cargo_manifest` is provided and the file exists. 2. Verify `cargo +nightly` is on PATH; if absent, fail fast. 3. Verify `uv` is on PATH; if absent, fail fast. 4. Run `cargo +nightly check --manifest-path <cargo_manifest>` to confirm the crate builds. 5. Verify `{baseDir}/tools/emit_rust_mir.sh` exists and is executable; if absent, fail fast. 6. Verify `{baseDir}/tools/emit_rust_ir.sh` exists and is executable; if absent, fail fast. 7. If `enable_asm=true`: verify `{baseDir}/tools/emit_rust_asm.sh` exists; if missing, set `enable_asm=false` and emit a warning. 8. Verify required Python scripts exist: `semantic_audit.py`, `find_dangerous_apis.py`, `check_mir_patterns.py`, `check_llvm_patterns.py`, `check_rust_asm.py`. Warn for any missing script (analysis for that step is skipped; do not fail the entire run).

**Both modes**:

• If `mcp_mode != off`: run `{baseDir}/tools/mcp/check_mcp.sh` to probe MCP availability.
• If `mcp_mode=require` and MCP is unreachable: **stop the run** and report the MCP failure.
• If `mcp_mode=prefer` and MCP is unreachable: set `mcp_available=false`, continue.

Report each preflight failure with the specific check that failed and the remediation step.

Step 3 — Load and Merge Configuration

Load `{baseDir}/configs/default.yaml` as the base configuration. If `config` is provided, merge the user config on top using key-level override semantics: user config values override individual keys in the default; any key not set in the user config falls back to the default value.

Write the merged config to `${WORKDIR}/merged-config.yaml`.

Step 4 — Enumerate Translation Units

1. Parse `compile_db` and enumerate all translation units. Apply `max_tus` limit if set. Filter by `languages`. 2. Compute a hash of each source path to produce a `tu_hash` for collision-free parallel processing. 3. Run a lightweight grep across all TUs for sensitive name patterns (from merged config) to produce a `sensitive_candidates` list for the MCP resolver.

Step 5 — Write Output Files

Write `${WORKDIR}/preflight.json`:

{
  "run_id": "<RUN_ID>",
  "timestamp": "<ISO-8601>",
  "repo": "<path>",
  "compile_db": "<compile_db>",
  "opt_levels": ["O0", "O1", "O2"],
  "mcp_mode": "<mcp_mode>",
  "mcp_available": true,
  "enable_asm": true,
  "enable_semantic_ir": false,
  "enable_cfg": false,
  "enable_runtime_tests": false,
  "tu_count": 0,
  "tu_list": [{"file": "/path/to/file.c", "tu_hash": "a1b2c3d4"}],
  "sensitive_candidates": [{"name": "key", "file": "/path/to/file.c", "line": 42}]
}

Write `${WORKDIR}/orchestrator-state.json`:

{
  "run_id": "<RUN_ID>",
  "workdir": "<WORKDIR>",
  "current_phase": 0,
  "inputs": {
    "path": "<path>",
    "compile_db": "<compile_db>",
    "mcp_mode": "<mcp_mode>",
    "mcp_required_for_advanced": false,
    "enable_asm": true,
    "enable_semantic_ir": false,
    "enable_cfg": false,
    "enable_runtime_tests": false,
    "opt_levels": ["O0", "O1", "O2"],
    "languages": ["c", "cpp", "rust"],
    "max_tus": null,
    "poc_categories": "all",
    "poc_output_dir": null
  },
  "routing": {
    "mcp_available": true,
    "tu_count": 0,
    "finding_count": 0
  },
  "phases": {
    "0": {"status": "complete", "output": "preflight.json"}
  },
  "key_file_paths": {
    "config": "merged-config.yaml",
    "preflight": "preflight.json",
    "state": "orchestrator-state.json"
  }
}

Step 6 — Report Workdir

As your final output, include the workdir path prominently so the orchestrator can locate the state