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.
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.
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.
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.