Funding and Staff Costs
=======================

Annual and typed funding
------------------------

Existing fiscal-year mappings and lists of year/amount records remain supported::

   funding:
     FY27: 600K
     FY28: 650K

A task may instead break its funding down by the built-in task types
``labor``, ``contract``, ``equipment``, ``services``, and ``nonlabor``::

   funding:
     labor:
       FY27:
         - id: STAFF_A
           percent: 10
       FY28: 50K
     contract:
       FY27: 500K
     nonlabor:
       FY27: 100K

Each type maps fiscal years to monetary amounts. A labor year may instead
contain a list of staff allocations, each with ``id``, ``percent``, and optional
``code`` selecting a coded staff entry. Use
either an amount or allocations for a particular labor year. Separate types
are added together; ``nonlabor`` is an independent bucket rather than an
automatic total of the other non-labor types. Avoid recording the same costs
in multiple buckets. Funding types do not require matching task ``type`` metadata.

Coarse fiscal-year keys and typed keys cannot be mixed in one funding mapping.
Unknown type names, unknown nested fields, duplicate staff allocations within a
year, and duplicate fiscal years after normalization are rejected. Missing years
contribute zero. Monetary typed entries use existing non-negative funding syntax:
``$100K``, ``100K``, ``1.5M``, or ``0``. Bare amounts are thousands of dollars.

Rates and staff availability
----------------------------

Configure the separate rates file::

   rates_file: rates.yaml
   labor_costing: annual

``rates_file`` is relative to the configuration file. A non-empty
``TUXFAN_PLANNER_RATES_FILE`` overrides it; relative environment paths resolve
from the working directory. Both accept ``~``. An empty environment value leaves
the configured path active. For example::

   export TUXFAN_PLANNER_RATES_FILE=/path/to/rates.yaml

The rates file contains two lists::

   rates:
     - id: STANDARD
       amount: $300K
       category: Research Staff
       band: "$50,000 - $69,999"

   staff:
     - id: STAFF_A
       rate: STANDARD
       fte: 40%
     - id: STAFF_B
       rate: STANDARD

Optional rate ``category`` and ``band`` fields preserve descriptive information
from source rate tables. Both must be non-empty text when supplied; surrounding
whitespace is trimmed. ``category`` is a free-form staff classification,
independent of configured task categories. ``band`` retains the authored salary
range, including forms such as ``< $50,000`` or ``>= $150,000``. These fields do
not determine staff costs or select rates automatically; calculations use the
rate's ``amount``. Existing files may omit both fields.

Each rate is the annual cost of one full-time person. A scalar amount applies
to every fiscal year; an effective-month mapping records changes over time. Rate and staff IDs are trimmed, case-sensitive,
non-empty strings. Rate IDs must be unique. Staff entries are unique by
``(id, code)``; entries without a code retain unique plain IDs. Staff rate
references must resolve. The optional ``fte`` is the staff member's available percentage
of full-time effort and defaults to 100%.

Coded staff allocations
~~~~~~~~~~~~~~~~~~~~~~~

Staff entries can group their allocations in a ``codes`` list. The shared
``rate`` belongs to the person; each code entry has its own ``id`` and available
``fte``::

   staff:
     - id: STAFF_A
       rate: STANDARD
       codes:
         - id: DEMO_CORE_0000
           fte: 40%
         - id: DEMO_SUPP_0000
           fte: 20%

Rate-file codes must use ``XXXX_XXXX_XXXX``: three groups of exactly four
uppercase ASCII letters or digits, separated by underscores. For example,
``DEMO_CORE_0000`` is valid; a dotted business notation such as
``DEMO.CORE.0000`` must be written with underscores in the rates file. Surrounding
whitespace is trimmed; case and separators are not converted automatically.
Quote entirely numeric codes, such as ``"1234_5678_9012"``, to keep YAML from
interpreting them as numbers. Both flat staff ``code`` and grouped ``codes[].id``
are checked, with errors pointing to the offending field in the rates file.
Uncoded staff entries remain valid; staff IDs and salary-rate IDs keep their
existing syntax. Codes identify activity or funding allocations independently
of salary-rate IDs. Each nested code may
supply a ``rate`` override; without an override it inherits the person's rate.
The person-level rate may be omitted when every code supplies its own rate.
A code with omitted ``fte`` defaults to 100%. The ``codes`` list must be
non-empty and cannot be combined with person-level ``code`` or ``fte`` fields.

The earlier flat format (separate entries with ``id``, ``code``, ``rate``, and
``fte``) remains supported, as do uncoded entries. Grouped and flat entries
resolve to the same person/code allocations and use the same validation.

A task selects the appropriate person/code pair::

   funding:
     labor:
       FY27:
         - id: STAFF_A
           code: DEMO_CORE_0000
           percent: 50%
         - id: STAFF_A
           code: DEMO_SUPP_0000
           percent: 100%

These entries cost 20% and 20% of the full-time rate, respectively. Duplicate
person/code pairs in the catalog or repeated references to the same resolved
allocation within one task/year are rejected. Different codes for the same
person can be selected together. An explicit code must match exactly.

Without ``code``, an uncoded staff entry is selected when one exists. Otherwise
an ID with exactly one coded allocation can be used alone. Multiple coded
allocations require ``code``; an ambiguous ID produces an error. Existing
uncoded files and task references retain their previous behavior. Terminal
funding details display the selected code in brackets after the staff ID.

Fiscal-year and monthly availability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See ``planner/examples/rates-timing.yaml`` for a complete fictional catalog.

An allocation's ``fte`` may be a scalar percentage (all months of all years),
or a mapping of fiscal years to annual percentages or monthly profiles::

   fte:
     default: 40%
     FY27: 50%
     FY28:
       M1Q1FY28: 40%
       M2Q1FY28: 40%
       M3Q1FY28: 40%
       M1Q2FY28: 50%
       M2Q2FY28: 50%
       M3Q2FY28: 50%
       M1Q3FY28: 60%
       M2Q3FY28: 60%
       M3Q3FY28: 60%
       M1Q4FY28: 40%
       M2Q4FY28: 40%
       M3Q4FY28: 40%

Fiscal years run October through September. ``M1Q1FY28`` is October 2027;
``M1Q2FY28`` is January 2028. Omitted months within an explicitly defined
monthly year default to 0%, even when ``default`` is supplied. For example::

   fte:
     default: 40%
     FY28:
       M1Q1FY28: 50%
       M1Q2FY28: 60%

Only October and January have availability in FY28; the other ten months are
zero. An empty year mapping (``FY28: {}``) means zero availability for the
entire year. Month keys must belong to their containing fiscal year. Duplicate normalized years/months, invalid periods, nulls and invalid
percentages are errors. Whole-year and monthly definitions cannot overlap.

``default`` supplies availability for years without an explicit definition;
an explicit year replaces it completely. Without ``default``, an unlisted year
is unknown and an allocation using it is an error. Omitted ``fte`` still means
100% for all years. These forms work on grouped code entries, flat coded staff
entries and uncoded staff.

Combined code availability for one person must not exceed 100% in any month,
including default years and unused explicit years. An uncoded entry is an
alternative fallback selection, rather than another code pool.

Effective rates and promotions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rate ``amount`` and staff ``rate`` accept either their existing scalar values
or non-empty effective-month mappings using the same fiscal syntax as plans::

   rates:
     - id: STANDARD
       category: Research Staff
       band: "$65,000 - $79,999"
       amount:
         M1Q1FY27: $250K
         M1Q2FY27: $260K
     - id: SENIOR
       amount:
         M1Q1FY27: $300K

   staff:
     - id: STAFF_A
       rate:
         M1Q1FY27: STANDARD
         M1Q3FY27: SENIOR
       codes:
         - id: DEMO_CORE_0000
           fte: {FY27: 40%}

Each entry takes effect at the beginning of its month and continues until
replaced, including subsequent fiscal years. Authored order does not matter.
Here the annual rate increases in January 2027 and the person is promoted in
April 2027. ``category`` and ``band`` remain descriptive properties of each
rate ID. A code-specific ``rate`` override accepts the same history format and
replaces the person's entire assignment history for that code.

For each costed month, planner selects the effective staff rate ID and then
that rate's effective annual amount. A month before either history begins is
an error; values are never extrapolated backward. Every referenced rate ID,
including future promotions, must exist. Duplicate normalized effective months,
invalid periods, empty histories and invalid amounts are rejected with source
locations. Scalar values remain valid for the entire supported fiscal range.

Staff percentages
~~~~~~~~~~~~~~~~~

Task ``percent`` is a percentage of that available effort, rather than a
percentage of full-time effort. Both ``fte`` and ``percent`` accept numbers
from 0 through 100, optionally written as text ending in ``%``; ``40`` and
``40%`` both mean forty percent. Booleans, nulls, non-finite values, negative
values, and percentages above 100 are rejected. Allocations across different
tasks are not automatically capped or rebalanced. Plan loads warn when direct
monthly task demand exceeds a selected allocation's available effort or a
person's full-time capacity. Annual mode considers all twelve months; duration
mode considers scheduled months only. Unfunded, complete and closed tasks are excluded. Shared
parent budgets count once, and covered funding does not add another claim.
Warnings leave funding totals unchanged.

With a $300K rate, ``fte: 40%`` and task ``percent: 10`` produce::

   $300K × 40 / 100 × 10 / 100 = $12K per fiscal year

For changing availability, rates or assignments, each costed month contributes::

   effective annual rate / 12 * monthly fte / 100 * task percent / 100

Calculation uses decimal arithmetic. Monthly products are summed before division
and rounding, without averaging annual rates or rounding each month. Each
staff/code/year cost is rounded to the nearest cent, with half cents rounded up,
before summing staff and funding types.
Typed monetary entries retain their authored precision. A supplied zero FTE or
zero task percentage produces zero staff cost.

The rates file is loaded only when a non-empty staff allocation list requires
it. Plans using coarse funding, typed monetary amounts or empty labor lists do
not require a rates file. Each plan load uses one rates snapshot; subsequent
plan loads reread the file. Missing files, staff and rates produce errors with
source locations. Authoring operations check the consumed rates snapshot before
saving, in addition to their normal plan-source checks.

Staff subscription reports
--------------------------

Use ``planner list staff`` to inspect available, assigned and remaining staff
effort by funding code::

   planner list staff plan.yaml --year FY27
   planner list staff plan.yaml --year FY27 --monthly --details
   planner list staff plan.yaml --month M1Q1FY27 --staff STAFF_A
   planner list staff plan.yaml --year FY27 --code DEMO_CORE_0000 --include-unfunded
   planner list staff plan.yaml --year FY27 --format csv > staff-subscription.csv

The text report follows normal list styling: framed staff sections, item rules
between codes/periods, colored IDs, headings and independently colored numeric
fields. Configure ``terminal.colors.subscription`` (``available``, ``used``,
``remaining``, ``ratio``, ``proposed``, ``overcommitted``, ``unknown``) or inspect
``planner avail colors`` / ``planner fields colors``. Standard terminal color
controls and configured width apply; CSV output is unaffected.

The report includes staff and codes from the active rates catalog even when
no task uses them. It requires a readable rates catalog, including for plans
with no staff funding. Configuration/environment rates-path selection works
as usual. The plan and catalog share one rates snapshot during the command;
reporting never edits either source.

``--year`` and ``--month`` are mutually exclusive. Without either, use the
plan's ``fiscal_current``, then its normalized fiscal years, then years present
in resolved staff allocations. If none are available, specify a year/month.
An explicit month uses the plan's fiscal-period syntax. ``--monthly`` compacts
consecutive identical months within each fiscal year. ``--details`` adds
consuming tasks, shared parent ownership/member IDs, and declared coverage
attribution. Rates and promotions continue to affect funding calculation;
subscription itself measures effort rather than monetary cost.

Each metric occupies its own labeled line. ``Subscribed`` is effort assigned
in this plan as a percentage of a full-time person. ``Available`` is unused
capacity defined in the rates file. ``Allocation`` shows total configured
capacity in the staff summary and capacity for each code::

   Staff: STAFF_A
     FY27
       Allocation: 60%
       Subscribed: 30%
       Available: 30%

     Code: DEMO_CORE_0000
       FY27
         Allocation: 40%
         Subscribed: 30%
         Available: 10%

     Code: DEMO_SUPP_0000
       FY27
         Allocation: 20%
         Subscribed: 0%
         Available: 20%

Here the catalog allocates 60% FTE across two codes, of which tasks subscribe
30% FTE. Person availability is therefore 30% FTE, not a theoretical 70% balance
against 100%. Used effort is assigned effort, not work performed or a timesheet
total.

When allocation varies across the selected months or includes a zero month,
the Allocation line also shows ``(Maximum Monthly Allocation 60%)``, using
the maximum for that period.

Annual figures average the selected months. Percentages of a code allocation
use FTE-month totals, not the mean of monthly ratios.
Overcommitted months remain visible even when annual averages look acceptable.
Monthly views show each compacted period's subscription directly.

Negative availability remains visible. Omitted months in an explicit FTE year are zero.
Missing availability for unused catalog years is ``Unknown`` rather than
assumed to be zero or 100%. Unresolved staff ranges/duration mark demand
incomplete, retain known subtotals and leave availability unknown. Explicit
year overrides retain known results where they replace an unresolved range.

Person summaries include all that person's codes. Configured capacity is the
sum of coded allocations when only codes exist, or the uncoded allocation when
no codes exist. An uncoded fallback overlaps the coded pool: when both exist,
use the larger pool, never their sum. Capacity remains unknown when any pool's
availability is unknown. Total subscribed effort across all selections is
subtracted from that configured capacity. No unlisted effort is assumed to be
available. Display filters do not change this calculation.

Complete and closed tasks are excluded. By default, unfunded tasks do not
consume subscribed effort. ``--include-unfunded`` shows them separately as
proposed demand and displays remaining capacity if funded, without changing
committed subscription. A shared parent budget counts once; it is committed
when any current part is funded and proposed when all current parts are
unfunded. Covered funding adds attribution without consuming staff again.
Monetary labor amounts do not identify people and cannot contribute staff
subscription. Demand from other plans is outside the report's scope: use a
complete/composite plan containing the work to include.

``--staff ID`` and ``--code CODE`` select exact IDs, ignoring case and surrounding
spaces; repeat either option to show multiple values. ``--code uncoded`` selects
uncoded entries. Filters apply after calculations; a person's totals continue
to include all codes when some rows are hidden. These report-specific flags
replace the ordinary record fields/``--only`` interface for this computed view.
Configured list element selections do not control the staff report.

CSV output always has one staff/code/month per row, including zero and unknown
availability, independent of ``--monthly``/``--details``. It uses plain decimal
percentage values without ANSI styling or percentage signs. ``scope`` is
``this_plan``. ``allocated_fte``, ``subscription_fte`` and ``availability_fte``
correspond to the text report's code fields. ``code_subscription_percent`` is
the share of code allocation, not another FTE value. ``demand_complete`` marks
whether subscription is complete or only a known subtotal. Empty availability
and ratio fields mean unknown, or not applicable for a zero allocation.
``person_allocated_fte``, ``person_subscription_fte`` and
``person_availability_fte`` use configured person capacity as defined above.
Conditional columns use ``availability_if_funded_fte`` and
``person_availability_if_funded_fte``. Person totals are repeated
on code rows for context and must not be summed across those rows. Proposed
columns are populated only with ``--include-unfunded``. Task IDs identify direct
budget owners; coverage task IDs are attribution rather than additional demand.

Historical task funding
-----------------------

``complete`` and ``closed`` tasks remain visible as progress context but are
excluded from current funding totals, Actual Value, Potential Value, task cost,
staff-demand checks and available coverage budgets. Output marks their funding
as ``Excluded (complete)`` or ``Excluded (closed)``. Authored funding remains in
the original source and is not removed or rewritten. Word imports cannot
reconstruct funding that was excluded from the document.

Completed tasks bypass funding resolution and validation entirely: obsolete
amounts, staff/rate references, coverage and funding ranges do not block loading
or exports, and rates are not loaded solely for completed work. Normal task
identity, relationships, prose and timing validation still apply. ``completed``
without an explicit status retains its usual implied ``complete`` status.
Closed tasks retain funding validation, including staff/rate and coverage
references, but their amounts and coverage shares do not consume current funds.

A multipart parent's authoritative budget counts once when any non-historical
part remains. Historical parts do not take inferred shares or determine the
budget's activity/B&R attribution. The budget is excluded when all parts are
complete or closed. Surviving parts still validate the parent budget, including
when the authored parent status is complete or closed. Shared-owner references
use the surviving parent's budget regardless of which part alias is referenced.
Coverage from a current task to an owner whose tasks are all complete or closed
is an unavailable-source error.

Annual and duration modes
-------------------------

``labor_costing: annual`` is the default. Every staff allocation is an annual
amount independent of task duration, including tasks without planning dates.
Only explicitly listed funding years contribute; no years are filled in.

Opt into schedule-based costing with::

   labor_costing: duration

In this mode only the task's scheduled months in that fiscal year contribute
their effective monthly costs. ``start`` and ``expected`` (or inclusive
``end``) must be explicitly supplied. Month counting follows normal task
scheduling and includes the start month. For example::

   start: M1Q4FY27
   expected: 6
   funding:
     labor:
       FY27:
         - id: STAFF_A
           percent: 10%
       FY28:
         - id: STAFF_A
           percent: 10%

There are three task months in each fiscal year. With the rate and FTE above,
the staff cost is $3K in FY27 and $3K in FY28. Unlisted years still contribute
zero. A staff allocation in a year with no scheduled task months is an error.
``ongoing`` tasks cannot use staff allocations in duration mode because their
schedule is itself derived from funding. They remain supported in annual mode.
Explicit monetary amounts, including labor amounts, are never prorated.

Totals, authoring and exports
-----------------------------

Resolved annual funding feeds existing task/activity/project/B&R totals,
actual/potential values, filtered totals and ongoing-task scheduling. Parent
budgets remain authoritative and count once; part overrides retain their
existing behavior. In duration mode an authoritative parent budget uses the
parent's own explicit timing. Funding inheritance replaces the entire
specification, without merging individual types or staff assignments.

``list tasks FILE funding`` shows annual totals, type amounts and staff
calculations. The complete terminal document also shows the breakdown.
Existing document, SVG, PowerPoint and Gantt outputs consume the resolved
annual amounts. Funding detail groups consecutive months with identical FTE
and rates, preserving concise output for constant profiles. Word imports recover coarse funding from those totals; they
cannot reconstruct type allocations, staff, percentages or rates from totals.

YAML/Python editing retains the original typed funding and staff references.
Composite operations retain the authored structure. Merge and ``split --funding
parts`` preserve type/staff detail. ``split --funding equal`` rejects typed
parent budgets rather than converting named allocations into cash amounts;
coarse budgets retain equal splitting. As before, preserving part budgets when
splitting can increase total funding.

The complete fictional rates example is ``planner/examples/rates.yaml``.

Task Cost Output
----------------

``cost`` is a derived task field for terminal list output. It is not valid in
authored task YAML/Python or export selections. Select it explicitly::

   planner list tasks plan.yaml cost
   planner list plan.yaml cost

It also appears in the default task/full-document views and ``list-detail``.
Existing configured layouts retain their selections; enable the field there::

   list:
     elements:
       tasks:
         id: true
         label: true
         cost: true

An ordered layout may use ``- cost: true`` (with optional sibling
``heading: false``). Like structured funding, cost cannot be placed inside an
inline ``line`` instruction. ``cost: false`` omits it.

The field shows amounts **per fiscal year**, grouped by funding type. Labor
allocations also identify the staff member and selected funding code. Covered
allocations show their attributed amount and share, without adding those dollars
to the receiving task's direct funding. No amount is summed across fiscal years.
Identical amounts with matching staff, source, code and share are compressed into
a year range. When one exact amount occurs in a majority of years, exceptions
appear underneath it::

   Cost:
     Labor:
       FY27–FY31: $16K/year
         STAFF_A
         50% parent share
         DEMO_CORE_0000
         FY29: $20K instead
     Contract:
       FY27: $500K
       FY28: $600K

Gaps are listed explicitly rather than implying intervening years. Grouping
compares exact amounts before rounding. Different staff, codes, sources or
shares remain separate. Coverage without a percentage displays ``Share
unspecified`` rather than inventing a dollar attribution or displaying zero.
Each annotation (staff ID, source/share explanation, and code) appears on its
own line, indented beneath the fiscal-year amount, without brackets or commas.
Amounts use the standard funding color; staff/source IDs and codes use the ID
color. Share/source explanations and remainders use ``terminal.colors.funding_share``
(default canary ``#FFFF99``, matching the description default). Headings and fiscal years use the field-heading color. Incomplete amounts
use the warning color, and closed/unfunded task colors take precedence. Plain
output and normal terminal color configuration remain supported.

Displayed costs use whole thousands, rounded to the nearest integer with halves
rounded up: ``$130.8572K`` displays as ``$131K`` and ``$1.234567M`` as ``$1235K``.
Calculations and stored funding retain their precision. All monetary funding
outputs use the same whole-K formatting. Staff costs
use the selected annual/duration costing mode exactly once; the display does
not apply another duration adjustment.

Coarse annual funding is shown as ``Unclassified`` without inferring a split
from task ``type`` metadata. Explicit zero amounts and empty staff lists for a
specified year give known zero costs. Omitted funding and explicitly selected
types with no annual amounts produce incomplete cost estimates. Unspecified
types are omitted, and omitted fiscal years retain their zero-funding meaning.

List/list-detail loading can retain staff calculations whose rates file is
unconfigured/unreadable or whose required duration timing is absent. Known
components remain visible::

   Cost:
     Labor:
       FY27: Incomplete — rates file unavailable
     Contract:
       FY27: $500K

An unresolved staff amount also marks the affected annual funding total,
current-year actual/potential value, and task funding total incomplete. It is
never counted as zero or compared with planned value as if complete. Other
years and unrelated funded sources retain their normal values. For an ongoing
task with unresolved annual amounts, timing is shown as unknown rather than
constructing a partial schedule from known years.

Malformed amounts/percentages, invalid rates catalogs, unknown staff/codes and
unsupported ongoing duration costing remain validation errors. The ``validate``,
export and authoring paths remain strict. An export also refuses a partially
resolved Python plan before replacing output. A valid task with no funding may
still be exported normally; its list cost is incomplete because no estimate
was supplied, whereas assigned funding remains zero under existing rules.

Multipart task rows with explicit parent coverage show the declared share.
Children without an allocation split the remaining directly funded parent
components automatically, even when they omit ``funding`` entirely. Parent summaries show the full
parent-owned annual amounts once and retain separate independent part budgets.
Filtering a shared part does not allocate or shrink its parent's financial
budget. Existing project funding/status rules remain in force.

Funding display precision
--------------------------

All displayed monetary funding values round to the nearest thousand dollars,
with halves rounded up, and omit decimal places. This applies to task funding
and costs, annual totals and activity/B&R/unfunded subtotals, planned/actual/
potential budgets, staff rate/allocation details, coverage amounts and known
incomplete subtotals. Terminal list/detail/summary/schedule/show views and
Word/PDF, SVG and PowerPoint representations use the same rule. Examples:
``$130.8572K`` becomes ``$131K``; ``$0.5K`` becomes ``$1K``; ``$1.234567M``
becomes ``$1235K``. Numeric export tables retain their K-unit headers and integer
formatting, for example ``1,235``.

Round after computing each final displayed amount. Two ``$0.6K`` allocations
each display as ``$1K``, but their exact ``$1.2K`` total also displays as ``$1K``.
A task's multi-year funding total, each annual total and each subtotal are
computed independently from exact amounts. Financial comparisons use exact
values even when their rounded displays match. Percentages and FTE values keep
their existing precision: they are not monetary amounts.

Source plans/rates, resolved annual values, ``funding_totals``, staff allocations
and coverage records retain their underlying precision. No whole-thousand
rounding participates in computation; existing per-staff/year cent rounding
remains in force. YAML/Python source and composite/merge/split data retain authored
amounts rather than adopting document display rounding.

Funding across the plan's fiscal range
--------------------------------------

Within any funding type, ``fiscal_range`` supplies the same entry for every
fiscal year declared by the plan::

   fiscal_range_begin: FY27
   fiscal_range_end: FY29
   execution:
     tasks:
       - id: SUPPORT
         label: Project support
         description: Support the project throughout the reporting period.
         category: development
         status: ongoing
         funding:
           labor:
             fiscal_range:
               - id: STAFF_A
                 percent: 20
           contract:
             fiscal_range: 100K
             FY28: 150K

This applies the staff allocation to FY27, FY28 and FY29, and assigns contract
funding of $100K, $150K and $100K respectively. Amounts are **per year**, not a
total divided across the range. An explicit fiscal-year entry replaces the
default for that type/year, regardless of YAML key order. Other types remain
independent. Use ``FY28: []`` to clear labor allocations for a year, or an explicit
zero amount to provide zero funding. Explicit years outside the declared range
retain their existing meaning and are not clipped.

The shorthand uses ``fiscal_range_begin``/``fiscal_range_end`` when present, or
the exact years in a non-empty ``fiscal_years`` list. It requires that plan
context; standalone task lists must continue using explicit years. Loading the
plan after extending its fiscal range automatically extends these allocations.
Source YAML retains the shorthand, while output and cost/funding totals use the
resolved fiscal-year entries. Activity/task code inheritance, staff FTE and
multipart parent-budget rules apply normally.

Annual labor costing remains independent of task duration. Duration costing
keeps its existing explicit-timing and year-overlap requirements: every effective
staff-funded year must overlap the task, including years supplied by
``fiscal_range``. Use explicit-year overrides when necessary. Scheduled tasks
with funding outside their dates retain the usual funding warnings.


Activity funding codes
----------------------

An activity can provide an optional ``code`` matching a staff code in the rates
catalog. Labor entries without their own code inherit the task's code, which
otherwise defaults to its activity's code::

   execution:
     activities:
       - id: DESIGN
         label: Design
         description: Develop the design.
         code: DEMO_CORE_0000
     tasks:
       - id: DESIGN_REVIEW
         label: Review design
         category: development
         status: planning
         description: Review the proposed design.
         activity: DESIGN
         funding:
           labor:
             FY27:
               - id: STAFF_A
                 percent: 10%

The example selects ``STAFF_A`` with code ``DEMO_CORE_0000``. A task-level
``code: DEMO_OTHR_0000`` changes the default for all its labor entries;
an entry-level ``code`` overrides either default for that individual allocation.
Codes are trimmed, case-sensitive strings. A task's explicit ``code: null`` or
``code: ""`` clears the activity default, restoring the existing uncoded or
unique-code lookup. A supplied labor-entry code must remain non-empty.
Activities without codes remain valid, and unused activity codes do not require
a rates-file match.

Multipart parts inherit a parent's explicit task code unless they override or
clear it; otherwise their effective activity supplies the default. Authoritative
parent funding uses the parent's own activity/code, independently of part
changes. Annual and duration labor costing use the same code selection rules.
Inherited codes are calculated during loading; source files retain their authored
fields. ``list tasks FILE code`` exposes each task's effective default, while
funding detail shows the actual selected code for every staff allocation.

Funding covered by another task
--------------------------------

A task can declare that another task's budget includes an entire funding type
or an individual staff allocation. Put ``covered_by`` in the position otherwise
occupied by an annual amount or a labor allocation::

   funding:
     contract:
       fiscal_range:
         covered_by: SHARED_SERVICES
     labor:
       fiscal_range:
         - id: STAFF_B
           covered_by: SHARED_STAFF

These entries require no duplicate amount or staff-time percentage. The source
task must have directly funded entries for the same type and every corresponding
year. An individual staff reference must match one source allocation. Optional
``code`` selects a particular code on the **source task**; when omitted, that
staff ID must be unambiguous among the source's allocations for the year. The
receiving task's activity/task code does not select a coverage source allocation.
Direct staff entries continue to inherit those codes normally.

Use exact task IDs, including expanded IDs for multipart parts. A parent ID is
also accepted when that parent owns an authoritative budget. References resolve
across the same plan and its includes, independently of declaration order.
Coarse funding has no type/staff breakdown, so a coverage source must use typed
funding. A directly funded component on a task can serve as a source even if
other components on that task are covered elsewhere. Source funding of an
explicit zero remains zero; coverage does not create money.

Optional attributed shares
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``share`` optionally records the percentage of a source allocation attributed
to the covered task::

   funding:
     labor:
       FY27:
         - id: STAFF_B
           covered_by: SHARED_STAFF
           share: 25%
     contract:
       FY27:
         covered_by: SHARED_SERVICES
         share: 25

If the source funds the staff member at $24K for FY27, a 25% share displays $6K
as included in that source budget. This is 25% of the **source task's staff
allocation**, after its rate, available FTE, task percentage and costing mode
have been applied. It is not 25% of full-time staff cost. The receiving task's
duration does not prorate the amount again. For whole-type coverage, the share
selects the same percentage of that type's direct funding for the year.

Shares accept numeric percentage points or percentage strings from 0 through
100, or the text ``remainder`` described below. External coverage without
``share`` has an unspecified dollar portion; this is valid coverage rather
than missing funding. A single unquantified child-to-parent entry instead
receives an implicit remainder. Use ``percent`` only for
direct staff-time allocations; coverage uses ``share``. A coverage entry cannot
also contain its own amount or direct staff ``percent``.

Specified shares of each source component/year cannot exceed 100% across all
receiving tasks. Whole-labor shares and staff-specific shares also count together
against each affected staff allocation. References through different parts of
one authoritative parent budget use the same share pool. External references
without a share make no quantitative claim.

Remainder shares
~~~~~~~~~~~~~~~~~

Use ``share: remainder`` to attribute what remains after numeric shares of the
same source allocation are counted::

   funding:
     labor:
       fiscal_range:
         - id: STAFF_B
           covered_by: SHARED_STAFF
           share: remainder
     contract:
       FY27:
         covered_by: SHARED_SERVICES
         share: remainder

Within a funded multipart child, ``{id: STAFF_B, share: remainder}`` can omit
``covered_by`` to select its parent. Alternatively, explicitly reference the
parent and omit ``share``::

   # Within a child of PARENT_SUPPORT:
   funding:
     labor:
       fiscal_range:
         - id: STAFF_B
           covered_by: PARENT_SUPPORT

If this is the only unquantified child-to-parent claim for that allocation, it
receives an **implicit remainder**. Other numeric child and external shares
consume their portions first. For example, 20% and 30% leave 50%; with no numeric
claims, the remainder is 100%. An already fully assigned allocation leaves a
valid 0% remainder. Children without an allocation divide the remaining
parent funding automatically as described below. External coverage without a
share remains unquantified and consumes no percentage.

Resolution is independent of task order and uses the complete plan before list
filters. Each source owner, funding type, fiscal year and staff/code allocation
has its own pool. ``range``, ``fiscal_range`` and explicit-year overrides select
years as usual. The remainder uses the computed source allocation without a
second adjustment for receiving-task duration. Financial ownership and totals
remain unchanged; source YAML retains the authored spelling or omitted share.

Only one authored remainder request is allowed for an allocation, whether
``share: remainder`` or an explicit unquantified child-to-parent reference.
Multiple unquantified child-to-parent claims are an ambiguity error:
specify numeric shares for the others and leave one remainder. Numeric claims
above 100% remain invalid. Whole-type numeric shares consume the same percentage
of each staff allocation, so a staff remainder deducts those as well as matching
staff-specific numeric shares. A whole-type remainder cannot be mixed with
staff-specific numeric shares or remainders; use individual staff remainders
instead. Distinct staff/code allocations may each have their own remainder.

Cost and funding detail make the inference visible::

   Cost:
     Labor:
       FY27: $12K
         STAFF_A
         implicit remainder (50%) parent share
         DEMO_CORE_0000

Explicit entries display ``remainder (50%)`` instead. If required source rates
or task dates are missing in list mode, the amount remains incomplete; unknown
years do not acquire fabricated percentages. Strict validation and exports
retain their existing requirements.

Automatic division among children
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A multipart child does not need a ``funding`` entry to receive a portion of its
parent's budget. For each directly funded parent type/year/staff/code allocation,
planner deducts numeric child and external coverage shares, then divides the
remainder equally among children without an explicit allocation for that
component. A single eligible child receives the entire remainder::

   tasks:
     - id: SUPPORT
       label: Shared support
       description: Provide common project support.
       category: development
       status: planning
       funding:
         contract:
           FY27: 100K
       parts:
         - id: FIXED
           funding:
             contract:
               FY27:
                 share: 20
         - id: FIRST
         - id: SECOND

``SUPPORT_FIXED`` receives the declared 20% ($20K). ``SUPPORT_FIRST`` and
``SUPPORT_SECOND`` each receive half the remaining 80% ($40K). Their cost output
shows ``FY27: $40K`` with ``implicit remainder (40%) parent share`` on an
indented line beneath it. The same rule applies independently to every
staff/code allocation and fiscal year.

An explicit ``share: remainder`` or sole unquantified child-to-parent reference
has priority and consumes the remainder before automatic division; other eligible
children then receive zero for that component. Multiple authored remainder
requests remain errors. A numeric whole-type share consumes that percentage of
each affected staff allocation. Explicit child amounts, staff allocations,
coverage references and explicit zero/empty annual staff lists exclude that
child for the corresponding component/year. Direct child amounts do not become
parent coverage claims: use ``share`` when deducting a portion of the parent.
Missing years/types/staff remain eligible; omitted, null or empty child funding
contains no allocations and is eligible. Task type labels do not select staff.

Inference uses all siblings and external claims before filtering. Adding or
removing an eligible sibling changes the automatic split. Child timing and
status do not choose a different split; annual/duration costing applies to the
parent's source allocation once. Closed/unfunded colors and source availability
still apply. Coarse parent amounts split as ``Unclassified`` without inventing
types. Covered parent components are not redistributed through coverage chains.
Missing rates remain incomplete with available staff/code identities retained;
unknown task-date ranges do not invent fiscal years or percentages.

Automatic attributions appear in cost and funding details, including selected
export funding fields. Financial table columns retain authoritative amounts;
automatic inference does not append standalone notes after those tables.

Automatic attribution is read-only. It does not insert funding into YAML,
alter schedules, change direct amounts or add dollars to financial totals.
Parent summaries retain the full authoritative budget once. Calculations retain
precision and cost output rounds only for display. Non-terminating automatic
percentages display approximately (for example ``≈33.33%``); a deterministic
sub-cent residual preserves the exact total of the attributed amounts.

Totals and output
~~~~~~~~~~~~~~~~~~

The source task keeps its entire budget. Covered entries add zero **direct**
funding to their receiving task; included shares are informational and are never
added again to project totals, annual totals, actual/potential values or direct
cost totals.
A task can mix direct and covered staff in a labor list, and directly fund other
types. Cost output shows the covered amount per year, with attribution::

   Cost:
     Labor:
       FY27: $6K
         STAFF_B
         25% share of SHARED_STAFF

External coverage without a share displays ``Share unspecified``. A covered-only row
omits the zero direct-funding total. These display amounts never enter budget
totals a second time.

Funding details and selected exports display the relationships. Word task tables
also include coverage notes, including when fiscal-year columns are the only
funding columns. Filtered task totals count only the selected tasks' directly
owned budgets; selecting a covered task does not pull its source task's money
into the selection. Multipart parent budgets and their shares count once.

Ongoing covered tasks use the years in which their sources provide positive,
funded allocations for scheduling. An unfunded source remains explicitly marked
``UNFUNDED source`` on the receiving task; it does not make that task appear
funded. Unavailable source rates in list mode produce incomplete coverage;
validation and authoring retain their normal strict rates requirements.

Validation and authoring
~~~~~~~~~~~~~~~~~~~~~~~~~

Missing sources/types/years/staff, ambiguous staff codes, self-references,
coverage cycles, duplicate direct/covered components and coverage chains are
errors. A referenced component must be directly funded. Fiscal-year overrides
replace ``fiscal_range`` coverage defaults in the usual way.

Rename updates ``covered_by`` references. Remove blocks incoming references by
default; ``--remove-references`` explicitly removes affected coverage entries.
Merge/split rewrite exact task references when the new owner remains unambiguous;
splitting a referenced parent into multiple owners requires explicit reference
updates first. Edit/add validate complete-plan coverage and share limits before
saving. References and shorthand remain in authored YAML.

Word import recovers coarse annual funding. Coverage shown in selected funding
fields is retained in review notes and reported for manual reconstruction;
it is not automatically recreated from the displayed attributed amounts.
See ``planner/examples/funding-coverage.yaml`` for a complete fictional example
using the packaged rates file.

Funding across a task's date range
-----------------------------------

Use ``range`` under a funding type to repeat an entry over every fiscal year
touched by the task's inclusive dates::

   execution:
     tasks:
       - id: DESIGN_REVIEW
         label: Design review
         description: Review the design over two fiscal years.
         category: development
         status: planning
         start: M1Q4FY27
         expected: 6
         funding:
           labor:
             range:
               - id: STAFF_B
                 percent: 8
           contract:
             range: 100K
             FY28: 150K

``end: M3Q1FY28`` can replace ``expected: 6`` in this example. Both forms select
FY27 and FY28. ``contract`` receives $100K in FY27 and $150K in FY28; explicit
year entries override the default for the matching type/year regardless of key
order. Explicit years outside the task span retain their normal meaning and
schedule warnings. A ``range`` amount is **per selected fiscal year**, not a
total divided across years or months. Zero amounts and empty labor lists remain
valid when the task span is known.

``range`` uses task dates independently of the plan's fiscal-year declarations.
It works in standalone task lists without plan-level fiscal metadata and may
include years outside the plan range. Annual overviews still display the plan's
selected fiscal years; extend the plan range when those additional years should
appear there. Within a funding type, choose either ``range`` or ``fiscal_range``;
supplying both is an error, even if explicit year entries are also present.
Different funding types can use different defaults.

Year selection does not change costing. Annual labor costing applies the full
annual allocation in each selected year. Duration labor costing uses the task's
actual overlapping months. In the six-month example, duration costing uses three
months in FY27 and three in FY28. Contract/equipment/services/nonlabor amounts
retain their annual amounts without automatic month proration.

Coverage and multipart tasks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whole-type coverage and individual staff coverage also accept ``range``::

   funding:
     labor:
       range:
         - id: STAFF_B
           covered_by: SHARED_SUPPORT
           share: 25%
     contract:
       range:
         covered_by: SHARED_SUPPORT

Each reference is checked for every year touched by the receiving task. Shares
use the source allocation's computed cost, independently of the receiving task's
duration. Covered dollars remain owned by their source and count once.

Parts resolve inherited ``range`` entries using their own effective start and
end/duration. An authoritative parent budget resolves its range using the
parent's own authored dates and still counts once. Parent budgets require their
own sufficient timing even when all parts have complete dates. Source YAML
retains ``range`` through normal loading, includes, Python plans and merge/split.

Missing or unsupported timing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``range`` requires an explicitly authored ``start`` (or its existing alias)
paired with ``end`` or ``expected``. Completion-marker fallback dates and
synthetic one-month durations do not define a funding range. Planning, closed
and complete tasks can use ``range`` when they provide the explicit timing.
Invalid dates, inconsistent end/duration and endpoints beyond FY99 remain errors.

Ongoing tasks cannot use ``range``, including for covered or zero allocations,
because ongoing timing derives from funding. Use explicit years or
``fiscal_range`` for those tasks.

Strict validation, authoring and exports reject missing range timing. List mode
can retain the unresolved range as incomplete, preserving known explicit-year
amounts and their overrides. Costs, task funding totals and applicable annual
actual/potential/totals remain visibly incomplete rather than treating the
unresolved default as zero. Annual totals conservatively retain uncertainty for
years without an explicit override until the task span is known. Coverage with
an unknown range is marked unresolved, and its per-year checks/share limits
finish once timing is supplied. Invalid entries, missing reference targets and
conflicting defaults remain errors. Direct exporters also reject these incomplete
plans before replacing an existing output file.

Implicit shares of a multipart parent's funding
------------------------------------------------

A child part can omit ``covered_by`` when it declares a ``share``. The source is
then its funded multipart parent, for the same type, fiscal year and staff
allocation::

   funding:
     labor:
       fiscal_range:
         - id: STAFF_A
           code: DEMO_CORE_0000
           percent: 20
   parts:
     - id: REPORT
       label: Report preparation
       description: Prepare the project report.
       status: planning
       start: M1Q3FY27
       expected: 3
       funding:
         labor:
           range:
             - id: STAFF_A
               share: 20%

The child selects the parent's ``STAFF_A`` allocation for FY27 and attributes
20% of that allocation's cost. For a parent allocation costing $24K that year,
the child's computed included amount is $4.8K (displayed as $5K).
The child's duration selects years through ``range``; it does not prorate the
source amount again. Its own activity code does not override the source code.
For whole-type attribution, use ``contract: {FY27: {share: 20}}`` within the
child's funding mapping.

``share`` is the attribution percentage; ``percent`` remains a direct staff-time
percentage. They cannot appear together in one coverage entry. A share-only
entry requires a child whose parent defines funding. Without that context,
specify an explicit ``covered_by`` task. Empty mappings do not declare coverage.

An explicit ``covered_by: PARENT_ID`` is also supported on the child. Omitting
its share requests an implicit remainder when it is the sole unquantified
child-to-parent claim for the allocation. True self-references, sibling
aliases to the same owned budget, and a parent referencing its own child remain
invalid. The parent's referenced component must be directly funded, as with
other coverage. Child shares and external shares of the same source allocation
count together toward the existing 100% per-component/year limit.

An explicit child-to-parent coverage entry makes cost output show the child's
declared funding/coverage portions, while the parent summary continues showing
the authoritative parent budget. Child monetary overrides remain subject to
normal parent-authoritative financial totals; attribution does not add dollars.
Without explicit coverage, unallocated children automatically divide the
remaining directly funded parent components. Financial totals count the parent's entire
budget once whenever a part is included, including filtered views. Parent renames preserve implicit
binding without adding a ``covered_by`` field to source YAML. Splitting away a
referenced parent requires explicit funding/reference decisions first.
