Plan Schema
===========

A plan file can be either a raw task list or a mapping with ``execution.tasks``
plus optional plan metadata. Execution owns ``description``, ``activities``,
``tasks``, ``milestones``, and ``deliverables``. Resourcing owns ``dependencies``,
``stakeholders``, ``users``, and ``risks``. Task references remain ID-based;
project dependencies and risks remain distinct from task references/private risks.

Existing flat plan fields remain accepted for compatibility. A collection or
prose field must appear in exactly one location, even when an occurrence is
empty. Unknown container keys and non-mapping containers are errors.
``planner fields plan`` emits the nested organization. To convert an existing
plan into a separate standalone file, use
``planner composite old.yaml nested.yaml --nested``. This expands includes;
source fragments can instead stay separate by moving their include directives
beneath the corresponding container.

YAML values may use ``!include`` to compose a plan from other YAML files.
See :doc:`composite` for list splicing, relative paths, and examples.

Top-Level Metadata
------------------

Supported metadata fields are:

``portfolios``
   Ordered portfolios or parent programs. Accepts scalar text, a YAML sequence,
   or a Markdown list block using ``-``, ``*`` or ``+``. The old ``portfolio``
   input name is rejected. ``managers`` and ``pocs`` accept the same forms.
   Literal (``|``) and folded (``>``) list blocks preserve item boundaries;
   ordinary folded prose is unchanged. Native sequences are the simplest form.
   Commas and slashes remain part of each value.

``project``
   High-level project name.

``managers``
   List of manager names.

``pocs``
   List of point-of-contact names.

``summary``
   High-level plan summary. Supports inline Markdown, including ``*italics*``
   around quoted text. Word/PDF retains every line break and blank line in the
   loaded value, with emphasis preserved across lines. Use YAML ``|``/``|-``
   to retain authored line breaks or ``>``/``>-`` to fold source wrapping into
   paragraphs. Quotes inside a literal block need no backslash escaping.

``background``
   Optional project background prose, separate from the summary. Omitted/null
   text becomes empty; structured mappings/lists are rejected. Supports the
   same Markdown prose formatting and bullets as descriptions. ASC v4 includes
   populated Background after Project Summary by default; other profiles may
   select it explicitly. Available through ``list background``, field discovery,
   and Word import/export.

``fiscal_current``
   Optional declared reporting fiscal year, a two-digit label such as ``FY27``.
   Case and surrounding whitespace normalize to uppercase. This value is
   author-maintained and independent of today's date and plan coverage; it does
   not change task schedules or select/filter tasks automatically.

``planned_value``
   Optional total project budget for ``fiscal_current``; requires that field. Accepts
   the scalar funding-amount syntax, such as ``$100K``, ``100K``, or ``1.5M``;
   omitted units mean thousands. Values normalize to dollar-prefixed thousands
   (``1.5M`` becomes ``$1500K``). Zero is valid. Negative/blank/invalid amounts,
   booleans, lists and mappings are rejected. Omitted/null means unspecified.

   For example:

   .. code-block:: yaml

      fiscal_current: FY27
      planned_value: $100K

``actual_value`` (calculated output only)
   Sum of funded task funding for ``fiscal_current`` across the complete project:
   every status except ``unfunded``, so it shows funded over- or underspending
   against ``planned_value``. A multipart parent's single budget counts as funded
   when any part is funded. Missing funding for that year contributes zero. Parent
   multipart budgets count once, following the existing funding-total policy.
   Exact decimal arithmetic determines both the total and comparison with the
   planned budget. The amount is green below budget, black at budget, and red
   above budget; without a planned budget it is neutral black. Without
   ``fiscal_current`` it is unavailable. CLI color controls still apply.

``potential_value`` (calculated output only)
   Sum of all task funding for ``fiscal_current``, including ``unfunded`` tasks:
   what the project would cost if everything were funded. It is not compared
   with ``planned_value`` and always displays in neutral black.

   Actual Value measures assigned task funding, not recorded expenditure. It is not
   an accepted plan input key, does not constrain task budgets, and is always
   recomputed after import. It is available in list/show and export selections.

``stakeholders``, ``users``
   Optional prose strings identifying stakeholders and intended users. Multiline
   YAML strings are supported; omitted/null values are empty.

``dependencies``
   Optional list of project commitments. Every record requires ``id``, ``label``,
   ``type``, ``description``, and ``promised``. IDs use letters, digits and
   underscores and cannot collide with task IDs or multipart parent/part aliases.
   Labels/descriptions must be non-empty. Type is ``internal`` or ``external``
   (trimmed/lowercased). Promised dates use ``M1Q1FY27`` fiscal periods.
   Optional ``risks`` is a list of project risk IDs; omitted/null/empty means none.
   References are trimmed and deduplicated in order. All five risk types may be
   referenced. Inline task risks cannot be referenced. Omitted/null/empty root
   collections mean no definitions; scalar prose is rejected.

``risks``
   Optional list of reusable project risks. Each record requires ``id``, ``label``,
   ``type``, ``level``, and ``mitigation``; ``description`` is optional. IDs are
   unique within this collection and use the standard identifier syntax.
   Types and levels use the same choices as inline task risks. Inline risks
   retain their existing structure and have no public ID or label.

   The old ``request_dependencies`` and ``external_risks`` plan/configuration
   fields are rejected. Move prose into structured definitions, supplying dates,
   classifications and mitigations after review. Word import preserves older
   unstructured prose in the summary with review notices instead of guessing.

``fiscal_range_begin`` and ``fiscal_range_end``
   Fiscal year range covered by the plan. Values are normalized to labels such
   as ``FY27``. Both values are required when using a range.

``fiscal_years``
   Explicit list of fiscal years, such as ``[FY27, FY28]``. It is used when no
   fiscal year range is supplied; a range takes precedence when both are present.

``execution``
   Mapping with optional ``description`` prose, ``activities``, ``tasks``,
   ``milestones``, and ``deliverables`` collections.
   Each activity requires non-empty string ``id``, ``label``, and ``description``
   fields. IDs are unique within activities and use letters, numbers, and
   underscores. Task ``activity`` references one of these IDs; it is optional
   and inherited by multipart parts unless overridden or cleared.

.. code-block:: yaml

   execution:
     description: >
       Explain the overall execution approach.
     activities:
       - id: MANAGEMENT
         label: Project Management
         description: >
           Coordinate the project.

Activities, tasks, milestones, and deliverables are sibling collections under
execution. Top-level collections remain readable for compatibility.
Activity IDs are stable identities. Display letters follow full-plan declaration
order, including empty activities; filtered output retains the same letters and
task numbers. Unlinked tasks form a generated Unassigned group after declared
activities. That group is not an authored activity or a valid task reference.

This is a breaking schema change: replace ``execution.overview`` with
``execution.description``, ``execution.sections`` with ``execution.activities``,
and task ``execution_section`` with ``activity``. Old keys and flat-list
execution input are rejected. Add explicit IDs to previously anonymous entries.
Word import accepts previous document structures and emits the new schema.

Deliverables
------------

An optional ``execution.deliverables`` list defines outputs with required
non-empty ``id``, ``label``, ``description``, and ``type``. IDs are unique
within deliverables and use letters, numbers, and underscores. Types are
``paper``, ``document``, ``presentation``, ``release``, ``software``, ``dataset``,
``model``, ``service``, ``training``, ``demonstration``, ``assessment``, ``design``,
and ``hardware``; values are trimmed and normalized to lowercase. The allowed types are defined in code. A ``document`` is material
such as internal documentation that does not require submission, unlike a
``paper`` intended for submission. A document can be marked complete directly;
there is no required submitted step.

For example::

   deliverables:
     - id: RESULTS
       label: Results paper
       description: A reviewed manuscript.
       type: paper

Tasks optionally reference these IDs using ``deliverables: [RESULTS]``.
Milestone ``deliverables`` lists also contain these IDs. References must resolve,
are trimmed, and are deduplicated in declaration order. Omitted/null/empty task
and milestone lists mean none. Multipart parts inherit task references and may
replace or clear them. Python sources support ``PLAN``/``plan`` mappings and
``DELIVERABLES``/``deliverables`` alongside ``TASKS``/``tasks``.

For an output with required status, every referencing task is a required producer. Output readiness is the latest
producer finish, or unknown if any producer is undated or closed. Complete tasks
use explicit ``completed`` dates when available; other finish dates are forecasts.
Ongoing tasks use their final funded month, so a separate dated task is useful
for an output produced during ongoing work. Completion of all producers is
reported as inferred completion, without claiming output acceptance.

Milestones require all directly linked tasks and all producers of their required outputs.
An output's required-by date is the earliest deadline of milestones requiring it;
a task's required-by date is the earliest direct or indirect milestone deadline.
Completion in the deadline month is allowed. Late work, unknown required timing,
and required outputs without producers issue warnings. Schedules, funding,
task dependency order, and task states remain unchanged.

Deliverable lifecycle
~~~~~~~~~~~~~~~~~~~~~

Optional ``status`` defaults to ``required`` and accepts these code-defined values,
trimmed and normalized to lowercase:

* ``required``: all producer and deadline checks apply.
* ``planning``: deferred from assessment; no requirements propagate through this output.
* ``blocked``: required output has an obstacle; all producer and deadline checks remain.
* ``submitted``: delivered for review but awaiting acceptance; all producer and deadline checks remain.
* ``complete``: delivered and considered fulfilled, independently of producer task states.
* ``closed``: no longer required; relationships are retained for historical reporting.

Planning and closed outputs have no derived readiness or required-by dates.
Structural validation always applies, including reference resolution. Direct
links from tasks to milestones, task dependencies, and obligations through other
required outputs are unaffected. Relationship filters and summary counts retain
historical links; ``DeadlineAssessment.milestone_tasks`` contains only currently
required producer tasks and directly linked tasks.

Optional ``completed`` records an actual fiscal completion period, such as
``M3Q2FY27``, and requires explicit ``status: complete``. A late completion warns;
completion within the milestone's deadline month is allowed. Without this field,
an explicitly complete output is fulfilled but its completion date is unknown.
No producer forecast is substituted and no missing-producer or unknown-timing
warning is issued for that output. Producer tasks retain their own states.

Completed producers do not unblock a blocked output or establish acceptance of
a submitted output. These explicit states remain authoritative, with no inferred
output completion. Producer readiness dates may still be shown, but do not claim
acceptance. ``completed`` is exclusive to ``complete``; there is no separate
submission period field.

Complete producers may still imply inferred completion of a required output;
this never changes the output's stored status or asserts acceptance. Explicit
null/empty statuses, invalid completion periods, and completion periods on other
statuses are rejected.

Milestone ``deliverables`` previously held free-form prose. Migrate that prose
to output definitions and replace it with IDs; unresolved references are errors.
Use separate definitions for draft and final outputs needed at different gates.

The API exposes ``ProjectPlan.deliverables`` and ``Task.deliverables``;
``planner.deadlines.assess_deadlines`` returns derived timing and relationships.
Filtered detail output computes readiness using the complete plan.

Milestones
----------

An optional ``execution.milestones`` list defines milestones separately from
tasks. Each entry has the following fields:

* ``id``: required unique ID using letters, numbers, and underscores.
* ``label``: required non-empty display text.
* ``description``: required non-empty description.
* ``deadline``: required fiscal period, such as ``M3Q1FY27``.
* ``reporting_level``: optional ``L1`` or ``L2`` designation; omitted/empty means unspecified.
* ``deliverables``: optional list of execution.deliverables IDs; omitted/null/empty means none.

For example::

   milestones:
     - id: FLIGHT_DELIVERABLE
       label: Flight Deliverables
       description: Deliver the requested features.
       deadline: M3Q1FY27
       deliverables: []

A task's optional ``milestones`` field is a list of these IDs, for example
``milestones: [Design, Implementation]``. Omitted/null values or an empty list
mean no milestones. Every ID must resolve, including references inherited or
overridden on multipart tasks. A
plan with no milestones may still contain tasks without milestone references.
The former task ``milestone`` field must be changed to a ``milestones`` list.
Entries must be non-empty strings; surrounding whitespace is trimmed and
duplicates are removed in input order. Summary counts include a task once under
each linked milestone.

Milestone deadlines do not override task start/duration schedules. The API
exposes definitions as ``ProjectPlan.milestones``, a tuple of ``Milestone``
objects. Python ``TASKS`` files may define ``MILESTONES`` or ``milestones``
alongside their task list; ``PLAN`` mappings use the same structure as YAML.

Task Defaults
-------------

The ``tasks`` list may contain one ``defaults`` entry, in addition to task
entries. Only ``site``, ``bnr``, ``type``, and ``priority`` may be specified::

   tasks:
     - defaults:
         site: Example Works
         bnr: EXAMPLE-001
         type: labor

     - id: MAINTENANCE
       label: Tool maintenance
       description: Maintain the planning tool.
       status: ongoing
       funding: {fy27: 50K}

The defaults apply to all tasks regardless of entry order. A task's explicit
value overrides a default; explicit null or empty text clears text defaults; null or empty text clears priority. Defaults
apply before multipart expansion, so precedence is defaults, parent, then part.
The entry is configuration and does not count as a task. All four fields remain
optional without defaults. The same structure works in raw YAML lists and
Python ``PLAN`` or ``TASKS`` lists. Defaults must be a mapping nested under
``defaults``; sibling values, unsupported keys, and duplicate defaults entries
are rejected.

Task Fields
-----------

``priority`` is an optional single ID from configuration ``task_priorities``
for every task status. Omission, null, and empty text mean unassigned.
IDs are trimmed and case-sensitive. Lists (including singleton lists), mappings,
non-string values, unknown IDs, and legacy urgency values are rejected.
There is no default urgency or calculated primary priority.

Task defaults may specify ``priority``. Parts inherit their parent's value;
an explicit ID replaces it, and null or empty text clears it. Precedence is task
defaults, parent, then part. Parent summaries show Mixed when values differ.
Every task requires one scalar ``category`` ID from ``task_categories``;
category cannot be cleared. Parent summaries derive multiple distinct categories
from their children for list/export presentation; this does not add a list form
to authored task categories. Project-level priorities are rejected.
Priorities do not alter scheduling or funding.

Ordinarily, each task requires ``id``, ``label``, ``description``, ``category``, ``start``,
either ``expected`` or ``end``, and ``status``.
``priority`` and ``risk`` are optional for every task status. Omitted priority
is unassigned; omission or an empty risk list means no risks. A task with ``status: complete`` and a
``completed`` fiscal period may omit the planning-only fields ``start`` and
``expected``. When ``completed`` is set, ``status`` may also
be omitted and defaults to ``complete``. Complete tasks without ``completed``
still require the planning fields. For ``status: ongoing`` or ``status: planning``, the same planning
fields are optional without a completion marker.

Task ``id``, ``label``, and ``description`` must be non-empty strings after
trimming whitespace.
Numeric identifiers must be quoted as text. Invalid task fields report their
source field's location.

YAML plan and export-option mappings reject duplicate explicit keys with a
filename and line number, including keys inside included files. YAML merge
keys (``<<``) may still supply inherited defaults that explicit entries override.

Optional task fields include ``activity``, ``code``, ``site``, ``bnr``,
``funding``, ``type``, ``tags``, ``milestones``, and ``note``. ``note`` is an optional string
for additional task information. ``type`` is one value or a list of values (for
example ``type: [labor, contract]``); a list displays joined with commas, and
each value must be one of the built-in IDs ``labor``, ``contract``,
``equipment``, ``services``, or ``nonlabor``. Unrecognized
keys are rejected uniformly.

``milestones``
   Optional list of IDs referencing defined milestones. Omitted/null values or
   an empty list mean no milestones. The Python API stores IDs as a tuple in
   ``Task.milestones``. Multipart tasks inherit the parent list; an explicit
   part list replaces it, and null or an empty list clears it.

``activity``
   ID of an activity under ``execution.activities``. The linked activity supplies
   the activity label and letter used in Word and SVG exports; the task keeps
   its own descriptive ``label``. Multiple tasks may link to the same activity.
   This is the sole task grouping field. Tasks without an activity link appear
   together under ``Unassigned``. The top-level ``project`` remains the plan name.

``id``
   String containing only letters, numbers, and underscores.

``start``
   A fiscal period in ``M{month}Q{quarter}FY{year}`` format, such as
   ``M1Q3FY26``.

``expected``
   Positive whole number of months defining the task duration. End dates are
   calculated from ``start``, counting the start month as month one. For example,
   ``start: M3Q4FY26`` and ``expected: 2`` end at ``M1Q1FY27``. A one-month task
   ends in its start month. The Python API exposes this calculated period as
   ``Task.end`` and the duration as ``Task.expected`` (also ``Task.duration``).
   For ongoing tasks, funding supplies the schedule instead, as described below.
   Durations must fit within the supported two-digit fiscal-year range, FY00–FY99.

   To migrate older inputs, rename ``expected duration`` or ``expected_duration``
   to ``expected`` and remove ``deadline``.

``end``
   Optional alternative to ``expected``, using the same fiscal-period syntax
   as ``start``. Endpoints are inclusive: ``start: M3Q4FY27`` and
   ``end: M2Q1FY28`` give a duration of three months. An end equal to the start
   gives one month; an end before the start is invalid. Supplying ``end`` requires
   a start (or the existing completed-task start fallback). Null/empty values
   are invalid. If both ``expected`` and ``end`` are supplied, they must agree.
   The loader normalizes the pair to ``Task.expected``; ``Task.end`` continues
   to expose the effective end for either input representation. The supported
   range remains FY00–FY99. Ongoing timing remains funding-driven: supplied
   start/end/duration metadata is validated but does not override funded-year spans.

   Multipart parts inherit timing, but specifying just ``end`` replaces an
   inherited ``expected`` and specifying just ``expected`` replaces an inherited
   ``end``. Supplying both on a part still requires consistency. Merge/split
   preserve authored timing fields and these inheritance rules.

``priority``
   Optional for every status; defaults to ``low`` when omitted. Supplied values
   must be one of ``low``, ``medium``, ``high``, or ``urgent``.

``status``
   One of ``pending``, ``planning``, ``active``, ``ongoing``, ``blocked``, ``unfunded``, ``complete``, or
   ``closed``. Use ``unfunded`` for work awaiting funding.

   Planning placeholders require only ``id``, ``label``,
   ``description``, ``category``, and ``status: planning``. They may omit ``start``, ``expected``,
   ``priority``, and ``risk``; supplied values are validated normally. Priority
   defaults to ``low`` and risks to an empty list. Start and duration estimates
   may be added independently. Until both exist, timing is ``Unscheduled``,
   ``Task.end`` is empty, and ``Task.schedule_spans`` is empty. Omitted duration
   is ``None`` in ``Task.expected`` and ``Task.duration`` and displays as
   ``Unspecified``. Once both timing fields exist, normal calculated timing
   applies. Funding contributes to totals without supplying a schedule.
   Undated placeholders sort after dated tasks and have no Gantt bars.
   The schedule state remains ``PLANNING`` regardless of dependencies, and a
   planning task does not satisfy a dependent task's completion requirement.
   Word narratives identify placeholders with ``[PLANNING]``. Changing status
   enforces the new status's normal requirements.

   Closed tasks require only ``id``, ``label``, ``description``, ``category``, and ``status: closed``.
   Priority defaults to ``low`` and risks to empty.
   Timing is ``Unscheduled`` until ``start`` and either ``expected`` or ``end`` exist; omitted
   duration is ``None`` and no Gantt bar is drawn. Supplied optional values are
   validated normally. With both timing fields, normal month-based timing applies.
   They display ``CLOSED`` in schedules and a gray ``[CLOSED]`` marker in Word
   narratives, and use the same gray styling as unfunded
   tasks. Only ``complete`` tasks satisfy dependencies. Valid status choices are
   listed alphabetically with ``closed`` last.

   Ongoing tasks may omit ``start``, ``expected``, ``priority``,
   and ``risk``. They run for each full fiscal year with
   positive numeric funding, ignoring any supplied start/duration for scheduling.
   Zero-funded and missing years create gaps. Their duration is twelve months
   per funded year; without positive funding they remain in lists and schedules
   but do not appear in Gantt output. Undated ongoing tasks sort after dated work.
   Omitted priority is unassigned and risks default to an empty list. Dependencies and tags are optional for all tasks. Supplied optional
   values still undergo normal validation.

   The Python API exposes ongoing year spans as ``Task.schedule_spans``, their
   total scheduled months as ``Task.duration``, and their last funded fiscal
   month as ``Task.end`` (an empty string when no years are funded). Omitted
   ``start`` remains an empty string and omitted ``expected`` is ``None``.

``completed``
   Optional fiscal period for already-completed work. When present on a
   complete task, it supplies the start month when ``start`` is omitted; an
   omitted ``expected`` defaults to one month. A task with ``completed`` and no explicit
   ``status`` is treated as complete.

``dependencies``
   Optional list of task or project dependency IDs. Omitted or null values mean
   no dependencies. Every supplied reference must resolve. Task edges retain
   cycle detection and dependency ordering. Project commitments do not become
   task graph nodes and never become fulfilled merely because their promised
   date passes. An otherwise-ready pending task remains BLOCKED while any
   referenced project commitment is unconfirmed. Existing explicit task status
   behavior is preserved. A task starting before a promised month warns without
   changing dates; starts in the same month are allowed. Fixed dependency
   output fields display ``None`` when empty; concise ``list`` omits the line.

``tags``
   Optional comma-separated text or list of task tags. Omitted or null values
   mean no tags. An explicitly selected Word Tags column displays ``None``
   when empty. Both tags and dependencies use empty tuples in the Python API.

``workitems``
   Optional mapping or list of mappings, each requiring an ``id`` such as
   ``aircraft/design#42`` (work item) or ``aircraft/design!69`` (merge request).
   Identifiers contain a namespace/project path, optionally with subgroups,
   followed by ``#`` or ``!`` and a positive decimal item number without leading
   zeroes. Each path segment starts with an ASCII letter or digit and contains
   only ASCII letters, digits, underscores, dots, or hyphens. Surrounding
   whitespace is trimmed. Full URLs, missing namespaces, and malformed
   references are rejected. No server connection or existence check is needed.
   The explicit ``type`` field is rejected with guidance to remove it;
   ``WorkItem.type`` is derived as ``workitem`` or ``mr`` in the Python API.
   The former ``value`` field is rejected with guidance to rename it to ``id``.
   Each entry accepts an optional ``status``
   of ``open`` or ``closed``, defaulting to ``open`` when omitted. Statuses
   are trimmed and normalized to lowercase; explicit null and other values
   are rejected. CLI and configured exports show the status with each reference.
   Optional ``assignees`` is a list of non-empty moniker strings, trimmed with
   case and order preserved. Omitted, null, or empty lists become an empty tuple.
   CLI and configured exports display assigned monikers alongside each reference.
   Optional ``label`` is a display name shown before the identifier in CLI and
   configured exports. Surrounding whitespace is trimmed; omitted or null
   labels become empty strings and non-string values are rejected. Labels
   support the same inline Markdown subset as task labels in Word/SVG exports.
   Optional ``description`` contains prose about the work item, with surrounding
   whitespace trimmed. Omitted or null descriptions become empty strings;
   non-string values are rejected. Descriptions appear alongside references in
   CLI output and configured Word/SVG exports, using the same inline Markdown
   subset as task descriptions in those exports.
   Omitted, null,
   or empty lists become an empty tuple of ``WorkItem`` objects in the Python
   API. Multipart tasks inherit references; parts can replace them or clear
   them with null or an empty list. Unknown entry fields are rejected.
   ``list-detail`` and ``schedule`` show references in task attributes.
   Select ``workitems`` in export options to include a Word summary-table
   column and SVG card attributes.

   .. code-block:: yaml

      workitems:
        - id: aircraft/design!59
          label: Solver update
          status: closed
          assignees: [designer_one, designer_two]
          description: Review solver changes.
        - id: aircraft/assembly#12
          status: open

``risk``
   An optional mapping or list of mappings. Omit it or use ``risk: []`` for no
   risks; null is rejected. Each risk entry must include ``type``,
   ``level``, and ``mitigation``, and may include ``description``. Risk levels
   are ``low``, ``medium``, ``high``, and ``extreme``. Required ``type`` must be
   ``technical``, ``schedule``, ``operational``, ``external``, or ``performance``;
   surrounding whitespace is trimmed and case is normalized to lowercase.
   Null, empty, non-string, and unknown types are rejected.
   ``mitigation`` must also be non-empty. Use ``planner avail risk.type`` to
   list the allowed types.

``funding``
   Mapping of fiscal year labels to funding levels, or a list of mappings with
   a year and level, for example ``[{year: FY27, level: 50K}]``. List entries
   also accept ``fiscal_year`` or ``fiscal year`` for the year, and ``funding``
   or ``amount`` for the level. Missing fiscal years are treated as unfunded for
   that task. A warning is issued when a funding year falls before the fiscal
   year of ``start`` or after the fiscal year of the calculated end month.
   This warning does not apply to ongoing tasks, whose dates come from funding.

Multi-Part Tasks
----------------

A task can use ``parts`` instead of schedule fields on the parent. Parent
metadata such as ``activity``, ``site``, ``bnr``, ``type``,
``tags``, and ``note`` is inherited by each part. Funding may be specified
on the parent or individual parts. A parent budget contributes once to fiscal-
year totals whenever any part is included, including filtered list output.
Without a parent budget, totals sum the included parts' amounts. Parts inherit
parent funding unless they supply their own. Explicit part funding controls
part-level display and ongoing time spans; the parent's full budget remains
authoritative for totals when present (including an explicitly empty budget).
Parent funding is not combined with part funding when computing totals.

Part ids expand to flat task ids using ``{parent_id}_{part_id}``. For example,
part ``A`` on parent ``AIRFRAME`` becomes ``AIRFRAME_A``. Dependencies inside a
multi-part task can reference sibling part ids, and other tasks can depend on
the parent id to depend on all expanded parts.
Exports place parts together within each activity at the position of the first
part encountered in end-date order. Parts are ordered by end date, with ties
retaining declaration order within the parent task. The ``list`` command uses
the same ordering, including
``list --label``. Dependency-aware schedules still respect dependencies.

Validation
----------

Validation rejects missing required fields, invalid ids, invalid fiscal
periods, non-positive or non-integer durations, invalid status or risk levels, dependencies
that reference missing tasks, dependency cycles, duplicate activity
IDs, references to missing activities, and calculated end dates
beyond FY99.

Validated output is sorted by calculated end month, activity, label, and id. Ongoing tasks
without funded years sort after dated tasks.

Strict Field Names
------------------

Every input mapping accepts only documented fields. Unknown fields are errors
with source locations, including plan, task, multipart parent/part, risk, work
item, milestone, execution, activity, funding-list, and export-option mappings.
Previously supported names receive the same generic error as any other unknown
name. Public field schemas also drive field selection, discovery, and templates.

``funding`` is the sole budget input. ``Task.funding_total`` computes the sum of
that task's effective fiscal-year amounts. Word's optional Funding column shows
this value. Plan totals continue to count a multipart parent's budget once when
any of its parts is included; per-part funding displays remain independent.

Task Categories
---------------

Every effective task requires a scalar ``category`` ID from the active
configuration's ``task_categories``. Multipart parts inherit their parent's
category unless overridden. Null, empty, and unknown values are errors.
Categories are independent of task ``type`` and task ``priority``.
See :doc:`configuration` for vocabulary definitions and migration.

Typed Funding
-------------

Task ``funding`` also accepts type/fiscal-year mappings and staff-based labor
allocations. See :doc:`funding` for rates, available FTE and duration costing.

Derived Task Cost
-----------------

``cost`` is a read-only task list field. It reports resolved funding totals by
specified type, or an incomplete estimate with known components. Authored task
``cost`` values are rejected. See :doc:`funding` for the calculation and
completeness rules.

Funding code defaults
---------------------

Activities accept optional ``code`` text. Tasks accept an optional ``code``
override, inherited by multipart parts. Labor allocations use their own explicit
code first, then the task default, then the linked activity code. Null or empty
task code clears the activity default. See :doc:`funding` for a complete example.

Typed funding ranges
---------------------

Under any built-in funding type, ``fiscal_range`` repeats an annual amount or
labor allocation list across the plan's declared fiscal years. Explicit year
entries replace that type's default for the matching year. A non-empty plan
fiscal range or ``fiscal_years`` list is required. See :doc:`funding` for examples.

Covered funding
----------------

Typed annual entries can use ``{covered_by: TASK_ID, share: 25%}`` instead of an
amount; ``share`` is optional. Labor lists can use ``{id: STAFF_B,
covered_by: TASK_ID, share: 25%}``, with optional source-allocation ``code``.
Covered entries have no direct amount/staff-time percent. The referenced
component/year must be directly funded. Shares attribute source dollars without
adding funding. ``share: remainder`` assigns what numeric claims leave for the
same source/type/year/staff/code allocation. A single child-to-parent reference
with omitted share receives an implicit remainder; multiple overlapping
remainders are rejected. Whole-type remainders cannot mix with staff-specific
claims. Children without explicit allocations automatically split remaining
parent funding per type/year/staff/code, after authored coverage claims. No
child ``funding`` entry is required; explicit zero counts as an allocation.
See :doc:`funding` for validation, totals and multipart rules.

Task-date funding ranges
-------------------------

Typed funding accepts ``range`` as an alternative to ``fiscal_range``. It repeats
an annual amount, labor allocation list or coverage reference over the fiscal
years touched by explicitly authored task start/end or start/expected. Explicit
year entries override it; both defaults within one type are rejected. Task dates
select years independently of plan fiscal metadata. Ongoing tasks cannot use
``range``. See :doc:`funding` for costing, multipart and incomplete-input rules.

Rates-file code identifiers
----------------------------

Flat staff ``code`` and grouped staff ``codes[].id`` use ``XXXX_XXXX_XXXX``:
three four-character groups of uppercase ASCII letters/digits separated by
underscores, for example ``DEMO_CORE_0000``. Whitespace around a code is trimmed;
dots, lowercase, extra separators and incorrectly sized groups are rejected.
Quote codes made entirely of digits. Staff entries without a code remain valid.

Implicit multipart coverage shares
------------------------------------

Within a funded multipart child's annual or range funding entry, ``share`` can
omit ``covered_by`` to select the parent. Labor entries additionally select staff
``id`` and optional source ``code``. An explicit child-to-parent reference is
also accepted; self-references to the child's own expanded ID remain errors.
Parent-owned dollars count once, and child/external attributed shares share the
same 100% limit. See :doc:`funding` for the complete example and cost display.
