Analyzes the repository's version control system (VCS) history to extract past vulnerabilities, security fixes, and vulnerability patterns. Use as an initial pre-processing step to build a historical vulnerabilities database (workspace/historical_learnings.jsonl) that informs subsequent stages about

History Analyzer (/mantis history) System Goal Historical Vulnerability Extractor. Analyzes repository's version control system (VCS) history to extract past vulnerabilities, security related fixes, patches, and associated files, creating a historical learnings database to inform downstream skills. Command Definition Command: /mantis history Description: Analyzes repository's version control system (VCS) history to extract past vulnerabilities and fixes, producing a structured historical learnings file ( workspace/historical learnings.jsonl ). Arguments (optional; supplied by the orchestrator, consumed by Block A): snapshot root / snapshot id / state root . History reads VCS logs from the LIVE repository root (Block A step 5), not the snapshot; it uses state root only to place its cache/output/script. All absent DEGRADED (behaves as today, live cwd). Input/Output Contract Reads : workspace/.mantis state.json (to track current loop pass). Codebase directory structure and key files (to determine stack). VCS history logs (commit messages, titles, diffs). mantis summary.md (optional, if available). Internal history analysis cache (optional, if exists). Writes : VCS extraction script (written on the fly to workspace). workspace/historical learnings.jsonl . Internal history analysis cache. All under state root/workspace/ (cache, historical learnings.jsonl , extraction script): kept outside the target tree. Optional history status marker ( UNSUPPORTED VCS / PARTIAL SHALLOW ). Preconditions : Target repository and VCS logs must be accessible. Idempotency Guarantee : The cache is the source of truth: the output DB is rebuilt from it every run and is never truncated to empty while the cache is non empty. The cache is invalidated on VCS history rewrite ( analyzed head no longer reachable) or a vcs type/repo identity change. On none / unknown VCS the stage writes an empty DB + history status=UNSUPPORTED VCS and exits. Instructions Step 0: Locator Resolution (run first) CRITICAL for history: the pinned snapshot copy STRIPS .git / .hg / .repo , so per Block A step 5 you MUST run every VCS log / diff / blame command in the LIVE repository root (the working directory Mantis was launched in), NOT under CODE ROOT. Do NOT stop because CODE ROOT lacks VCS metadata. Write the cache, workspace/historical learnings.jsonl , and your generated extraction script under state root/workspace/ (STATE RELATIVE) — never into the target tree, so a sync/clean cannot wipe them. Record active snapshot.snapshot id on entries only for provenance. Your task is to analyze the codebase architecture, determine what constitutes security relevant history, and write a script on the fly to extract and document historical vulnerabilities from the project's version control system (VCS). Execute the history analysis stage as follows: 1. Phase 1: Analyze Codebase and Define Target History: Read existing summaries (e.g. mantis summary.md if available) or quickly inspect the root codebase structure to understand the primary files, programming languages, and core components. Determine what types of historical security issues (e.g., memory corruption, authentication bypass, SQL injection, buffer overflow, or others) are relevant to this project and what keywords or commits should be targeted. 2. Phase 2: Write a History Extraction Script: VCS support guard (run BEFORE writing/executing the script): Determine vcs type from .mantis state.json vcs info (or detect it in the LIVE root). If vcs type is none or unknown , OR the VCS history is otherwise unreachable: write an EMPTY workspace/historical learnings.jsonl , set a top of file / sidecar marker history status = "UNSUPPORTED VCS" , and EXIT — never fabricate history. For multi vcs (.repo): either iterate history per sub project, or write the empty file with history status = "UNSUPPORTED VCS" rather than run a git shaped script that errors. For a SHALLOW git clone ( git rev parse is shallow repository == true): proceed but set history status = "PARTIAL SHALLOW" so downstream stages do NOT read "no historical vuln for this file" as "clean." Read the active pass number from the state file workspace/.mantis state.json and resolve the current ISO 8601 timestamp. Write a script (e.g. Python, bash, or your choice) directly in your workspace that interacts with your repository version control system (VCS) history logs. Cost Efficiency & Scale Optimization: To ensure the historical analysis remains cost effective and runs efficiently, the script must implement the following optimizations: Commit Message/Description Pre filtering: Before retrieving diffs, the script should dynamically determine relevant keywords for commit message screening. It can do this by first inspecting the repository's files and languages/domains in scope to establish its primary stack (e.g. software versus hardware/RTL), then either querying an LLM/analysis agent for a tailored list of security/bug keywords or using a broader set of keywords augmented with these specific domain terms. Skip revisions whose messages or titles do not match these relevant keywords to avoid unnecessarily retrieving and analyzing changesets that are irrelevant to the codebase in scope. Diff Filtering and Size Limits: Ignore commits that only touch non production code (e.g., tests, documentation, or configuration files). Skip commits with excessively large diffs (e.g., more than several thousand lines changed), as they are usually automated formatting changes or massive refactorings rather than discrete security patches. Caching Results (cache is the source of truth): Maintain a local cache (JSON or SQLite) under workspace/ mapping revision id analyzed , AND storing the full extracted record for each analyzed revision plus an analyzed head high water mark and the vcs type + repo identity the cache was built against. On each run, REBUILD workspace/historical learnings.jsonl from the cache (do NOT skip a revision merely because the cache says "analyzed" and then leave the output empty — that is the desync bug). NEVER truncate a non empty output DB to empty. Only analyze revisions NEWER than analyzed head . Rewrite detection: before trusting the cache, verify analyzed head still resolves in the current LIVE history (git: git cat file e < analyzed head succeeds AND git merge base is ancestor < analyzed head HEAD ; hg: hg log r < analyzed head succeeds). If it does not (force push / rebase / squash) OR vcs type /repo identity changed, INVALIDATE the cache and re extract from scratch. Batch Processing (Batching Diffs): Instead of making one LLM call per commit diff, the script should batch multiple commit diffs and messages (e.g. 3 to 5 commits) into a single LLM call. Ask the LLM to analyze all commits in the batch and return a JSON array of findings for the batch, reducing request overhead and cost. Model Selection: Use lightweight and cost efficient models for the initial commit analysis/filtering, and only fall back to heavier model tiers if deeper verification of a suspected vulnerability is needed. Detailed Analysis: For revisions or commits that look security relevant, the script should retrieve the commit diffs and messages/change descriptions. LLM/Agent Analysis: The script should make API calls (e.g., via subagent messages or Agent API subcommands) or use an LLM subagent to analyze the changes' diffs and messages to determine whether a revision/commit was a security fix, what component was affected, the vulnerability type, impact, and the mitigation diff. Make sure it uses batching and caching to minimize API calls. Missing Information: Do not overindex on the lack of security related keywords. Many security fixes do not get CVEs, and many security vulnerabilities are fixed without realizing they were vulnerabilities. Output Format: Instruct your script to output the extracted findings into a JSONL file named workspace/historical learnings.jsonl , matching the following format: Historical Learnings Schema Format ( workspace/historical learnings.jsonl ) 1. Phase 3: Execute and Verify: Run the script you just wrote to analyze the VCS history, process revisions, and generate the workspace/historical learnings.jsonl file. Wait for the script to finish and verify that workspace/historical learnings.jsonl has been written successfully and contains extracted data. When complete, notify the user.

mantis-history