| name | collie:autoiter |
| description | Main loop orchestrator for collie. Drives the 'run → observe → triage → deep-verify → fix → rerun' self-iteration pipeline. Called by commands/autoiter.md on every ralph-loop session restart. Implements a persistent state machine (§3.5) across ralph-loop session restarts: fresh-start → Stage 0 (Discovery planmode) → Stage 1 (kickoff) → Stage 2 (run trigger) → Stage 3 (observe + auto-recovery) → Stage 4a (Triage) → Stage 4b (Deep Verify) → Stage 5.0 (fix-plan) → Stage 5.1 (flow) → Stage 5.2 (G6 diff audit + rerun) → Stage 6 (rollback + stop check). Completion signal: <promise>Collie: AUTOITER DONE</promise> (emitted ONLY by the §3.5 terminal branch after ralph-loop restart, NEVER inline). |
| dependencies | ["collie:flow","collie:review","ralph-loop","superpowers:subagent-driven-development"] |
collie:autoiter — Main Autoiter Orchestrator
Drives the iterative improvement pipeline: run trigger → observe → triage → deep-verify → gated fix → rerun → stop check. Invoked by commands/autoiter.md on every ralph-loop session restart.
Completion signal: <promise>Collie: AUTOITER DONE</promise>
Sentinel rule: Emitted ONLY by the §3.5 terminal branch. NO other stage emits it inline.
Flowchart
digraph autoiter {
rankdir=TB;
node [shape=box, style=rounded];
entry [label="SKILL entry\n§3.5 state machine"];
nested_check [label="Nested-call check\n(COLLIE_AUTOITER_ACTIVE?)"];
fail_fast [label="fail-fast escalate\n(do NOT rm current-run)", shape=ellipse];
no_current_run [label="current-run missing?", shape=diamond];
fresh_start [label="Fresh start:\ngenerate runId\nwrite current-run"];
stage0 [label="Stage 0\nDiscovery & Lock\n(planmode)"];
ralph_restart [label="ExitPlanMode\n→ ralph-loop restart"];
run_spec_missing [label="run-spec.md missing?", shape=diamond];
recovery [label="Recovery chain:\nlast-plan.json→plan file\n→plan-source→cp run-spec.md"];
recovery_fail [label="Recovery failed\nrm current-run", shape=ellipse];
worktree_prepare [label="Create worktree\nautoiter-prepare (if needed)\ninit state.json(iter=1)"];
read_state [label="Read state.json"];
terminal [label="status=terminal:\nrm current-run\nemit sentinel", shape=ellipse];
stage1 [label="Stage 1 Kickoff"];
stage2 [label="Stage 2 Run Trigger\n(background)"];
stage3 [label="Stage 3 Observe"];
blocker [label="Blocking issue?\nauto-recovery ladder", shape=diamond];
blocker_fail [label="Write escalated → return\n(§3.5 handles)", shape=ellipse];
stage4a [label="Stage 4a Triage\n(opus, reverse suspicion)"];
stage4b [label="Stage 4b Deep Verify\n(opus, adversarial, parallel)"];
stage50 [label="Stage 5.0 Fix Plan\n(G7 check first)"];
g7_fail [label="G7 deadlock\nescalated → return", shape=ellipse];
stage51 [label="Stage 5.1 flow"];
stage52 [label="Stage 5.2 G6 Diff Audit"];
g6_fail [label="G6 fail\nescalated → return", shape=ellipse];
stage53 [label="Stage 5.3 Rerun + scalar"];
stage6 [label="Stage 6 Rollback + Stop Check"];
stop [label="Stop: write terminal state\nreturn (§3.5 handles sentinel)", shape=ellipse];
next_iter [label="iter++\nstate=running → Stage 1"];
entry -> nested_check;
nested_check -> fail_fast [label="COLLIE_AUTOITER_ACTIVE set"];
nested_check -> no_current_run [label="not nested"];
no_current_run -> fresh_start [label="yes"];
no_current_run -> run_spec_missing [label="no"];
fresh_start -> stage0;
stage0 -> ralph_restart;
ralph_restart -> entry [label="next session §3.5 re-entry"];
run_spec_missing -> recovery [label="yes"];
recovery -> recovery_fail [label="chain fails"];
recovery_fail -> fresh_start [label="fresh start"];
recovery -> worktree_prepare [label="success"];
worktree_prepare -> stage1;
run_spec_missing -> read_state [label="no"];
read_state -> stage1 [label="status=running"];
read_state -> stage6 [label="status=iter_done"];
read_state -> terminal [label="status=terminal"];
stage1 -> stage2;
stage2 -> stage3;
stage3 -> blocker;
blocker -> stage4a [label="no blocking issues"];
blocker -> blocker_fail [label="ladder exhausted"];
stage4a -> stage4b;
stage4b -> stage50;
stage50 -> g7_fail [label="G7 deadlock"];
stage50 -> stage51 [label="ok"];
stage51 -> stage52;
stage52 -> g6_fail [label="audit FAIL"];
stage52 -> stage53 [label="PASS"];
stage53 -> stage6;
stage6 -> stop [label="SC1-SC5 met"];
stage6 -> next_iter [label="continue"];
next_iter -> stage1;
}
Section 0 — Orchestrator Contract（必读，约束所有 stage）
⛔ 主 session 是协调器，不是执行器。
主 session 禁止做的事
- ❌ 读项目源代码（src 文件）
- ❌ grep / find / 全文搜索项目代码（除单点 hash/scalar 提取）
- ❌ 写实现代码 / 修复代码
- ❌ 解析 > 50 行日志
- ❌ inline 执行 git revert / git reset --hard 实质操作
主 session 必须做的事
- ✅ 决策（基于 subagent 输出）
- ✅ dispatch 子 agent + 状态文件读写
- ✅ 写 status.md / progress.md / fix-plan.md（汇总 subagent 输出）
- ✅ 触发外部命令（trigger / rerun bash 启动）但不解析 stdout
主 session 例外项（明文允许 inline）
仅以下 5 类操作允许 inline，逻辑上是单点动作：
- Stage 2
nohup bash 启动 trigger（单行命令）
- Stage 5.0 写
fix-plan.md（仅汇总 4b deep-verify 输出，禁止读源码）
- Stage 5.2
git diff HEAD~1..HEAD --name-only（单行 git，结果不解析）
- 状态文件 IO（
~/.collie/autoiter/... 下的 status / progress / state）
- iter 边界的目录创建（
mkdir -p iter-N/）
Subagent 派发裁定基准（主 agent 自主裁定，不在 plan 硬编码）
每次需要执行操作时，主 agent 按以下基准自主裁定 inline vs dispatch + model：
裁定步骤：
- 此步是"决策"还是"执行"？决策 inline，执行 dispatch
- 输入是否会污染主 agent 上下文（log / source code / 大返回）？是 → dispatch
- 选 model：参考用户
~/.claude/CLAUDE.md 中的"Agent 模型选择速查"+"Subagent 派发策略"两节
Agent 模型选择速查（节选自用户 CLAUDE.md）：
Explore → haiku（文件搜索、代码分析、只读探索）general-purpose 轻量 → haiku（文档生成、简单分析）general-purpose 标准 → sonnet（代码实现、中等复杂度）general-purpose 复杂 → opus（架构决策、复杂重构）code-reviewer → sonnetPlan → opus（架构设计、规划）
典型应用例子（参考，非强制；具体 stage 由主 agent 实时裁定）：
- 应用 fix patch 到 worktree → 实现型 → dispatch sonnet
- 解析 raw.log 提 scalar → 文档/分析型 → dispatch haiku
- 写 fix-plan.md 综合 → 决策型 → inline（受 §例外项 #2 约束）
- 跑 git revert + verify hash → 执行型 → dispatch haiku
- Triage / Deep Verify → 复杂推理型 → dispatch opus（这是历史不变式，contract test 强制）
历史不变式（contract test 强制保留）
- Stage 4a/4b（Triage / Deep Verify）必须保持 opus subagent，不可降为 inline 或更低 model
- Stage 5.0 fix-plan 必须保持 inline 但受 §例外项 #2 约束
任何其他 stage 的 inline / dispatch + model 选择由主 agent 实时裁定，plan 不硬编码。
§3.5 Entry State Machine (FIRST thing executed every session)
Setup
PROJECT_ID=$(node -e "const s=require('./hooks/_state.js'); console.log(s.projectId())")
CURRENT_RUN_FILE=$(node -e "const s=require('./hooks/_state.js'); console.log(s.currentRunFile('$PROJECT_ID'))")
Nested-call check
If COLLIE_AUTOITER_ACTIVE environment variable is set → this is a nested call from inside another /auto or /autoiter session.
Action: call scripts/escalate.sh "nested_loop_call" "$PROJECT_ID" then stop immediately. Do NOT rm current-run (the outer run owns it).
If not nested: set export COLLIE_AUTOITER_ACTIVE=1 for all subprocesses in this session, then proceed.
Branch A — No current-run file
~/.collie/autoiter/{project-id}/current-run does NOT exist → Fresh start:
- Generate
runId: YYYYMMDD-HHMMSS-{shortSessionId} (use date +%Y%m%d-%H%M%S + first 6 chars of $CLAUDE_SESSION_ID or random hex)
mkdir -p ~/.collie/autoiter/{project-id}/- Write runId to current-run file
- Proceed to Stage 0
Branch B — current-run exists, run-spec.md does NOT exist
Post-planmode recovery path:
runId = $(cat $CURRENT_RUN_FILE)- Attempt recovery chain:
- Read
~/.collie/state/{sessionId}/last-plan.json → get plan file path
- Read first 3 lines of plan file → extract
plan-source field value
- If recovery chain fails at any step →
rm $CURRENT_RUN_FILE → go to Branch A
- Recovery succeeded:
mkdir -p ~/.collie/autoiter/{project-id}/{runId}/
cp "$PLAN_SOURCE" ~/.collie/autoiter/{project-id}/{runId}/run-spec.md
git worktree add .worktrees/autoiter-{runId} -b autoiter/{runId}
echo "$(pwd)/.worktrees/autoiter-{runId}" > ~/.collie/autoiter/{project-id}/{runId}/worktree-path
- Read
skip_prepare from run-spec.md
- If
skip_prepare=false AND prepare-report.md does NOT exist:
- Call
Skill('collie:autoiter-prepare') with: run_spec_path, report_path, project_id, run_id, worktree_path
- PASS → continue
- FAIL (interactive):
AskUserQuestion "Prepare failed: [X]. Fix material and retry, or abort?"
- FAIL (queued): write
state.json.status="escalated" → return (§3.5 terminal handles on next restart)
- Initialize
state.json:
{
"runId": "<runId>",
"iter": 1,
"status": "running",
"should_continue": true,
"stop_reason": null,
"last_scalar": null,
"baseline_scalar": null,
"promise_signal": "Collie: AUTOITER DONE"
}
- Proceed to Stage 1
Branch C — current-run AND run-spec.md exist
Read state.json:
| status | action |
|---|
"running" | Re-enter Stage 1 kickoff (idempotent: skip write if kickoff.md already exists) |
"iter_done" | Proceed to Stage 6 stop check |
"converged" / "budget_exhausted" / "escalated" | Terminal: rm current-run → print [autoiter {runId}] All done — status={status} → emit <promise>Collie: AUTOITER DONE</promise> → stop |
| missing | Treat same as Branch B (run-spec.md missing path) |
Stage 0 — Discovery & Lock (planmode)
Only reached on fresh start from Branch A.
Step 0.1 — Enter planmode
Call EnterPlanMode.
Step 0.2 — Discovery subagent (haiku, Explore / read-only)
Dispatch haiku subagent using system prompt from skills/autoiter/references/discovery-prompt.md. Input: project root. Output:
- Ranked candidate trigger list (each: command, kind, score 1-5, rationale)
- Suggested
success_criterion type (all_green / scalar_threshold / convergence_delta / custom)
- Suggested
primary_goal (correctness / optimization / both)
Step 0.3 — AskUserQuestion (Q1-Q5)
Collect all 5 in one batch:
- Q1: Which trigger? (show ranked list from Discovery; allow custom)
- Q2: Success criterion type and threshold?
- Q3:
primary_goal? (correctness / optimization / both)
- Q4:
iter_rollback_policy? (default: kind_aware)
- Q5: Skip Stage 0.5 prepare check? (default: No)
Step 0.4 — Write run-spec to planmode plan file
Write to planmode system-prompt-specified plan file (do NOT override path). Top 3 lines must be:
<!-- plan-source: <planmode plan file absolute path> -->
<!-- plan-kind: autoiter-stage0 -->
<!-- plan-executor: collie:autoiter -->
Body YAML:
task: <user prompt verbatim>
primary_goal: <Q3>
trigger:
kind: shell|replay|dataset
invocation: "<shell command>"
expected_output: "stdout stream / junit xml / custom parser"
scalar_extraction: "<grep/regex/jq path>"
success_criterion:
type: all_green|scalar_threshold|convergence_delta|custom
threshold: <Q2 value>
budget:
max_iterations: 5
max_tokens: unlimited
max_wallclock_min: unlimited
overfit_guards: [G1, G2, G3, G4, G5, G6, G7, G8]
iter_rollback_policy: kind_aware
skip_prepare: false
Step 0.5 — ExitPlanMode
Call ExitPlanMode. This is the ONLY exit from Stage 0.
ralph-loop restarts the session. §3.5 Branch B (recovery path) handles everything after.
Stage 1 — Kickoff (idempotent)
Step 0 — TaskCreate stage 锚定（每 iter 起始必做）
⛔ 每次进入 Stage 1（iteration 起始）必须先做这一步，再做原 Step 1。
-
上一 iter 的 [iter-{N-1} stage-*] 任务先标 completed（正常结束）或 deleted（被 rollback）
-
TaskCreate 6 次建立本 iter 锚点：
[iter-N stage-1] Kickoff（git HEAD + baseline）[iter-N stage-2] Run trigger（subprocess background + Monitor/tail）[iter-N stage-3] Observe（ISSUE 收集 + auto-recovery 阶梯）[iter-N stage-4] Triage + Deep Verify（4a/4b opus）[iter-N stage-5] Fix Plan + flow + G6 audit + Rerun（5.0/5.1/5.2/5.3）[iter-N stage-6] Rollback + Stop Check
N 从 state.json 读取
-
TaskUpdate [iter-N stage-1] in_progress，进入原 Step 1
-
Self-anchor：长 dispatch（subagent 返回 > 200 字符或耗时 > 30s）后，主 agent 必须先 TaskList 确认当前 anchor 与 SKILL 当前 stage 一致；漂移 → STOP + escalate stage_anchor_drift。Stage 切换时 TaskUpdate 切 completed/in_progress 后再进入下一 stage。
All Stage 1+ work runs inside the worktree. Read worktree-path to get the absolute path.
WORKTREE=$(cat ~/.collie/autoiter/{project-id}/{runId}/worktree-path)
ITER_DIR=~/.collie/autoiter/{project-id}/{runId}/iter-{N}
mkdir -p $ITER_DIR/fixes
Write iter-N/kickoff.md (skip if already exists — idempotency):
# Kickoff — iter-N
git_head: <git rev-parse HEAD>
baseline_metric: <state.last_scalar or "none (first iter)">
iter_goal: <based on progress.md DEFERRED pool if iter > 1>
timestamp: <ISO-8601>
Observability:
- Overwrite
status.md: iter N/M · Stage 1 · Kickoff · preparing trigger
- Append
user-log.md: ## iter-N · <ts>\nKickoff. HEAD: <sha>. Baseline scalar: <val>.
- Stdout:
[autoiter {runId}] iter-N Stage 1 → Kickoff
Stage 2 — Run Trigger
Subprocess timeout
timeout_min = min(max_wallclock_min / max_iterations, 30)
# "unlimited" in either field → use 30 min
Launch (background)
cd $WORKTREE
timeout ${timeout_min}m bash -c "<trigger.invocation>" \
> $ITER_DIR/raw.log 2>&1
echo "EXIT_CODE:$?" >> $ITER_DIR/raw.log
Monitor detection (once per session, cache result)
ToolSearch query="select:Monitor"
Monitor available: Subscribe to stdout stream in real-time. Record observations to iter-N/raw.log.
Monitor NOT available (fallback):
ScheduleWakeup delaySeconds=60 on each poll cycle- On wakeup: Read last 100 lines of
raw.log
- Scan for ISSUE patterns (errors, metrics)
- Loop until
EXIT_CODE: line appears in raw.log
Observability:
- Overwrite
status.md: iter N/M · Stage 2 · Running trigger · <elapsed>s elapsed
- Stdout:
[autoiter {runId}] iter-N Stage 2 → trigger running (timeout: {timeout_min}min)
Stage 3 — Observe & Auto-Recovery
⚠️ 本 stage 内每次执行操作前请按 §Section 0 裁定基准选择 inline / dispatch + model。fix 应用属"执行"型，参考速查表选 sonnet。
Step 3.1 — Write observations.md
Parse raw.log. For each issue:
## ISSUE-{nnn}
- title: <one-line summary>
- evidence: <log excerpt, max 5 lines>
- severity: 1-5
- first_seen_ts: <monotonic>
- blocking: true|false
Non-blocking issues → record and continue to Stage 4a.
Step 3.2 — Blocking issue: auto-recovery ladder
Triggered when blocking: true or exit code non-zero.
Step 1: Kill subprocess:
kill -TERM <pid>; sleep 5; kill -KILL <pid> 2>/dev/null || true
Step 2: Assess complexity → choose start model:
- Simple (syntax/params/config) → haiku
- Medium (logic/deps/env) → sonnet
- Complex (concurrency/perf/arch) → opus
Step 3: Recovery loop, max 3 attempts:
- Dispatch diagnostic subagent at current model (input: last 200 lines of
raw.log + run-spec.md; output: root_cause + fix_patch)
- Apply fix in worktree
- Rerun trigger with 5-min cap for quick validation
- If passes → break (recovery succeeded), proceed to Stage 4a
- If fails → upgrade model: haiku→sonnet→sonnet→opus→opus (cap at opus)
Step 4: All 3 attempts fail → unrecoverable:
- Write
iter-N/blocker-report.md (each attempt: model, root_cause, fix_applied, result)
- Overwrite
status.md: iter N/M · Stage 3 · BLOCKED · auto-recovery ladder exhausted
- Append to
user-log.md
scripts/escalate.sh "blocker_unrecoverable" "$RUN_ID"- If
$COLLIE_AUTOITER_NOTIFY_CMD set: bash -c "$COLLIE_AUTOITER_NOTIFY_CMD" with env COLLIE_AUTOITER_EVENT=blocker_unrecoverable, COLLIE_AUTOITER_RUN_ID, COLLIE_AUTOITER_STATUS_FILE
- Write
state.json.status = "escalated"
- RETURN — §3.5 terminal handles sentinel on next restart. Do NOT emit inline.
Observability:
- Overwrite
status.md: iter N/M · Stage 3 · Observing · {n} issues found
- Stdout:
[autoiter {runId}] iter-N Stage 3 → {n} issues recorded, {m} blocking
Stage 4a — Triage (opus, "reverse suspicion")
Dispatch single opus subagent.
System prompt requirements (G3):
- Must include the phrase "reverse suspicion"
- Must instruct: "Start by finding reasons why each issue is NOT real before concluding it is"
- Max 2 lines verbatim from
observations.md (anchor prevention)
Inputs: iter-N/observations.md + run-spec.md + progress.md
Output: iter-N/triage.md
## ISSUE-{nnn}
verdict: Real | Discarded | Unclear
confidence: 1-5
rationale: <adversarial reasoning>
G8 Gate (Triage level)
| condition | action |
|---|
| confidence ≥ 3, verdict Real/Unclear | Proceed to Stage 4b |
| confidence ≤ 2, verdict Real/Unclear | Write to progress.md DEFERRED pool, tag triage_low_confidence; skip Stage 4b |
| Discarded (any confidence) | Drop silently; do NOT write to DEFERRED |
Observability:
- Overwrite
status.md: iter N/M · Stage 4a · Triage · {n_real} Real, {n_deferred} DEFERRED
- Stdout:
[autoiter {runId}] iter-N Stage 4a → triage complete ({n} → {m} to Deep Verify)
Stage 4b — Deep Verify (opus, per-issue parallel)
For each issue that passed G8 Triage gate, dispatch ONE opus subagent in parallel.
System prompt requirements (G3):
- Must include the phrase "adversarial"
- Must instruct: "Attempt proof of falsification before writing fix outline"
- Max 2 lines verbatim from
observations.md
Output: iter-N/fixes/FIX-{nnn}.md
id: FIX-{nnn}
kind: correctness | optimization | mixed
severity: 1-5
fix_confidence: 1-5
root_cause: "<text — must be non-empty>"
reproduction_test: |
<runnable test reproducing issue BEFORE fix>
fix_outline: "<what to change, where>"
why_root_cause: "<adversarial justification>"
dependencies: [FIX-xxx, ...]
uncertainty_tag: triage_unclear | none
G8 Gate (Deep Verify) + G2 Gate
| condition | action |
|---|
fix_confidence ≤ 2 | DEFERRED pool, tag deep_verify_low_confidence; exclude from Stage 5.0 |
root_cause empty | DEFERRED pool, tag g2_incomplete; exclude from Stage 5.0 |
reproduction_test empty | DEFERRED pool, tag g2_incomplete; exclude from Stage 5.0 |
fix_confidence ≥ 3 AND both fields non-empty | Eligible for Stage 5.0 |
Observability:
- Overwrite
status.md: iter N/M · Stage 4b · Deep Verify · {n} FIX in verification
- Stdout:
[autoiter {runId}] iter-N Stage 4b → {n} issues in parallel Deep Verify
Stage 5.0 — Consolidated Fix Plan
⚠️ 本 stage 是 §Section 0 例外项 #2（受约束 inline）。仅汇总 4b deep-verify 输出到 fix-plan.md，禁止读源码。如需补充信息 → 按裁定基准 dispatch。
G7 check FIRST (before filling template)
const { jaccard, bucketize } = require('./skills/autoiter/lib/jaccard.js');
const ratio = jaccard(currentTasksText, prevTasksText);
const bucket = bucketize(ratio);
See skills/autoiter/references/overfit-guards.md §G7 for bucket thresholds.
If bucket >= 4 AND consecutiveDelta0 >= 2:
- Append to
iter-N/summary.md: Jaccard ratio + bucket
- Write
state.json.status = "escalated"
scripts/escalate.sh "loop_no_progress" "$RUN_ID"- If
$COLLIE_AUTOITER_NOTIFY_CMD set: notify with COLLIE_AUTOITER_EVENT=deadlock
- RETURN — §3.5 terminal handles sentinel on next restart
Fill fix-plan.md
Only FIX entries with fix_confidence ≥ 3 AND non-empty root_cause AND non-empty reproduction_test are eligible.
Write iter-N/fix-plan.md using skills/autoiter/references/fix-plan-template.md:
- 3 metadata lines (top):
<!-- plan-source: <absolute path to iter-N/fix-plan.md> -->
<!-- plan-topic: autoiter-iter-N-fixes -->
<!-- plan-executor: collie:flow -->
- Task Execution DAG (from FIX
dependencies fields; independent FIX = same batch)
- Task Details:
root_cause → Why, fix_outline → How, reproduction_test → Verify
- Impact Assessment: aggregate affected files; Reverse impact must be filled (write
None — iter-local change if no shared-state impact)
- E2E Assessment: inherit from
run-spec.md — do NOT re-derive
Observability:
- Overwrite
status.md: iter N/M · Stage 5.0 · Building fix-plan · {n} FIX eligible
- Stdout:
[autoiter {runId}] iter-N Stage 5.0 → fix-plan.md built ({n} FIX)
Stage 5.1 — flow
Skill('collie:flow')
Input: iter-N/fix-plan.md. Runs full pipeline: TDD → implement → review → simplify → regression → [collie-final-review].
Stage 5.2 — G6 Diff Audit (INLINE, after Stage 5.1 returns)
⚠️ git diff --name-only 是 §Section 0 例外项 #3（inline 取文件清单不解析内容）。审计 diff 内容属"执行+分析"型，按裁定基准 dispatch。
Execute immediately after flow returns.
git diff HEAD~1..HEAD --name-only
For each changed file: verify it appears in fix-plan.md Task list "Key files", OR is a mechanical consequence of a listed fix (auto-generated file, build artifact).
If any diff line is NOT traceable to any FIX entry:
- Log untraceable file + reason
- Write
state.json.status = "escalated"
scripts/escalate.sh "g6_diff_audit_failed" "$RUN_ID"- RETURN — §3.5 terminal handles sentinel on next restart
If audit passes → proceed to Stage 5.3.
See skills/autoiter/references/overfit-guards.md §G6 for full audit rules.
Observability:
- Stdout:
[autoiter {runId}] iter-N Stage 5.2 → G6 diff audit PASS (or FAIL)
Stage 5.3 — Rerun + Record Scalar
⚠️ 启动 rerun bash 是 §Section 0 例外项 #1（inline）。raw.log 解析 / scalar 提取属"执行+分析"型，按裁定基准 dispatch。
cd $WORKTREE
bash -c "<trigger.invocation>" > $ITER_DIR/rerun.log 2>&1
Parse scalar from rerun.log using run-spec.trigger.scalar_extraction.
Write iter-N/summary.md:
# Summary — iter-N
scalar_before: <state.last_scalar>
scalar_after: <new_scalar>
scalar_delta: <new - before>
convergence: yes|no
decision: continue | stop_converged | stop_cap | stop_budget
fixes_applied: [FIX-001, FIX-002, ...]
Update state.json: { "last_scalar": <new_scalar>, "status": "iter_done" }
Observability:
- Overwrite
status.md: iter N/M · Stage 5.3 · Rerun done · scalar={new} (was {old}, Δ={delta})
- Append
user-log.md: narrative of this iter's outcome
- Stdout:
[autoiter {runId}] iter-N Stage 5.3 → rerun done, scalar={new}
Stage 6 — Rollback & Stop Check
⚠️ "是否 rollback"决策 inline；执行 rollback 命令属"执行"型 + 涉及 ❌ 第 5 条（inline git reset），必须按裁定基准 dispatch。
Rollback decision
MUST consult skills/autoiter/references/stop-criterion.md for the authoritative rollback matrix before executing any revert. The inline table below is a quick-reference summary only; the reference document governs all edge cases.
Full matrix in skills/autoiter/references/stop-criterion.md. Summary:
primary_goal | scalar_delta | action |
|---|
correctness | any | Never whole-iter rollback. Keep correctness FIX. Per-FIX revert optimization if scalar degrades. |
optimization | degrades | Per-FIX revert all kind=optimization; force-keep kind=correctness |
optimization | flat/improves | Keep all |
both | degrades + ≥50% optimization FIX | Per-FIX revert optimization; keep correctness |
both | degrades + ≥80% correctness FIX | Keep all (crash-fix priority) |
both | degrades + 50-80% correctness | Per-FIX revert optimization; keep correctness |
both | flat/improves | Keep all |
Per-FIX revert:
git revert --no-commit <commit-sha>
git commit -m "chore: revert optimization FIX(es) due to scalar regression (iter-N)"
Append rollback_log section to iter-N/summary.md for each reverted FIX.
Stop check (SC1-SC5, hybrid OR)
Full spec in skills/autoiter/references/stop-criterion.md.
| ID | Condition | Terminal status |
|---|
| SC1 | iter >= max_iterations | budget_exhausted |
| SC2 | all_green reached OR scalar >= threshold | converged |
| SC3 | Last 2 iters: |scalar_delta| ≤ ε (ε=0 for int 1-5; ε=0.01×|baseline| for continuous) | converged |
| SC4 | tokens_used >= max_tokens OR elapsed >= max_wallclock_min | budget_exhausted |
| SC5 | stop-steps-counter.js triggered (same error ×3 or no file changes ×5) | escalated |
If any stop condition true:
- Write final
iter-N/summary.md decision field
- Overwrite
status.md: DONE · {reason} · scalar={final} (baseline={base}, Δ={total})
- Append final entry to
user-log.md
- If
$COLLIE_AUTOITER_NOTIFY_CMD set: bash -c "$COLLIE_AUTOITER_NOTIFY_CMD" with COLLIE_AUTOITER_EVENT=autoiter_done (or escalated/budget_exhausted)
- Write
state.json.status = <terminal status>
- RETURN — do NOT emit sentinel inline. Preserve worktree. §3.5 terminal branch handles
rm current-run + sentinel on next ralph-loop restart.
- Stdout:
[autoiter {runId}] Stage 6 → STOP ({reason})
If continue:
- Increment iter:
state.json.iter = N+1, status = "running"
- Proceed to Stage 1
- Stdout:
[autoiter {runId}] Stage 6 → continue to iter-{N+1}
Observability (§14 — mandatory at every stage/iter boundary)
At every stage transition and iter boundary, update ALL of:
status.md (overwrite): iter N/M · Stage X · <description> · scalar=<val>user-log.md (append): human-readable narrative- stdout tick:
[autoiter {runId}] iter-N Stage X → ...
- External notify (terminal events only): if
$COLLIE_AUTOITER_NOTIFY_CMD set:
COLLIE_AUTOITER_EVENT=<event> \
COLLIE_AUTOITER_RUN_ID=<runId> \
COLLIE_AUTOITER_STATUS_FILE=<path/to/status.md> \
bash -c "$COLLIE_AUTOITER_NOTIFY_CMD"
Terminal events: autoiter_done, escalated, budget_exhausted, blocker_unrecoverable, prepare_failed, deadlock
Key Invariants
- Sentinel uniqueness:
<promise>Collie: AUTOITER DONE</promise> emitted ONLY by §3.5 terminal branch. Never from Stage 3/5/6 inline.
- run-spec.md is write-once: Written by
cp in Branch B recovery; never modified after creation.
- current-run cleared before sentinel:
rm current-run THEN emit sentinel (crash-safe ordering).
- Worktree preserved: On sentinel, worktree is NOT merged or removed. User reviews and decides.
- G1 invariant: No test file modified unless FIX is
kind=correctness with explicit reproduction_test new-file addition. See overfit-guards.md §G1.
- autoiter-prepare idempotency: If
prepare-report.md already exists, skip prepare entirely.
- Nested calls rejected:
COLLIE_AUTOITER_ACTIVE check prevents /autoiter inside /auto or another /autoiter.
Reference Files
skills/autoiter/references/overfit-guards.md — G1-G8 rules (enforced at Stage 3 / Stage 5.0 / Stage 5.2)skills/autoiter/references/stop-criterion.md — SC1-SC5 + full rollback matrixskills/autoiter/references/fix-plan-template.md — Stage 5.0 templateskills/autoiter/references/discovery-prompt.md — Stage 0.2 Discovery subagent system promptskills/autoiter/references/iter-prompt.md — per-iter observation guidanceskills/autoiter/lib/jaccard.js — G7 token-set Jaccard similarity (zero external deps)
