fix: address CodeRabbit review findings on goal continuation and todos

- Goal auto-continuation now requires the primary turn to end cleanly
  (no_tool_calls): a tool rejection or stuck primary turn no longer
  triggers continuations, matching the rule already applied between
  continuation turns. Ralph-loop runs never continue (own strategy).
- Soften the SetTodoList single-in_progress invariant from a hard
  rejection to a corrective notice: pythinker's parallel-subagent
  fan-out legitimately tracks one in_progress sub-todo per running
  child (system.md orchestration rules), so rejecting such lists would
  break the documented workflow. The tool description, system.md
  status-discipline bullet, and changelog wording are reconciled to
  state the sequential rule and its fan-out exception.
- Document compact_prompt as nullable in the config reference, fix a
  malformed report fence token in tasks/todo.md, and add boundary
  tests for goal.max_continuations (1-10).

Declined (with rationale): mechanical enforcement of the blocked-audit
three-strike gate inside UpdateGoal — Codex itself enforces it as a
prompt contract, and 'same blocking condition' is semantic, so code
enforcement would misfire on legitimate impasses. H1 headings for the
prompt markdown assets — injected prompt files conventionally start
with body text in this repo (init.md, compact.md) and there is no
markdownlint gate.

Author: elkaix

CHANGELOG.md

@@ -17,7 +17,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 - **New `/goal` command: goal-driven execution ported from Codex CLI.** `/goal <objective>` sets a persistent thread goal the agent pursues across turns until it is verifiably complete. The objective is stored in session state (survives restarts and context compaction), kicks off work immediately with a success-criteria derivation prompt, and is re-injected on later turns as a continuation reminder carrying Codex's fidelity rules (no scope-shrinking, no easier-to-test substitutes) and evidence-based completion audit — the agent may only claim completion after proving every requirement against current state, and the user confirms with `/goal clear`. Subcommands: `view`, `pause`, `resume`, `clear`. Objectives are injected as untrusted data (`<objective>` framing), never as higher-priority instructions.
 - **New `/best-practices` command (alias `/bp`).** Injects opt-in engineering best-practice guidance distilled from the Codex CLI system prompts — code-change discipline, dirty-worktree safety (never revert changes you didn't make), specific-to-broad testing strategy, todo hygiene, progress-update cadence, debugging methodology, and final-answer style — into the session context without consuming a turn. `/best-practices <section>` injects a single section.
-- **SetTodoList enforces the single-`in_progress` invariant.** Todo lists with more than one `in_progress` item are now rejected with a corrective error (ported from Codex's plan-tool contract), and the system prompt gains matching status-discipline guidance: no single-step lists, no `pending`→`done` jumps, no batch-completing after the fact.
+- **SetTodoList nudges the single-`in_progress` discipline.** Todo lists with more than one `in_progress` item now get a corrective notice (ported from Codex's plan-tool contract, softened because parallel-subagent fan-out legitimately tracks one `in_progress` sub-todo per running child), and the system prompt gains matching status-discipline guidance: no single-step lists, no `pending`→`done` jumps, no batch-completing after the fact.
 - **`UpdateGoal` tool + opt-in goal auto-continuation: the full "loop until verified".** The agent can now mark the active `/goal` `complete` (only after the evidence-based completion audit) or `blocked` (only after Codex's strict three-strike blocked audit) via the new root-only `UpdateGoal` tool, which stops goal reminders and continuations; `/goal resume` reactivates either state. With `goal.auto_continue = true` (new config table, default off, `max_continuations` 1–10 capped at 3 by default), each user message is followed by automatic continuation turns toward the active goal — carrying the Codex continuation prompt — until the goal is marked, a tool call is rejected, or the cap is reached, with a budget-style wrap-up instruction on the final continuation.
 - **Approval-mode-aware validation guidance.** Auto/yolo-mode injections now tell the agent to proactively run tests and lint before finishing (no user present to confirm), while the back-to-interactive reminder defers slow test/lint commands to user confirmation except for test-related tasks — ported from the Codex CLI validation philosophy.
 - **`compact_prompt` config override.** A new optional top-level config key replaces the built-in compaction summarization prompt for both manual and automatic compaction; a `/compact` focus argument is still appended on top, and leaving it unset preserves current behavior.

docs/en/configuration/config-files.md

@@ -38,7 +38,7 @@ The configuration file contains the following top-level configuration items:
 | `models` | `table` | Model configuration |
 | `loop_control` | `table` | Agent loop control parameters |
 | `goal` | `table` | Thread-goal (`/goal`) behavior, including auto-continuation |
-| `compact_prompt` | `string` | Override the built-in compaction summarization prompt; unset keeps the default handoff-structured prompt (a `/compact` focus argument is still appended on top) |
+| `compact_prompt` | `string \| null` | Override the built-in compaction summarization prompt; `null`/unset keeps the default handoff-structured prompt (a `/compact` focus argument is still appended on top) |
 | `background` | `table` | Background task runtime parameters |
 | `services` | `table` | External service configuration (search, fetch) |
 | `mcp` | `table` | MCP client configuration |

src/pythinker_code/agents/default/system.md

@@ -168,7 +168,7 @@ For any non-trivial request, decompose before acting:
 - Preview the terrain first: scan the directory structure, file headers, and relevant module boundaries before choosing an implementation path.
 - **`SetTodoList` marks the start of execution, not planning.** Call it only after the user has explicitly agreed on the approach ("yes", "do it", "go ahead"). Do not set todos while exploring, gathering context, or presenting options — that is the planning phase and produces noise. Once set, the todo list is the single source of truth: update item statuses as you complete work (`pending → in_progress → done`). Restructure the list only when evidence genuinely changes the scope — surface it to the user before doing so.
 - **Granular todos, not umbrella todos.** Each todo must name a single concrete deliverable a human can recognize as "this part is done." Avoid umbrella titles like "Determine X" or "Investigate Y" that cover hours of parallel work — they freeze the progress UI while real work happens underneath. If a single todo would stay `in_progress` for more than ~3 minutes, it is too coarse: split it before launching work.
-- **Status discipline.** Do not make single-step todo lists or pad simple work with filler steps. Never jump an item from `pending` to `done` — set it `in_progress` first, keeping at most one item `in_progress` at a time — and never batch-complete multiple items after the fact. End the turn with every item `done` or explicitly `cancelled`.
+- **Status discipline.** Do not make single-step todo lists or pad simple work with filler steps. Never jump an item from `pending` to `done` — set it `in_progress` first, keeping at most one item `in_progress` at a time for your own sequential work (parallel-subagent fan-out is the exception: one `in_progress` sub-todo per running child, per the rule below) — and never batch-complete multiple items after the fact. End the turn with every item `done` or explicitly `cancelled`.
 - **Progress cadence.** Post a short Progress note (1-2 sentences) when you uncover a meaningful insight or change direction — notes replace, not duplicate, narration in your final text. Before the first tool call of substantial work, state the goal, constraints, and next steps. Announce longer heads-down stretches and summarize what you learned when you resume; call out plan changes explicitly in the next update.
 - **One todo per dispatched child.** When you launch `RunAgents` with N children, the visible todo list MUST contain one in_progress sub-todo per child (or per independent objective the batch covers) **before** the batch starts. Update each sub-todo to `done` as that child returns — do not wait for the whole batch to finish to flip a single umbrella todo. Same rule applies to multiple parallel `Agent` calls in the same turn.
 - Split broad work into independent chunks; use parallel tool calls or focused subagents for chunks that do not depend on each other. Scale the number of agents to the task's independent subparts — a single lookup needs none, a small comparison 2-4 — and prefer the fewest that cover the work; over-provisioning burns the multi-agent token premium.

src/pythinker_code/soul/pythinkersoul.py

@@ -1002,6 +1002,7 @@ async def run(
             user_message = Message(role="user", content=user_input)
             text_input = user_message.extract_text(" ").strip()
 
+            primary_outcome: TurnOutcome | None = None
             if command_call := parse_slash_command_call(text_input):
                 command = self._find_slash_command(command_call.name)
                 if command is None:
@@ -1018,7 +1019,7 @@ async def run(
                 )
                 await runner.run(self, "")
             else:
-                await self._turn(user_message)
+                primary_outcome = await self._turn(user_message)
 
             # --- Stop hook (max 1 re-trigger to prevent infinite loop) ---
             if not self._stop_hook_active:
@@ -1039,8 +1040,8 @@ async def run(
                             self._stop_hook_active = False
                         break
 
-            if command_call is None:
-                await self._run_goal_continuations()
+            if primary_outcome is not None:
+                await self._run_goal_continuations(primary_outcome)
 
             wire_send(TurnEnd())
             turn_finished = True
@@ -1100,15 +1101,17 @@ async def run(
                 reset_current_approval_source(approval_source_token)
             self._prompt_queue_lock.release()
 
-    async def _run_goal_continuations(self) -> None:
+    async def _run_goal_continuations(self, primary_outcome: TurnOutcome) -> None:
         """Auto-continue toward the active /goal after the primary turn.
 
         Ported from Codex CLI's automatic goal continuations, bounded per user
         submission by ``goal.max_continuations``. Hard stops (cancellation,
         MaxStepsReached, provider errors) propagate out of ``_turn`` and end
-        the loop together with the run; a rejected tool call or a goal marked
-        complete/blocked (via UpdateGoal) ends it gracefully.
+        the loop together with the run; a rejected tool call, a stuck turn, or
+        a goal marked complete/blocked (via UpdateGoal) ends it gracefully.
         """
+        if primary_outcome.stop_reason != "no_tool_calls":
+            return
         goal_config = self._runtime.config.goal
         if not goal_config.auto_continue or self.is_subagent or self.plan_mode:
             return

src/pythinker_code/tools/todo/__init__.py

@@ -67,18 +67,21 @@ def __init__(self, runtime: Runtime) -> None:
     async def __call__(self, params: Params) -> ToolReturnValue:
         if params.todos is None:
             return self._read_todos()
+        result = self._write_todos(params.todos)
         in_progress = sum(1 for todo in params.todos if todo.status == "in_progress")
         if in_progress > 1:
-            return ToolReturnValue(
-                is_error=True,
-                output=(
-                    "Invalid todo list: at most one item can be in_progress at a time. "
-                    "Resubmit with exactly one in_progress item."
-                ),
-                message="Invalid todo list",
-                display=[],
+            # Codex plan-tool contract, softened: parallel-subagent fan-out
+            # legitimately tracks one in_progress sub-todo per running child.
+            base_output = result.output if isinstance(result.output, str) else ""
+            result = ToolReturnValue(
+                is_error=False,
+                output=base_output
+                + "\nNote: keep at most one item in_progress at a time for your own "
+                "sequential work; multiple in_progress items are expected only while "
+                "tracking parallel subagents (one sub-todo per running child).",
+                message=result.message,
+                display=result.display,
             )
-        result = self._write_todos(params.todos)
         if self._runtime.role == "root" and len(params.todos) >= 3:
             await self._journal_todo_update(params.todos)
         return result

src/pythinker_code/tools/todo/set_todo_list.md

@@ -13,7 +13,7 @@ Once the todo list is set, it is the single source of truth for in-progress work
 
 Once you finish a subtask/milestone, update its status before moving to the next item.
 
-At most one item can be in_progress at a time — lists with more than one are rejected. Do not jump an item from `pending` to `done`: set it `in_progress` first, and do not batch-complete multiple items after the fact.
+Keep at most one item in_progress at a time for your own sequential work — the only exception is parallel-subagent fan-out, where one in_progress sub-todo per running child is expected. Do not jump an item from `pending` to `done`: set it `in_progress` first, and do not batch-complete multiple items after the fact.
 
 **Do NOT use this tool:**
 

tasks/todo.md

@@ -68,7 +68,7 @@ Scouted via 6-explorer workflow + synthesis; primary sources re-read before port
 
 ## Out of scope (observed, logged)
 
-- Codex P0-P3 JSON review schema (pythinker has its own ```report contract).
+- Codex P0-P3 JSON review schema (pythinker has its own `report` fenced-block contract).
 - Per-goal token budgets ({{ token_budget }} vars) — no per-goal usage meter yet.
 - User prompt-template shadowing (a user `goal.md` template vs builtin) — builtin
   soul commands and prompt templates share the slash namespace; collision behavior

tests/core/test_config.py

@@ -645,3 +645,19 @@ def test_load_config_no_args_uses_scope_resolution(tmp_path, monkeypatch):
     config = load_config()
     assert config.theme == "light"
     assert "user" in config.source_scopes
+
+
+def test_goal_config_bounds():
+    """goal.max_continuations is clamped to 1-10 by validation."""
+    import pytest
+    from pydantic import ValidationError
+
+    from pythinker_code.config import GoalConfig
+
+    assert GoalConfig().max_continuations == 3
+    assert GoalConfig(max_continuations=1).max_continuations == 1
+    assert GoalConfig(max_continuations=10).max_continuations == 10
+    with pytest.raises(ValidationError):
+        GoalConfig(max_continuations=0)
+    with pytest.raises(ValidationError):
+        GoalConfig(max_continuations=11)

tests/core/test_goal_auto_continuation.py

@@ -157,3 +157,36 @@ async def test_no_continuation_in_plan_mode(self, runtime: Runtime, tmp_path: Pa
         turn_mock = soul._turn
         assert isinstance(turn_mock, AsyncMock)
         assert turn_mock.await_count == 1
+
+    async def test_no_continuation_when_primary_turn_rejected(
+        self, runtime: Runtime, tmp_path: Path
+    ) -> None:
+        """A tool rejection in the primary turn must not trigger continuations."""
+        runtime.config.goal.auto_continue = True
+        runtime.session.state.goal = GoalState(objective="ship it", status="active")
+        soul = _make_soul(runtime, tmp_path)
+
+        turn_mock = soul._turn
+        assert isinstance(turn_mock, AsyncMock)
+        turn_mock.return_value = TurnOutcome(
+            stop_reason="tool_rejected", final_message=None, step_count=1
+        )
+
+        await soul.run("do the thing")
+
+        assert turn_mock.await_count == 1
+
+    async def test_no_continuation_when_primary_turn_stuck(
+        self, runtime: Runtime, tmp_path: Path
+    ) -> None:
+        runtime.config.goal.auto_continue = True
+        runtime.session.state.goal = GoalState(objective="ship it", status="active")
+        soul = _make_soul(runtime, tmp_path)
+
+        turn_mock = soul._turn
+        assert isinstance(turn_mock, AsyncMock)
+        turn_mock.return_value = TurnOutcome(stop_reason="stuck", final_message=None, step_count=1)
+
+        await soul.run("do the thing")
+
+        assert turn_mock.await_count == 1

tests/tools/test_todo.py

@@ -344,10 +344,12 @@ async def test_subagent_malformed_individual_item(self, runtime: Runtime):
 
 
 class TestSingleInProgressInvariant:
-    """Ported from Codex CLI's plan tool contract (plan_spec.rs):
-    at most one step can be in_progress at a time."""
+    """Ported from Codex CLI's plan tool contract (plan_spec.rs): at most one
+    step in_progress at a time — softened to a notice because pythinker's
+    parallel-subagent fan-out legitimately tracks one in_progress sub-todo
+    per running child (system.md orchestration rules)."""
 
-    async def test_two_in_progress_items_rejected(
+    async def test_multiple_in_progress_accepted_with_notice(
         self, set_todo_list_tool: SetTodoList, runtime: Runtime
     ):
         result = await set_todo_list_tool(
@@ -358,10 +360,10 @@ async def test_two_in_progress_items_rejected(
                 ]
             )
         )
-        assert result.is_error
+        assert not result.is_error
         assert "at most one" in result.output
-        # The invalid list must not be persisted.
-        assert runtime.session.state.todos == []
+        # The list is persisted despite the notice (parallel fan-out is legal).
+        assert len(runtime.session.state.todos) == 2
 
     async def test_exactly_one_in_progress_accepted(self, set_todo_list_tool: SetTodoList):
         result = await set_todo_list_tool(