Module plan 

AI Plan Definition

A Plan is a sequence of PlanSteps derived from an Intent’s analyzed content. It defines what to do — the strategy and decomposition — while Run handles how to execute it. The Plan is step ③ in the end-to-end flow described in mod.rs.

Position in Lifecycle

 ②  Intent (Active)       ← content analyzed
      │
      ├──▶ ContextPipeline ← seeded with IntentAnalysis frame
      │
      ▼
 ③  Plan (pipeline, fwindow, steps)
      │
      ├─ PlanStep₀ (inline)
      ├─ PlanStep₁ ──task──▶ sub-Task (recursive)
      └─ PlanStep₂ (inline)
      │
      ▼
 ④  Task ──runs──▶ Run ──plan──▶ Plan (snapshot reference)

Revision Chain

When the agent encounters obstacles or learns new information, it creates a revised Plan via new_revision. Each revision links back to its predecessor via previous, forming a singly-linked revision chain. The Intent always points to the latest revision:

Intent.plan ──▶ Plan_v3 (latest)
                  │ previous
                  ▼
                Plan_v2
                  │ previous
                  ▼
                Plan_v1 (original, previous = None)

Each Run records the specific Plan version it executed via a snapshot reference (Run.plan), which never changes after creation.

Context Range

A Plan references a ContextPipeline via pipeline and records the visible frame range fwindow = (start, end) — the half-open range [start..end) of frames that were visible when this Plan was created. This enables retrospective analysis: given the context the agent saw, was the plan a reasonable decomposition?

ContextPipeline.frames:  [F₀, F₁, F₂, F₃, F₄, F₅, ...]
                          ^^^^^^^^^^^^^^^^
                          fwindow = (0, 4)

When replanning occurs, a new Plan is created with an updated frame range that includes frames accumulated since the previous plan.

Steps

Each PlanStep has a description (what to do) and a status history (statuses) tracking every lifecycle transition with timestamps and optional reasons, following the same append-only pattern used by Intent.

Step Context Tracking

Each step tracks its relationship to pipeline frames via two ID vectors:

• iframes — stable frame_ids of frames the step consumed as context.
• oframes — stable frame_ids of frames the step produced (e.g. StepSummary, CodeChange).

Frame IDs are monotonic integers assigned by ContextPipeline::push_frame. Unlike Vec indices, IDs survive eviction — a step’s iframes remain valid even after older frames are evicted from the pipeline. Look up frames via ContextPipeline::frame_by_id.

All context association is owned by the step side; ContextFrame itself is a passive data record with no back-references.

ContextPipeline.frames:  [F₀, F₁, F₂, F₃, F₄, F₅]
                           │    │         ▲
                           ╰────╯         │
                        iframes=[0,1]  oframes=[4]
                             ╰── Step₀ ──╯

Recursive Decomposition

A step can optionally spawn a sub-Task via its task field. When set, the step delegates execution to an independent Task with its own Run / Intent / Plan lifecycle, enabling recursive work breakdown:

Plan
 ├─ Step₀  (inline — executed by current Run)
 ├─ Step₁  ──task──▶ Task₁
 │                     └─ Run → Plan
 │                          ├─ Step₁₋₀
 │                          └─ Step₁₋₁
 └─ Step₂  (inline)

Purpose

• Decomposition: Breaks a complex Intent into manageable, ordered steps that an agent can execute sequentially.
• Context Scoping: pipeline + fwindow record exactly what context the Plan was derived from. Step-level iframes/oframes track fine-grained context flow.
• Versioning: The previous revision chain preserves the full planning history, enabling comparison of strategies across attempts.
• Recursive Delegation: Steps can spawn sub-Tasks for complex sub-problems, enabling divide-and-conquer workflows.

Structs

Plan

A sequence of steps derived from an Intent’s analyzed content.

PlanStep

A single step within a Plan, describing one unit of work.

StepStatusEntry

A single entry in a step’s status history.

Enums

StepStatus

Lifecycle status of a PlanStep.