nav-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Navigator Loop Skill

Execute tasks iteratively until completion with structured signals, stagnation detection, and dual-condition exit gates.

通过结构化信号、停滞检测和双条件退出门控，迭代执行任务直至完成。

Why This Exists

为什么存在

Traditional AI coding requires manual "keep going" prompts. Navigator Loop provides:

Structured completion signals (NAVIGATOR_STATUS block)
Dual-condition exit gate (heuristics + explicit signal)
Stagnation detection (circuit breaker for stuck loops)
Progress visibility (phases: INIT → RESEARCH → IMPL → VERIFY → COMPLETE)

Based on Ralph's autonomous loop innovations, adapted for Navigator's context-efficient architecture.

传统 AI 编程需要手动输入“keep going”提示。Navigator Loop 提供：

结构化完成信号（NAVIGATOR_STATUS 块）
双条件退出门控（启发式条件 + 明确信号）
停滞检测（用于打破卡住循环的熔断机制）
进度可见性（阶段：INIT → RESEARCH → IMPL → VERIFY → COMPLETE）

基于 Ralph 的自主循环创新，针对 Navigator 的上下文高效架构进行了适配。

When to Invoke

调用时机

Auto-invoke when:

User says "run until done", "keep going until complete"
User says "iterate until finished", "autonomous mode"
User says "loop mode", "don't stop until done"
Task document has
```
loop_mode: true
```

DO NOT invoke if:

Single-step task (no iteration needed)
User says "just do this once"
Already in loop mode (prevent nested loops)
User explicitly disabled loop mode

自动调用场景：

用户说“run until done”“keep going until complete”
用户说“iterate until finished”“autonomous mode”
用户说“loop mode”“don't stop until done”
任务文档中包含
```
loop_mode: true
```

请勿调用的情况：

单步任务（无需迭代）
用户说“just do this once”
已处于循环模式（防止嵌套循环）
用户明确禁用了循环模式

Configuration

配置

Loop mode settings in

.agent/.nav-config.json

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"
  }
}

Core options:

```
enabled
```
: Default state for new tasks
```
max_iterations
```
: Hard cap to prevent infinite loops (1-20)
```
stagnation_threshold
```
: Same-state count before pause (2-5)
```
exit_requires_explicit_signal
```
: Require EXIT_SIGNAL alongside heuristics
```
show_status_block
```
: Render NAVIGATOR_STATUS each iteration

Autonomous / overnight options (v6.2.2+):

```
iteration_approval
```
: When to prompt the user for accept/reject between iterations.
- ```
"none"
```
  (default) — never prompt; loop runs uninterrupted
- ```
"strict"
```
  — prompt after every iteration
- ```
"periodic"
```
  — prompt every N iterations (where N =
```
periodic_interval
```
  , default 3)
```
periodic_interval
```
: When
```
iteration_approval == "periodic"
```
, the cadence of prompts. Default 3 (every 3rd iteration). Set higher for less frequent check-ins on long overnight runs (e.g., 5 or 10).
```
never_pause_on_stagnation
```
: If
```
true
```
, stagnation triggers auto-diversification instead of an
```
AskUserQuestion
```
pause. Required for true overnight runs. Inspired by karpathy/autoresearch's NEVER STOP directive.
```
stagnation_diversify_strategy
```
: Which recovery to attempt when
```
never_pause_on_stagnation
```
fires.
- ```
"combine"
```
  — combine previous near-misses / partially-met indicators
- ```
"radical"
```
  — try a substantially different approach (re-architect, swap library)
- ```
"reread"
```
  — re-read the in-scope task/system docs for missed signals

Safety guard: Setting

never_pause_on_stagnation: true

REQUIRES

max_iterations

to be set explicitly (the default of 5 is fine; the point is — no infinite default). Without a max, an autonomous loop can spin forever on a fundamentally broken task.

.agent/.nav-config.json

中的循环模式设置：

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 也可以；关键在于不能采用无限循环的默认值）。如果没有上限，自主循环可能会在存在根本性问题的任务上无限运行。

Execution Steps

执行步骤

Step 1: Initialize Loop State

第 1 步：初始化循环状态

Load configuration:

bash

python3 functions/phase_detector.py --init

Initialize tracking variables:

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

Display loop start:

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

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

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

加载配置：

bash

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...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 2: Execute Iteration

第 2 步：执行迭代

Perform task work based on current phase:

Phase	Actions
INIT	Load context, understand requirements
RESEARCH	Explore codebase, find patterns
IMPL	Write code, make changes
VERIFY	Run tests, validate functionality, simplify code
COMPLETE	All indicators met, ready to exit

Track changes during iteration:

Files read (for RESEARCH detection)
Files changed (for IMPL detection)
Tests run (for VERIFY detection)
Commits made (for completion indicator)

根据当前阶段执行任务：

阶段	操作
INIT	加载上下文，理解需求
RESEARCH	探索代码库，查找模式
IMPL	编写代码，进行更改
VERIFY	运行测试，验证功能，简化代码
COMPLETE	所有指标均已满足，可以退出

迭代期间跟踪变化：

读取的文件（用于 RESEARCH 检测）
更改的文件（用于 IMPL 检测）
运行的测试（用于 VERIFY 检测）
创建的提交（用于完成指标判断）

Step 3: Generate Status Block

第 3 步：生成状态块

After each iteration, generate NAVIGATOR_STATUS:

bash

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}"

Display status block:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

每轮迭代后，生成 NAVIGATOR_STATUS：

bash

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}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3.5: Per-Iteration Approval Gate (optional)

第 3.5 步：每次迭代的审批门控（可选）

Skip this step if

config.loop_mode.iteration_approval == "none"

(default).

Run this step if the user wants oversight between iterations — for risky changes, learning the loop's behavior, or sanity-checking before a long run.

Setting	Behavior
`"none"`	Never prompt. Loop continues to Step 4.
`"strict"`	Prompt after every iteration.
`"periodic"`	Prompt every Nth iteration. N defaults to 3; configurable via `loop_mode.periodic_interval` .

When prompting, use AskUserQuestion immediately after the status block:

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

Decision handling:

Continue: Proceed to Step 4 normally.
Adjust: Capture the user's feedback into a transient note, do NOT advance hash history (so the next iteration is judged as fresh progress), continue to Step 4.
Abort: Jump to Step 8 (Cleanup) with
```
status: "user_aborted"
```
.

This gate runs BEFORE stagnation detection so that a rejected iteration doesn't accidentally accumulate stagnation count.

如果

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

决策处理：

Continue：正常进入第 4 步。
Adjust：将用户反馈记录到临时备注中；不要推进哈希历史（这样下一轮迭代会被判定为新的进展），然后继续进入第 4 步。
Abort：跳转到第 8 步（清理），并设置
```
status: "user_aborted"
```
。

此门控在停滞检测之前运行，避免被拒绝的迭代意外累积停滞计数。

Step 4: Check Stagnation

第 4 步：检查停滞

Calculate state hash:

bash

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

If stagnation detected (same hash for N iterations), the response depends on

never_pause_on_stagnation

计算状态哈希：

bash

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

如果检测到停滞（连续 N 轮迭代的哈希相同），响应取决于

never_pause_on_stagnation

。

Default behavior (

never_pause_on_stagnation: false

)

默认行为（

never_pause_on_stagnation: false

）

Prompt the user:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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

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

Use AskUserQuestion for choice:

Continue: Reset stagnation counter, continue loop
Clarify: User explains blocker, incorporate and continue
Abort: Exit loop with partial completion marker

提示用户：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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 让用户选择：

Continue：重置停滞计数器并继续循环
Clarify：用户说明阻塞原因，将其纳入考量后继续
Abort：退出循环并创建部分完成标记

Autonomous behavior (

never_pause_on_stagnation: true

)

自主行为（

never_pause_on_stagnation: true

）

The loop is running unattended (overnight, CI, etc.). Do NOT prompt — auto-diversify based on

stagnation_diversify_strategy

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

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

Strategy	What to attempt next iteration
`combine`	Re-examine partially-met indicators; combine 2 near-miss approaches from previous iterations
`radical`	Discard the current approach; try a substantially different design (different library, different architecture, different algorithm)
`reread`	Re-read the in-scope task doc + relevant system docs; look for a missed signal or constraint

After diversifying:

Reset stagnation counter to 0
Record the diversification in the iteration's notes (so the next status block reflects it)
Continue to Step 5

Hard stop: Even in autonomous mode, the loop still terminates on

max_iterations

. If diversification has been triggered ≥3 times within a single run, escalate to the abort path (creates a

loop-aborted

marker and exits) — repeated diversification is itself a signal that the task is fundamentally stuck.

Inspired by karpathy/autoresearch's NEVER STOP directive: "If you run out of ideas, think harder — read papers, re-read in-scope files for new angles, try combining previous near-misses, try more radical architectural changes."

循环正在无人值守地运行（通宵执行、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

处终止。如果单次运行中多样化操作触发 ≥3 次，则升级到中止路径（创建

loop-aborted

标记并退出）——反复多样化本身就表明任务从根本上陷入了僵局。

受 karpathy/autoresearch 的 NEVER STOP 指令启发：“如果想不出办法，就更深入地思考——阅读论文，重新阅读任务范围内的文件以寻找新角度，尝试组合之前接近成功的方案，尝试更激进的架构变更。”

Step 5: Check Exit Conditions

第 5 步：检查退出条件

Evaluate dual-condition gate:

bash

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

Exit conditions:

Heuristics: At least 2 completion indicators met
EXIT_SIGNAL: Explicit signal that task is complete

Completion indicators (mapped from autonomous protocol):

```
code_committed
```
: Changes committed to git
```
tests_passing
```
: Test suite passes (exit code 0)
```
code_simplified
```
: Code simplified for clarity (v5.4.0+)
```
docs_updated
```
: Documentation files changed
```
ticket_closed
```
: PM tool ticket marked done
```
marker_created
```
: Completion marker exists

Exit decision logic:

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

评估双条件门控：

bash

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

退出条件：

启发式条件：至少满足 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

Step 6: Handle Max Iterations

第 6 步：处理最大迭代次数

If 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

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

如果 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

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

Step 7: Complete Loop

第 7 步：完成循环

When exit conditions met, emit the exit signal in JSON format and display completion:

pilot

{"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}

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

Execute autonomous completion protocol:

Commit changes (if not already)
Archive task documentation
Close ticket (if PM configured)
Create completion marker (with loop state)
Suggest compact

满足退出条件时，以 JSON 格式发出退出信号并显示完成信息：

pilot

{"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}

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

执行自主完成协议：

提交更改（如尚未提交）
归档任务文档
关闭工单（如已配置 PM）
创建完成标记（包含循环状态）
建议执行 compact

Setting EXIT_SIGNAL

设置 EXIT_SIGNAL

The EXIT_SIGNAL is set explicitly by Claude when:

All primary task requirements are met
Code is functional and tested
No obvious remaining work

How to signal completion (v2 JSON format):

pilot

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

The JSON format in a

pilot-signal

code block ensures unambiguous detection by Pilot automation. The

reason

field should briefly describe why the task is complete.

Signal fields:

```
v
```
: Version (always
```
2
```
)
```
type
```
: Signal type (always
```
"exit"
```
for completion)
```
success
```
: Whether task completed successfully (
```
true
```
/
```
false
```
)
```
reason
```
: Brief explanation of completion state

This explicit declaration prevents premature exits when heuristics are met but work remains.

EXIT_SIGNAL 由 Claude 在以下情况下显式设置：

所有主要任务需求均已满足
代码功能正常且已经过测试
没有明显剩余的工作

如何发出完成信号（v2 JSON 格式）：

pilot

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

在

pilot-signal

代码块中使用 JSON 格式，可确保 Pilot 自动化可靠、无歧义地检测到信号。

reason

字段应简要说明任务完成的原因。

信号字段：

```
v
```
：版本（始终为
```
2
```
）
```
type
```
：信号类型（完成时始终为
```
"exit"
```
）
```
success
```
：任务是否成功完成（
```
true
```
/
```
false
```
）
```
reason
```
：完成状态的简要说明

这种显式声明可防止在启发式条件已满足但工作仍未完成时过早退出。

Phase Detection

阶段检测

Phases auto-detected based on context:

python

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"

阶段会根据上下文自动检测：

python

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"

Integration with Navigator

与 Navigator 集成

With Autonomous Completion

与自主完成机制集成

Loop mode enhances (not replaces) the autonomous protocol:

Completion indicators map to autonomous steps
EXIT_SIGNAL triggers autonomous completion
Marker includes loop state for restoration

循环模式增强（而非取代）自主协议：

完成指标映射到自主执行步骤
EXIT_SIGNAL 触发自主完成流程
标记包含循环状态，以便恢复

With nav-simplify (v5.4.0+)

与 nav-simplify（v5.4.0+）集成

Simplification runs during VERIFY phase:

After tests pass, before committing
Configurable via
```
simplification.enabled
```
in .nav-config.json
Adds
```
code_simplified
```
completion indicator
Skip if no code changes (docs-only tasks)

简化操作在 VERIFY 阶段运行：

测试通过后、提交之前执行
可通过 .nav-config.json 中的
```
simplification.enabled
```
配置
增加
```
code_simplified
```
完成指标
如果没有代码更改（仅涉及文档的任务），则跳过

With nav-diagnose

与 nav-diagnose 集成

Stagnation triggers nav-diagnose quality check:

3 same-state loops = potential quality issue
nav-diagnose helps identify root cause
Re-anchoring can resolve stuck loops

停滞会触发 nav-diagnose 质量检查：

连续 3 次相同状态的循环意味着可能存在质量问题
nav-diagnose 有助于识别根本原因
重新锚定可以解决卡住的循环

With nav-marker

与 nav-marker 集成

Markers capture loop state:

Current iteration and max
Phase at time of marker
State hash for continuity
Completion indicators status

标记会捕获循环状态：

当前迭代次数和最大迭代次数
创建标记时所处阶段
用于保持连续性的状态哈希
完成指标状态

With ToM Features

与 ToM 功能集成

Loop mode respects ToM configuration:

Verification checkpoints still apply in VERIFY phase
Profile preferences affect communication style
Belief anchors can help clarify stuck states

循环模式遵循 ToM 配置：

VERIFY 阶段仍会应用验证检查点
Profile 首选项会影响沟通风格
Belief anchors 有助于澄清卡住的状态

Predefined Functions

预定义函数

functions/status_generator.py

Generates formatted NAVIGATOR_STATUS block.

生成格式化的 NAVIGATOR_STATUS 块。

functions/exit_gate.py

Evaluates dual-condition exit (heuristics + explicit signal).

评估双条件退出机制（启发式条件 + 明确信号）。

functions/stagnation_detector.py

Calculates state hash and detects consecutive same-states.

计算状态哈希并检测连续相同状态。

functions/phase_detector.py

Auto-detects current task phase from context.

根据上下文自动检测当前任务阶段。

Error Handling

错误处理

Config not found:

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

Function execution fails:

Fall back to manual evaluation
Log error but don't interrupt loop
Continue with best-effort phase detection

User aborts mid-loop:

Create partial completion marker
Document progress made
List remaining work

未找到配置：

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

函数执行失败：

回退到手动评估
记录错误但不中断循环
继续尽力检测阶段

用户在循环中途中止：

创建部分完成标记
记录已完成的进展
列出剩余工作

Success Criteria

成功标准

Loop mode succeeds when:

Task completes within max_iterations
No stagnation pauses (or resolved quickly)
EXIT_SIGNAL + heuristics both satisfied
Completion marker includes loop state
User sees clear progress each iteration

循环模式在满足以下条件时成功：

任务在
```
max_iterations
```
内完成
没有停滞暂停（或已快速解决）
EXIT_SIGNAL 和启发式条件均已满足
完成标记包含循环状态
用户每轮都能看到清晰的进度

Examples

示例

Example 1: Simple Feature

示例 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

pilot

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

→ Loop complete in 3 iterations

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

pilot

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

→ Loop complete in 3 iterations

Example 2: Stagnation Recovery

示例 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

pilot

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

→ Loop complete in 4 iterations

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

pilot

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

→ Loop complete in 4 iterations

Limitations

限制

Cannot handle:

External blockers (waiting for API, permissions)
Subjective completion criteria ("make it look nice")
Tasks requiring human judgment mid-loop

Should not use for:

Quick fixes (single iteration sufficient)
Exploratory work (no clear completion state)
Tasks with security implications (need human review)

This skill provides Ralph-style "run until done" capability while maintaining Navigator's context efficiency and ToM integration.

无法处理：

外部阻塞（等待 API、权限）
主观完成标准（“让它看起来更美观”）
需要中途人工判断的任务

不应使用于：

快速修复（单轮迭代即足够）
探索性工作（没有明确的完成状态）
具有安全影响的任务（需要人工审查）

此 skill 提供 Ralph 风格的“运行直至完成”能力，同时保持 Navigator 的上下文效率和 ToM 集成。

nav-loop

Original

Translation

Navigator Loop Skill

Navigator Loop Skill

Why This Exists

为什么存在

When to Invoke

调用时机

Configuration

配置

Execution Steps

执行步骤

Step 1: Initialize Loop State

第 1 步：初始化循环状态

Step 2: Execute Iteration

第 2 步：执行迭代

Step 3: Generate Status Block

第 3 步：生成状态块

Step 3.5: Per-Iteration Approval Gate (optional)

第 3.5 步：每次迭代的审批门控（可选）

Step 4: Check Stagnation

第 4 步：检查停滞

Default behavior (never_pause_on_stagnation: false)

默认行为（never_pause_on_stagnation: false）

Autonomous behavior (never_pause_on_stagnation: true)

自主行为（never_pause_on_stagnation: true）

Step 5: Check Exit Conditions

第 5 步：检查退出条件

Step 6: Handle Max Iterations

第 6 步：处理最大迭代次数

Step 7: Complete Loop

第 7 步：完成循环

Setting EXIT_SIGNAL

设置 EXIT_SIGNAL

Phase Detection

阶段检测

Integration with Navigator

与 Navigator 集成

With Autonomous Completion

与自主完成机制集成

With nav-simplify (v5.4.0+)

与 nav-simplify（v5.4.0+）集成

With nav-diagnose

与 nav-diagnose 集成

With nav-marker

与 nav-marker 集成

With ToM Features

与 ToM 功能集成

Predefined Functions

预定义函数

functions/status_generator.py

functions/status_generator.py

functions/exit_gate.py

functions/exit_gate.py

functions/stagnation_detector.py

functions/stagnation_detector.py

functions/phase_detector.py

functions/phase_detector.py

Error Handling

错误处理

Success Criteria

成功标准

Examples

示例

Example 1: Simple Feature

示例 1：简单功能

Example 2: Stagnation Recovery

示例 2：停滞恢复

Limitations

限制

Default behavior (
`never_pause_on_stagnation: false`
)

默认行为（
`never_pause_on_stagnation: false`
）

Autonomous behavior (
`never_pause_on_stagnation: true`
)

自主行为（
`never_pause_on_stagnation: true`
）