Mantis Report

Reporter (/mantis-report)

System Goal

Security Reporting Expert. Synthesizes complex, technical finding logs into a high-quality, human-readable review packet for developers and stakeholders.

Command Definition

• Command: /mantis-report
• Description: Generates a human-readable security review packet containing confirmed findings and exploit chains.

Input/Output Contract

• Reads:
• workspace/findings/*.json (all active finding files for this pass).
• workspace/archive/findings_pass_*/*.json (archived findings from prior passes) and legacy workspace/archive/loop*_findings/*.json. The report is a campaign-wide view: this pass's full findings plus carried-forward findings that prior passes stopped retrying (e.g. hit the retry cap) so they do not vanish from the report.
• workspace/.mantis_state.json (to track current loop pass, and to read vcs_info and active_snapshot {root, snapshot_id, snapshot_pinned} for provenance).
• Per-finding snapshot provenance fields, all OPTIONAL: discovery_commit, repro_snapshot_id, patch_base_snapshot. When any is absent/empty it is rendered as "(not recorded)" — never a reason to drop a finding.
• Writes:
• workspace/report/review_packet_pass_<N>_<snapshot_tag>.md (pass- and snapshot-tagged markdown report). Falls back to the unsuffixed review_packet_pass_<N>.md on a legacy pass with no recorded snapshot.
• Updates copy/symlink at workspace/report/review_packet-latest.md.
• Preconditions:
• Calibrated and reproduced findings exist in workspace/findings/ or workspace/archive/. The report is a campaign-wide view: it reports the current state of every unresolved finding discovered in this or any prior pass, de-duplicated to each finding's latest state. A confirmed-but-unfixed finding that plan stopped carrying back (e.g. it hit the 2-attempt retry cap) does NOT vanish — it appears here at its most recent archived state.
• Idempotency Guarantee:
• Writes to pass-and-snapshot-tagged files. In-place overwrite of review_packet-latest.md. Re-running the SAME pass on the SAME snapshot updates the same tagged file. Re-running the same pass number on a DIFFERENT snapshot writes a DISTINCT file (the <snapshot_tag> suffix prevents cross-snapshot overwrite). Legacy passes with no recorded snapshot keep the unsuffixed review_packet_pass_<N>.md name and overwrite in place, exactly as before.

Instructions

Step 0 — Locator Resolution.

LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.

Then the following FINDINGS-ONLY notes apply to the Reporter:

• The Reporter is a FINDINGS-ONLY stage (Block A, ROLE step 0): it SKIPS locator steps 2–6, does NOT require or resolve a CODE_ROOT, and NEVER stops because a code root or sentinel is unset.
• It STILL reads active_snapshot (root, snapshot_id, snapshot_pinned) and vcs_info from workspace/.mantis_state.json for provenance — used to build the header, the top banners, and the output file name.
• Every path the Reporter touches (workspace/findings/*.json, workspace/.mantis_state.json, workspace/report/*, workspace/archive/*) is STATE-RELATIVE and is NEVER prefixed with CODE_ROOT.

Compile a professional Markdown report detailing the verified/reproduced vulnerabilities and exploit chains.

Execute the reporting stage as follows:

1. Load findings — this pass in full, plus carried-forward open findings (newest-first fold; no script). Build a working set keyed by finding identity, each finding once at its most-recent state:

SAME-BUG PREDICATE (used for ALL current↔archived dedup, fold, and suppression in this stage; over-reporting is always safe here, hiding a real finding is never acceptable): two findings are the SAME BUG only if EITHER (i) they have the exact same id (UUID); OR (ii) ALL THREE hold — they share a non-empty lineage_id, they share a non-empty signature, AND at least one code_paths entry compared WITH its trailing :line (line-inclusive) is identical between them. Otherwise they are DISTINCT — render BOTH. NEVER treat two findings as the same bug on lineage_id alone or signature alone: both are coarser than a bug's true identity (basename-derived lineage can link two distinct same-named files; a signature strips the line number so it collides between distinct same-file bugs), and collapsing on either alone can silently drop a real finding.

Design note (re-anchoring vs fold): mantis-plan's re-anchoring (Phase 2\) only provides a line hint that steers RE-DISCOVER — it does NOT rewrite the carried finding's code_paths. A re-discovered finding surfaces at its NEW line on the current snapshot. Because the fold predicate requires a line-inclusive code_paths match, the re-discovered finding will NOT fold with its ancestor (the line numbers differ). This is SAFE over-reporting — both entries render, the current one shows the new location. A future phase could relax the predicate to path-only matching when BOTH findings carry the same signature AND lineage_id AND the ancestor's line is confirmed absent on the current snapshot, but the conservative line-inclusive match is used