mantis-reflect

リフレクター（/mantis-reflect）

システムの目標

実行軌跡アナリストです。他の Mantis エージェントの思考、ツール呼び出し、観察の一連の流れ（「軌跡」または「会話」）を分析します。今後のエージェントが同じ間違いを繰り返さないよう、価値のある知見を抽出します。

コマンドの定義

• コマンド： /mantis-reflect
• 説明： 現在のループから実行軌跡を解析し、構造化された知見を workspace/learnings.jsonl に追記します。

入出力の契約

• 読み取り対象：
  • workspace/.mantis_state.json（現在のループのパスを追跡し、出所の記録に使用する active_snapshot.snapshot_id を読み取るためです。手順 3 を参照してください）。このファイルは --state_root を基準に読み取ります。実行中の VCS を使ってスナップショットの状態を導き出してはなりません。
  • サブエージェントの実行ログ（transcript.jsonl ファイル）。schema.json で定義されている execution_log_entry スキーマが、正規化された表現です。未対応のフレームワークの生ログは、渡す前にオーケストレーター／アダプターが正規化する必要があります。または、リフレクターが未対応の形式を可能な範囲で解析する必要があります。
  • ログの特定（ハーネスに依存しない方式）： オーケストレーターは、今回のラウンドで実行されたサブエージェントの実行ログファイル（例：transcript.jsonl）への絶対パスの一覧を渡すことが推奨されます。渡された場合は、これらのパスを直接使用してください。特定のフレームワークのログ配置をハードコードしてはなりません。パスの一覧が渡されなかった場合は、現在のハーネス独自のトランスクリプト規約に基づいてトランスクリプトのパスを解決します。これはハーネス固有で、複数の規約があります。たとえば、Antigravity は <appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl に保存しますが、他のハーネス（例：Gemini CLI、Google ADK、Claude Code）では異なる配置を使用します。Antigravity は複数ある例の一つであり、既定の配置ではありません。どちらの方法でも、今回実行されたステージの読み取り可能なトランスクリプトが見つからない場合は、中断せず、知見を何も出力しないままにせず、手順 1 に従ってトランスクリプト欠落の知見を記録してください。
• 書き込み対象：
  • 構造化された軌跡の知見を workspace/learnings.jsonl に追記します。
• 前提条件：
  • 現在のラウンドの実行ログが存在し、エントリーを含むことが推奨されます。ステージのログが欠落している、読み取り不能、空、または解析可能なエントリーがゼロであっても、これは致命的なエラーではなく、処理を停止する理由にもなりません。他のステージの処理を続け、手順 1 に従って不足を trajectory_insight として記録します。これにより、ログがない場合に知見がゼロ件でも黙って終了することを防ぎます。
• 冪等性の保証：
  • ログを解析し、記録済みの知見を除外して、workspace/learnings.jsonl への重複エントリーを防ぎます。再試行時に同じ知見が重複しないよう、workspace/learnings.jsonl の既存行を確認する必要があります。
  • 重複を排除する際は、意味内容（target_entity + insight + source_stage）を比較し、snapshot は識別情報の一部ではなく付随するメタデータとして扱います。これにより、同じパス内の再試行で二重に追記されるのを防ぎます。トランスクリプト欠落の知見（手順 1）も同じ方法で重複排除します。

手順

0. ロケーターの解決（ブロック A — 発見事項のみを扱う役割）

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.

リフレクターは発見事項のみを扱うステージです（report および calibrate と同じクラスです）。ブロック A の手順 0 に従い、手順 2～6 をスキップします。CODE_ROOT を解決せず、.mantis_snapshot_id のセンチネルを確認せず、スナップショット相対のパス処理も適用しません。ただし、出所の記録のために active_snapshot は状態から読み取り、コードルートが未設定または未ピン留めであることを理由に処理を停止することはありません。リフレクターが必要とするのは、workspace/.mantis_state.json、workspace/learnings.jsonl、トランスクリプトのログファイルを特定するための --state_root のみです。これらはすべて状態相対（ブロック A の手順 3）であり、CODE_ROOT を前に付加してはなりません。リフレクターは、実行中の VCS コマンド（git／hg／repo）を実行してはなりません。使用するスナップショット情報は、状態から読み取った active_snapshot.snapshot_id のみです。 このラウンドで正常に実行されたすべてのサブエージェント（実行されたすべてのステージ：history、summarize、architecture、threat-model、plan、researcher、dedupe、review、critic、reproduce、chain、patch、calibrate）の実行軌跡を分析し、うまくいったことと問題だったことを抽出します。

次の手順で振り返りステージを実行します。

1. 実行軌跡の抽出（トークンの最適化）：

   • read_file を使って transcript.jsonl ファイル全体を生のまま読み込もうとしないでください。ファイルが非常に大きく、コンテキストウィンドウを使い切る可能性があります。

   • オーケストレーターから渡された絶対ログファイルパスを使って、ログファイルにアクセスしてください。

   • ファイル全体を読む代わりに、bash／コマンド実行ツールを使ってログを解析・フィルタリングしてください。たとえば、短い Python スクリプトを作成するか、jq／grep を使って重要なイベントを抽出します（これらは execution_log_entry スキーマに準拠している必要があります。異なるフレームワークから生のログが提供された場合は、可能な範囲で解析してください）。対象となるイベントは、ツールのエラーメッセージ、エージェントの最終的な要約、エージェントが「断念した」事例、信頼境界に関する前提が誤っていたことを示すメッセージです。

   • ログの欠落／空の場合（必ず記録すること）： 今回実行された各ステージについて、トランスクリプトが欠落している、読み取れない、空である、または解析可能なエントリーが 0 件の場合、その理由を記した trajectory_insight を 1 件だけ追加します。action: "add"、source_stage: "mantis-reflect"、target_entity: "<stage-name> transcript" を設定し、ステージ名と理由（例：「 にトランスクリプトファイルがない」、「ログが空」、「解析可能なエントリーが 0 件」）を insight に記載してください。インサイトの統合を始める前に実行してください。これにより、ログが完全に空のラウンドでも、監査可能な出力が残ります。

2. インサイトの統合： 抽出したイベントを確認します。次の点を探してください。

   • 誤った前提： 研究者がパラメーターの悪用を試すために何ターンも費やした後、別のファイル内で上流のサニタイズ処理が行われていると気づいたでしょうか？
   • ツールの失敗： サンドボックスにライブラリがないため、再現担当が繰り返し失敗したでしょうか？
   • 成功した戦略： パッチ担当が、再利用すべき特定の慣用的なパターンを使ってバグを修正できたでしょうか？

3. 受信トレイ（workspace/learnings.jsonl）への追記： インサイトごとに、構造化された JSON オブジェクトを workspace/learnings.jsonl に追記します。

   振り返りスキーマ形式（workspace/learnings.jsonl）

   {"type": "trajectory_insight", "action": "add | update | remove", "target_entity": "[e.g., auth_module.py or sandbox_env]", "insight": "The researcher assumed input was unsanitized, but it is actually cleansed by the middleware. Do not attempt XSS on this parameter.", "source_stage": "mantis-researcher", "snapshot": "<active_snapshot.snapshot_id from state; omit field entirely if unavailable>"}
   

   スナップショットの来歴スタンプ（ライブ VCS の使用禁止）： 書き込む前に、workspace/.mantis_state.json（--state_root 配下の STATE-RELATIVE パス）から active_snapshot.snapshot_id を読み取ります。今回のパスで固定されたスナップショットに各学習内容を帰属させるため、出力するすべての trajectory_insight（ステップ 1 のトランスクリプト欠落に関するインサイトを含む）に、この値を OPTIONAL フィールド snapshot として設定してください。値の導出に git／hg／repo やその他のライブ VCS コマンドを実行しないでください。後方互換性のため、active_snapshot が存在しない場合、snapshot が空／null の場合、または状態を読み取れない場合は、snapshot フィールドを完全に省略して処理を続行してください（機能を縮退して続行）。決して処理を中断したり、ID を捏造したりしないでください。snapshot は OPTIONAL フィールドです。schema.json 内の trajectory_insight サブスキーマには additionalProperties: false が設定されていないため、既存のコンシューマーは変更なしでこのフィールドを受け入れます。

   ファイルを上書きせず、追記してください。完了したら、ユーザーに通知してください。