mantis-summarize

Summarizer (/mantis-summarize)

システムの目標

リポジトリマッパーです。後続の計画および調査の段階で必要となるトークン数を削減するため、ディレクトリの内容に関するセキュリティ重視の決定的な要約を自動生成します。

コマンド定義

• コマンド： /mantis-summarize
• 説明： リポジトリを前処理し、計画と調査を効率化するために、各ディレクトリのセキュリティ重視の要約（mantis-summary.md）を生成します。
• 引数（任意。オーケストレーターから渡され、Block A で使用）： --snapshot_root/--snapshot_id/--state_root。PINNED モードでは、ソースは CODE_ROOT の下から読み取られますが、要約はスキップされます（出力先を参照）。すべて省略された場合は、MODE-OFF（従来どおり、ツリー内に要約を作成）になります。

入出力の契約

• 読み込み対象：
  • workspace/.mantis_state.json（現在のループパスを追跡するため）。
  • コードベースのディレクトリとソースファイル（node_modules、vendor、.git、ビルド出力、および tests/ を除く）。
  • 子ディレクトリの要約（サブディレクトリ内の mantis-summary.md ファイル）。
  • workspace/historical_learnings.jsonl（任意。要約を充実させるため）。
• 書き込み対象：
  • ワークスペースへのトラバーサルスクリプト。
  • MODE-OFF：各ソースディレクトリに mantis-summary.md を作成します（従来どおり）。PINNED：スキップします（出力先を参照）。
• 前提条件：
  • ソースファイルとディレクトリ構造が存在している必要があります。
• 冪等性の保証：
  • 既存の mantis-summary.md ファイルをその場で決定的に上書きし、更新されたロールアップを作成します。

手順

Step 0: ロケーターの解決 + 出力先（最初に実行）

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.

出力先（必須）：

• PINNED モード（snapshot_pinned true）：このパスでは要約をスキップします。PINNED モードでは CODE_ROOT は読み取り専用であり（Block A step 4）、コンシューマー（plan、history、researcher）は mantis-summary.md を状態ディレクトリ相対のミラーではなく、コードツリー内のソースディレクトリから読み取ります。コンシューマーが読み取らないミラーに書き込むと、作業が無駄になります。PINNED モードでは、mantis-summary.md ファイルを一切作成しないでください。（将来の変更でコンシューマーがミラーを参照し、プロベナンスマーカーを介して再マッピングするようになれば再検討できますが、現時点では PINNED モードの要約は機能しません。）
• HALT モード（active_snapshot が存在し、snapshot_pinned=false）：MODE-OFF と同様に動作します（各ソースディレクトリに mantis-summary.md を作成）。スナップショットは読み取り専用ではなく（不変のコピーが固定されていないため）、ツリーへの書き込みは安全です。
• MODE-OFF（active_snapshot なし。現在のデフォルト）：従来どおりに動作し、各ソースディレクトリに mantis-summary.md を作成します。
• PINNED 以外のすべてのモードで、mantis-summary.md ファイルはすべての VCS の変更チェックに検出されない状態を保ち、同期の前にターゲットツリーから削除する必要があります（メタエージェントが Block C STEP 0 でこれを徹底します）。要約によってツリーが変更されたように見える状態にしてはなりません。

リポジトリのディレクトリツリーを走査し、ソースコードを含む各ディレクトリに mantis-summary.md ファイルを作成するスクリプトを作成して実行してください。

これは、ストラテジスト（/mantis-plan）に必要なコンテキストウィンドウのサイズを大幅に削減し、リサーチャー（/mantis-researcher）向けにすばやく参照できるマップを提供するための、任意の前処理フェーズです。

次の手順で要約ステージを実行してください。

1. トラバーサルスクリプトの作成（ボトムアップの階層型）： ワークスペース内にスクリプト（例：Python または bash）を作成し、ボトムアップ（ポストオーダー）トラバーサルでリポジトリのディレクトリツリーを走査します。

   • スクリプトは、node_modules、vendor、.git、ビルド出力、tests/ などのソースコード以外のディレクトリを無視する必要があります。
   • ボトムアップでたどることで、スクリプトは親ディレクトリより先にサブディレクトリを要約します。
   • ディレクトリを分析する際、スクリプトはそのディレクトリ内のローカルなソースファイルと、直下のサブディレクトリにある mantis-summary.md ファイルを LLM に渡す必要があります。サブディレクトリの生のソースファイルを親ディレクトリに渡してはいけません。
   • 非常に大きなディレクトリを分析する場合、コンテキストウィンドウのサイズが問題になる可能性があります。ファイルやディレクトリの要約をまとめて渡すのではなく、ファイルごとの要約を生成するか、より効率的な単位に分割して処理し、LLM が扱うトークン数が多くなりすぎないようにしてください。

2. セキュリティ要約を生成する（Map-Reduce）： スクリプトは workspace/historical_learnings.jsonl（存在する場合）を読み込み、現在のディレクトリ内のファイルに関連する過去の脆弱性やセキュリティ修正を確認して、コンテキストに含める必要があります。スクリプトは LLM またはエージェントツールに、ディレクトリの簡潔でセキュリティに焦点を当てた要約を生成するよう指示する必要があります。ディレクトリツリーの上位階層でトークン数を適切に保つため、LLM は下位レベルの詳細を抽象化し、集約されたアーキテクチャに焦点を当てる必要があります。スクリプトで使用するプロンプトでは、次の点を尋ねてください。

   • 主要コンポーネント： 主なファイルやサブディレクトリは何で、それぞれどのような役割を果たしていますか？
   • API エンドポイントとエクスポート： 他のモジュールに公開されている関数やクラスは何ですか？
   • 信頼境界と外部入力： このディレクトリは、信頼できないデータ、ネットワークリクエスト、またはユーザー入力を処理しますか？
   • 機微な操作： パーサー、暗号関数、またはメモリ管理操作はありますか？
   • 過去の脆弱性と修正： workspace/historical_learnings.jsonl に記録されている、過去の脆弱性やセキュリティ関連の修正があった、このディレクトリ内のファイルまたはコンポーネントは何ですか？過去のリグレッションや繰り返し発生する弱点を明らかにするため、過去の修正、影響を受けたコンポーネント、脆弱性の種類を要約してください。

   要約は、より大きな問題に取り組む際に取り込める適切な分量にする必要があります。そのため、数千語以内を目安にしてください。

3. mantis-summary.md に出力する： MODE-OFF（または HALT）では、対応するソースディレクトリに mantis-summary.md を書き込みます（存在する場合は上書きします）。PINNED モードでは書き込まないでください。このパスでは要約をスキップします（上記の出力先を参照）。読み取り専用スナップショットには決して書き込まないでください。

4. スクリプトを実行する： 作成したスクリプトを実行して、リポジトリ全体の要約をすべて生成します。正常に完了するまで待ちます。

5. 完了： 要約の生成が完了しました。ユーザーに通知します。

完了したら、ユーザーに通知します。