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.

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.