4-report-assembler

name: 4-report-assembler
description: "Collects all findings from source and compiler analysis, applies supersessions and confidence gates, normalizes IDs, and produces a comprehensive markdown report with structured JSON for downstream tools. Supports dual-mode invocation: interim (findings.json only) and final (merge PoC results, produce final-report.md)."
model: inherit
tools: Read, Grep, Glob, Write, Bash

4-report-assembler

Collect all findings from source and compiler analysis phases, apply supersessions and confidence gates, normalize finding IDs to `ZA-NNNN`, and produce structured findings and a comprehensive markdown report. This agent is invoked twice: once in interim mode (findings only) and once in final mode (merge PoC results and produce the report).

Input

You receive these values from the orchestrator:

| Parameter | Description | |---|---| | `workdir` | Run working directory (e.g. `/tmp/zeroize-audit-{run_id}/`) | | `config_path` | Path to merged config file (`{workdir}/merged-config.yaml`) | | `mcp_available` | Boolean — whether MCP was successfully used | | `mcp_required_for_advanced` | Boolean — gates advanced findings on MCP availability | | `baseDir` | Resolved skill directory containing SKILL.md (for tool and schema paths) | | `mode` | `interim` or `final` — controls which steps execute and which outputs are produced | | `poc_results` | Path to `poc_final_results.json` (final mode only) |

Mode Branching

• **`interim` mode**: Execute Steps 1–5. Write `findings.json` only. Do **not** produce `final-report.md`.
• **`final` mode**: Read existing `findings.json`, execute Step 5b (merge PoC results), then produce both an updated `findings.json` and `final-report.md` (Step 6).

Process

Step 0 — Load Configuration

Read `config_path` to load the merged config (confidence gate thresholds, severity rules, report settings).

Step 1 — Collect All Findings

Read finding files from the working directory:

1. **Source findings**: `{workdir}/source-analysis/source-findings.json` 2. **Compiler findings (C/C++)**: For each subdirectory in `{workdir}/compiler-analysis/*/`:

• `ir-findings.json`
• `asm-findings.json`
• `cfg-findings.json`
• `semantic-ir.json`

3. **Compiler findings (Rust)**: Read from `{workdir}/rust-compiler-analysis/`:

• `mir-findings.json`
• `ir-findings.json`
• `asm-findings.json`
• `cfg-findings.json`
• `semantic-ir.json`

4. **Coverage gaps**: `{workdir}/rust-compiler-analysis/coverage-gaps.json` (if it exists) — Section D patterns the crate uses that no script audits. These are not findings and do not enter the gate; they populate Analysis Coverage so a clean report cannot be read as "nothing to find here". 5. **Sensitive objects**: `{workdir}/source-analysis/sensitive-objects.json` 6. **MCP status**: `{workdir}/mcp-evidence/status.json` (if exists) 7. **Preflight metadata**: `{workdir}/preflight.json`

Merge all findings into a single list. Handle missing directories gracefully — a TU's `compiler-analysis/<tu_hash>/` directory or `rust-compiler-analysis/` may be absent if that agent failed.

Step 2 — Apply Supersessions

Read `superseded-findings.json` from:

• each C/C++ compiler-analysis subdirectory (`{workdir}/compiler-analysis/*/superseded-findings.json`)
• Rust compiler analysis (`{workdir}/rust-compiler-analysis/superseded-findings.json`)

For each supersession:

• Remove the superseded finding (e.g., `F-SRC-0005` for `NOT_ON_ALL_PATHS`)
• Keep the superseding finding (e.g., `F-CFG-a1b2-0003` for `NOT_DOMINATING_EXITS` or `MISSING_ON_ERROR_PATH`)
• Record the supersession in `notes.md`

Step 3 — Apply Confidence Gates

Apply the confidence gating rules from the SKILL.md. Optionally use the mechanical enforcer:

uv run --no-project {baseDir}/tools/mcp/apply_confidence_gates.py \
  --findings <raw_findings_json> \
  --mcp-available <mcp_available> \
  --mcp-required-for-advanced <mcp_required_for_advanced>

**Key rules (authoritative version in SKILL.md):**

• A finding needs 2+ independent signals to be `confirmed`; 1 signal -> `likely`; 0 strong signals -> `needs_review`.
• `OPTIMIZED_AWAY_ZEROIZE` requires IR diff evidence. Never emit from source alone.
• `STACK_RETENTION` and `REGISTER_SPILL` require assembly evidence. Never emit from source or IR alone.
• If `mcp_available=false` and `mcp_required_for_advanced=true`: downgrade `SECRET_COPY`, `MISSING_ON_ERROR_PATH`, `NOT_DOMINATING_EXITS` to `needs_review` unless 2+ non-MCP signals exist.
• If a rationalization override was attempted, retain the finding and note in evidence.

Step 4 — Normalize IDs

Assign final `ZA-NNNN` IDs (sequential, zero-padded to 4 digits) to all surviving findings. Record the mapping from namespaced IDs to final IDs in `id-mapping.json`.

Ordering:

• C/C++ source findings first (by `F-SRC-NNNN` order)
• Rust source findings next (by `F-RUST-SRC-NNNN` order)
• C/C++ compiler findings grouped by TU (sorted by TU hash, then by finding type: IR, ASM, CFG, SIR)
• Rust compiler findings last (ordered by finding type: MIR, IR, ASM)

Step 5 — Produce Structured Findings JSON

Write `findings.json` — a structured JSON file consumed by downstream agents (`5-poc-generator`, `6-test-generator`). This file matches `{baseDir}/schemas/output.json`:

{
  "run_id": "<from preflight.json>",
  "timestamp": "<ISO-8601>",
  "repo": "<path>",
  "findings": [],
  "summary": {
    "total": 0,
    "by_severity": {},
    "by_category": {},
    "by_confidence": {}
  }
}

Each finding includes:

| Field | Content | |---|---| | `id` | `ZA-NNNN` | | `category` | Finding category enum | | `severity` | `high` or `medium` | | `confidence` | `confirmed`, `likely`, or `needs_review` | | `location` | `{file, line}` | | `object` | `{name, type, size_bytes}` | | `evidence` | Array of evidence objects `{source, detail}` | | `evidence_source` | Tags: `source`, `mcp`, `ir`, `asm`, `cfg` | | `compiler_evidence` | IR/ASM ev