batteries/orchestration/outline

Remarks

A model's context window is smaller than a plan will get, so it must be able to work on a plan it cannot hold. This module is that mechanism, and its shape is load-bearing:

• ONE FLAT LEVEL. Never two. planOutline returns a single flat list of phases — no sub-phases, no index that needs an index. This is not a style preference: a controlled study of this pattern found one routing level helps and a second "never helps and sometimes breaks accuracy outright" (0.9126 → 0.6398 on one cell), because in a two-level pack every child description sits in context before the router commits, recreating the very pressure progressive disclosure exists to relieve.
• Entries carry EXACT SURFACE FORMS, not paraphrase. Per the same study, per-chunk metadata must be a short summary PLUS a list of key elements, because the element list supplies "exact surface forms that a one-sentence summary would paraphrase away". For a plan that is decisive: a model writing NodeRef{node:'archive_files'} needs the EXACT node id, and a prose summary of a phase destroys it. So each PhaseEntry carries, verbatim: the phase name, the node ids, the tool name of each call node in that phase, an open-issue count, and a one-line summary.
• unphased is addressed identically. Nodes with no phase are not second-class — they get their own PhaseEntry so a model reaches them the same way.
• The outline's key IS the reader's key. planRead takes the SAME identifiers the outline printed — a phase name or a node id. No line numbers anywhere.
• Each slice is SELF-LOCATING. A returned slice carries its phase and the immediate predecessors/successors of the slice as a whole (boundary), so a model can keep linking new nodes without re-fetching the outline.
• Scoped reading is available, not mandatory. The study's own conclusion is that progressive disclosure "buys context, not intelligence" — decisive once an artifact is too large to read, redundant when an agent can navigate it directly. So a five-node plan should be read whole; the outline hop is not compulsory.

Functions

Function	Description
planOutline	Build a flat outline of a plan: one entry per phase, plus a single entry for unphased nodes.
planRead	Read a self-locating slice of a plan by the exact identifier the outline printed.