refactor(state): derive Next Action from Todo-bound recommendation receipts

demo/auto_research/demo_e2e.py

@@ -118,13 +118,12 @@ def _seed_visible_demo_control_plane(
 
     from loopx.bootstrap import bootstrap_project
     from loopx.configure_goal import configure_goal
-    from loopx.state_refresh import now_local, replace_next_action_section
     from loopx.todos import add_goal_todo
 
     control_project = demo_root / "visible-control-plane"
     control_registry = demo_root / "visible-control-plane.registry.json"
     control_runtime = demo_root / "visible-control-plane.runtime"
-    bootstrap = bootstrap_project(
+    bootstrap_project(
         project=control_project,
         registry_path=control_registry,
         runtime_root=control_runtime,
@@ -146,18 +145,6 @@ def _seed_visible_demo_control_plane(
         dry_run=False,
         sync_global=False,
     )
-    state_file = Path(str(bootstrap["state_file"]))
-    if state_file.exists():
-        updated_state, state_changed = replace_next_action_section(
-            state_file.read_text(encoding="utf-8"),
-            next_action=(
-                "Goal-level route delegates to role frontier; panes own execution."
-            ),
-            updated_at=now_local(),
-        )
-        if state_changed:
-            state_file.write_text(updated_state, encoding="utf-8")
-
     lanes = [lane for lane in supervisor.get("lanes") or [] if isinstance(lane, dict)]
     agents = sorted(
         {

docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md

@@ -567,6 +567,21 @@ provider-neutral aggregate requires a separate reviewed transaction boundary.
 `Next Action` remains compatibility prose and a read projection. It is never a
 claim, lease, Goal amendment, replan settlement, or authority decision.
 
+Integrated recommendation checkpoint: `refresh-state --next-action` evolves
+the existing recommendation receipt into an actor-bound, within-Todo step;
+it no longer overwrites the compatibility prose. Single and multiple peers
+use the same rule. The existing lane selector chooses work, then the TS
+recommendation owner decorates it with a still-valid step. Task text and
+claim/lease prerequisites remain intact. Peer summaries use those same derived
+routes, with no independent plan store. Source/task/actor-step read fences reject
+stale writes and discard stale read decorations. See the
+[writeback contract](../../quota-allocation.md).
+
+This advances advisory continuity, not Stage 3 amendment commit. The source-facts
+digest is not a canonical intent revision; run history is not the shared
+Todo/claim/lease transaction store. Ordinary task changes, protected intent,
+acceptance, Vision and replan settlement retain their existing owners.
+
 ### 9.1 Semantic handoff and execution-route integration
 
 Use the existing alignment projection to supply a receiver's actual work

docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md

@@ -489,6 +489,18 @@ projection 与 proposal contract 交付；把 commit 映射进 provider-neutral
 `Next Action` 继续是 compatibility prose 与 read projection。它永远不是 claim、
 lease、Goal amendment、replan settlement 或 authority decision。
 
+融合 recommendation checkpoint：`refresh-state --next-action` 演进现有
+recommendation receipt，记录绑定当前 agent/Todo 的任务内步骤，不再覆盖兼容文本。
+单 peer 和多 peer 使用同一规则：先由现有 lane selector 选任务，再由 TS
+recommendation owner 附加仍有效的步骤，保留任务原文及 claim/lease 前置条件。
+各 peer 的汇总复用这些派生路线，不增加独立计划库。来源、任务和当前 agent 步骤
+的读取依据检查拒绝过期写入，并在读时丢弃过期步骤。详见
+[写回合同](../../quota-allocation.md)。
+
+这推进 advisory continuity，不代表 Stage 3 amendment commit 已交付。来源事实
+摘要不是 canonical intent revision；run history 不是共享 Todo/claim/lease 事务库。
+普通任务修改、受保护意图、验收、Vision 和 replan settlement 继续由原 owner 负责。
+
 ### 9.1 语义交接与执行路线衔接
 
 用既有 alignment 投影给接收方提供真实工作基线。意图内的路线重规划仍走接收方

docs/project-agent-todo-contract.md

@@ -411,9 +411,20 @@ collisions without writing broad prompt scope into todo metadata or pretending
 that a soft claim is already a hard lease. When a runnable current-agent or unclaimed
 advancement todo exists, quota may also expose
 `agent_lane_next_action.schema_version=agent_lane_next_action_v0`. That field is
-the peer's current slice for this turn; it does not overwrite the durable
-goal-level `Next Action`. `loopx status --agent-id <agent-id>` may attach the same derived field to matching status
-queue items for observation, while leaving the project-level route unchanged.
+the peer's selected task for this turn. Its `text`, identity, claim/lease and
+capability facts remain task facts. Optional `next_step` and `next_action_basis`
+come from the existing recommendation receipt, validated against the current
+selected Todo before display; they do not select a task or change authority.
+`refresh-state --agent-id PEER --next-action TEXT [--next-action-basis BASIS]`
+records this within-task step in run history without overwriting the compatibility
+`## Next Action` section. Single- and multi-peer Goals share this rule.
+`status --agent-id PEER` exposes the same derived lane and basis;
+`status --include-task-graph` summarizes all peers' routes. Source and stale-read
+boundaries are defined in the [quota contract](quota-allocation.md).
+Canonical Todos remain the task source even if their Markdown display is missing
+or stale. Promoted provider failure is an error, never permission to select a
+legacy Markdown task. Task edits, dependencies and ownership changes continue
+through their existing Todo writers; stage direction changes use Vision/replan.
 When a candidate has `target_capabilities` and missing target bridge
 capabilities, quota may mark it `capability_repair_mode=true`; scoped
 next-action selection should prefer that repair-mode candidate over ordinary
@@ -553,6 +564,16 @@ The default scoped refresh is an agent-lane run: it is useful for keeping the
 same turn's writeback/accounting identity intact, but it does not replace the
 goal-level status route.
 
+`--next-action` records a step bound to the registered Agent's selected eligible
+Todo, in either personal or Goal report scope; it does not replace shared prose.
+`--next-action-basis` optionally rejects an edit planned from an older source
+read. If the basis is stale, read the current task/step and retry; if no eligible
+task is available, resolve its existing lifecycle or routing boundary first.
+Native Turn host `next_action` remains follow-up guidance in its durable result,
+not this explicit task-step edit: completion or repair may leave no runnable
+current task. See [Next Action writeback](quota-allocation.md) for attribution,
+snapshot conflicts and the unchanged claim, lease and intent boundaries.
+
 ## Lifecycle Contract
 
 Agents should not patch active-state checkboxes directly to move work forward.

docs/quota-allocation.md

@@ -1105,31 +1105,81 @@ so agent executors know to write newly discovered user/owner work with
 hiding it in `Next Action`, review docs, or chat. Multi-agent writes must also
 name `--bound-agent <registered-agent>` or `--goal-bound`; agent-scoped
 `user_gate` writes bind to the same agent named by `--blocks-agent`.
-When available, `quota should-run` also keeps next-action signals separate:
-`active_state_next_action` is the durable `## Next Action`,
-`latest_run_recommended_action` is the latest non-agent-lane run's
-recommendation, and `agent_lane_next_action` is the current `--agent-id`
-slice. Agent-scoped payloads may also include
-`goal_route_hint.schema_version=goal_route_hint_v0`, a compact read-only
-synthesis that says whether the current lane should run, claim, wait, or
-reassign while preserving `## Next Action` as durable goal-level guidance. It
-is an advisory routing hint, not a writeback instruction and not a replacement
-for `agent_todo_summary`.
-When projected, `goal_frontier_projection.schema_version =
-goal_frontier_projection_v0` is the per-goal progress/frontier view used before
-lane-local quiet or wait decisions. Its `autonomous_replan_decision` says that a
-required replan must be selected independently of `monitor_quiet_skip` or
-`agent_scope_wait`; the policy lives in `loopx.control_plane.goals.goal_frontier`, while
-quota only wires the selected mode into `interaction_contract`.
-If the active-state and latest-run actions differ,
-`next_action_projection_warning` asks the executor to explicitly write back the
-intended durable route with a primary goal-scope `refresh-state --next-action`
-or keep treating the signals as distinct.
-`refresh-state` records `recommended_action_source` so hosts can tell whether a
-run recommendation came from an explicit argument, durable `## Next Action`, an
-Agent Todo compatibility fallback, or the generic default. Dispatch still comes
-from `agent_lane_next_action` / todo projection, not from shared `## Next Action`
-alone.
+When available, `quota should-run` keeps next-action signals separate:
+`active_state_next_action` is the compatibility `## Next Action` display,
+`latest_run_recommended_action` is a historical run recommendation, and
+`agent_lane_next_action` is the currently selected Todo for `--agent-id`.
+The lane retains the task's `text`, identity and execution prerequisites; an
+optional `next_step` refines what to try within that task. Task selection happens
+first. Prose mentioning a Todo id cannot select it; the existing typed Next
+Action breadcrumb remains a compatibility read input.
+
+A registered peer can record its own task step without promoting its report:
+
+```bash
+loopx --format json status --goal-id GOAL --agent-id PEER
+loopx refresh-state --goal-id GOAL --agent-id PEER \
+  --next-action "Evaluate the alternate approach; retain the incumbent." \
+  --next-action-basis BASIS
+```
+
+`BASIS` is the matching queue item's `next_action_basis`, also exposed in quota's
+`agent_lane_next_action.next_action_basis`. The existing
+`recommended_action_resolution` receipt records `recommended_action_source=
+agent_lane_step`, the actor, selected Todo and read basis in run history.
+Semantic history retains the latest bound receipt per actor beyond the recent
+run window. Reads attach its step only while the actor, selected task and source
+facts still match. A changed, completed, reassigned or blocked task cannot
+inherit a stale step. Selecting another task uses the normal Todo owner; this
+flag neither overwrites Markdown nor creates another task or route store.
+
+Single- and multi-agent Goals use the same rule. `progress_scope` still controls
+report presentation, not task authority. `status --include-task-graph` includes
+`agent_next_actions` derived from each registered peer's Todo selector and valid
+step receipt; one peer's step does not replace another's. Shared registry reads
+resolve to the project source registry. Missing sources cannot mint a write
+basis; promoted canonical provider failures do not fall back to Markdown tasks.
+
+The basis binds the complete registered roster, source Goal identity/lifecycle/
+routing and narrative facts, the selected task's semantic facts, and the actor's
+latest bound step. It is a source-facts fence, **not a canonical Goal intent
+revision**. Ordinary peer Todo edits and peer step receipts do not change this
+actor's basis. Same-actor concurrent writers using one basis cannot both commit;
+`next_action_basis_conflict` returns the current basis and selected task for
+reread and rejudgment. The writer rechecks the source under existing locks before
+appending the receipt. This does not CAS or lock the canonical Todo transaction;
+a concurrent provider commit may leave an obsolete historical step, which the
+next read discards. Without the optional flag, it captures a fresh invocation
+basis; it cannot detect a model's older planning read outside that invocation.
+
+**Default behavior change:** `refresh-state --next-action` now requires a
+registered `--agent-id` and an eligible selected advancement Todo, for both
+personal and Goal-scoped reports. Supplying `--recommended-action` alongside it
+requires the same text. It no longer performs a shared prose replacement.
+Existing Todo, claim/lease, settlement and Vision checks retain their owners;
+a within-task step alone is not a durable mainline change, replan ACK or Goal
+amendment. Native Turn host results keep `recommended_action` and `next_action`
+as distinct durable follow-up guidance; they do not implicitly invoke this
+task-step editor or replace shared prose, including after completion or repair.
+Refreshes without `--next-action` keep their existing recommendation
+and report behavior. Historical prose-update receipts remain readable.
+
+CLI status omits the reducer's internal source context and duplicate basis;
+the selected route and explicit peer detail retain the editable read fence.
+The unchanged base/head fixture adds 100 pretty / 94 compact JSON characters
+to ordinary quota for that fence. Explicit task-graph detail adds 457 pretty /
+346 compact characters for two peer routes after compaction. The differential
+guard recognizes this bounded first 0-to-N fence transition only on the affected
+JSON views; absolute ceilings and later N-to-N growth budgets remain unchanged.
+This is a measured readback cost, not a claim of token or end-to-end time savings.
+
+Agent-scoped payloads may also include `goal_route_hint_v0`, a read-only
+synthesis of run, claim, wait or reassign advice. It is not a writer or a
+replacement for `agent_todo_summary`. `goal_frontier_projection_v0` evaluates a
+required replan independently of monitor quiet or agent-scope wait; its owner
+remains `loopx.control_plane.goals.goal_frontier`. Next-step decoration does not
+change eligibility, replan priority or the requirement to claim/lease work.
+
 When `agent_lane_next_action.selected_by=unclaimed_todo`, the payload marks
 `claim_required_before_work=true`; executors must claim the todo before editing
 or launching delivery work.

docs/reference/protocols/goal-vision-replan-contract-v0.md

@@ -287,9 +287,12 @@ memory or owner reminders.
 ## Vision Checkpoint
 
 `refresh-state` always emits a per-agent `vision_checkpoint_v0`, and defaults
-to the `semantic_closeout` delivery boundary. A material delivery outcome or a
-durable `## Next Action` update at that boundary requires an explicit vision
-decision:
+to the `semantic_closeout` delivery boundary. A material delivery outcome at
+that boundary requires an explicit vision decision. A within-Todo recommendation
+step (`refresh-state --next-action`) is not a durable mainline change and does
+not, by itself, trigger a Vision checkpoint or settle a replan. Direction changes
+still use the existing Vision/`path_delta` owner. Historical durable prose-update
+receipts retain their checkpoint semantics:
 
 ```json
 {
@@ -322,8 +325,8 @@ loopx refresh-state \
 ```
 
 This boundary is valid only for the selected agent-bound or unclaimed open
-advancement Todo while it is still in flight. It rejects Todo completion, a
-durable Next Action update, autonomous replan writeback, and any outcome other
+advancement Todo while it is still in flight. It permits a bound within-Todo
+step, but rejects Todo completion, autonomous replan writeback, and any outcome other
 than `outcome_progress`. Its checkpoint has `decision=not_required`,
 `required=false`, and a typed
 `in_flight_continuation` trigger carrying the Todo id. The next quota decision

examples/control_plane/cli-output-probe-runner.py

@@ -126,6 +126,7 @@ def _receipt_row(
             if isinstance(payload, dict)
             else []
         ),
+        "next_action_basis_count": semantics.next_action_basis_count(payload),
     }