nav-loop

Navigator Loop スキル

構造化されたシグナル、停滞の検出、2 条件の終了ゲートを使って、タスクを完了するまで反復実行します。

これが必要な理由

従来の AI コーディングでは、手動で「続けて」と促す必要があります。Navigator Loop は次の機能を提供します。

• 構造化された完了シグナル（NAVIGATOR_STATUS ブロック）
• 2 条件の終了ゲート（ヒューリスティック＋明示的なシグナル）
• 停滞の検出（ループが行き詰まった際のサーキットブレーカー）
• 進捗の可視化（フェーズ：INIT → RESEARCH → IMPL → VERIFY → COMPLETE）

Ralph の自律ループに関するイノベーションを基に、Navigator のコンテキスト効率に優れたアーキテクチャに合わせて調整されています。

呼び出すタイミング

次の場合は自動的に呼び出します。

• ユーザーが「終わるまで実行して」「完了するまで続けて」と言った場合
• ユーザーが「完了するまで反復して」「自律モード」と言った場合
• ユーザーが「ループモード」「終わるまで止まらないで」と言った場合
• タスクドキュメントに loop_mode: true が設定されている場合

次の場合は呼び出さないでください。

• 1 ステップで完了するタスク（反復が不要）
• ユーザーが「これを 1 回だけ実行して」と言った場合
• すでにループモードである場合（ネストしたループを防止）
• ユーザーがループモードを明示的に無効にしている場合

設定

ループモードの設定は .agent/.nav-config.json にあります。

{
  "loop_mode": {
    "enabled": false,
    "max_iterations": 5,
    "stagnation_threshold": 3,
    "exit_requires_explicit_signal": true,
    "show_status_block": true,
    "iteration_approval": "none",
    "periodic_interval": 3,
    "never_pause_on_stagnation": false,
    "stagnation_diversify_strategy": "combine"
  }
}

主なオプション：

• enabled：新しいタスクのデフォルト状態
• max_iterations：無限ループを防ぐ上限値（1～20）
• stagnation_threshold：一時停止するまでの同一状態の回数（2～5）
• exit_requires_explicit_signal：ヒューリスティックに加えて EXIT_SIGNAL も必要とするかどうか
• show_status_block：各反復で NAVIGATOR_STATUS を表示するかどうか

自律実行／夜間実行のオプション（v6.2.2 以降）：

• iteration_approval：反復の合間にユーザーに承認または拒否を求めるタイミングです。
  • "none"（デフォルト） — 確認を求めず、ループを中断せずに実行します
  • "strict" — 各反復の後に確認を求めます
  • "periodic" — N 回の反復ごとに確認を求めます（N = periodic_interval、デフォルトは 3）
• periodic_interval：iteration_approval == "periodic" の場合に、確認を求める間隔を指定します。デフォルトは 3（3 回ごと）です。長時間の夜間実行で確認頻度を下げるには、より大きい値（例：5 や 10）を設定します。
• never_pause_on_stagnation：true の場合、停滞時に AskUserQuestion で一時停止する代わりに、自動的に多様なアプローチを試します。夜間に真の自律実行を行う場合に必要です。karpathy/autoresearch の NEVER STOP 指令に着想を得ています。
• stagnation_diversify_strategy：never_pause_on_stagnation が発動したときに試す復旧方法です。
  • "combine" — これまでの惜しい結果や一部達成した指標を組み合わせます
  • "radical" — 大幅に異なるアプローチを試します（再設計、ライブラリの入れ替えなど）
  • "reread" — 見落としたシグナルがないか、対象範囲内のタスク／システムドキュメントを読み直します

安全ガード：never_pause_on_stagnation: true を設定するには、max_iterations を明示的に設定する必要があります（デフォルトの 5 で問題ありません。重要なのは、上限なしのデフォルトを避けることです）。上限がないと、根本的に破綻したタスクで自律ループが永久に回り続ける可能性があります。

実行手順

ステップ 1：ループ状態を初期化する

設定を読み込む：

python3 functions/phase_detector.py --init

追跡用変数を初期化する：

iteration = 1
max_iterations = config.loop_mode.max_iterations or 5
stagnation_threshold = config.loop_mode.stagnation_threshold or 3
hash_history = []
phase = "INIT"

ループ開始を表示する：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LOOP MODE ACTIVATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_DESCRIPTION}
Max iterations: {max_iterations}
Stagnation threshold: {stagnation_threshold}

Starting iteration 1...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ステップ 2：反復を実行する

現在のフェーズに基づいてタスク作業を実行します。

フェーズ	アクション
INIT	コンテキストを読み込み、要件を理解します
RESEARCH	コードベースを調査し、パターンを探します
IMPL	コードを記述し、変更を加えます
VERIFY	テストを実行し、機能を検証し、コードを簡素化します
COMPLETE	すべての指標を満たしており、終了できます

反復中の変更を追跡します：

• 読み込んだファイル（RESEARCH の判定用）
• 変更したファイル（IMPL の判定用）
• 実行したテスト（VERIFY の判定用）
• 作成したコミット（完了指標用）

ステップ 3：ステータスブロックを生成する

各反復の後に、NAVIGATOR_STATUS を生成します。

python3 functions/status_generator.py \
  --phase "{phase}" \
  --iteration "{iteration}" \
  --max-iterations "{max_iterations}" \
  --indicators "{indicators_json}" \
  --state-hash "{current_hash}" \
  --prev-hash "{previous_hash}" \
  --stagnation-count "{stagnation_count}"

ステータスブロックを表示する：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NAVIGATOR_STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase: {PHASE}
Iteration: {N}/{MAX}
Progress: {PERCENT}%

Completion Indicators:
  [{x or space}] Code changes committed
  [{x or space}] Tests passing
  [{x or space}] Code simplified
  [{x or space}] Documentation updated
  [{x or space}] Ticket closed
  [{x or space}] Marker created

Exit Conditions:
  Heuristics: {MET}/{TOTAL} (need 2+)
  EXIT_SIGNAL: {true/false}

State Hash: {HASH}
Previous Hash: {PREV_HASH}
Stagnation: {COUNT}/{THRESHOLD}

Next Action: {NEXT_ACTION}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ステップ 3.5：反復ごとの承認ゲート（任意）

次の場合はこのステップをスキップします：config.loop_mode.iteration_approval == "none"（デフォルト）。

次の場合はこのステップを実行します：リスクの高い変更、ループの動作の把握、長時間実行前の確認などのために、反復の間に監督を行いたい場合。

設定	動作
"none"	プロンプトを表示しません。ループはステップ 4 に進みます。
"strict"	反復ごとにプロンプトを表示します。
"periodic"	N 回目の反復ごとにプロンプトを表示します。N のデフォルトは 3 です。loop_mode.periodic_interval で設定できます。

プロンプトを表示する場合は、ステータスブロックの直後に AskUserQuestion を使用します。

Question: "Accept iteration {N} and continue?"
Options:
  1. [Continue] - Iteration accepted, proceed to next
  2. [Adjust]   - Provide feedback, incorporate into next iteration
  3. [Abort]    - End loop, create partial-completion marker

判断の処理：

• 続行：通常どおりステップ 4 に進みます。
• 調整：ユーザーのフィードバックを一時的なメモに記録し、ハッシュ履歴は更新せず（次の反復が新たな進捗として評価されるようにします）、ステップ 4 に進みます。
• 中止：ステップ 8（クリーンアップ）に移動し、status: "user_aborted" とします。

このゲートは停滞検出の前に実行されるため、却下された反復によって停滞回数が誤って増えることはありません。

ステップ 4：停滞の確認

状態ハッシュを計算します：

python3 functions/stagnation_detector.py \
  --phase "{phase}" \
  --indicators "{indicators_json}" \
  --files-changed "{files_json}" \
  --history "{hash_history_json}"

停滞が検出された場合（同じハッシュが N 回の反復で続いた場合）、never_pause_on_stagnation の設定に応じて対応が変わります。

デフォルトの動作（never_pause_on_stagnation: false）

ユーザーにプロンプトを表示します。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STAGNATION DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Same state detected for {N} consecutive iterations.

Current State:
  Phase: {PHASE}
  Indicators: {MET}/{TOTAL}
  Last Action: {LAST_ACTION}

Possible causes:
1. Blocked by external dependency
2. Unclear requirements
3. Test failures preventing progress
4. Missing context or permissions

Options:
1. [Continue] - Try one more iteration
2. [Clarify] - Explain what's blocking
3. [Abort] - End loop, manual intervention

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

選択には AskUserQuestion を使用します。

• 続行：停滞カウンターをリセットし、ループを続行します
• 明確化：ユーザーが障害について説明し、その内容を反映して続行します
• 中止：部分完了マーカーを付けてループを終了します

自律動作（never_pause_on_stagnation: true）

ループは無人で実行されています（夜間、CI など）。プロンプトは表示せず、stagnation_diversify_strategy に基づいて自動的にアプローチを多様化します。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STAGNATION → AUTO-DIVERSIFY ({STRATEGY})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Same state for {N} iterations. Auto-recovery: {STRATEGY}
Stagnation counter reset.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

戦略	次の反復で試すこと
combine	一部達成した指標を再検討し、以前の反復で惜しかった 2 つのアプローチを組み合わせます
radical	現在のアプローチを破棄し、大幅に異なる設計（異なるライブラリ、アーキテクチャ、アルゴリズム）を試します
reread	対象範囲内のタスクドキュメントと関連するシステムドキュメントを読み直し、見落とした手がかりや制約を探します

多様化した後：

• 停滞カウンターを 0 にリセットします
• 多様化の内容を反復のメモに記録します（次のステータスブロックに反映されるようにします）
• ステップ 5 に進みます

強制終了：自律モードでも、ループは max_iterations に達すると終了します。1 回の実行中に多様化が 3 回以上行われた場合は、中止処理に移行します（loop-aborted マーカーを作成して終了します）。多様化が繰り返されること自体が、タスクが根本的に行き詰まっている兆候です。

karpathy/autoresearch の NEVER STOP 指令に着想を得ています。「アイデアが尽きたら、もっと深く考えてください。論文を読み、対象範囲内のファイルを読み直して新たな切り口を探し、以前惜しかったアプローチを組み合わせたり、より大胆なアーキテクチャ変更を試したりしてください。」

ステップ 5：終了条件の確認

二重条件ゲートを評価します：

python3 functions/exit_gate.py \
  --indicators "{indicators_json}" \
  --exit-signal "{exit_signal}" \
  --require-explicit "{config.exit_requires_explicit_signal}"

終了条件：

1. ヒューリスティクス：完了指標を少なくとも 2 つ満たしている
2. EXIT_SIGNAL：タスクが完了したことを示す明示的なシグナル

完了指標（自律プロトコルから対応付け）：

• code_committed：変更が git にコミットされている
• tests_passing：テストスイートが成功している（終了コード 0）
• code_simplified：コードが明確になるように簡素化されている（v5.4.0+）
• docs_updated：ドキュメントファイルが変更されている
• ticket_closed：PM ツールのチケットが完了としてマークされている
• marker_created：完了マーカーが存在する

終了判定ロジック：

IF heuristics >= 2 AND exit_signal == true:
  → EXIT: Task complete
ELIF heuristics >= 2 AND exit_signal == false:
  → CONTINUE: Awaiting explicit completion signal
ELIF exit_signal == true AND heuristics < 2:
  → BLOCKED: Cannot exit with insufficient indicators
ELSE:
  → CONTINUE: More work needed

ステップ 6：最大反復回数の処理

iteration >= max_iterations の場合：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MAX ITERATIONS REACHED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Completed {MAX} iterations without full completion.

Current State:
  Phase: {PHASE}
  Indicators: {MET}/{TOTAL}
  EXIT_SIGNAL: {true/false}

Progress made:
- {PROGRESS_ITEM_1}
- {PROGRESS_ITEM_2}

Options:
1. [Extend] - Add 3 more iterations
2. [Complete] - Accept current state as done
3. [Abort] - Exit without completion

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ステップ 7：ループの完了

終了条件を満たした場合、終了シグナルを JSON 形式で出力し、完了を表示します。

{"v":2,"type":"exit","success":true,"reason":"All criteria met"}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LOOP COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_DESCRIPTION}
Iterations: {FINAL_COUNT}/{MAX}
Final Phase: COMPLETE

Completion Indicators:
  [x] Code changes committed
  [x] Tests passing
  [x] Code simplified
  [x] Documentation updated
  [ ] Ticket closed (skipped - no PM tool)
  [x] Marker created

Exit Conditions:
  Heuristics: 4/5 (passed)
  EXIT_SIGNAL: true (passed)

Summary:
- {KEY_CHANGE_1}
- {KEY_CHANGE_2}
- {KEY_CHANGE_3}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

自律完了プロトコルを実行します：

1. 変更をコミットします（まだの場合）
2. タスクドキュメントをアーカイブします
3. チケットをクローズします（PM が設定されている場合）
4. 完了マーカーを作成します（ループの状態を含めます）
5. コンパクト化を提案します

---

EXIT_SIGNAL の設定

EXIT_SIGNAL は、以下の条件を満たしたときに Claude が明示的に設定します。

• 主要なタスク要件がすべて満たされている
• コードが機能し、テスト済みである
• 明らかに残っている作業がない

完了を通知する方法（v2 JSON 形式）：

{"v":2,"type":"exit","success":true,"reason":"All requirements met"}

pilot-signal コードブロック内の JSON 形式により、Pilot の自動化で曖昧さなく検出できます。reason フィールドには、タスクが完了した理由を簡潔に記述します。

シグナルのフィールド：

• v：バージョン（常に 2）
• type：シグナルの種類（完了時は常に "exit"）
• success：タスクが正常に完了したかどうか（true/false）
• reason：完了状況の簡潔な説明

この明示的な宣言により、ヒューリスティック条件を満たしていても作業が残っている場合に、早まって終了することを防ぎます。

---

フェーズの検出

フェーズはコンテキストに基づいて自動検出されます。

def detect_phase(context):
    # COMPLETE: Exit conditions met
    if indicators_met >= 4 and exit_signal:
        return "COMPLETE"

    # VERIFY: Tests running or recently run
    if context.tests_running or context.test_exit_code is not None:
        return "VERIFY"

    # IMPL: Files being modified
    if context.files_changed:
        return "IMPL"

    # RESEARCH: Reading files, searching
    if context.files_read and not context.files_changed:
        return "RESEARCH"

    # INIT: Default starting state
    return "INIT"

---

Navigator との統合

自律的な完了との連携

ループモードは自律プロトコルを置き換えるのではなく、強化します。

• 完了インジケーターを自律ステップに対応付けます
• EXIT_SIGNAL が自律的な完了をトリガーします
• マーカーには復元用のループ状態が含まれます

nav-simplify との連携（v5.4.0+）

簡素化は VERIFY フェーズ中に実行されます。

• テストに合格した後、コミットする前に実行します
• .nav-config.json の simplification.enabled で設定できます
• code_simplified 完了インジケーターを追加します
• コードに変更がない場合（ドキュメントのみのタスク）はスキップします

nav-diagnose との連携

停滞すると、nav-diagnose による品質チェックがトリガーされます。

• 同じ状態が 3 ループ続くと、品質上の問題が疑われます
• nav-diagnose は根本原因の特定に役立ちます
• 再アンカーにより、行き詰まったループを解消できる場合があります

nav-marker との連携

マーカーにはループ状態が記録されます。

• 現在の反復回数と最大反復回数
• マーカー作成時のフェーズ
• 継続性を保つための状態ハッシュ
• 完了インジケーターの状態

ToM 機能との連携

ループモードは ToM の設定を尊重します。

• VERIFY フェーズでは検証チェックポイントが引き続き適用されます
• プロファイルの設定はコミュニケーションスタイルに影響します
• 信念アンカーは、行き詰まった状態の明確化に役立つ場合があります

---

定義済み関数

functions/status_generator.py

整形済みの NAVIGATOR_STATUS ブロックを生成します。

functions/exit_gate.py

二重条件による終了（ヒューリスティック＋明示的シグナル）を評価します。

functions/stagnation_detector.py

状態ハッシュを計算し、連続して同じ状態になっていることを検出します。

functions/phase_detector.py

コンテキストから現在のタスクフェーズを自動検出します。

---

エラー処理

設定ファイルが見つからない場合：

Loop mode config not found in .nav-config.json.
Using defaults: max_iterations=5, stagnation_threshold=3

関数の実行に失敗した場合：

• 手動評価に切り替えます
• エラーを記録しますが、ループは中断しません
• 可能な範囲でフェーズの検出を続けます

ループの途中でユーザーが中止した場合：

• 部分完了マーカーを作成します
• これまでの進捗を記録します
• 残りの作業を一覧表示します

---

成功基準

以下を満たすと、ループモードは成功です。

• max_iterations 以内にタスクが完了する
• 停滞による一時停止がない（または速やかに解消される）
• EXIT_SIGNAL とヒューリスティック条件の両方を満たしている
• 完了マーカーにループ状態が含まれている
• 各反復でユーザーに明確な進捗が示される

---

例

例 1：簡単な機能

User: "Run until done: add isPrime function with tests"

Iteration 1 (INIT → RESEARCH):
  - Read existing math utils
  - Found test patterns

Iteration 2 (IMPL):
  - Created isPrime function
  - Created test file

Iteration 3 (VERIFY):
  - Ran tests: PASS
  - Committed changes

{"v":2,"type":"exit","success":true,"reason":"isPrime function implemented and tests passing"}

→ Loop complete in 3 iterations

例 2：停滞からの復帰

User: "Run until done: fix authentication bug"

Iteration 1-3 (IMPL):
  - Same changes attempted
  - Tests still failing
  - State hash unchanged

→ STAGNATION DETECTED

User: "The test needs a mock for the auth service"

Iteration 4 (IMPL):
  - Added mock
  - Tests pass

{"v":2,"type":"exit","success":true,"reason":"Auth bug fixed with mock service"}

→ Loop complete in 4 iterations

---

制限事項

対応できないもの：

• 外部要因によるブロッカー（API や権限の待機など）
• 主観的な完了基準（「見栄えをよくする」など）
• ループの途中で人間の判断が必要なタスク

次の用途には使用しないでください：

• 簡単な修正（1 回の反復で十分なもの）
• 探索的な作業（明確な完了状態がないもの）
• セキュリティ上の影響があるタスク（人間によるレビューが必要）

---

このスキルにより、Navigator のコンテキスト効率と ToM 統合を維持しながら、Ralph スタイルの「完了するまで実行」機能を利用できます。