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. Initially the same rate
applies to every fiscal year. 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.

Each allocation currently has one FTE percentage, rather than a monthly profile.
An annual average can represent a varying monthly allocation for annual costing;
it does not reproduce the month's individual costs under duration costing.

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.

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

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

Calculation uses decimal arithmetic. Each staff/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.

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 the annual staff cost is multiplied by the task's scheduled months
in that fiscal year divided by twelve. ``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. 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 sums resolved annual amounts by each specified funding type, then
shows a task total. Displayed costs use whole thousands, rounded to the nearest
integer with halves rounded up: ``$130.8572K`` displays as ``$131K``. Each type
subtotal, overall total and known subtotal is rounded only after its exact sum
is calculated. Model values and existing funding outputs retain their precision.
For example, two ``$0.6K`` components each display as ``$1K``, while their exact
``$1.2K`` total also displays as ``$1K``. Inputs in millions are converted to K
before display rounding: ``$1.234567M`` displays as ``$1235K``. Staff costs use
the selected annual/duration costing mode exactly once; cost does not apply
another duration adjustment::

   Cost:
     Labor: $12K
     Contract: $500K
     Total: $512K

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: Incomplete — rates file unavailable
     Contract: $500K
     Total: Incomplete
     Known subtotal: $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 use an authoritative parent budget when present and label
it ``Shared parent budget``. Parent summaries count that source once, retain
its type breakdown and combine independent part budgets when there is no
parent budget. Filtering a shared part does not allocate or shrink its parent's
budget. Existing project funding/status rules remain in force.

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. Without ``share``, coverage is declared but its dollar portion is unspecified;
this is valid coverage, rather than missing funding. 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. References without a
share make no quantitative claim and are not assumed to consume 100%.

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 costs.
A task can mix direct and covered staff in a labor list, and directly fund other
types. Cost output displays coverage by type and calls the monetary total
``Direct funding total`` when coverage is present. A covered staff entry may
look like::

   Labor: FY27: Covered by SHARED_STAFF — STAFF_B; share 25% ($6K included)
   Direct funding total: $0K

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.
