Composite YAML Plans
====================

Split a plan across YAML files with ``!include``. The tag can replace any YAML
value: a mapping, list, or scalar. Paths resolve relative to the file containing
the directive, including within nested includes. Quoted paths support spaces.
Included files must have a ``.yaml`` or ``.yml`` suffix.

.. code-block:: yaml

   # plan.yaml
   project: FY27 Plan
   summary: !include prose/summary.yaml
   execution:
     milestones: !include milestones.yaml
     description: !include prose/overview.yaml
     activities:
       - !include activities/solver.yaml
       - !include activities/runtime.yaml
     tasks:
       - !include tasks/solver.yaml
       - !include tasks/runtime.yaml

An activity file contains a mapping:

.. code-block:: yaml

   # activities/solver.yaml
   id: solver
   label: Solver Development
   description: Develop and validate solver capabilities.

A task file can contain a list, inserted into the surrounding list in order:

.. code-block:: yaml

   # tasks/solver.yaml
   - id: SOLVER_UPDATE
     label: Update solver
     activity: solver
     description: !include ../prose/solver-description.yaml
     status: ongoing
     funding: !include ../budgets/solver.yaml

The prose file contains a YAML scalar, while funding contains a mapping:

.. code-block:: yaml

   # prose/solver-description.yaml
   >-
     Develop the solver and validate its integration.

.. code-block:: yaml

   # budgets/solver.yaml
   fy27: 100K
   fy28: 150K

Expansion rules
---------------

* In a mapping value, the include is replaced by the included value.
* In a list, an included list is spliced into its surrounding list in order.
  An included mapping or scalar becomes one item. Ordinary nested lists remain
  nested.
* A whole file can consist of a single ``!include`` directive.
* Includes may be nested, and files may be included more than once. Include
  cycles, including cycles through symbolic links, are errors.
* Includes are supported in value positions, not mapping keys. There are no
  implicit mapping merges or overrides. Normal plan validation runs after
  expansion; defaults and multipart tasks work across included task lists.
* YAML anchors and aliases remain local to each file. Recursive aliases are
  rejected. Custom Python tags and included Python files are unsupported.

Read commands expand composite YAML into a temporary standalone snapshot before
loading the plan, and remove that snapshot automatically. Diagnostics retain
original filenames and lines for included task, milestone, and activity mappings;
included scalar fields may identify the containing mapping or include site.
Python plan files and general configuration files do not support ``!include``.

Write a standalone composite
----------------------------

.. code-block:: bash

   planner composite plan.yaml expanded.yaml
   # With TUXFAN_PLANNER_DATAFILE set:
   planner composite expanded.yaml

Output is required. This command writes expanded YAML without applying task
defaults, normalizing model fields, or expanding multipart tasks. It checks
include structure and file access but does not require a valid task schema;
use ``planner validate expanded.yaml`` to validate the resulting plan. Inputs
without includes also work.

Output contains expanded data, not original comments, formatting, or include
directives. Existing output is replaced atomically only after successful
expansion. Output must not overwrite the root input or any included file,
including through symbolic or hard links.

Source editing
--------------

``format`` formats the main file and every recursively included YAML source once,
preserving include directives and file boundaries. Each formatter runs from its
source's directory, using normal configuration discovery (including ancestor
directories). Source encoding and line endings are retained. The complete include
graph is checked before tools run; missing or invalid includes and cycles are
errors. All formatted results must preserve YAML structure, values, and include
references before any source is saved. Changed files receive numbered backups
and atomic replacement individually; saving the complete set is not one atomic
transaction, so later write failures can leave earlier files formatted.

``spell-check`` follows nested includes and reviews original source prose once
per field in one interactive session. Field context crosses include boundaries,
so scalar descriptions and lists of manager names are reviewed, while IDs,
references, include paths, and enum fields remain protected. Text shared between
prose and structural contexts is skipped with a manual-review message. The
include graph is checked before tools run. Corrections are staged across all
files, summarized by source, and saved only after one final confirmation;
cancellation during review discards all corrections and dictionary additions.

The session selects one personal dictionary: explicit ``--personal`` wins,
otherwise discovery starts at the main plan's directory and uses the nearest
``.planner-words.pws`` in that directory or an ancestor, falling back to Aspell's
usual personal dictionary. Included files do not select separate dictionaries.
Ignore-all and dictionary additions apply throughout the session. Additions are
saved only after the final confirmation. Each changed source receives a numbered
backup and atomic replacement. Saving all sources and the dictionary is not a
single atomic transaction; later failures report files already saved.

Migrating plan organization
---------------------------

``planner composite old.yaml nested.yaml --nested`` expands includes and writes
collections under execution and resourcing without changing task definitions,
references, defaults, or multipart structure. The output is a standalone file;
original sources are untouched. Without ``--nested``, authored organization is
retained. To keep includes, instead move tasks/milestones/deliverables include
entries under execution and project dependencies/risks/prose under resourcing.
Included list fragments need no extra wrapper.
