mantis-report

name	mantis-report
description	Generates a human-readable security review packet compiled from confirmed findings and exploit chains. Use at the end of a review cycle to produce stakeholder-facing documentation. Don't use for auditing code or verifying patches directly.

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 today to prevent any silent-drop risk.

   1. Read all active workspace/findings/*.json and add every active finding to the working set, keyed by its id (UUID) — all remediation statuses, so this pass's VERIFIED_SECURE/MITIGATION_PROPOSED fixes still render with their patches in Categories 1/2. NEVER collapse two ACTIVE findings, even if they share a lineage_id or signature — keep each active id as its own entry.
   2. Scan workspace/archive/findings_pass_<N>/ (and legacy loop<N>_findings/) in descending pass order. Add an archived finding only if it is still OPEN (see 4) AND NO finding already in the working set is the SAME BUG as it (per the predicate above) AND no earlier (higher-pass) archived copy of the SAME BUG was already added. First copy met = latest state; ignore later same-bug copies in lower dirs. (An archived finding is suppressed ONLY when a genuine same-bug supersedes it; a mere or coincidence does NOT suppress it.)