Skip to content

auto-loop.md

Latest commit

 

History

History
255 lines (190 loc) · 11.8 KB

auto-loop.md

File metadata and controls

255 lines (190 loc) · 11.8 KB

Auto-Loop Rule ⚠️ CRITICAL

Fix -> immediately re-review -> fail -> fix again -> ... -> ✅ Pass -> next step

Prohibited Behaviors

❌ Fixing ≠ Verifying: Claiming "issue fixed" or "already addressed" without running re-review is a violation. Every fix must be verified by invoking the review command — self-assessment does not count. ❌ Skipping dual dispatch: Code review commands must launch both Codex + secondary reviewer in parallel on every iteration (first pass AND loop re-reviews). Secondary is always dispatched in v1. ❌ Asking "Should I re-review?" or "Continue?" after fixing ❌ Asking "要執行嗎？" / "should I execute?" / any confirmation before required review steps — auto-loop mandates execution, not permission ❌ Stopping after outputting a summary without executing review ❌ Waiting for user instructions ❌ Declaring as executing: Saying "need to run X" without actually invoking the tool ❌ Summary as completion: Outputting a polished summary then stopping, without executing the next step ❌ Context/token excuse: Citing context window limits, long session, or token budget as reason to skip or defer review. If context is genuinely exhausted, the model must still attempt the review — failure to invoke is a violation regardless of reason. See @rules/context-management.md for measurement-based context policy. ❌ Polished summary during active loop: Outputting a completion-style summary (table, checklist, "all done" language) while fix-review-precommit cycle is still active. Brief operational status lines ("Fixed 3 issues, running review...") are allowed; terminal summaries are not until all gates pass.

Token budget advisory: <budget:token_budget> tags in skill definitions are planning signals only. They never justify stopping, skipping review, or deferring auto-loop obligations. See @rules/context-management.md for full context policy.

Auto-Trigger

Change Type Event Execute Immediately
code files Fix P0/P1/P2 /codex-review-fast
code files review Ready + P2/Nit P2/Nit Quality Sweep
code files review Ready (no P2/Nit) /precommit
code files precommit Pass Adequacy Gate (if request doc) → Doc Sync
code files precommit failure Fix -> re-run
.md Fix doc issues /codex-review-doc
.md review failure Fix -> re-run

Dual Review Mode

Code review commands dispatch two reviewers in parallel. This section defines the interaction with auto-loop.

Rule Description
First-pass dual Code review command must dual-dispatch on first pass (Codex + secondary background)
Non-blocking secondary Secondary reviewer runs in background and does not block initial gate emission
Late P0/P1 Within same review session, late secondary P0/P1 re-opens fix→re-review loop
Loop re-review --continue loops re-dispatch both reviewers (Codex --continue + secondary fresh). Secondary is always dispatched in v1 (no skip exception).
Pre-precommit checkpoint Before /precommit, reconcile any pending secondary result; if late P0/P1, re-enter review loop
Cycle reset Any code edit resets the review cycle — both reviewers must re-run regardless of prior pass status

P2/Nit Quality Sweep

Gate ✅ Ready + P2/Nit exists → batch fix → verify → precommit

When Codex review returns ✅ Ready but findings include P2 or Nit items:

Step Action Detail
1 Batch-fix Fix all P2/Nit in one pass (1 attempt)
2 Verify 1 batched Codex --continue re-review
3 Evaluate Check resolution status
4 Continue Proceed to /precommit or stop

Resolution Evaluation

Priority Condition Action
1 Unresolved P2 ⚠️ Need Human — stop, report reason
2 Unresolved Nit only Continue — Nit exemption with log
3 All resolved /precommit

Nit Exemption Log

When unresolved Nit items are exempted, output structured log:

[NIT_DEFERRED] file:line | issue | reason: possible-false-positive | timestamp

No P2/Nit Path

Gate ✅ Ready + no P2/Nit → directly /precommit (unchanged behavior).

Exit Conditions (Only)

  • ✅ All Pass
    • Code changes: review + precommit all passed
    • Doc changes: doc review passed
  • ⛔ Need Human — Architecture changes, feature removal, user requests stop
  • ⚠️ Need Human — Feature docs not found (3-level fallback exhausted)
  • ⚠️ Need Human — P0/P1 dismiss candidate awaiting human confirmation (via /seek-verdict)
  • 🔄 max_rounds exceeded (default 10, configurable in auto-loop-project.md) — Report blocker, request intervention. State tracked in .claude_review_state.json iteration_history.current_round
  • 🔄 Convergence plateau — findings_by_round[n].total >= findings_by_round[n-1].total AND fingerprint overlap >= 50% for 3+ consecutive rounds → ⚠️ Need Human (same issues recurring despite fixes). State tracked in iteration_history.findings_by_round[].fingerprints

Strategic Reset (opt-in, near-cap)

When total_rounds_session >= max_rounds - 3 and strategic_reset_fired = false, the post-compact hook injects a [STRATEGIC_RESET] checklist. This fires once per state-file lifetime (reset when the state file is recreated).

Enable via auto-loop-project.md: ## Think Harder: enabled

The checklist prompts re-reading original requirements, challenging assumptions, and trying fundamentally different approaches before escalating at max_rounds.

total_rounds_session is incremented on every review iteration (in _update_iteration()) and is never reset on code edits (unlike current_round). This ensures the strategic reset fires based on cumulative effort, not per-cycle effort.

Correct Behavior

"Fixed 3 issues, running /codex-review-fast..."
[Execute: Codex --continue + Secondary fresh — parallel dispatch]
"Codex: ✅ Ready. Secondary: ✅ Ready. Running /precommit..."
[Execute]
"All passed ✅"

⚠️ Behavior Anchor: Execute Within the Same Reply

Correct Pattern

[Edit complete] -> Invoke review tool in the same reply -> Wait for result -> Report

Claude: [Edit tool complete]
        ↓
        "Updated, running review..."
        ↓
        [Skill tool: /codex-review-doc]  <- Same reply
        ↓
        "Review passed ✅" or "Issues found, fixing..."

Incorrect Pattern

[Edit complete] -> Output summary -> [Stop] -> User follows up -> Then execute review

Claude: [Edit tool complete]
        ↓
        "Updated requirements doc ✅"
        ↓
        [Output polished table summary]
        ↓
        "Next step: suggest running /codex-review-doc"  <- ❌ Declaring as executing
        ↓
        [Stop, waiting for user]  <- ❌ Violates rule

Key Principles

Principle Description
Declaring ≠ Executing Saying "need to run" does not equal having run it
Summary ≠ Completion After outputting a summary, the review process is still ongoing
Execute in same reply After Edit completes, must invoke review tool in the same reply
Stop only on result Can only stop after seeing review result (Pass/Fail)

Enforcement Mechanism

Three-Layer Defense

[Edit/Write] -> [PostToolUse Hook] -> [State file update]
                                          ↓
[Context Compact] -> [SessionStart compact] -> [Re-inject auto-loop from state]
                                          ↓
[Stop Hook] <- Read state file <- [Review command executed]
Layer Mechanism Trigger
PostToolUse Track file changes + review result Edit/Bash execution
SessionStart (compact) Re-inject auto-loop rules after compaction (stdout → context) Context compaction
Stop Hook Warn before stopping if review pending (strict mode: block) When attempting stop

State File Schema

File: .claude_review_state.json (locally ignored)

{
  "session_id": "abc123",
  "updated_at": "2026-01-26T10:00:00Z",
  "has_code_change": true,
  "has_doc_change": false,
  "code_review": {
    "executed": true,
    "passed": true,
    "last_run": "2026-01-26T10:00:00Z"
  },
  "doc_review": { "executed": false, "passed": false },
  "precommit": {
    "executed": true,
    "passed": true,
    "last_run": "2026-01-26T10:01:00Z"
  }
}

Note: The above shows the full field schema; the actual hook may only update a subset of fields.

Debug and Escape Hatch

Environment Variable Purpose Use Case
HOOK_DEBUG=1 Output debug information Troubleshooting
HOOK_BYPASS=1 Skip Stop Hook checks Emergency

Standard Gate Sentinels

Review commands must output standard markers. Hook-parsed sentinels are consumed by stop-guard.sh; behavior-layer sentinels are consumed by Claude's auto-loop logic only.

Sentinel Context Meaning Parsed by
✅ Ready Code review No P0/P1 Hook + behavior
⛔ Blocked Code review Has P0/P1 Hook + behavior
✅ Mergeable Doc review No 🔴 items Hook + behavior
⛔ Needs revision Doc review Has 🔴 items Hook + behavior
✅ All Pass Precommit All checks passed Hook
⛔ FAIL / ❌ FAIL Precommit Check failed Hook
⚠️ Need Human Any Needs human intervention Behavior-layer only

Adequacy Gate (behavior-layer, request-doc-aware)

After precommit Pass, if a request doc with ## Acceptance Criteria is detected:

Step Action
1 Auto-detect request doc (3-level fallback, same as doc sync)
2 /codex-test-review --ac-trace <request-path>
3 Evaluate gate (mode from testing-project.md ## Adequacy Mode)

Mode behavior:

Mode ✅ Adequate ⚠️ Adequate with exceptions ⚠️ Need Human ⛔ Inadequate
advisory (default) Continue Continue + log Warn + continue Warn + continue
strict Continue Continue + log Stop (blocking) Re-enter fix loop
off Skip Skip Skip Skip

Detection: No request doc with AC section → skip (no gate). Same 3-level fallback as Doc Sync: context → git diff → ⚠️ Need Human.

v1 scope: Behavior-layer only (no hook enforcement). Advisory mode default. Strict opt-in via testing-project.md.

Doc Sync Note

Doc Sync is a behavior-layer rule (not hook-enforced). After precommit Pass, only when the change maps to a feature under docs/features/, auto-trigger:

  1. /update-docs <tech-spec-path> — Incremental update of changed sections
  2. /create-request --update <request-path> — Update Progress / Status / AC (e.g. docs/features/<feature>/requests/<date>-<title>.md)

Target detection: 3-level fallback (context → git diff → ⚠️ Need Human). See /update-docs for algorithm details.

Safety valve: After doc sync, compare code diff against pre-sync baseline; if new code changes exist, return to review loop. See /update-docs Safety Valve section.

Project Customization

Project-specific overrides belong in auto-loop-project.md (not this file). See @rules/auto-loop-project.md for your project's custom auto-loop behavior.