SouveraineOS/docs/substrate/tasks/itinerary-system.md

title	phase	priority	status	area
Itinerary System	3.0	🟡 Medium	landed	Tools / TUI

Itinerary System

Description

An itinerary is an ordered sequence of stops — the agent's route through the current work. Each stop optionally links to a todo commitment by ID; linked stops inherit the todo's nature/energy for display in the header strip. The itinerary is not a task list — it's the active face of whatever the agent is doing right now.

Persisted to system/dynamic/itinerary.md in the agent's memfs (same volatile zone as energy balance, context pressure). Agent-controlled via itinerary tool (set / advance / describe / clear). "Cancel" and "stop" signals from the user during a long tool loop trigger a mid-turn subconscious checkpoint that can HALT the loop.

What Landed

• src/core/tools/itinerary.rs — ItineraryTool, Itinerary, Stop, StopStatus data types, YAML frontmatter persistence, todo enrichment (reads nature/energy from linked tasks/{id}.md), route_line() for compact strip display
• src/server/turn.rs — emits BackendEvent::Itinerary(route_line) on itinerary tool calls so the TUI picks it up
• src/ui/chat/mod.rs — itinerary_line field on ChatState
• src/ui/chat/render.rs — header strip showing ⟡ title · ✓ stop ● stop ○ stop with nature/energy glyphs
• src/ui/chat/events.rs — BackendEvent::Itinerary → updates itinerary_line
• src/ui/component.rs — TuiEvent::ItineraryChanged for future component integration
• src/ui/app/mod.rs — dispatches ItineraryChanged from consciousness events
• src/backend/mod.rs — BackendEvent::Itinerary(String) variant
• src/core/tools/todo.rs — cross-reference in description pointing to itinerary
• src/core/prompt.rs — when live todos exist without an active itinerary, injects: "I have N live commitments — I could use itinerary to lay them out..."

Agent Commands

• itinerary set title:<str> stops:[{name, description?, todo_id?}] — lay out a new route
• itinerary advance [todo_id:<str>] — mark current stop done, move to next; optionally auto-complete linked todo
• itinerary describe — read back the route with nature/energy details
• itinerary clear — dismiss the itinerary (does NOT touch linked todos)

Files Changed

18 files touched across the implementation.

Remaining

• Persistent UI element: the Panel now renders the itinerary as a dedicated status ribbon above chat input. Its living contract and remaining glass proof are in souveraine/saf/surface/04-agent-pane.md; the former task is archived.
• Auto-advance detection: watch for tool patterns or commits that naturally complete a stop
• Cross-session restore: read itinerary.md at startup and re-render the strip