@vigolium/piolium 0.0.1

package/skills/zeroize-audit/tools/track_dataflow.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Track data-flow of sensitive variables to detect untracked copies.
+#
+# Usage:
+#   track_dataflow.sh --src path/to/file.c --config config.yaml --out /tmp/dataflow.json
+#
+# Detects:
+# - memcpy/memmove of sensitive buffers
+# - Struct assignments (potential copies)
+# - Function arguments passed by value
+# - Return by value (secrets in return values)
+
+usage() {
+  echo "Usage: $0 --src <file> --out <analysis.json> [--config <config.yaml>]" >&2
+}
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\t'/\\t}"
+  printf '%s' "$s"
+}
+
+SRC=""
+CONFIG=""
+OUT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --src)
+      SRC="$2"
+      shift 2
+      ;;
+    --config)
+      CONFIG="$2"
+      shift 2
+      ;;
+    --out)
+      OUT="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$SRC" || -z "$OUT" ]]; then
+  usage
+  exit 2
+fi
+
+if [[ ! -f "$SRC" ]]; then
+  echo "Source file not found: $SRC" >&2
+  exit 2
+fi
+
+# Load sensitive name patterns from config (if provided)
+SENSITIVE_PATTERN="(secret|key|seed|priv|private|sk|shared_secret|nonce|token|pwd|pass)"
+if [[ -n "$CONFIG" ]] && [[ -f "$CONFIG" ]]; then
+  # Extract patterns from YAML (POSIX-compatible, no grep -P)
+  PATTERNS=$(grep -A 20 "^sensitive_name_regex:" "$CONFIG" | sed -n 's/.*"\([^"]*\)".*/\1/p' | head -1 || echo "")
+  if [[ -n "$PATTERNS" ]]; then
+    SENSITIVE_PATTERN="$PATTERNS"
+  else
+    echo "WARNING: config file provided but no patterns extracted from $CONFIG" >&2
+  fi
+fi
+
+# Arrays to collect findings
+MEMCPY_COPIES=()
+STRUCT_ASSIGNS=()
+FUNC_ARGS=()
+RETURN_VALUES=()
+RETURN_RE='return[[:space:]]+([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*;'
+CALL_RE='([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*\(([^)]*)\)'
+
+# Parse source code
+LINE_NUM=0
+IN_FUNCTION=""
+
+while IFS= read -r line; do
+  ((LINE_NUM++))
+
+  # Skip comments (simple heuristic)
+  [[ "$line" =~ ^[[:space:]]*// ]] && continue
+  [[ "$line" =~ ^[[:space:]]*\* ]] && continue
+
+  # Track function boundaries
+  if [[ "$line" =~ ^[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]+([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*\( ]]; then
+    IN_FUNCTION="${BASH_REMATCH[1]}"
+  fi
+
+  # Detect memcpy/memmove of sensitive data
+  if [[ "$line" =~ (memcpy|memmove)[[:space:]]*\([^,]*,[[:space:]]*([a-zA-Z_][a-zA-Z0-9_]*) ]]; then
+    FUNC="${BASH_REMATCH[1]}"
+    SRC_VAR="${BASH_REMATCH[2]}"
+    if [[ "$SRC_VAR" =~ $SENSITIVE_PATTERN ]]; then
+      MEMCPY_COPIES+=("{\"line\": $LINE_NUM, \"function\": \"$FUNC\", \"variable\": \"$SRC_VAR\", \"context\": \"$(json_escape "$line")\"}")
+    fi
+  fi
+
+  # Detect struct assignments (potential copies)
+  if [[ "$line" =~ ([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*=[[:space:]]*\*([a-zA-Z_][a-zA-Z0-9_]*) ]]; then
+    DEST="${BASH_REMATCH[1]}"
+    MATCH_SRC="${BASH_REMATCH[2]}"
+    if [[ "$MATCH_SRC" =~ $SENSITIVE_PATTERN ]] || [[ "$DEST" =~ $SENSITIVE_PATTERN ]]; then
+      STRUCT_ASSIGNS+=("{\"line\": $LINE_NUM, \"dest\": \"$DEST\", \"source\": \"$MATCH_SRC\", \"context\": \"$(json_escape "$line")\"}")
+    fi
+  fi
+
+  # Detect return by value
+  if [[ "$line" =~ $RETURN_RE ]]; then
+    RET_VAR="${BASH_REMATCH[1]}"
+    if [[ "$RET_VAR" =~ $SENSITIVE_PATTERN ]]; then
+      RETURN_VALUES+=("{\"line\": $LINE_NUM, \"function\": \"$IN_FUNCTION\", \"variable\": \"$RET_VAR\", \"context\": \"$(json_escape "$line")\"}")
+    fi
+  fi
+
+  # Detect function calls with sensitive arguments (simple heuristic)
+  if [[ "$line" =~ $CALL_RE ]]; then
+    CALLED_FUNC="${BASH_REMATCH[1]}"
+    ARGS="${BASH_REMATCH[2]}"
+    # Check if any argument matches sensitive pattern
+    if [[ "$ARGS" =~ $SENSITIVE_PATTERN ]]; then
+      # Extract variable names from arguments
+      for arg in ${ARGS//,/ }; do
+        arg="${arg#"${arg%%[! ]*}"}" # trim leading spaces
+        arg="${arg%"${arg##*[! ]}"}" # trim trailing spaces
+        if [[ "$arg" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]] && [[ "$arg" =~ $SENSITIVE_PATTERN ]]; then
+          FUNC_ARGS+=("{\"line\": $LINE_NUM, \"called_function\": \"$CALLED_FUNC\", \"argument\": \"$arg\", \"context\": \"$(json_escape "$line")\"}")
+        fi
+      done
+    fi
+  fi
+
+done <"$SRC"
+
+# Generate JSON report
+mkdir -p "$(dirname "$OUT")"
+
+cat >"$OUT" <<EOF
+{
+  "source_file": "$SRC",
+  "sensitive_pattern": "$SENSITIVE_PATTERN",
+  "findings": {
+    "memcpy_copies": [
+      $(
+  IFS=,
+  echo "${MEMCPY_COPIES[*]}"
+)
+    ],
+    "struct_assignments": [
+      $(
+  IFS=,
+  echo "${STRUCT_ASSIGNS[*]}"
+)
+    ],
+    "function_arguments": [
+      $(
+  IFS=,
+  echo "${FUNC_ARGS[*]}"
+)
+    ],
+    "return_values": [
+      $(
+  IFS=,
+  echo "${RETURN_VALUES[*]}"
+)
+    ]
+  },
+  "summary": {
+    "total_copies": $((${#MEMCPY_COPIES[@]} + ${#STRUCT_ASSIGNS[@]} + ${#FUNC_ARGS[@]} + ${#RETURN_VALUES[@]})),
+    "memcpy_count": ${#MEMCPY_COPIES[@]},
+    "struct_assign_count": ${#STRUCT_ASSIGNS[@]},
+    "func_arg_count": ${#FUNC_ARGS[@]},
+    "return_value_count": ${#RETURN_VALUES[@]}
+  }
+}
+EOF
+
+# Validate JSON output
+if command -v jq &>/dev/null; then
+  if ! jq empty "$OUT" 2>/dev/null; then
+    echo "ERROR: generated JSON is malformed: $OUT" >&2
+    exit 1
+  fi
+fi
+
+echo "OK: data-flow analysis written to $OUT"

package/skills/zeroize-audit/tools/validate_rust_toolchain.sh

@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+# validate_rust_toolchain.sh — Preflight check for Rust zeroize-audit prerequisites.
+#
+# Validates that all tools required by the Rust analysis pipeline are available
+# and functional. Outputs a JSON status report.
+#
+# Exit codes:
+#   0  all required tools available (warnings may still be present)
+#   1  at least one required tool is missing
+#   2  argument error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  validate_rust_toolchain.sh [options]
+
+Options:
+  --manifest <Cargo.toml>  Check that the manifest exists and the crate builds
+  --json                   Output machine-readable JSON (default: human-readable)
+  --help                   Show this help text
+
+Checks (required):
+  - cargo on PATH
+  - cargo +nightly available
+  - uv on PATH (for Python analysis scripts)
+
+Checks (optional, warning only):
+  - rustfilt on PATH (for symbol demangling)
+  - cargo-expand on PATH (for macro expansion debugging)
+
+If --manifest is provided, additionally:
+  - Manifest file exists
+  - cargo check passes for the crate
+EOF
+}
+
+die_arg() {
+  echo "validate_rust_toolchain.sh: $*" >&2
+  exit 2
+}
+
+MANIFEST=""
+JSON_OUTPUT=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --manifest)
+      [[ -n "${2-}" ]] || die_arg "missing value for --manifest"
+      MANIFEST="$2"
+      shift 2
+      ;;
+    --json)
+      JSON_OUTPUT=true
+      shift
+      ;;
+    --help | -h)
+      usage
+      exit 0
+      ;;
+    *)
+      die_arg "unknown argument: $1"
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Tool checks
+# ---------------------------------------------------------------------------
+
+declare -A TOOL_STATUS
+declare -A TOOL_VERSION
+ERRORS=()
+WARNINGS=()
+
+check_tool() {
+  local name="$1"
+  local required="$2"
+  local cmd="${3:-$name}"
+
+  if command -v "$cmd" &>/dev/null; then
+    TOOL_STATUS["$name"]="present"
+    local ver
+    # Use a separate variable so we can distinguish a version-check failure
+    # (e.g. shared-library missing) from the tool simply not being on PATH.
+    if ver=$("$cmd" --version 2>/dev/null | head -1); then
+      TOOL_VERSION["$name"]="$ver"
+    else
+      TOOL_VERSION["$name"]="(version check failed)"
+      WARNINGS+=("$name is present but '--version' failed — tool may be broken")
+    fi
+  else
+    if [[ "$required" == "true" ]]; then
+      TOOL_STATUS["$name"]="missing"
+      ERRORS+=("$name is required but not found on PATH")
+    else
+      TOOL_STATUS["$name"]="missing"
+      WARNINGS+=("$name is not found on PATH (optional: ${4:-enhanced analysis})")
+    fi
+  fi
+}
+
+check_tool "cargo" "true"
+check_tool "uv" "true"
+check_tool "rustfilt" "false" "rustfilt" "Rust symbol demangling in assembly analysis"
+check_tool "cargo-expand" "false" "cargo-expand" "macro expansion debugging"
+
+# Check cargo +nightly
+NIGHTLY_STATUS="unavailable"
+NIGHTLY_VERSION="unknown"
+if [[ "${TOOL_STATUS[cargo]}" == "present" ]]; then
+  if cargo +nightly --version &>/dev/null 2>&1; then
+    NIGHTLY_STATUS="available"
+    NIGHTLY_VERSION=$(cargo +nightly --version 2>/dev/null | head -1 || echo "unknown")
+  else
+    NIGHTLY_STATUS="unavailable"
+    ERRORS+=("cargo +nightly is required but the nightly toolchain is not installed (run: rustup toolchain install nightly)")
+  fi
+fi
+
+# Check that emit/analysis scripts exist
+declare -A SCRIPT_STATUS
+REQUIRED_SCRIPTS=(
+  "emit_rust_mir.sh"
+  "emit_rust_ir.sh"
+  "emit_rust_asm.sh"
+)
+OPTIONAL_SCRIPTS=(
+  "diff_rust_mir.sh"
+  "scripts/check_mir_patterns.py"
+  "scripts/check_llvm_patterns.py"
+  "scripts/check_rust_asm.py"
+  "scripts/semantic_audit.py"
+  "scripts/find_dangerous_apis.py"
+)
+
+for script in "${REQUIRED_SCRIPTS[@]}"; do
+  if [[ -f "$SCRIPT_DIR/$script" ]]; then
+    SCRIPT_STATUS["$script"]="present"
+  else
+    SCRIPT_STATUS["$script"]="missing"
+    ERRORS+=("required script $script not found at $SCRIPT_DIR/$script")
+  fi
+done
+
+for script in "${OPTIONAL_SCRIPTS[@]}"; do
+  if [[ -f "$SCRIPT_DIR/$script" ]]; then
+    SCRIPT_STATUS["$script"]="present"
+  else
+    SCRIPT_STATUS["$script"]="missing"
+    WARNINGS+=("optional script $script not found at $SCRIPT_DIR/$script")
+  fi
+done
+
+# Check manifest and crate build (if requested)
+MANIFEST_STATUS="not_checked"
+BUILD_STATUS="not_checked"
+if [[ -n "$MANIFEST" ]]; then
+  if [[ -f "$MANIFEST" ]]; then
+    MANIFEST_STATUS="present"
+    if [[ "$NIGHTLY_STATUS" == "available" ]]; then
+      cargo_err=$(mktemp) || {
+        ERRORS+=("mktemp failed — cannot capture cargo output")
+        cargo_err="/dev/null"
+      }
+      if cargo +nightly check --manifest-path "$MANIFEST" 2>"$cargo_err"; then
+        BUILD_STATUS="pass"
+      else
+        BUILD_STATUS="fail"
+        # Include up to 20 lines of cargo output so callers can diagnose
+        # the failure without re-running manually.
+        cargo_snippet=$(head -20 "$cargo_err" 2>/dev/null | tr '\n' ' ')
+        ERRORS+=("cargo check failed for $MANIFEST: ${cargo_snippet:-see stderr}")
+      fi
+      rm -f "$cargo_err"
+    else
+      BUILD_STATUS="skipped"
+      WARNINGS+=("cargo check skipped (nightly not available)")
+    fi
+  else
+    MANIFEST_STATUS="missing"
+    ERRORS+=("manifest not found: $MANIFEST")
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Output
+# ---------------------------------------------------------------------------
+
+OVERALL_STATUS="ready"
+[[ ${#ERRORS[@]} -gt 0 ]] && OVERALL_STATUS="blocked"
+
+if [[ "$JSON_OUTPUT" == true ]]; then
+  # Build tool statuses as JSON
+  TOOLS_JSON="{"
+  first=true
+  for name in cargo uv rustfilt cargo-expand; do
+    [[ "$first" == true ]] && first=false || TOOLS_JSON+=","
+    TOOLS_JSON+="\"$name\":{\"status\":\"${TOOL_STATUS[$name]:-unknown}\",\"version\":\"${TOOL_VERSION[$name]:-unknown}\"}"
+  done
+  TOOLS_JSON+="}"
+
+  # Build script statuses as JSON
+  SCRIPTS_JSON="{"
+  first=true
+  for script in "${REQUIRED_SCRIPTS[@]}" "${OPTIONAL_SCRIPTS[@]}"; do
+    [[ "$first" == true ]] && first=false || SCRIPTS_JSON+=","
+    SCRIPTS_JSON+="\"$script\":\"${SCRIPT_STATUS[$script]:-unknown}\""
+  done
+  SCRIPTS_JSON+="}"
+
+  # Build errors/warnings arrays using Python for correct JSON escaping.
+  # The sed-based approach only escaped double quotes but not backslashes,
+  # newlines, or control characters — all of which can appear in cargo output.
+  _json_str_array() {
+    # Read lines from stdin, emit a JSON array of properly escaped strings.
+    python3 -c '
+import json, sys
+items = [l.rstrip("\n") for l in sys.stdin]
+print(json.dumps(items))
+'
+  }
+  ERRORS_JSON=$(printf '%s\n' "${ERRORS[@]+"${ERRORS[@]}"}" | _json_str_array)
+  WARNINGS_JSON=$(printf '%s\n' "${WARNINGS[@]+"${WARNINGS[@]}"}" | _json_str_array)
+
+  cat <<EOF
+{
+  "status": "$OVERALL_STATUS",
+  "tools": $TOOLS_JSON,
+  "nightly": {"status": "$NIGHTLY_STATUS", "version": "$NIGHTLY_VERSION"},
+  "scripts": $SCRIPTS_JSON,
+  "manifest": {"status": "$MANIFEST_STATUS", "build": "$BUILD_STATUS"},
+  "errors": $ERRORS_JSON,
+  "warnings": $WARNINGS_JSON
+}
+EOF
+else
+  echo "=== Rust Toolchain Validation ==="
+  echo ""
+  echo "Tools:"
+  for name in cargo uv rustfilt cargo-expand; do
+    status="${TOOL_STATUS[$name]:-unknown}"
+    version="${TOOL_VERSION[$name]:-}"
+    if [[ "$status" == "present" ]]; then
+      echo "  [OK]   $name ($version)"
+    else
+      echo "  [MISS] $name"
+    fi
+  done
+  echo ""
+  echo "Nightly: $NIGHTLY_STATUS ($NIGHTLY_VERSION)"
+  echo ""
+  echo "Scripts:"
+  for script in "${REQUIRED_SCRIPTS[@]}"; do
+    status="${SCRIPT_STATUS[$script]:-unknown}"
+    if [[ "$status" == "present" ]]; then
+      echo "  [OK]   $script"
+    else
+      echo "  [MISS] $script (required)"
+    fi
+  done
+  for script in "${OPTIONAL_SCRIPTS[@]}"; do
+    status="${SCRIPT_STATUS[$script]:-unknown}"
+    if [[ "$status" == "present" ]]; then
+      echo "  [OK]   $script"
+    else
+      echo "  [MISS] $script (optional)"
+    fi
+  done
+
+  if [[ -n "$MANIFEST" ]]; then
+    echo ""
+    echo "Manifest: $MANIFEST ($MANIFEST_STATUS)"
+    echo "Build:    $BUILD_STATUS"
+  fi
+
+  if [[ ${#ERRORS[@]} -gt 0 ]]; then
+    echo ""
+    echo "ERRORS:"
+    for err in "${ERRORS[@]}"; do
+      echo "  - $err"
+    done
+  fi
+  if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+    echo ""
+    echo "WARNINGS:"
+    for warn in "${WARNINGS[@]}"; do
+      echo "  - $warn"
+    done
+  fi
+  echo ""
+  echo "Overall: $OVERALL_STATUS"
+fi
+
+[[ "$OVERALL_STATUS" == "ready" ]]

package/skills/zeroize-audit/workflows/phase-0-preflight.md

@@ -0,0 +1,150 @@
+# Phase 0 — Preflight, Configuration, and Work Directory
+
+## Preconditions
+
+None — this is the first phase.
+
+## Instructions
+
+Spawn agent `0-preflight` via `Task` with:
+
+| Parameter | Value |
+|---|---|
+| `path` | `{{path}}` |
+| `compile_db` | `{{compile_db}}` |
+| `cargo_manifest` | `{{cargo_manifest}}` |
+| `config` | `{{config}}` |
+| `languages` | `{{languages}}` |
+| `max_tus` | `{{max_tus}}` |
+| `mcp_mode` | `{{mcp_mode}}` |
+| `mcp_timeout_ms` | `{{mcp_timeout_ms}}` |
+| `mcp_required_for_advanced` | `{{mcp_required_for_advanced}}` |
+| `enable_asm` | `{{enable_asm}}` |
+| `enable_semantic_ir` | `{{enable_semantic_ir}}` |
+| `enable_cfg` | `{{enable_cfg}}` |
+| `enable_runtime_tests` | `{{enable_runtime_tests}}` |
+| `opt_levels` | `{{opt_levels}}` |
+| `poc_categories` | `{{poc_categories}}` |
+| `poc_output_dir` | `{{poc_output_dir}}` |
+| `baseDir` | `{baseDir}` |
+
+The agent creates the work directory, runs all preflight checks, merges configuration, enumerates TUs, and writes `orchestrator-state.json`.
+
+### What the `0-preflight` agent must do
+
+**Step 1 — Determine language mode** from inputs:
+- `compile_db` set and `cargo_manifest` not set → `language_mode=c`
+- `cargo_manifest` set and `compile_db` not set → `language_mode=rust`
+- Both set → `language_mode=mixed`
+- Neither set → **stop the run**: at least one of `compile_db` or `cargo_manifest` is required.
+
+**Step 2 — C/C++ preflight** (skip if `language_mode=rust`):
+
+1. Verify `compile_db` 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.
+7. 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, and apply confidence downgrades in the report assembly phase.
+
+**Step 3 — Common preflight** (always):
+
+8. Verify `{baseDir}/tools/generate_poc.py` exists and is executable. If missing: **stop the run** — PoC generation is mandatory.
+
+**Step 4 — Rust preflight** (skip if `language_mode=c`):
+
+9. Verify `cargo_manifest` file exists (must be a `Cargo.toml` path).
+10. Run `cargo check --manifest-path <cargo_manifest>` to confirm the crate is buildable. If it fails: **stop the run**.
+11. Verify `cargo +nightly --version` succeeds. If not: **stop the run** — nightly toolchain is required for MIR and LLVM IR emission.
+    - Note: use `~/.cargo/bin/cargo +nightly` (rustup proxy) rather than a system cargo that may not support the `+toolchain` syntax.
+12. Verify `uv --version` succeeds. If not: **stop the run** — `uv` is required to run Python analysis scripts.
+13. Verify `{baseDir}/tools/emit_rust_mir.sh` exists and is executable. If missing: **stop the run** — MIR analysis is required.
+14. Verify `{baseDir}/tools/emit_rust_ir.sh` exists and is executable. If missing: **stop the run** — LLVM IR analysis is required.
+15. For each tool below: if missing or not executable, warn and mark that capability as skipped (do not fail the run):
+    - `{baseDir}/tools/emit_rust_asm.sh` — if missing, set `enable_asm=false` for Rust; warn `STACK_RETENTION`/`REGISTER_SPILL` findings will be skipped.
+    - `{baseDir}/tools/diff_rust_mir.sh` — if missing, warn that MIR-level optimization comparison will be skipped.
+16. For each Python script below: if missing, warn and mark that sub-step as skipped (do not fail the run):
+    - `{baseDir}/tools/scripts/semantic_audit.py`
+    - `{baseDir}/tools/scripts/find_dangerous_apis.py`
+    - `{baseDir}/tools/scripts/check_mir_patterns.py`
+    - `{baseDir}/tools/scripts/check_llvm_patterns.py`
+    - `{baseDir}/tools/scripts/check_rust_asm.py` — if missing, assembly analysis findings (`STACK_RETENTION`, `REGISTER_SPILL`) will be skipped even if `enable_asm=true`.
+
+**Step 5 — TU / crate enumeration**:
+
+- **C/C++** (skip if `language_mode=rust`): Parse `compile_db` and enumerate all translation units. Apply `max_tus` limit if set. Filter by `languages`. Compute `tu_hash = sha1(source_path)[:8]` for each TU. Run a lightweight grep across TU sources for sensitive name patterns (from merged config) to produce `sensitive_candidates`.
+- **Rust** (skip if `language_mode=c`): Compute `rust_tu_hash = sha1(abspath(cargo_manifest))[:8]`. Set `rust_crate_root = dirname(cargo_manifest)`.
+
+**Step 6 — Create work directory**:
+
+```bash
+RUN_ID=$(date +%Y%m%d%H%M%S)
+WORKDIR="/tmp/zeroize-audit-${RUN_ID}"
+mkdir -p "${WORKDIR}"/{mcp-evidence,source-analysis,compiler-analysis,rust-compiler-analysis,report,poc,tests,agent-inputs}
+```
+
+**Step 7 — Write `{workdir}/preflight.json`**:
+
+```json
+{
+  "run_id": "<RUN_ID>",
+  "timestamp": "<ISO-8601>",
+  "repo": "<path>",
+  "language_mode": "<c|rust|mixed>",
+  "compile_db": "<compile_db or null>",
+  "cargo_manifest": "<cargo_manifest or null>",
+  "rust_crate_root": "<dirname(cargo_manifest) or null>",
+  "rust_tu_hash": "<hash or null>",
+  "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": [],
+  "tools_verified": ["uv", "cargo+nightly"],
+  "notes": ""
+}
+```
+
+**Step 8 — Write `{workdir}/orchestrator-state.json`** with the full state structure.
+
+Report each preflight failure with the specific check that failed and the remediation step.
+
+**After completion**: The agent's response includes the `workdir` path. Read `{workdir}/orchestrator-state.json` to initialize:
+
+- `workdir` — use for all subsequent phases
+- `routing.mcp_available` — MCP probe result
+- `routing.tu_count` — number of TUs to process
+- `key_file_paths.config` — path to merged config file
+
+## State Update
+
+The `0-preflight` agent writes the initial `orchestrator-state.json`. No additional update needed by the orchestrator.
+
+## Error Handling
+
+| Failure | Behavior |
+|---|---|
+| Agent fails or times out | Stop the run, report failure |
+| Neither `compile_db` nor `cargo_manifest` provided | Stop the run |
+| Preflight validation fails | Stop the run (agent reports specific check and remediation) |
+| Config load fails | Stop the run |
+| Preflight tool check fails | Stop the run |
+| MCP unreachable + `mcp_mode=require` | Stop the run |
+| MCP unreachable + `mcp_mode=prefer` | Continue — `routing.mcp_available` will be `false` |
+| `cargo check` fails (Rust preflight) | Stop the run — crate must be buildable |
+| `cargo +nightly` not available (Rust preflight) | Stop the run — nightly required for MIR/IR emission |
+| `uv` not available (Rust preflight) | Stop the run — required for Python analysis scripts |
+| `emit_rust_asm.sh` missing (Rust preflight) | Warn, set `enable_asm=false` for Rust, continue |
+| Python script missing (Rust preflight) | Warn and skip that sub-step, continue |
+
+## Next Phase
+
+Phase 1 — Source Analysis