Metadata-Version: 2.4
Name: tuxfan-planner
Version: 0.2.62
Summary: Simple text-driven project planning system
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-pptx>=1.0
Requires-Dist: ruamel.yaml>=0.18
Requires-Dist: docx2pdf>=0.1.8; sys_platform == "darwin" or sys_platform == "win32"
Provides-Extra: format
Requires-Dist: black>=24.0; extra == "format"
Provides-Extra: docs
Requires-Dist: Sphinx>=7.2; extra == "docs"
Requires-Dist: furo; extra == "docs"

# Project Planner

A small planning system that lets you define project plans and tasks in YAML or
Python. Validate plans, inspect funding and dependencies, and export documents,
diagrams, presentation slides, and fiscal-month Gantt charts.

## Why tuxfan-planner?

- **Keep plans easy to review.** Author readable YAML or Python files, track
  changes in Git, and review plan updates alongside your code.
- **Catch planning problems early.** Validate task references and dependency
  cycles, and get warnings about late or unknown milestone and deliverable
  timing, with source locations that help you find the cause.
- **Plan around fiscal years.** Track funding by fiscal year, schedule ongoing
  work across funded years, and total multipart budgets without double counting.
- **Connect tasks to outcomes.** Link work to execution narratives, deliverables,
  and milestones, and keep GitLab work item and merge request references with
  the tasks they support.
- **Find the view you need.** Filter tasks, activities, milestones, deliverables,
  work items, and risks without editing the underlying plan or losing full-plan
  readiness information.
- **Organize larger plans.** Reuse YAML fragments with includes, inherit shared
  task metadata, and merge or split multipart tasks as the plan evolves.
- **Publish from one source.** Generate Word documents, SVG diagrams, editable
  PowerPoint plan slides and Gantt charts, and PDFs through Microsoft Word.
  Apply your own PowerPoint presentation or template for consistent branding.

Repository: `git@re-git.lanl.gov:tpp/planner.git`

Release notes: [NEWS.md](NEWS.md).

## Installation

Use **Python 3.11 or newer**.

### Install from PyPI

If you only want to use the planner, create and activate a virtual environment
and install the published package. No repository checkout is needed:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install tuxfan-planner
planner --help
```

This installs the planner and its required Python dependencies. Activate `.venv`
again when starting a new shell. To get started with your own plan, follow
[Your first plan](#your-first-plan) below.

### Install from source

For development or to use a local checkout, run these commands from the
repository root:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
planner --help
```

The editable installation uses the source in this checkout. CMake installation
and development setup are described in
[DEVELOPER.md](DEVELOPER.md).

## Quick start

From the repository root, validate the fictional example plan, list its tasks,
and export a Word document:

```bash
planner validate data/tasks.yaml
planner list data/tasks.yaml
planner export data/tasks.yaml /tmp/plan.docx --config planner/examples/config.yaml
```

The output file is written to `/tmp/plan.docx`. For other outputs, see
[Exporting](#exporting).

[`data/tasks.yaml`](data/tasks.yaml) is the canonical fictional jet-airplane
development fixture. [`data/composite.yaml`](data/composite.yaml) includes the
same plan. Their values are invented; use them instead of private plans for
future development. See the [fixture guide](data/README.md) for coverage and
examples.

## Contents

- [Why tuxfan-planner?](#why-tuxfan-planner)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Basic commands](#basic-commands)
- [Your first plan](#your-first-plan)
- [Plan structure and fields](#plan-structure-and-fields)
- [Viewing and filtering](#viewing-and-filtering)
- [Importing Word plans](#importing-word-plans)
- [Exporting](#exporting)
- [Advanced plan authoring](#advanced-plan-authoring)
- [Configuration and optional tools](#configuration-and-optional-tools)
- [Troubleshooting and further documentation](#troubleshooting-and-further-documentation)

## Basic commands

| Command | Purpose |
| --- | --- |
| `validate` | Check a plan and report validation statistics. |
| `list` | Show the full terminal planning document. |
| `list KIND` | Show a selected top-level plan element; compatibility object views remain available. |
| `list-detail` | Show full task details. |
| `show` | Print unique values used by one field in a plan. |
| `avail` | Print predefined schema options for one field, without a plan. |
| `fields` | Print a copyable YAML template for a mapping type. |
| `summary` | Show counts by activity and milestone, plus funding totals. |
| `schedule` | Show tasks in dependency order and their readiness. |
| `export` | Write a Word (`.docx`), SVG (`.svg`), PDF (`.pdf`), or PowerPoint (`.pptx`) plan. |
| `import` | Import a planner-style Word document into a YAML draft. |
| `export-gantt` | Write an SVG or PowerPoint (`.pptx`) Gantt chart. |
| `composite` | Expand YAML includes into a standalone file. |
| `merge` | Merge standalone YAML tasks into a multipart task. |
| `split` | Split a multipart YAML task into standalone tasks. |
| `format` | Format a YAML or Python plan with an optional external formatter. |
| `spell-check` | Review prose interactively with Aspell. |
| `completion` | Generate a shell completion script. |

Run `planner COMMAND --help` (or `planner help COMMAND`) for arguments and examples, or see the
[CLI reference](docs/cli.rst).

The legacy `tuxfan-planner` command remains available as an alias.
Help also follows command/topic paths:

```bash
planner help                  # top-level help
planner help fields           # same as planner fields --help
planner fields help task      # fields help; task is a validated mapping type
planner help list tasks        # same as planner list tasks --help
planner list help tasks
planner list tasks help
```

`help` may appear once along a command/topic path. Positional choices such as
`fields task`, `config init`, and `completion bash` show their parent command's
help. Unknown topics report an error with the nearest relevant help. Help uses
the same colors and pager as `--help`, without loading plans or initializing
configuration. Bash, zsh, and fish complete help topics. Use `./help` or
`list -- help` to pass a literal filename named `help`; option values named
`help` remain ordinary values. Help aliases do not apply after filenames or
other unrestricted arguments.

Run `planner --help` to see the current package version and the current values
of all planner environment variables alongside the command help.

## Your first plan

Save this as `tasks.yaml`. It defines one pending task with a two-month duration:

```yaml
project: Aircraft Development
execution:
  tasks:
    - id: DraftDesign
      category: development
      priority: capability
      label: Draft aircraft design
      description: Produce the initial airframe design.
      start: M1Q1FY27
      expected: 2
      status: pending
      risk:
        - type: schedule
          level: low
          mitigation: Review progress weekly.
```

```bash
planner validate tasks.yaml
planner list tasks.yaml
```

Export configuration follows the same nesting: `export.elements.execution`
contains activities, tasks, milestones, and deliverables;
`export.elements.resourcing` contains project dependencies, stakeholders, users,
risks, and the generated task table. Their declaration order supplies the default
export placement. `export.structure` optionally overrides placement. Existing
flat selections remain accepted; defining the same field in both locations is
an error. `planner fields config` prints the canonical nested configuration.

`execution` contains `description`, `activities`, `tasks`, `milestones`, and
`deliverables`. `resourcing` contains project `dependencies`, `stakeholders`,
`users`, and `risks`. Fiscal coverage and project budgets stay at the top level.
Existing flat plans remain readable; defining the same field in both locations
is an error. `planner fields plan` prints the nested starter. To migrate to a
separate standalone file, run `planner composite old.yaml nested.yaml --nested`;
this expands includes. Included list fragments need no wrapper when their
include directives move under the appropriate container.

`id` identifies the task for dependency references; `label` is its display name.
`activity` links tasks to the corresponding entry in `execution.activities`. Tasks without a link appear under Unassigned. The top-level `project` names the overall plan. `start` is a
fiscal period, and `expected` counts months including the start month. This task
runs from October through November 2026. `priority`, `status`, and `risk` describe
the planned work. Ongoing and completed tasks have exceptions to the planning
field requirements, explained below.

### Fiscal period values

`start` and `completed` must use `M{month}Q{quarter}FY{year}`:

- `month` is `1` to `3` within the quarter
- `quarter` is `1` to `4`
- `year` is a 2-digit fiscal year, for example `FY26`

Fiscal years begin on October 1:

- `Q1` = October through December
- `Q2` = January through March
- `Q3` = April through June
- `Q4` = July through September

Examples:

- `M1Q1FY26` = October 2025
- `M2Q3FY26` = May 2026
- `M3Q4FY26` = September 2026

### Duration and completion

Task dates use `start` plus either `expected` (months) or `end` (a fiscal period). For example:

```yaml
start: M3Q4FY26
expected: 2
```

An equivalent input is:

```yaml
start: M3Q4FY26
end: M1Q1FY27
```

The endpoints count inclusively. If both `expected` and `end` are supplied,
they must agree; end cannot precede start. Parts may replace inherited duration
with an end or inherited end with a duration. The existing funding-driven timing
for ongoing tasks remains unchanged. Use `line: [start, end]` in task formatting
to show effective dates for either input form.

This task spans `M3Q4FY26` through `M1Q1FY27`. A duration of `1` stays in the
start month. Compact completed tasks may omit both scheduling fields; they use `completed` as the start and a
one-month duration.

### Status values

Use one of:

- `pending`
- `planning`
- `active`
- `ongoing`
- `blocked`
- `unfunded`
- `complete`
- `closed`

## Plan structure and fields

A plan can be a raw task list or a mapping containing `tasks` and optional
plan metadata. Start with the mapping form shown above.

### Plan metadata

A plan can include optional top-level project metadata:

- `portfolios`: ordered portfolios or parent programs. Accepts a scalar, a YAML list, or a Markdown list block (the former `portfolio` key is rejected).
- `project`: high-level project name.
- `managers`: list of manager names.
- `pocs`: list of point-of-contact names.
- `summary`: high-level plan summary.
- `background`: optional project background prose; selected by the ASC v4 profile.
- `fiscal_range_begin` and `fiscal_range_end`: optional fiscal year range covered by the plan, for example `27` through `31`.
- `execution`: a mapping with optional `description` prose and an `activities` list. Each activity requires `id`, `label`, and `description`; tasks link with `activity: ID`. Legacy names and flat-list execution input are rejected.

### Project dependencies and risks

Project `dependencies` define commitments with `id`, `label`, `type`
(`internal` or `external`), `description`, and a fiscal `promised` date.
Their optional `risks` list references project-level risk IDs of any of the
five predefined risk types. Task `dependencies` can mix task IDs and commitment
IDs. IDs in that shared namespace must be unambiguous, including multipart aliases.

Project `risks` require `id`, `label`, `type`, `level`, and `mitigation`, with an
optional `description`. Inline task `risk` entries keep their existing structure
and remain private; dependencies cannot reference them.

```yaml
dependencies:
  - id: TEST_HARDWARE
    label: Test hardware arrival
    type: external
    description: Hardware required for integration tests.
    promised: M1Q2FY27
    risks: [DELIVERY_DELAY]
risks:
  - id: DELIVERY_DELAY
    label: Delivery delay
    type: schedule
    level: high
    description: Hardware may arrive late.
    mitigation: Reserve capacity and identify alternatives.
```

Use `planner list dependencies plan.yaml`, `planner list risks plan.yaml`,
`planner fields dependency`, and `planner fields project-risk` to inspect or
create records. `planner avail dependencies.type` lists commitment types.
Project commitments remain unconfirmed; their promised dates do not automatically
unblock pending tasks. Starts before a promised month warn without changing dates.

`export.elements.risks` produces a consolidated section with project risks and
all inline task risks, retaining severity colors and task ownership. It supports
ordered `line:` instructions, field styles, heading controls, and spacing.
`tasks.risk` independently controls risk details beneath tasks. See the
[export formatting reference](docs/export-options.rst) for an example.

The old `request_dependencies` and `external_risks` prose keys are rejected.
Migrate their content into definitions after reviewing missing dates and risk
attributes. Import preserves older Word prose in the summary for review.

### Planning placeholders

Use `status: planning` to add a task before its schedule, priority, and risks
are known. Only five task fields are required:

```yaml
tasks:
  - id: FUTURE_DESIGN
    category: development
    priority: capability
    label: Future design work
    description: Scope and deliverables to be developed.
    status: planning
```

Add optional fields as the plan develops. Supplied values are validated normally;
omitted priority is unassigned and risks default to an empty list. A start or duration
may be supplied individually, but timing remains `Unscheduled` until both `start`
and either `expected` or `end` exist. Unknown duration displays as `Unspecified`. With both fields,
normal month-based timing applies, including a provisional Gantt bar. Undated
placeholders sort after dated tasks.

Funding estimates contribute to totals without creating dates or full-year bars
(as they do for `ongoing`). Dependencies are allowed, but planning tasks do not
satisfy dependencies and always show `PLANNING` in the schedule. Lists and exports
retain placeholders; Word narratives mark them `[PLANNING]`. Changing to an
execution status enforces its usual required fields.

Closed tasks are marked `[CLOSED]` in gray in Word narratives.
Closed tasks require only `id`, `label`, `description`, `category`, and `status: closed`
and display `CLOSED` in schedules. Activity, timing, priority, and risk are optional;
supplied values are validated. Without `start` and either `expected` or `end`, timing remains
`Unscheduled` and no Gantt bar is drawn. They use gray styling; unfunded tasks use muted amber. Valid choices from
`planner avail status` and generated templates list `closed` last.

YAML plan and export-option files reject duplicate explicit keys with source
locations. Explicit entries may still override values inherited through `<<` merges.

### Task fields

Tasks use only `activity` for grouping and `funding` for budgets. The
optional Funding export column calculates the sum of a task's fiscal-year amounts;
parent budgets retain the existing count-once rule in plan totals. Top-level
`project` remains the overall plan title. Every unknown key is an error at its
source location, including task/part keys, nested metadata, and export options.
There are no special diagnostics or compatibility aliases for removed fields.


Each task supports these fields. `priority` and `risk` are optional for every task.
Planning timing (`start` with `expected` or `end`) is optional for closed tasks, [planning placeholders](#planning-placeholders),
[ongoing tasks](#ongoing-tasks-and-funding), and complete
tasks with a `completed` period:

- `category`: required ID from configuration `task_categories`; parts inherit their parent category unless overridden.
- `id`: required non-empty string task id (quote numeric IDs). Must contain only letters, numbers, or underscores, with no spaces.
- `label`: required non-empty string display name for the task.
- `site`: optional single site ID; restricted by configuration `sites` when supplied.
- `bnr`: optional single budget and reporting ID; restricted by configuration `bnrs` when supplied.
- `type`: optional task type ID, or a list of IDs such as `[Labor, Contract]`; each is restricted by configuration `types` when supplied.
- `tags`: optional comma-separated string or list of task tags. Omitted or null values mean no tags.
- `activity`: optional ID of an activity under `execution.activities`. Linked tasks use that activity's label and position for activity headings and task numbers in exports. An unknown ID is rejected.
- `description`: required non-empty string describing the task.
- `note`: optional string with additional task information. Unrecognized keys are rejected uniformly.
- `workitems`: optional GitLab work item or merge request references; see [Work item references](#work-item-references).
- `start`: required fiscal period string in `M{month}Q{quarter}FY{year}` format, where `month` is `1` to `3` within the quarter.
- `expected`: positive whole number of months for the task duration; required unless `end` is supplied or the task status permits omitted timing. The end month is computed from `start`, counting the start month as month one.
- `end`: alternative inclusive end period with `start`. If both `end` and `expected` are supplied, they must agree.
- `completed`: optional fiscal period string for work that is already complete. A task with `status: complete` and `completed` may omit planning-only fields: `start` and `expected`. A complete task without `completed` still requires these fields.
- `milestones`: optional list of milestone IDs, for example `[Design, Implementation]`. Every ID must match a top-level milestone definition. Omitted/null values or an empty list mean no milestones.
- `priority`: optional single configured `task_priorities` ID. Omitted/null/empty text means unassigned. Lists, unknown IDs, and legacy urgency values are rejected.
- `status`: required string status. Allowed values are `pending`, `planning`, `active`, `ongoing`, `blocked`, `unfunded`, `complete`, and `closed`. Use `unfunded` for work awaiting funding.
- `dependencies`: optional list of task ids. Omitted or null values mean no dependencies. Each supplied dependency must reference another task `id`.
- `risk`: optional risk entry or list of risk entries. Omit it or use `risk: []` for no risks; null is rejected. Each entry requires `type`, `level`, and `mitigation`, and may include `description`. Types are `technical`, `schedule`, `operational`, `external`, and `performance` (trimmed and normalized to lowercase); `level` must be `low`, `medium`, `high`, or `extreme`. Use `planner avail risk.type` to list types.
- `funding`: sole budget input, an optional mapping of fiscal year to funding level, for example `fy27: 50K`. A task is treated as unfunded for fiscal years not present in this mapping. For tasks other than `ongoing`, a warning is issued when a funding year falls outside the fiscal years covered by the task's `start` and calculated end month.

Omitted dependencies and tags are empty collections internally. Outputs that
need a value display `None`, including dependency fields in `list-detail` and
`schedule`, SVG dependency text, and an explicitly selected Tags table column.
The concise `list` output continues to omit empty Dependencies lines.

### Milestones

Define milestones at the top level with `id`, `label`, `description`, and a
fiscal `deadline`. `deliverables` is an optional list of IDs referencing
top-level deliverable definitions. Omitted/null/empty lists mean no references. IDs must be unique and use letters, numbers, and underscores.
Tasks can omit `milestones`; every supplied ID must be defined, including links
inherited by multipart tasks. Task files without milestone references need no section.
Milestone deadlines do not change task durations or dependency scheduling.

Summary counts include a task under each of its milestones. Duplicate task
milestone IDs are counted once. CLI metadata and Word output include milestone
definitions; plan SVG headers summarize milestone labels and deadlines. Word
and SVG exports display milestone labels without IDs.

### Deliverables and deadline checks

Define outputs in a top-level `deliverables` list. Each entry requires `id`,
`label`, `description`, and `type`. IDs use letters, numbers, and underscores;
types are `paper`, `document`, `presentation`, or `release` (trimmed and normalized to
lowercase). A `document` is material such as internal documentation that does not
require submission, unlike a `paper` intended for submission. It can be marked
`complete` directly; no `submitted` step is required. Additional types are added
in code, not through plan configuration.

```yaml
deliverables:
  - id: RESULTS
    label: Results paper
    description: Reviewed manuscript describing the results.
    type: paper
milestones:
  - id: REVIEW
    label: Program review
    description: Results available for review.
    deadline: M3Q2FY27
    deliverables: [RESULTS]
tasks:
  - id: WRITE
    category: development
    priority: capability
    label: Prepare manuscript
    description: Analyze and write up the results.
    status: planning
    start: M1Q2FY27
    expected: 3
    deliverables: [RESULTS]
```

A task's optional `deliverables` list identifies its outputs. **Every task
referencing a required output is a required producer.** References are trimmed and
deduplicated; omitted/null/empty means none. Multipart parts inherit the list
and may replace or clear it. All task and milestone references must resolve.

For a required deliverable, readiness is the latest finish of all its producers. Its required-by
date is the earliest deadline of milestones requiring it. Each task must finish
by every milestone it cites and every milestone requiring one of its required outputs.
Completion in the deadline month is allowed. These constraints produce warnings;
they never move tasks, add duration/funding, or change dependency readiness.

Explicit `completed` dates on complete tasks supply actual timing; other finish
dates are forecasts. An undated or closed producer keeps output readiness
unknown. Ongoing task forecasts use the final funded month; use a separate dated
task when an output is due before ongoing work ends. A required output without
producers also produces a warning. All producers being complete means *inferred
complete*, not submission or acceptance. Separate draft and final outputs if
milestones require different versions.

Deliverables accept an optional `status`:

| Status | Meaning | Effect |
| --- | --- | --- |
| `required` | Committed output; default when omitted | All producer and deadline checks apply |
| `planning` | Output is still being planned | Defer assessment through this output |
| `blocked` | Required output has an obstacle | Retain all producer and deadline checks |
| `submitted` | Delivered for review; awaiting acceptance | Remain outstanding and retain all producer and deadline checks |
| `complete` | Output has been delivered and considered fulfilled | Satisfy its requirement independently of producer states |
| `closed` | Output is no longer required | Remove its requirement while retaining the record |

Status values are trimmed and normalized to lowercase; explicit null/empty or
unknown statuses are invalid. Planning and closed outputs do not acquire a
readiness or required-by date. Producer references remain visible for history.
Filtering and summary relationship counts retain these historical links; they
do not indicate outstanding obligations. Direct task-to-milestone requirements,
task dependencies, and requirements through other outputs still apply.
Structural validation (including all references and required definition fields)
always applies, regardless of status.

A complete deliverable may record an actual completion period:

```yaml
  - id: RESULTS
    label: Results paper
    description: Reviewed manuscript describing the results.
    type: paper
    status: complete
    completed: M3Q2FY27
```

`completed` requires explicit `status: complete` and a valid fiscal period.
Completion after a milestone deadline produces a historical timing warning;
completion during that month is allowed. Without `completed`, the output still
satisfies its requirement and displays "completion date unknown", without
borrowing a producer's forecast or issuing missing-producer/timing warnings.
Producer completion can still yield *inferred complete* for a required output,
but never changes its stored status. Marking an output complete does not complete
its producer tasks. Blocked and submitted outputs retain the same producer and
deadline constraints as required outputs. Completed producers do not imply that
a blocked output is unblocked or a submitted output is accepted; their explicit
states remain authoritative. `complete` means delivered and considered fulfilled,
including acceptance when that is required. `completed` remains exclusive to
`complete`; no submission date is recorded in this version.

`validate` counts definitions and warnings; `list-detail`, `summary`, and plan
exports show outputs and derived timing. `list ... deliverables`,
`show ... deliverables.type`, `show ... deliverables.status`, `fields deliverable`,
`avail deliverables.type`, and `avail deliverables.status`
help inspect and author them. `--only deliverables=ID` also accepts a label;
milestone filters and summary counts include indirectly linked producers.
Filtered detail output retains readiness computed from all producers.

**Migration:** milestone `deliverables` formerly contained prose. Move each
item into a top-level definition and replace milestone text with its ID. Unknown
references are errors; legacy prose is not silently accepted.

### Work item references

`workitems`: optional mapping or list of mappings, each requiring `id` as a GitLab project-path reference such as `aircraft/design#42` or `aircraft/design!69`. The path must include a namespace and project (nested subgroups are accepted), using ASCII letters, digits, underscores, dots, and hyphens, with each segment starting with a letter or digit. A positive decimal item number follows `#` (work item) or `!` (merge request). Surrounding whitespace is trimmed. IDs are server-relative references, not URLs; no server or item-existence lookup is performed. Explicit `type` is rejected; the Python API derives `WorkItem.type` as `workitem` or `mr`.

Each entry also accepts `status`: `open` (the default when omitted) or `closed`, trimmed and normalized to lowercase. Explicit null or other statuses are rejected. CLI and configured exports display the status.

Optional `assignees` accepts a list of non-empty moniker strings, trimmed with case and order preserved. Omitted, null, or empty lists mean no assignees. CLI and configured exports display assigned monikers.

Optional `label` is a display name, trimmed with omitted/null values becoming empty strings; non-string values are rejected. Labels appear before work item identifiers in CLI and configured exports and support inline Markdown in Word/SVG.

Optional `description` is prose text, trimmed with omitted/null values becoming empty strings. Descriptions appear with the reference in CLI output and configured exports, where the task-description inline Markdown subset is supported.

Omitted, null, or empty lists mean no references. Multipart parts inherit the parent's references unless they replace or clear them. References appear in `list-detail` and `schedule` attributes; select `workitems` in export options for a Word column or SVG card attributes.

For example, a task can reference a merge request and an issue:

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

### YAML format

A plan can be a raw task list or a mapping with `execution.tasks`. Existing top-level `tasks` collections remain readable for compatibility, including the flat examples below. The mapping form can also include plan-level metadata such as `portfolios`, `project`, `managers`, `pocs`, `summary`, `fiscal_range_begin`, `fiscal_range_end`, and `execution`.

```yaml
portfolios: Advanced Simulation and Computing
project: Task-Parallel Project
managers:
  - Alice Example
pocs:
  - Casey Example, PI
summary: >
  High-level planning context for the task collection.
fiscal_range_begin: 27
fiscal_range_end: 29
execution:
  description: >
    Overall execution context for the plan.
  activities:
    - id: deliverable_a
      label: Deliverable A
      description: >
        Narrative execution detail for this deliverable.

deliverables:
  - id: ARCHITECTURE
    label: Architecture document
    description: Reviewed architecture document.
    type: paper
  - id: PARSER
    label: Parser
    description: Released parser implementation.
    type: release
milestones:
  - id: Design
    label: Design
    description: Complete the architecture draft.
    deadline: M2Q3FY26
    deliverables: [ARCHITECTURE]
  - id: Implementation
    label: Implementation
    description: Deliver the task parser.
    deadline: M2Q3FY26
    deliverables: [PARSER]
  - id: Phase_A
    label: Phase A
    description: Complete the first phase.
    deadline: M3Q2FY27
    deliverables: []
  - id: Phase_B
    label: Phase B
    description: Complete the second phase.
    deadline: M3Q4FY28
    deliverables: []

tasks:
  - id: DraftArchitecture
    category: development
    priority: capability
    label: Draft architecture
    bnr: EXAMPLE-001
    site: Example Works
    type: labor
    tags:
      - architecture
    activity: deliverable_a
    description: Produce the first architecture draft.
    start: M1Q3FY26
    expected: 2
    milestones: [Design]
    status: complete
    dependencies: []
    risk:
      - type: technical
        level: medium
        description: Integration requirements may change during implementation.
        mitigation: Review the architecture with stakeholders before implementation starts.
    funding:
      fy27: 50K
      fy29: 100K

  - id: BuildParser
    category: development
    priority: capability
    label: Build parser
    description: Load task definitions from YAML and Python files.
    start: M2Q3FY26
    expected: 1
    milestones: [Implementation]
    status: pending
    dependencies:
      - DraftArchitecture
    risk:
      - type: technical
        level: medium
        mitigation: Add schema validation tests for both YAML and Python task sources.

  - id: MultiYearDelivery
    category: development
    priority: capability
    label: Multi-year delivery
    site: Example Works
    parts:
      - id: A
        category: development
        priority: capability
        label: First phase
        funding: {fy27: 50K}
        description: Complete the first phase.
        start: M1Q1FY27
        expected: 6
        milestones: [Phase_A]
        status: active
        dependencies: []
        risk:
          - type: schedule
            level: low
            mitigation: Review progress monthly.
      - id: B
        category: development
        priority: capability
        label: Second phase
        funding: {fy28: 100K}
        description: Complete the second phase.
        start: M1Q3FY27
        expected: 18
        milestones: [Phase_B]
        status: pending
        dependencies:
          - A
        risk:
          - type: technical
            level: medium
            mitigation: Keep integration tests current.
```

## Viewing and filtering

Use `list` for an activity-based view, `list-detail` for all task fields,
`summary` for counts and funding, and `schedule` for dependency readiness.

```bash
planner list-detail data/tasks.yaml
planner summary data/tasks.yaml
planner schedule data/tasks.yaml
```

### Choose what to list

`planner list plan.yaml` displays the full terminal planning document: project
metadata, fiscal coverage, execution narratives (including empty
sections), milestone and deliverable definitions, and numbered tasks with
category labels, planning attributes, notes, risks, and work item details.
Unreferenced definitions remain visible. `planner list` does the same when
`TUXFAN_PLANNER_DATAFILE` supplies the input. Terminal Markdown, colors,
80-column prose wrapping, multipart grouping, and automatic paging apply.

Export content selection and layout settings do not limit
list output. Use `planner list plan.yaml summary tasks` or other existing field
selections to project information, and `--only` to filter tasks and their related
definitions. Readiness and numbering retain full-plan context; referenced tasks
may still appear in definition relationships. No matching tasks produces the
existing notice and zero funding totals.

Use `planner list tasks plan.yaml` for the original compact task-only view.
`planner list plan plan.yaml` retains the scoped metadata/relationship summary.

Use `planner list KIND [task_file] [FIELD ...]` to select the objects to display.
The primary kinds match the top-level names accepted by `export.elements`:
`portfolios`, `project`, `managers`, `pocs`, `summary`, `background`,
`fiscal_range_begin`, `fiscal_range_end`, `fiscal_years`, `fiscal_current`, `planned_value`,
calculated `actual_value`, `execution`,
`milestones`, `deliverables`, `tasks`, `dependencies`, `stakeholders`,
`users`, and `risks`. Each has its own help.
For example, `planner list summary plan.yaml` prints only the summary;
`planner list execution plan.yaml` prints the execution description and all activities.
Missing metadata displays `None`; names retain their order.
The `execution` fields are `description` and `activities`.

The compatibility views `activities`, `workitems`, `risks`, and `plan` remain
available with their existing behavior. With `TUXFAN_PLANNER_DATAFILE` configured,
omit `task_file`. Kind names take precedence over default-input field projections;
put the filename first to combine projections, such as
`planner list plan.yaml project summary tasks`. Prefix reserved-kind filenames
with `./`.

| Kind | Default contents |
| --- | --- |
| `tasks` | Existing activity-grouped task listing |
| `milestones` | Definitions, deadlines, outputs, associated tasks, direct links, and current required tasks |
| `deliverables` | Definitions, lifecycle status, producers, readiness, and required-by dates |
| `activities` | Every activity, including empty activities, with tasks, counts, and funding; Unassigned appears when needed |
| `workitems` | Unique reference IDs with owners and every conflicting metadata variant |
| `risks` | Each risk entry with severity, mitigation, and owning task |
| `plan` | Plan metadata, execution description/activities, and relationship summaries |

In `planner list plan`, activity definitions use `Activity A: label [ID]` headings in
declaration order, with `ID:` and `Description:` indented beneath each heading.
The same layout applies when selecting the `execution` field.

```bash
planner list tasks data/tasks.yaml
planner list deliverables data/tasks.yaml --only type=document
planner list deliverables data/tasks.yaml label status ready required_by
planner list milestones data/tasks.yaml --only deliverables=NEEDS
planner list activities data/tasks.yaml label task_count funding
planner list workitems data/tasks.yaml --only status=open
planner list risks data/tasks.yaml --only level=high
planner list plan data/tasks.yaml
planner list deliverables --help
```

Fields are scoped to the requested kind: `list tasks ... status` selects task
status only; `list workitems ... status` selects reference status. Identity
headings remain visible. Field names are exact, and each kind's help lists its
choices. Additional fields are `tasks`, `direct_tasks`, `producer_tasks`, and `required_tasks` for
milestones; `producers`, `ready`, and `required_by` for deliverables; `tasks`,
`task_count`, and `funding` for activities; `tasks` and derived `type`
(`workitem`/`mr`) for workitems; and `tasks` for risks.
These view fields do not extend the input schema or the `show` command.

Filters apply directly to the requested objects, so unreferenced definitions and
empty activities remain visible. Target a native field such as `id`, `label`,
`type`, `status`, or `level`, or related `tasks`, `activities`, `activities`, `tags`,
`milestones`, `deliverables`, or `workitems`. Relationship targets accept IDs or
labels (workitems use their IDs). Singular aliases work, and `producers`/`producer`
aliases `tasks`. Use `TARGET=VALUE` to match whole values or `TARGET~VALUE` for
literal substring matching within that target. Bare values match substrings
across all searchable fields. Matching ignores case and trims whitespace. Comma-separated values
are OR alternatives; repeated flags are AND requirements. For example:

```bash
planner list deliverables data/tasks.yaml --only type=document,paper --only status=complete
planner list deliverables data/tasks.yaml --only tasks=PURPOSE
planner list milestones data/tasks.yaml --only direct_tasks=PURPOSE
planner list tasks data/tasks.yaml --only 'id~HARD'
planner list tasks data/tasks.yaml --only 'id~HARD,SOFT' --only status=active
planner list deliverables data/tasks.yaml --only 'label~report'
```

`id~HARD` matches `HARD_DEVELOPMENT`, `HARD_SUPPORT`, and
`SOFTWARE_HARDENING`. Matching is literal, with no regular expressions or globs;
the first `=` or `~` separates target and value, and later operators are literal
characters in the value. `=~` is not a separate operator: `label=~draft` matches
the exact label `~draft`. These substring selectors apply to explicit `list KIND`
commands; legacy `list [task_file]` and `list-detail` retain their existing filters.

For tasks, `--only id=ASSEMBLY` selects every expanded part of multipart parent
`ASSEMBLY`; `--only id=ASSEMBLY_A` selects only that expanded task. Standalone IDs
still match exactly. Exact comparisons ignore case, but do not match prefixes or local
part IDs. `id~TEXT` searches both expanded and parent IDs for a substring.
Parent selectors can be combined with other filters, for example:

```bash
planner list tasks data/tasks.yaml --only id=AIRFRAME --only tags=build
```

Readiness always uses every producer in the full plan. Activity funding uses all
its tasks, counts multipart parent budgets once per activity, and includes
configured zero-funded years; years are inferred from funding if none are
configured. Milestone `tasks` retains historical links, `direct_tasks` shows direct links,
`producer_tasks` shows tasks required through outputs, and `required_tasks`
reflects current lifecycle requirements. Filtering does not change those values.

Shared workitem IDs appear once. Identical metadata merges owners; conflicting
labels, descriptions, statuses, or assignees remain in owner-labeled variants.
Repeated filters must match one variant. A selected reference still displays all
variants, so conflicts remain visible. Risks remain separate entries under their
owning tasks. All views share Markdown, links, 80-column wrapping, colors,
`NO_COLOR`, and automatic paging. IDs in identity headings and reference fields
use bold standard magenta so they stand out from labels and prose. Closed task entries stay gray; unfunded task entries use muted amber, with bold IDs. Plain and redirected automatic output
remain uncolored; `--color always` can explicitly enable the highlighting.

Task relationship lists use `parent:child` for multipart references, for example,
`Baseline Design [AIRFRAME:BASELINE]`. This applies to milestone task lists,
deliverable producers, activity tasks, workitem owners, risks, and plan task
summaries. Task labels use normal cyan; IDs retain their magenta styling.
The colon form is for display: YAML, dependencies, and exact selectors still
use expanded IDs such as `AIRFRAME_BASELINE`. Underscores within the parent
or child ID are preserved. Normal grouped task headings retain local part IDs.
Task relationship fields put each task on its own indented, hyphen-bulleted line, including
when selecting fields explicitly:

```text
Tasks:
  - Baseline Design [AIRFRAME:BASELINE]
  - Advanced Design [AIRFRAME:ADVANCED]
```

This also applies to direct tasks, producer tasks, required tasks, and
deliverable producers. Each reference wraps at 80 visible columns, and empty
lists display `None`.

`planner list plan.yaml` and `planner list plan.yaml FIELD ...` preserve the legacy
task view, including its cross-context field selection and task filters. With a
default input, reserved kind names now select object views: `planner list deliverables`
lists definitions. Use `planner list plan.yaml deliverables` for the legacy
container projection. If a filename equals a kind, qualify it as `./tasks`, etc.
The following task-list and filtering details describe the legacy shorthand;
`list tasks` without fields retains its task layout.

### List output and ordering

Normal `list` output identifies each multipart group with an unnumbered parent
heading, such as `Airframe Development [AIRFRAME]`. Its parts are indented
beneath it, with their descriptions and details one level deeper. Filtering
retains the parent heading for matching parts. Part numbers and dependency
references stay the same. Field-selected output keeps its existing layout.
Child headings show the part ID exactly as written in the source, for example,
`Task A.1: Baseline Design [BASELINE]` beneath `Airframe Development [AIRFRAME]`.
Standalone headings show the task ID. Dependencies and selectors still use
expanded child IDs such as `AIRFRAME_BASELINE`; local IDs are not selector aliases.
Task heading labels use normal cyan, retaining explicit Markdown emphasis.
IDs use the shared ID colors,
with closed task IDs gray and unfunded task IDs muted amber.
In descriptions containing bullet lists, source line breaks within prose paragraphs
and indented bullet continuations reflow to the available width. Blank lines and
nested bullets are preserved, so YAML `|-` blocks can use readable source wrapping.

If a parent or task heading would exceed 80 visible columns, its bracketed ID
moves to a separate line indented two spaces further. Long labels and IDs wrap
within that limit, with Unicode widths and color codes accounted for.
All divider lines end at column 80, including indented dividers between parts.

The explicit `list tasks FILE` view prints tasks in Word activity and task-number order with each task's description, a `Note:` line when present, numbered dependencies when present, status, and a single funding line for identified fiscal years (for example, `Funding: $500K (FY27), $250K (FY28)`). For configured fiscal years, a `Funded Total:` line at the bottom shows every year in thousands of dollars, including `$0K` years. Linked activity headings also show their activity descriptions. Activity/task descriptions and notes wrap at 80 terminal columns, accounting for wide characters, combining marks, and styling. Main sections have bold muted cyan headings framed by muted orange double rules; indented subsections use bold muted cyan headings and thin gray rules. Activity headings use muted cyan and record titles use cyan, with lighter gray separators between items. Complete plans group child sections under Execution and Resourcing, and configured lists preserve their declared order. Field-only projections remain compact. It uses color when stdout is a compatible terminal, with dollar amounts in light green, statuses by state, and the entire entry for an `unfunded` task in muted amber and a `closed` task in gray; `--color always` or `--color never` overrides automatic detection. `NO_COLOR` disables automatic color. Accepts a task file or uses `TUXFAN_PLANNER_DATAFILE`. Use field names such as `label`, `status`, or `assignees` to specialize output with nested context; combine them with `--only` to filter tasks first. `label` alone gives the compact label outline with work item ID fallback. Field selection omits funding totals.

`list-detail` prints full task details in calculated end-month order, including
start/end fiscal periods and duration. Compatible terminals use cyan headings
and task labels, blue field labels, subdued magenta IDs, status colors, and
severity colors for priority and risk. Funding totals are green. Closed task blocks stay gray; unfunded task blocks use muted amber, with matching bold IDs. Use `--color auto`,
`--color always`, or `--color never`; `NO_COLOR`, `TERM=dumb`, and redirection
disable automatic color. Colorization preserves the existing text and layout,
including literal Markdown, and works with automatic paging.

### Paging long terminal output

Configure a pager once to keep colors without piping each command:

```bash
export TUXFAN_PLANNER_PAGER='less -R'
planner list
```

Long output opens in the pager automatically when both input and output are
terminals. Short output stays direct. Planner detects colors before opening
the pager, so `--color always` is unnecessary. `NO_COLOR` and `--color never`
still control styling. Redirecting or piping output bypasses automatic paging;
`TERM=dumb` also bypasses it. Unset the variable or set it to an empty value
to disable paging.

Paging applies to `list`, `list-detail`, `summary`, `schedule`, `show`, `avail`,
`fields`, and stdout help. Warnings/errors stay on stderr; validation output,
completion scripts, editing prompts, and export/transform messages stay direct.
The pager value is an executable plus arguments, with quoted paths supported,
and runs without a shell. If it cannot start, planner prints the output directly.
Output height accounts for wrapped lines and ignores ANSI color sequences.

### Filter list output

Run `planner list --help` or `planner list-detail --help` for built-in filtering
examples, or see the [CLI reference](docs/cli.rst) for detailed matching and
funding rules.

Use `--only` with `list` or `list-detail` to select tasks by activity,
activity ID, tag, or milestone ID/label:

```bash
planner list tasks.yaml --only tags="Tag1, Tag2"
planner list-detail tasks.yaml --only milestones="Flight Deliverables"
planner list tasks.yaml --only activities=Aircraft --only tags=gpu
planner list tasks.yaml label --only tags=gpu
planner list tasks.yaml --only "aircraft, gpu"
```

Use `list FIELD` to specialize output by any supported field identifier,
such as `label`, `status`, `assignees`, or `mitigation`. Replace `FIELD`
with the exact input field name. Combine field names to display several fields.
Nested selections retain the activity, task, and item context needed to identify
their values. Container names such as `workitems` show their complete contents.
Combine field selection with `--only` to filter tasks before displaying the
requested information. Run `planner list --help` for supported field names.
Shared names apply at each supported level: `status` selects task
and work item statuses. `type` selects task and risk types; work item types
are inferred and are not selectable input fields.

```bash
planner list tasks.yaml status assignees --only tags=gpu
planner list tasks.yaml risk mitigation
planner list tasks.yaml workitems
```

`label` alone retains the compact activity/task/work item outline, with two
spaces per level and work item IDs when labels are absent. Field names are exact canonical input
names (including underscores), without abbreviations, aliases, or computed
properties. Input composition directives such as `defaults` and `parts` are
expanded during loading, rather than exposed as selectable fields.

`--only` still filters tasks before rendering; work item labels/IDs and task
labels are not additional filter fields. Selected tasks keep their work items;
filtered metadata retains only associated milestone definitions and execution
sections. Selected output omits unrelated details, separator rules, generated
numbering, and funding totals. Empty requested fields display `None`; branches
without a matching field are omitted. See the [CLI reference](docs/cli.rst) for
the full supported field list and contextual output examples.

A `target=` prefix limits matching to that field. Supported targets are
`activities`, `activities`, `tags`, `milestones`, and `deliverables`; singular names
also work. Activities match an activity name, activity ID, or generated label
such as `Activity B`. Milestones match IDs or display labels. Targeted values
match complete field values, so `tags=gpu` does not match `gpu-kernels`.

Without a target, bare text matches **substrings** across all supported fields:
`--only "aircraft"` can match a milestone ID, its label, a project, or a tag that
contains `aircraft`. Matching ignores case and trims whitespace. Comma-separated
values within one flag are alternatives; **repeated `--only` flags must all
match**. For example, `--only activities=Aircraft --only tags=gpu` requires both the
project and the tag. Quote values containing spaces.

Only matching tasks and their associated activities are listed. With `list --only`,
activity headings show only IDs and labels, omitting activity descriptions.
Dependencies
are shown as references but do not pull other tasks into the view. Activity
letters, task numbers, and dependency numbers stay consistent with the full
plan. No matches produces a message and zero totals for configured years.
Unknown targets and empty value lists are usage errors.

Fiscal-year totals use the matching tasks. If a multipart parent has `funding`,
its full budget contributes once when any part matches, even when several parts
match or the parts specify their own funding. If the parent has no funding,
only matching parts' amounts contribute. `list-detail` also limits its activity
metadata and funding totals to the selection. Filtering does not change exports.

### Discover field values and valid options

Field selectors use positional names throughout: `list tasks.yaml label status`,
`show tasks.yaml tags`, `avail status`, and `fields task`. The former `--FIELD`
selectors are no longer accepted. With a configured default data file, use
`list label status` or `show tags`. Options such as `--only` and `--color` retain
their usual syntax.

Use `fields` to see a mapping's supported keys and copy an example into a plan:

```bash
planner fields task
planner fields risk
planner fields workitems
planner fields plan > new-plan.yaml
planner fields config > new-config.yaml
```

Types are `config`, `plan`, `task`, `workitem`, `risk`, `project-risk`, `dependency`,
`milestone`, `deliverable`, `execution`, and `activity`; plural names `tasks`, `workitems`,
`project-risks`, `risks`, `dependencies`, `milestones`, `deliverables`, and `activities`
are also accepted, as is `execution.activities`. `risk` describes a private task risk;
`risks` describes a project risk definition. Output is plain YAML with example
values and comments listing fixed choices. Nested fields are expanded.
Examples are starter values, not schema defaults. Optional completion and
alternative fiscal-year fields are commented out. Individual mapping templates
need the containing key or list and appropriate indentation when pasted;
`fields plan` produces a complete plan. No input file is needed.

`fields config` prints a complete configuration template using packaged defaults,
with bare entries for enabled export content and explicit `false` for disabled fields,
including the complete nested `export.elements` tree, optional task ID
allowlists, and table layout examples. Export sections follow their declaration
order. The command ignores `--config` and does not read or initialize user configuration, so it
works even when that file is missing or invalid. Other template types use the
active configuration for vocabulary examples.
Task `site`, `bnr`, and `type` examples honor configured allowlists; `type` accepts
one ID or a list of IDs. Omitted allowlists leave IDs unrestricted.

Print the tags used in a plan, or inspect the schema's allowed statuses:

```bash
planner show tasks.yaml tags
planner show tasks.yaml site
planner show tasks.yaml workitems.assignees
planner avail status
planner avail priority
planner avail level
planner avail risk.type
```

Both commands require exactly one field name. Values print one per line;
`avail status` adds explanatory group headings.
`show` removes exact duplicates, skips empty values, and sorts alphabetically
while preserving spelling and case. It accepts scalar fields and lists of
scalars, including tags, dependencies, milestone references, and assignees.
Unqualified fields collect values from every applicable context; use qualified
names such as `tasks.status` or `workitems.status` to limit the context.
Structured containers such as `risk`, `workitems`, and `funding` are not
selectable. Includes and multipart inheritance follow normal plan loading.
No values means no output. The usual input environment variables apply.

`avail` needs no data file. `status` prints separate labeled groups explaining
the options for a task's status and a work item entry's status;
`priority` means task priorities, `level` means risk levels, and `risk.type`
lists the five predefined risk types.
Risk levels print in severity order: `low`, `medium`, `high`, `extreme`.
Priority choices print configured IDs, labels, and descriptions in declaration order.
Task statuses are alphabetical with `closed` last; work item statuses print `open`, then `closed`.
`avail` accepts `status`, `priority`, `level`, `deliverables.type`,
`deliverables.status`, `category`, `site`, `bnr`, and `type`.
The last three print IDs from configured task allowlists; an omitted allowlist
has no predefined options and produces an error.
`deliverables.type` prints `paper`, `document`, `presentation`, `release`. Other qualified
field names are available with `show`; use it to discover free-form values.

### Summary and dependency schedules

groups tasks by activity and milestone and prints funding totals when task funding is present.

prints tasks in dependency order and marks them as `READY`, `BLOCKED`, `ACTIVE`, `ONGOING`, or `COMPLETE`.

## Importing Word plans

```bash
planner import proposal.docx
planner validate proposal.yaml
```

Import reads the visible content of a document structured like a planner Word
export: project metadata, activity definitions, task narratives, milestones,
deliverables, risks, and available table attributes and annual funding. It
generates stable IDs and reconnects deliverable references by their labels.
Top-level YAML fields and activity definitions retain their first-appearance
order in the document. Blank lines and labeled comment dividers separate
top-level YAML fields. One blank line separates list entries with an `id` field
at every nesting level, including tasks, milestones, deliverables, execution
sections, and work items. Task entries follow document order in the generated
YAML; later CLI views and exports use the planner's normal task sorting rules.

The output filename is optional: `planner import plans/proposal.docx` writes
`plans/proposal.yaml` beside the source. Supply an output filename to override
this default. Relative paths use the current directory; planner environment
overrides do not apply. The output must be a new `.yaml` or `.yml`
file. The source is unchanged, and output is validated before publication.

The result is a draft for review. Missing task IDs are generated from their
labels: `Engine Model Development` becomes `ENGINE_MODEL`, for example. IDs use
uppercase ASCII words separated by underscores, drop common connectors and
routine terms such as `development` and `improvements`, and shorten `preparation`
to `PREP`. Qualifiers are retained without a fixed word limit. Duplicate or
conflicting IDs receive `_2`, `_3`, etc., in document order, reserving recovered
explicit IDs and project dependency IDs. Multipart tasks use the new parent ID
with their existing local part IDs. A label without usable ASCII words falls
back to `TASK`; numeric labels receive a `TASK_` prefix. Recovered explicit task
IDs are preserved, and recovered relationships use the resulting IDs.

Word exports may omit original IDs, multipart structure, task milestone links,
dependencies, dates, priorities, and some statuses. Missing forecast timing is inferred from positive fiscal-year funding:
start defaults to `M1Q1` of the first year with a positive amount, and end to
`M3Q4` of the last such year. Existing start/end dates and durations are preserved.
These provisional bounds cover intervening funding gaps; review notices in the
report and YAML identify inferred fields. Allocation parts use their own effective
funding. Zero, missing, or placeholder amounts do not establish dates, and an
annual breakdown cannot be recovered from a total alone.

Tasks retain recovered statuses, including `unfunded`, when required timing is
available. Missing statuses and tasks without recoverable required timing use
`planning`; closed markers are preserved. Ongoing tasks keep their funding-driven
timing, and completion dates are never inferred. Completed tasks require a full
completion period to remain complete: the normal export retains only a year, so these become planning tasks
with a review warning. Review comments are included in the YAML, and the command prints warnings
with document block and table-row locations. Ambiguous deliverable references,
unrecognized task structure, and validation errors prevent output.

If the document uses custom table headers, pass the options used for export:

```bash
planner import proposal.docx proposal.yaml --config config.yaml
```

Unrecognized columns are reported in review comments. A work item cell with
multiple references is retained in the task note when its boundaries are
ambiguous. The importer supports bold, italic, and hyperlinks in narrative
prose; page layout and arbitrary Word formatting are not part of the YAML model.

## Exporting

Select the ASC version 6 output contract in your configuration:

```yaml
export:
  standard: asc-v6
  header: 'CUI // EXAMPLE'
  layout:
    spacing: normal
    headings:
      underline: false
    task_table:
      orientation: landscape
      fiscal_years: [FY28, FY29, FY30, FY31, FY32, FY33]
```

For ASC v4, use `export: {standard: asc-v4}` with `elements` and `layout`
omitted to apply its defaults: normal spacing, underlined headings, portrait
funding tables, and v4 section/column order. An optional plan `background`
field appears after the summary. The v4 table uses Site, BNR, Funded/Unfunded
Status, Type, Tags, and annual amounts with units; priority/category columns
and totals are optional additions. Existing explicit selections/layout settings
still override profile defaults. Omitting `standard` continues to select
`legacy`; existing user configuration files are not rewritten.

Keep separate rules in `export.standards.asc-v4` and `export.standards.asc-v6`,
each containing optional `header`, `elements`, and `layout` settings. The active
`export.standard` selects its block. Built-in profile defaults are overridden
by shared export settings, then by that block. Layout mappings merge; selections
and ordered lists replace. An omitted selection inherits shared settings;
`elements: null` restores profile defaults. All blocks are validated, including
inactive ones. `planner fields config` shows an example; see the
[export options reference](docs/export-options.rst) for full merge rules.

Override the configured standard for a single export:

```bash
planner export data/tasks.yaml plan-v4.docx --standard asc-v4
```

`--standard` accepts `legacy`, `asc-v4`, and `asc-v6` and selects the matching
configured rules without changing the file. Without it, `export.standard`
remains the default. It applies to Word, PDF, SVG, and PowerPoint output.

Use the same override when validating the plan and its configuration:

```bash
planner validate data/tasks.yaml --standard asc-v4
```

Validation resolves the selected rules and checks all configuration blocks,
including inactive ones, without generating output or modifying the config.

ASC v6 restores section headings, defaults to underlined headings and landscape
Word/PDF table pages, and uses the new funding-table columns. The example
disables underlining for other deliverables. Header and footer use the same
literal marking; an empty string removes both. Omitting `standard` preserves
legacy output. Existing `elements` selections still apply; omit `elements` and
column layout to use the complete ASC defaults. `planner fields config` shows
configuration examples.

`export.layout.spacing` accepts `normal` (the ASC v4 default, using reference
document spacing) or `tight` (the legacy/ASC v6 default). Word/PDF normal paragraphs
use 8-point gaps, while tables stay single-spaced. SVG and PowerPoint adapt their
paragraph spacing and layout accordingly.
After portrait tables, the following paragraph receives an 8-point gap in
`normal` mode or 4 points in `tight` mode, preserving existing spacers and breaks.

Plans may add prose fields `dependencies`, `stakeholders`, `users`, and
`risks`; milestones may add `reporting_level: L1` or `L2`. Import an older
Word draft with `planner import old.docx updated.yaml --update asc-v6` to request
migration and receive review notices for missing information. Imported drafts
record their output version in comments; choose the same export standard in
configuration when exporting them.

The output filename selects the format. All commands use the general YAML configuration described under
[Configuration](#configuration-and-optional-tools). Export settings live in its
`export` section. Gantt exports use configuration for plan validation but do not
apply task-table settings.

```bash
# Planner initializes the default user configuration automatically on first use.
planner export data/tasks.yaml /tmp/plan.docx
planner export data/tasks.yaml /tmp/plan.svg
planner export-gantt data/tasks.yaml /tmp/gantt.svg
planner export-gantt data/tasks.yaml /tmp/gantt.pptx
```

Plan SVG and Gantt SVG/PowerPoint use pale amber (`#E8D5A8`) for unfunded
tasks and light gray (`#D1D5DB`) for closed tasks. Terminal unfunded entries use
ANSI color 137 (`#AF875F`), a subdued ochre.

All Word, PDF, plan SVG/PowerPoint, and Gantt SVG/PowerPoint exports use an empty
marking by default. Set `export.header` to add matching centered, bold headers
and footers. Word repeats them on every page; PowerPoint
includes them on every slide.

### Selecting exported elements

`export.elements` in the general configuration is the single content-selection
mechanism for Word, PDF, SVG, and PowerPoint. Use `true` for an entire branch,
`false` to disable it, and a mapping to select children. A bare entry such as
`milestones:` means `milestones: true`, including nested fields and table columns. Omitted children are
disabled; omitted/null `elements` enables everything. The packaged default
lists every supported field explicitly and disables notes. Sections follow
declaration order; selection does not change validation, numbering, schedules,
or funding totals.

```yaml
export:
  elements:
    project: true
    summary: true
    execution:
      tasks:
        number: true
        label: true
        category: true
        description: true
        note: false
        site: true
        funding: true
        risk:
          type: true
          level: true
          description: true
          mitigation: false
    resourcing:
      task_table:
        columns:
          number: true
          site: true
          funding: true
          fiscal_funding: true
        totals: true
```

Task fields select narrative content independently of table columns. An enabled
column remains available when its narrative field is omitted or false. `task_table: false` removes the Word/PDF summary table. Risk and
mitigation appear within each owning task; there is no separate mitigation
section. Nested selections also work for work items, activity definitions,
milestones, and deliverables. Generated task fields include `number`, `end`,
`duration`, `state`, and `funding_status`. `fiscal_years` takes precedence over the individual
fiscal-range endpoints when all are selected.

Table totals accept the same children as `list.elements.totals`:

```yaml
totals:
  activity: true  # table subtotals default to bottom; top/bottom also accepted
  bnr: true
  unfunded: false  # true adds a separate Unfunded Total
```

Place this under `export.elements.task_table` to include the overall total and
selected subtotals. Regular totals exclude unfunded budgets; `unfunded: true`
adds an **Unfunded Total:** row immediately before **Funded Total:** with the
same formatting as activity and B&R subtotals. It previously included unfunded
amounts in regular totals. Bare `totals:` or `totals: true` shows only the overall total;
`false`, `{}`, or all-false children disables it. The previous sibling settings
`totals_activity`, `totals_bnr`, and `totals_unfunded` remain supported with
boolean/bare totals, but cannot be mixed with a totals mapping.

Task priorities appear in task narratives and in the `priority` table column,
which reads each task independently and preserves assignment order. `export-gantt` and terminal listing remain
independent of these controls. See [Export Options](docs/export-options.rst)
for the complete selection and layout reference.

### Parent-only task exports

To show each multipart parent once while retaining standalone tasks, add:

```yaml
export:
  layout:
    multipart: parents
```

The default is `multipart: expanded`. This setting applies to Word/PDF task
narratives and tables, SVG cards, and PowerPoint task slides, and supports
per-standard overrides. Parent entries use the authored parent label,
description, note, risks, and work items; missing parent prose stays empty.
Child prose is omitted from the task entries. Common classifications and status
are retained; differences display as `Mixed`. Dates cover the children's overall
calendar span when all parts have timing; otherwise the entry indicates partial
or unspecified timing. The span can include gaps and is not summed effort.

Funding totals, subtotals, budget comparisons, dependency checks, and readiness
continue to use the original parts. Shared parent budgets still count once.
References to hidden children use their parent's displayed number; sibling-only
references are omitted from that parent's entry. Standalone tasks stay visible.
A parent spanning activities appears in its first declared part's activity, with
a warning; activity/B&R subtotals keep their original assignments.

Separately selected relationship/risk sections keep their original detail.
Gantt charts and terminal lists retain their current behavior. Summary exports
are lossy: `Mixed` values and omitted child fields may require manual review
before importing a summary document as a task plan.

### Task narrative layout

All four `export` formats place the task's existing number, label, and status
first, then Category: and Priority: with their configured labels, followed by the description
and optional italic notes. For example, within an activity in Word/PDF:

```text
1. Design the wing [UNFUNDED]
Category: Development
Produce and review the initial wing design.
Note: Coordinate with the structures team.
```

The `Category:` prefix is bold; the category display label is normal text,
without an appended ID. This emphasis is fixed even inside styled lines;
an explicit `heading: false` hides the prefix. Category appears when `elements.tasks.category` is enabled, independently of
selected table columns. Optional category columns remain available in the Word/PDF summary;
SVG cards and PowerPoint task bodies avoid repeating the category as an
attribute. Word/PDF preserve their complete/planning/closed markers and also
mark unfunded tasks. SVG retains its task ordinal and schedule state;
PowerPoint retains its generated task number, stored status, and schedule state
in the heading. Notes follow the description when enabled. Rendered children are indented one
level below their parent: task fields beneath tasks, and risk/work-item fields
beneath their individual headings. Wrapped lines preserve this hierarchy in
Word/PDF, SVG, and PowerPoint. SVG cards expand
for complete wrapped content; PowerPoint continues long tasks at the existing
font size. Word keeps each heading and category with the following description.

Word import resolves displayed category labels against the active configuration.
Missing or ambiguous labels receive a reported review placeholder. Older
documents with appended category IDs remain supported. An imported UNFUNDED marker is reported and converted to a
planning draft because the narrative does not provide its required planning
fields; review funding and timing before restoring that status.

### Word, SVG, and PDF plans

writes a Word plan for a `.docx` output path or a graphical plan for `.svg`. SVG plan export warns about empty or duplicate generated element IDs (including dependency-marker conflicts), identifies affected tasks, and still writes the output with unchanged IDs. Enable `export.elements.execution.tasks.note` in the configuration to show an italic `Note:` line after each task description. Use the configuration `export` section selected by `--config PATH` to control optional task attributes in both formats. The Word document includes a schedule and a detailed task table, starting on a new page with its section headings. When fiscal years are configured, the table includes one column per year with each task's funding level or a blank cell, plus a final total row. The SVG uses the same activity letters and task numbers as Word, and shows fiscal-year funding totals, completion years, and numbered dependencies. Its fill color reflects status, border color reflects risk, and an accent bar reflects priority. Both formats keep multipart task parts adjacent. Custom column labels also apply to PowerPoint plan attributes; table alignment applies to Word/PDF.

PDF export generates the same Word document and asks Microsoft Word to save it
as PDF, preserving Word's page layout, page breaks, tables, headers, and footers.
It requires Microsoft Word installed and activated on macOS or Windows; macOS
may prompt for permission to automate Word. On macOS, conversion files are
staged inside Word's own sandbox so Word does not need access to each export
folder. Planner copies the finished PDF to the requested destination and removes
the temporary files. On Windows, conversion files are staged beside the output.
Word stays open after conversion.
The same nested export selection, table labels, and alignment
apply to Word and PDF. Pagination depends on the installed Word version and
fonts, just as when saving a PDF directly from Word. Conversion failures report
an error without replacing an existing output PDF. Linux users can export
`.docx` and save it as PDF in Word on a supported system.

```bash
planner export data/tasks.yaml /tmp/plan.pdf --config planner/examples/config.yaml
```

### PowerPoint plans and templates

A `.pptx` output starts with a title slide showing the project name, portfolios,
managers, points of contact, and fiscal years. Managers and contacts retain input
order and appear one name per indented line beneath their headings; commas
inside a name are preserved. Fiscal years stay on one line when possible. Each activity, milestone, deliverable, and
task starts on its own slide; different items are never combined. Project and
execution descriptions and fiscal funding totals have separate slides. Task slides
include descriptions, schedules, dependencies, risks, and selected attributes.
Text boxes expand within the slide's margins and reclaim excess title space to
keep titles and names on single lines where possible. Long titles wrap onto
additional lines instead of being shortened with ellipses; continuation slides
reserve the same title space. Title font sizes stay fixed. Body text uses a consistent size across the deck, without shrinking or
enlarging individual items. Long entries split across continuation slides for
the same item.
Prose reflows across the available text width rather than retaining YAML source
line wrapping; blank lines preserve paragraph breaks. Task, milestone, and
deliverable descriptions are separated from their following fields by a blank
line. Task numbering and
multipart grouping follow the other plan exports. The nested content selection and
configured task attributes/custom labels apply; table alignment is specific to
Word/PDF. PowerPoint status values and risk labels use the Word export colors: complete is green, planning is blue-gray, closed is gray, and risks follow severity. Inline bold, italic, and links are retained. PowerPoint does not need
to be installed to generate these slides.

```bash
planner export data/tasks.yaml /tmp/plan.pptx --config planner/examples/config.yaml
export TUXFAN_PLANNER_TEMPLATE_DIRECTORY="$PWD/templates"
planner export data/tasks.yaml /tmp/branded-plan.pptx --config planner/examples/config.yaml
```

Use `--template custom.potx` (or an absolute `.potx`/`.pptx` path) to select a
specific template for `.pptx` output. It bypasses template search; a missing or
invalid file is an error.

Without `--template`, Planner searches `TUXFAN_PLANNER_TEMPLATE_DIRECTORY` first, then the current directory.
In each directory, it tries `template.pptx` before `template.potx`. An empty
variable is unset. Relative directories resolve from the current directory;
`~` is expanded. If neither directory contains a template, Planner uses its
built-in design. A configured directory must exist. An existing invalid or
unreadable template is an error, rather than silently falling back. This setting
applies to `export` plan slides; `export-gantt` keeps its existing chart layout.

An existing `.pptx` presentation is a valid design source. Planner retains its
slide size, masters, layouts, theme, and master/layout graphics, and replaces its
slides with the plan. It selects a spacious title/body layout by geometry,
including layouts whose title is a text placeholder. If none fits, it adds text
boxes over a simple layout. Graphics placed only on example slides are not
carried over; put reusable branding on the slide master or layout. Fixed text
and dates on masters/layouts remain as provided, so remove stale sample dates
when preparing your template. The original template file is unchanged, and
output cannot overwrite it.

PowerPoint's native template format is `.potx`, which Planner also accepts as
`template.potx`. To create one, open a presentation, use **View > Slide Master**
to prepare the theme, branding, and a title/content layout, then select
**File > Save As** (or **Save as Template** on Mac) and choose **PowerPoint
Template (.potx)**. Save it as `template.potx` in the configured directory.
Do not just rename a `.pptx` file to `.potx`; use PowerPoint's format selection.
See [Microsoft's template instructions](https://support.microsoft.com/en-us/powerpoint/create-and-save-a-powerpoint-template).

### Gantt charts

writes a fiscal-month Gantt chart as `.svg` or `.pptx`, selected by the output file extension. For ordinary tasks, bars span `start` through the end month calculated from `expected`. Ongoing tasks instead have separate full-year bars for each year with positive funding. By default, the axis covers the configured fiscal year range exactly; tasks outside it are omitted and overlapping bars are clipped. Without configured fiscal years, it covers task and completion dates. Optional inclusive `--from` and `--through` bounds override the corresponding axis endpoints and accept a fiscal year such as `FY26` or an exact period such as `M1Q1FY26`; a fiscal year expands to its first or last month as appropriate. Rows follow execution activity order; each task row keeps its number and label on one line when they fit, otherwise wraps the label at a word boundary within the two-line cell. Arrows leave the dependency bar's right edge and enter the dependent bar's left edge, routing around overlaps without bending farther right than either bar requires; they connect bars within each activity, and PowerPoint draws an arrow when both bars appear on the same slide. Status colors and completion markers identify progress. The SVG is a vector image; the PowerPoint file uses editable native shapes and splits activities into slides of up to ten tasks, with additional slides for timelines longer than five fiscal years. Copy the desired slide into an existing presentation. Gantt exports do not use task table export options.

```bash
planner export-gantt data/tasks.yaml /tmp/fy27-fy28.svg --from FY27 --through FY28
planner export-gantt data/tasks.yaml /tmp/partial.pptx --from M1Q1FY27 --through M3Q2FY28
```

### Inline formatting in exports

Word (`.docx`) and plan SVG (`.svg`) exports support a small inline Markdown
subset in displayed text fields, including labels, descriptions, summaries,
notes, milestone text, and optional table values:

```yaml
description: "Deliver the **prototype**, review *performance*, and see [the report](https://example.com/report)."
note: 'Use __bold__ or _italic_ text; escape markers as \*literal asterisks\*.'
```

Use `**bold**` or `__bold__`, `*italic*` or `_italic_`, and
`[link text](https://example.com)`. Bold and italics can be combined or nested.
Links accept `http`, `https`, and `mailto` URLs and remain clickable when text
wraps. Backslash escapes make marker characters literal; use single-quoted YAML
strings for these escapes, or double the backslash inside double-quoted YAML.
Unmatched markers and unsupported link targets remain literal text. Underscores
inside words and identifiers remain literal.

This is inline formatting only; headings, lists, images, code, and HTML markup
are not interpreted. Source values keep their original text. The `list` command
also interprets this subset in activity and task labels and descriptions, using
terminal bold/italic styles when color is enabled. Links display as `label (URL)`.
Plain output removes formatting markers and retains link destinations; descriptions
wrap at 80 visible characters. Existing colors, including muted amber unfunded entries,
are preserved. Other CLI commands and `export-gantt` retain their original text.
Notes in task narratives require
`export.elements.tasks.note: true` to appear.

### Terminal list configuration

An optional `list:` section selects terminal content and formatting independently
of `export:`. If absent, existing list behavior is preserved. The syntax shares
bare entries, booleans, nested selections, section ordering, repeated `line:`
instructions, and per-field bold/italic/color settings:

```yaml
list:
  elements:
    project:
    milestones:
      - line: [id, label]
        bold: true
      - required_tasks:
    tasks:
      - line: [id, label, status]
        bold: true
      - description:
      - risk:
          mitigation:
    deliverables:
```

Omitted children in mappings are excluded; bare/true branches include their
available fields. Omitted/null `elements` includes the full document. Terminal
views also expose their existing relationship fields, such as milestone
`required_tasks`, and calculated task fields such as `end`, `state`, and
`funding_status`. Deliverables expose an additional `assessment` text field.
`task_table` and export `layout` controls are not accepted under `list`.
`planner fields config` includes a commented example; adding it is optional.

An explicit kind requests that kind even if configured selection omits it; its
configured formatting applies when present. Explicit positional fields use the
existing projection layout and override configured selection/formatting. Filters
still restrict objects, while calculations and numbering use the complete plan.
Bare elements inherit their normal terminal layout, grouping, and colors even
when other elements have custom instructions. Field-only mappings retain the
standard scoped field rendering. Custom lines inherit semantic label/ID/status
colors and closed/unfunded shading; standalone fields keep normal label colors,
indentation, and relationship bullets. Explicit style overrides take precedence.
Existing color controls, NO_COLOR, 80-column wrapping, links and paging apply.

```sh
planner list plan.yaml --ignore-config
planner list tasks plan.yaml --ignore-config --only status=planning
```

`--ignore-config` bypasses list presentation and shows complete records within
the requested scope. Explicit fields and filters still apply. Category and
priority vocabularies and task allowlists remain active for validation and label
lookup. Invalid list presentation is bypassed too; other configuration validation
still runs. Combining `--config` with `--ignore-config` is an error, in any position.
The option is available only for `list`, including scoped kinds. Without a list
section or the bypass option, existing compact/full list layouts are unchanged.

### Export options

The configuration `export` section accepts `elements` for content and `layout`
for presentation. `planner fields config` prints the complete nested example.
Column styles never enable content:

```yaml
export:
  elements:
    tasks:
      number: true
      site: true
    task_table:
      columns:
        number: true
        site: true
  layout:
    task_table:
      columns:
        - attribute: number
          alignment: left
        - attribute: site
          label: Institution
          alignment: left
```

`columns` can select any supported task field, including formerly fixed task
numbering, independently of task narrative selections. `fiscal_funding` expands
fiscal-year columns without requiring narrative funding. `totals` controls the funding totals row. Tables with no effective
columns and their headings are omitted. Layout controls column order, labels,
and left/center/right alignment; fiscal-year columns remain last.

The generated `funding_status` attribute is `false` only for tasks with
`status: unfunded`, and `true` otherwise, regardless of their fiscal funding
amounts. Exports display `Funded` or `Unfunded`. Enable `elements.task_table.columns.funding_status` to add the column;
`elements.tasks.funding_status` independently enables narrative output. Packaged
defaults leave both disabled. It is a computed value, not a plan input field.
Completed fiscal table cells are green when task status is selected; their
completion year appears only when `elements.tasks.completed` is also enabled.

Section order follows the declaration order in `export.elements`, with the
project title/PowerPoint cover fixed first. `elements.task_table` is independent
of `elements.tasks` and controls the Word/PDF summary table. The former
`elements.tasks.table` location remains accepted for existing configurations.

Word/PDF summary tables reserve space for each column's longest word, including
BNR codes and `Unfunded`, plus bold headers and cell padding. Multiword text can
wrap between words. If estimated widths cannot fit the page, export warns;
use landscape orientation or fewer columns. Font size and page margins stay fixed.
Cell left/right margins are 2.7 pt per side, or 3 pt for merged activity/parent rows.

Set independent font sizes in points under `export.layout`:

```yaml
layout:
  font_size: 12
  task_table:
    font_size: 10
```

Word/PDF body and table defaults are 12 pt and 10 pt respectively. Half-point
sizes such as `10.5` are supported. The body setting also controls SVG and
PowerPoint text and reflow; omitting it retains their native sizes. Display
titles and header/footer markings retain their existing sizes. Table sizing
uses the chosen table font; the table setting is independent of the body size.

Task exports can use an ordered list with repeated `line:` instructions:

Within a task line, `{field: number, format: short}` prints a bare displayed
number such as `A.1.1`. Omit `format` or use `full` to retain `Task A.1.1`.
This preserves the existing numbering scheme and is separate from `id`, the
stable identifier in the plan. The same syntax works in configured terminal
task lines; table numbering is unchanged.

```yaml
export:
  elements:
    milestones:
    tasks:
      - line:
          - field: number
            format: short
          - id
          - field: label
            italic: true
          - field: status
            bold: false
            color: auto
        bold: true
      - description:
      - line: [category, priority]
        color: gray
      - risk:
          type:
          level:
          mitigation:
    deliverables:
    task_table:
      columns:
        number:
        funding_status:
```

Only listed content appears, in instruction order. `- id` inside a line prints
the task ID; it is shorthand for `- field: id`. Standalone field instructions
retain their existing rendering. Field styles override line defaults;
`bold: false` and `italic: false` disable inherited emphasis. Colors accept named
colors, quoted hex values, `auto` for semantic coloring, and `default` for normal
text. Long lines wrap to fit. Structured/list fields retain separate rendering.
The previous mapping with `tasks.line` or `tasks.lines` is accepted for
compatibility. Bare `tasks:` retains the default layout. `planner fields config`
includes the new syntax as a commented replacement for the default task mapping.
See the export-options reference for supported fields and validation rules.

Add `heading: true` or `heading: false` beside a standalone field instruction
to show or hide its label. Standalone labels are enabled by default; this example
keeps the task description prefix and hides the category prefix:

```yaml
tasks:
  - line: [number, label, status]
  - description:
    heading: true
  - category:
    heading: false
```

Put this under `export.elements` or `list.elements`. Grouped lines also accept
`heading` as a line-wide default, overridden by individual field mappings such
as `{field: start, heading: true}`. For structured standalone fields such as
`risk`, the switch controls the parent heading and all selected child labels.
Omitting it enables standalone field labels, including `Description:`;
grouped lines retain their existing defaults. Section/item titles, table headers,
and heading underlining have separate behavior.

Milestones and deliverables accept the same ordered interface:

```yaml
milestones:
  - line: [id, label]
    bold: true
  - description:
  - line: [deadline]
  - deliverables:
deliverables:
  - line: [id, label, status]
    bold: true
  - description:
  - line: [type, ready, required_by]
  - producers:
```

Put this under `export.elements`. Relationship lists (`deliverables` on a
milestone and `producers` on a deliverable) remain standalone instructions.
Scalar fields, including calculated dates, can share a line. Existing bare
entries and field mappings retain their output. `planner fields config` includes
commented examples for tasks, milestones, and deliverables.

The retired `--include-note`, `include_note`, `task_table_columns`, and
`task_table_attributes` controls are rejected in the CLI/general configuration.
Move note selection to `elements.tasks.note`, column selection to
`elements.task_table.columns`, and column styles to `layout.task_table.columns`.
Replace old top-level element lists with mappings of names to booleans.

Project-year budgets use two optional top-level inputs:

```yaml
fiscal_current: FY27
planned_value: $100K
```

`fiscal_current` is a declared two-digit reporting year, independent of today's date and
plan coverage. `planned_value` requires it and accepts funding amount syntax;
amounts display in dollar-prefixed thousands. Zero is valid. The read-only
`actual_value` value sums funded task funding for that year across the complete project
(every status except `unfunded`), with authoritative multipart parent budgets once,
so it shows funded over- or underspending. `potential_value` adds unfunded tasks and is
always neutral black. Both measure assigned funding, not expenditures. The amount is green below the planned value,
black at it, and red above it, with exact decimal comparison. Without a planned
budget it is neutral black; without a current year it is unavailable.

Use `planner list actual_value plan.yaml` or `planner show plan.yaml potential_value` to inspect
them. `fiscal_current`, `planned_value`, `actual_value`, and `potential_value` are independent `export.elements` and
`list.elements` selectors; default exports include populated values before
Execution. List filters do not change the project total. Word import recovers
budget inputs and recomputes Actual Value from recovered funding; hidden allocations
or original parent budgets require review. Author only `fiscal_current` and
`planned_value`; the `actual_value` input key is rejected. `planner fields plan` and
`planner fields config` include examples.

## Advanced plan authoring

These features help organize larger plans and represent recurring or multipart work.

### Task defaults

One optional `defaults` entry inside the `tasks` list sets `site`, `bnr`, and
`type` for every task that omits them:

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

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

Default values must be indented beneath `defaults`. Only one defaults entry
is allowed, and it applies to all tasks regardless of its position. Explicit
task values override defaults; explicit null or empty values clear a default.
Multipart parents inherit defaults, and part values override parent values.
`priority` may also be set in defaults; a task/part can replace it or clear it with null/empty text.
Without defaults, `site`, `bnr`, `type`, and `priority` remain optional. This also works in
raw YAML lists and Python `PLAN`/`TASKS` lists. See
[`planner/examples/task-defaults.yaml`](planner/examples/task-defaults.yaml).

### Ongoing tasks and funding

For `status: ongoing`, `start`, `expected`, `priority`, and
`risk` are optional (dependencies and tags are optional for every task). Scheduling uses every fiscal year with
positive numeric funding for its full twelve months, even when start/duration
fields are supplied. Supplied optional fields are still validated. Omitted
priority is unassigned; dependencies and risks
default to empty lists.

```yaml
id: Maintenance
label: Tool maintenance
project: Planning System
description: Maintain the planning tool.
status: ongoing
funding:
  fy27: 50K
  fy28: 0K
  fy29: 50K
```

This task spans all of FY27 and FY29, with no bar in FY28. Ongoing work has one
Gantt bar per funded year; gaps are preserved. Its duration is twelve months per
funded year. Without positive funding, it remains in lists and schedules but
has no Gantt bar. Ongoing tasks without funded years sort after dated tasks.

### Multipart tasks

A task can also be a multi-part task by using `parts` instead of the per-task
schedule fields on the parent. Parent fields such as `activity`, `site`, `bnr`, `note`,
`type` and `tags` are inherited by each part, while each part
provides its own `id`, `label`, `description`, `start`, `expected`,
`priority`, `status`, `dependencies`, and
`risk`. Funding can be specified on the parent or on individual parts. Part ids are expanded as `{parent_id}_{part_id}`. Dependencies inside a
multi-part task can reference sibling part ids, and dependencies from other
tasks can reference the parent id to depend on all expanded parts. A parent-level budget contributes once to fiscal-year totals whenever any of
its parts is included. Without a parent budget, totals sum the included parts
only. Parts inherit parent funding unless they specify their own; explicit part
funding controls their displayed amounts and ongoing time spans, while totals
use the parent budget when present.
In exports, parts in the same activity stay together at the position of their
first part encountered in end-date order. Parts are ordered by end date, with
ties retaining declaration order in the parent's `parts` list. The `list`
command uses the same ordering, including
`list label`. Dependency-aware schedules still respect dependencies.

### Merging and splitting tasks

Use `merge` and `split` to restructure YAML tasks without changing the input
file. Both accept a complete plan mapping or an incomplete task-list fragment,
including a file that another plan includes. Supply the input filename and a
new `.yaml` or `.yml` output filename explicitly:

```bash
planner merge tasks.yaml DraftDesign BuildPrototype --id Airframe --label "Airframe work" --output merged.yaml
planner split merged.yaml Airframe --output split.yaml
```

Merge accepts at least two standalone task IDs defined in the input file. It
puts the parent at the earliest selected task's position and preserves source
declaration order for the parts, regardless of command-line ID order. Identical
shared fields may move to the parent; differing values and funding stay on the
parts. Expanded IDs usually change (for example, `DraftDesign` becomes
`Airframe_DraftDesign`), and the command prints the ID mapping and rewrites
dependencies in the supplied file.
Dependencies between the merged parts retain short sibling IDs, such as
`DraftDesign`. References from other tasks use expanded IDs such as
`Airframe_DraftDesign`.

Split replaces a parent with its parts in declaration order, materializes
inherited parent fields, retains expanded IDs, and replaces local dependencies
on the parent with dependencies on all resulting tasks. If the parent has a
funding field, choose a policy explicitly:

```bash
planner split tasks.yaml Airframe --funding parts --output split.yaml
planner split tasks.yaml Airframe --funding equal --output allocated.yaml
```

`parts` preserves each part's effective funding, including inherited amounts;
totals can increase when the original parent budget counted only once. `equal`
replaces part funding with equal shares of the parent budget, allocating any
remaining cents to the first parts in declaration order. Both commands report
local funding totals before and after where available.

Comments, quoted strings, block scalars, UTF-8 BOMs, and line-ending conventions
are retained where possible; YAML indentation may be normalized. Existing
outputs cannot be overwritten. `!include` directives stay external, with
relative paths adjusted if the output moves to another directory. Select tasks
in the file that defines them; included files are never edited. Python input
is not supported.

These commands check supplied task fields, visible ID collisions, and local
dependency cycles. They permit external dependencies and missing required
fields that may come from the containing plan. Review the ID mapping, update
references in other files, and run `planner validate` on the assembled plan
after replacing the fragment. Successful transformation means a structurally
valid fragment, not a fully validated standalone plan.

### YAML includes and composite plans

YAML plans can be split across files with `!include` at any value position:

```yaml
project: FY27 Plan
summary: !include prose/summary.yaml
milestones: !include milestones.yaml
execution:
  activities:
    - !include activities/solver.yaml
tasks:
  - !include tasks/solver.yaml
  - !include tasks/runtime.yaml
```

An included file contains the YAML value expected at that position: a mapping,
list, or scalar. In a list, included lists are spliced in place; mappings and
scalars become one item. Nested paths resolve relative to their containing file.
Cycles and missing files are errors. Includes are value-only, with no implicit
mapping merges; normal task validation follows expansion. Python plans and
general configuration files do not support includes.

Read commands load a temporary expanded snapshot and clean it up automatically.
Write a standalone copy with:

```bash
planner composite plan.yaml expanded.yaml
# With TUXFAN_PLANNER_DATAFILE set:
planner composite expanded.yaml
```

The output argument is required. Output preserves data and ordering, including
defaults and multipart definitions, but not comments or formatting. It is written
atomically after expansion, without requiring task-schema validation, and cannot
overwrite any input file. `format` formats the main YAML file and all recursively
included files in place, preserving include directives. `spell-check` reviews
prose across the main file and included sources in one session, with one final
save confirmation. See [composite documentation](docs/composite.rst)
for field-level examples and details.

### Python format

Define `PLAN` or `plan` in a `.py` file for metadata plus tasks. The legacy `TASKS` or `tasks` list still works.

```python
PLAN = {
    "portfolios": "Advanced Simulation and Computing",
    "project": "Task-Parallel Project",
    "managers": ["Alice Example"],
    "pocs": ["Casey Example, PI"],
    "summary": "High-level planning context for the task collection.",
    "fiscal_range_begin": 27,
    "fiscal_range_end": 29,
    "execution": {
        "description": "Overall execution context for the plan.",
        "activities": [
            {
                "id": "deliverable_a",
                "label": "Deliverable A",
                "description": "Narrative execution detail for this deliverable.",
            }
        ],
    },
    "deliverables": [
        {"id": "ARCHITECTURE", "label": "Architecture document",
         "description": "Reviewed architecture document.", "type": "paper"},
    ],
    "milestones": [
        {
            "id": "Design",
            "label": "Design",
            "description": "Complete the architecture draft.",
            "deadline": "M2Q3FY26",
            "deliverables": ["ARCHITECTURE"],
        }
    ],
    "tasks": [
        {
            "id": "DraftArchitecture",
            "category": "development",
            "label": "Draft architecture",
            "bnr": "EXAMPLE-001",
            "site": "Example Works",
            "type": "labor",
            "tags": ["architecture"],
            "activity": "deliverable_a",
            "description": "Produce the first architecture draft.",
            "start": "M1Q3FY26",
            "expected": 2,
            "milestones": ["Design"],
            "priority": "capability",
            "status": "complete",
            "dependencies": [],
            "risk": [
                {
                    "type": "technical",
                    "level": "medium",
                    "mitigation": "Review the architecture with stakeholders before implementation starts.",
                }
            ],
            "funding": {"fy27": "50K", "fy29": "100K"},
        }
    ],
}
```

## Configuration and optional tools

The general YAML configuration controls classification vocabularies and exports.
Environment variables provide input defaults. Formatting, spell
checking, and shell completion are optional conveniences.

### User configuration

The package ships a default configuration and copies it on first use to
`~/.config/tuxfan-planner/config.yaml`, or
`$XDG_CONFIG_HOME/tuxfan-planner/config.yaml` when `XDG_CONFIG_HOME` is set to an
absolute directory. Edit this user copy to customize the planner. Package
upgrades never overwrite it. Initialize it explicitly with `planner config init`;
that command refuses to overwrite an existing file.

All operational commands require a valid configuration. `--config PATH` selects
an alternate file and can appear before or after the command. Relative paths
resolve from the current directory. An explicitly selected missing file, or an
existing invalid/unreadable file, is an error; there is no silent fallback.
Help and shell-completion generation do not initialize configuration.

```yaml
config_version: 1
task_priorities:
  - id: capability
    label: Capability
    description: Deliver new or improved capabilities.
  - id: safety
    label: Safety
    description: Reduce safety risks.
task_categories:
  - id: development
    label: Development
    description: Develop and demonstrate capabilities.
export:
  elements:
    project: true
    tasks:
      label: true
      category: true
      description: true
      note: false
```

Each vocabulary is a non-empty list of entries with unique `id` values and
non-empty `label` and `description` strings. IDs contain ASCII letters, digits, or
underscores. Matching is case-sensitive after trimming surrounding whitespace.
The shipped task-priority vocabulary entries are `safety`, `capability`, and `efficiency`;
task categories are `research`, `development`, and `operations`. Configuration
files are complete documents: vocabulary lists are not merged with defaults.
`export: {}` selects the existing default export settings.

Tasks optionally specify one `priority: capability` ID from `task_priorities`.
Omitted/null/empty text means unassigned. IDs are trimmed and matched exactly;
lists, mappings, and unknown IDs are errors. Defaults and parent/part inheritance
apply; an explicit ID replaces the inherited value and null/empty text clears it.
Every task requires one configured `category`, which cannot be cleared.
Use `planner list tasks FILE priority` and `--only priority=capability`.
`show tasks.priority`, `avail priority`, and field templates retain canonical IDs.
Terminal task displays (including projections, detail, schedule, and configured
lines) and export task narratives show configured category and priority labels.
Task tables show IDs formatted as `ASC 1` and `Cat 1`; canonical IDs remain
`ASC_1` and `CAT_1` in authored data and discovery.

Optional `sites`, `bnrs`, and `types` sections restrict task `site`, `bnr`,
and `type`. Entries need only an `id`, for example:

```yaml
sites:
  - id: Workshop One
  - id: Workshop Two
bnrs:
  - id: EXAMPLE-001
types:
  - id: labor
  - id: equipment
```

Each task may select one scalar ID per field, and different tasks may select
different IDs. Values are trimmed and matched case-sensitively after defaults
and multipart inheritance. Missing/null/empty task values remain allowed;
lists and mappings are rejected. Omit a configuration section to leave the
field unrestricted; an empty list permits only empty task values. Exports show
the IDs in the selected optional attribute columns. `planner avail site`,
`planner avail bnr`, and `planner avail type` show active IDs. Generated task
and plan templates use those choices. See
[General Configuration](docs/configuration.rst)
for the full configuration reference.

**Migration:** add a non-empty `label` to every vocabulary entry in existing configurations. Labels are display names; plans continue to reference IDs. Then move the entire old export-options mapping beneath `export:` in
a complete configuration, add the two vocabulary sections and `config_version`,
and replace `--export-options` with `--config`. The retired
`TUXFAN_PLANNER_EXPORT_OPTIONS` environment variable is ignored.

Migrate older YAML plans and configuration explicitly:

```bash
planner migrate-priorities FY27 --config configs/asc.yaml
planner migrate-priorities FY27 --config configs/asc.yaml --write
```

The first command previews affected files. The second saves numbered backups,
renames the vocabulary to `task_priorities`, moves project assignments into task
list defaults, converts singleton task lists to scalar `priority`, and updates
presentation selections/table columns. Multiple IDs and legacy urgency values
require an explicit choice; the migration stops before writing any files. Includes and
comments are preserved. Conflicting assignments stop before writing. Review
unrelated schema errors separately. For Python input, move priorities into task
records manually. Word import recovers per-task priorities; missing assignments
stay empty, and legacy document-wide assignments produce a migration notice.

### Environment variables

`TUXFAN_PLANNER_TEMPLATE_DIRECTORY` selects the first directory searched for
`template.pptx` or `template.potx` when exporting a PowerPoint plan. See
[PowerPoint plans and templates](#powerpoint-plans-and-templates).

If you set `TUXFAN_PLANNER_DATAFILE`, the CLI uses that file by default:

An empty value behaves as unset. Supply an explicit input filename in that case;
omitting it produces the normal usage error (exit status 2).

```bash
export TUXFAN_PLANNER_DATAFILE=planner/examples/tasks.yaml
# Planner initializes the default user configuration automatically on first use.
planner validate
planner list
planner list-detail
planner export /tmp/plan.docx
planner export /tmp/plan.svg
planner export-gantt /tmp/gantt.pptx
```

Set `TUXFAN_PLANNER_DATA_DIRECTORY` to work with multiple files by filename:

```bash
export TUXFAN_PLANNER_DATA_DIRECTORY="$PWD/data"
planner validate tasks.yaml
planner list composite.yaml label
planner export tasks.yaml /tmp/airplane.docx
export TUXFAN_PLANNER_DATAFILE=tasks.yaml
planner validate
```

Relative input filenames use the configured directory first, including a relative
`TUXFAN_PLANNER_DATAFILE`. If the file is missing there, the same relative filename
is tried in the current directory. Existing invalid or unreadable inputs do not
trigger fallback. Absolute inputs
bypass the setting. Output and export-options paths are unchanged, and includes
remain relative to their containing files. The directory must exist; an empty
value acts as unset. Setting the directory alone does not choose a default file.

### Shell completion

The CLI can print completion scripts for `bash`, `zsh`, and `fish`:

```bash
planner completion bash
planner completion zsh
planner completion fish
```

For a one-session bash setup:

```bash
source <(planner completion bash)
```

To load completion automatically whenever you activate the Python virtual
environment where Planner is installed, run once using that environment's planner:

```bash
planner completion install
```

Reactivate the environment afterward. This adds hooks to its existing
`bin/activate` (Bash/Zsh) and `bin/activate.fish` scripts, retaining `.bak`
backups. Repeating the command updates the hooks without duplicating them.
Zsh initializes its completion system if needed. Installation requires a Python
virtual environment and does not edit shell startup files. Rerun the command if
the environment is recreated. Completion definitions remain in the shell after
deactivation. CMake's default `install-editable` target runs this setup automatically.

The generated completion supports the basic planner subcommands, the
`tuxfan-planner` alias, file path completion for task and output arguments, and
`--config` for export commands. It also completes `list`/`list-detail --only`,
`list` field names such as `label` and `assignees`, and `list --color` values, plus `spell-check --lang` and `--personal`.

Bash, Zsh, and Fish also suggest `.yaml` and `.yml` input files from
`TUXFAN_PLANNER_DATA_DIRECTORY`, alongside normal local filename completion.
Suggestions use relative filenames, support spaces and nested directories, and
read the setting at completion time without loading or validating plans.
For example, with the directory configured, `planner list milestones pla<TAB>`
can complete `plan.yaml` there. Missing, unreadable, or unset directories add no
suggestions. Absolute paths use normal filename completion.

Data-directory suggestions apply only to plan input positions, including the
first input to `merge` and `split`. Output paths, configuration files, personal
dictionaries, field names after an input, and option values keep their normal
completion behavior. For `export`, `export-gantt`, and `composite`, when
`TUXFAN_PLANNER_DATAFILE` supplies the input, the first filename is treated as
an output and receives no data-directory suggestions.

After updating planner, reactivate the environment (or reload its completion
script) to refresh the rules in your current shell. Running
`planner completion install` alone updates activation hooks, not rules already
loaded in the current shell.

### Formatting data files

Format a single data file in place, or use `TUXFAN_PLANNER_DATAFILE`:

```bash
planner format tasks.yaml
planner format tasks.py
planner format
```

YAML (`.yaml`/`.yml`) uses planner's built-in style and needs no external
tool: mappings indent two spaces, sequences sit two spaces in, long plain or
quoted prose becomes a folded `>` block, multi-line text and text with lists
becomes a literal `|` block, and runs of blank lines collapse to one. Authored
block scalars, comments, tags, anchors and explicit nulls are kept, and
formatting is idempotent.

Python (`.py`) uses Black from the same Python environment as planner:

```bash
python -m pip install 'tuxfan-planner[format]'
# In a checkout:
python -m pip install -e '.[format]'
```

An explicit path overrides the environment value. YAML formatting follows all
`!include` directives recursively and formats each distinct source once, retaining
the directives and separate files. Paths resolve relative to the file containing
each include. Python formatting operates on one file and never executes it.
Source encoding and
line-ending convention are retained. YAML structure and values are checked
before saving. Missing/invalid includes, cycles, and formatter failures stop the
operation before any source or backup is written. All results are prepared and
checked before saving begins; full task-schema validation is not required.

Changed files receive a numbered `.bak` backup and are replaced atomically.
Saves are atomic per file, not across the complete set; a write failure after
saving begins may leave some files formatted and others unchanged.
Already formatted files are left alone. Missing formatter dependencies produce
an installation error; other commands remain available. This CLI command
formats data files; CMake's `format` target formats the planner source code.

### Interactive spell checking

`spell-check` requires the **Aspell executable and a language dictionary**.
These are system dependencies, installed separately from pip:

```bash
brew install aspell                    # macOS / Homebrew
sudo apt install aspell aspell-en       # Debian / Ubuntu
```

Check availability with `aspell --version` and `aspell dicts`. The default
language is `en_US`; select another installed dictionary with `--lang`.

```bash
planner spell-check tasks.yaml
planner spell-check                     # uses TUXFAN_PLANNER_DATAFILE
planner spell-check tasks.yaml --lang en_GB
planner spell-check tasks.yaml --personal /path/to/project-words.pws
```

The terminal prompts show the filename, field, line, context, and numbered
suggestions. On color-capable terminals, the exact occurrence under review is
highlighted in bold red in the context. Other occurrences remain unhighlighted;
`NO_COLOR`, `TERM=dumb`, and redirected output keep the context plain.
Suggestions use as many columns as fit the terminal, up to 80 columns wide,
with numbering increasing down each column. All suggestions remain available
and selectable by their original number; narrow terminals use fewer columns,
and long suggestions wrap. The fallback width is 80 columns.
With an English dictionary, valid numeric ordinals such as `2nd`, `30th`, and
`111th` do not trigger suffix warnings. Standalone suffixes, malformed ordinals
such as `22th`, and embedded alphanumeric strings remain subject to Aspell's
normal checks. Other dictionary languages are unaffected.
Choose a suggestion number, `r` for a manual replacement, `i` to
ignore once, `a` to ignore that spelling for the session, `d` to add it to the
personal dictionary, or `q` to cancel. At the end, review the change summary
and answer the save prompt. The default answer discards changes. Quitting,
Ctrl-C, or end-of-input before saving discards staged corrections and dictionary
additions. Interactive terminal input is required.

Composite YAML plans are supported: includes are checked before Aspell starts,
then prose is reviewed in the original files, retaining field context across
includes. This includes scalar or list fragments such as
`description: !include description.yaml` and `managers: !include managers.yaml`.
Each original source string is reviewed once, even when included repeatedly.
Include paths are never spell-checked or changed. Shared text used as both prose
and structural data is skipped with a manual-review message. Ignore-all and
dictionary additions apply throughout the session. All corrections are staged
before any source is saved; the final summary groups corrections by file.
Python remains a one-file review.

Spelling checks cover prose: plan/project names, managers/contacts, summaries,
execution narratives, task and milestone labels/descriptions, notes,
deliverable labels/descriptions, risk descriptions/mitigations, and task site/type/tags.
Schema keys, IDs/references, fiscal periods, status/priority/risk-level/risk-type values,
funding, and Markdown link destinations are skipped. Original source strings
are checked once, including inherited multipart text and YAML aliases. Aliases
or Python literals shared with structural fields require manual review. Notes
are checked regardless of export visibility. Files need valid syntax but do
not need to pass task validation.

Accepted corrections preserve source comments, quoting, block styles,
indentation, line endings, and encoding. Saving creates a `.bak` backup
(`.bak.1`, `.bak.2`, etc. if earlier backups exist) and atomically replaces the
source after syntax and protected-value checks. Every source and any explicit or
discovered personal dictionary are checked for concurrent changes before saving begins.
Saves are atomic per source, not across all files or the dictionary; a later
failure reports sources already saved. Symbolic links used by includes are
preserved by editing their resolved targets; use the resolved target when
invoking spell-check on a symbolic link directly. Python inputs are inspected
without execution. Ordinary and triple-quoted literal strings can be edited;
computed values, raw strings, and concatenated literals receive manual-review
messages. Escaped spellings that cannot be replaced without changing syntax
also require manual editing. Dictionary additions are saved only after the
final prompt. Other planner commands work without Aspell.

#### Project word lists

To share accepted project terms, put an Aspell personal dictionary named
`.planner-words.pws` in the data file's directory or an ancestor directory:

```text
personal_ws-1.1 en 3 utf-8
FleCSI
FleCSolve
Kokkos
```

The header specifies the base language, word count (a hint), and encoding;
subsequent lines contain one word each. Use `en` in English word-list headers;
`--lang en_US` or `--lang en_GB` selects the installed spelling variant.

An explicit `--personal PATH` wins; relative explicit paths resolve from the
current working directory. Otherwise, the nearest `.planner-words.pws` from the
main input's directory upward is used. With no project dictionary, Aspell uses
its usual personal dictionary. A discovered file must be readable and valid;
an invalid nearer file is an error rather than a fallback to an ancestor.
The selected dictionary is loaded before correction prompts and reported at
startup. Explicit dictionary paths may name a new file, created only when
confirmed additions are saved.

For composite plans, selection starts from the main input file, and that one
dictionary applies to every included file. Dictionaries beside included files
do not override it. The `d` action stages additions to the selected dictionary;
it does not modify the file until the final confirmation. Selecting a project
dictionary replaces Aspell's usual personal dictionary for that invocation;
the installed language dictionary remains active.

## Troubleshooting and further documentation

Ill-formed commands print an error and the relevant help text to stderr, then
exit with status 2. Use `planner COMMAND --help` to check accepted arguments.

Input-file warnings and errors show `filename:line` when available. Funding
warnings identify the funding entry; task validation errors identify the task
block. Line numbers also cover literal Python inputs and YAML/Python syntax
errors. Computed Python task entries may only have a filename.

### Validation

checks required fields, invalid status values, invalid fiscal periods or non-positive/non-integer expected durations, invalid ids, duplicate ids, missing dependencies, and dependency cycles. Prints PASS/FAIL and statistics instead of plan metadata: activities (using list/export grouping), expanded tasks, milestone and deliverable definitions, activity definitions, configured fiscal years, work item references per task, and emitted warnings. Warnings appear on stderr with source locations and terminal styling and are also counted; failures retain error diagnostics on stderr.

### Migrating older plans

For existing task files, rename `expected duration` or `expected_duration` to
`expected` and remove the task `deadline` field. Milestone definitions still use
`deadline`.

Replace the former task `milestone` field with a `milestones` list. Legacy
milestone names must become IDs with top-level definitions.

The former `list --labels` flag has been replaced by `list label`.

### Documentation

Sphinx documentation lives in `docs/`. See the
[developer setup and checks](DEVELOPER.md) for the current dependency and HTML
build commands.

The repository's `Documentation` workflow is defined in
`.github/workflows/docs.yml`. It builds the Sphinx output and publishes it to
the `gh-pages` branch.

### Updating the virtual environment

Follow the [CMake workflow](DEVELOPER.md#cmake-workflow) or the
[direct dependency commands](DEVELOPER.md#install-or-upgrade-dependencies) in
the developer guide to update the root `.venv` and check the result.

After configuring CMake, the default build performs an editable install:

```bash
cmake -S . -B build
cmake --build build
# Equivalently, from inside build/:
cmake --build . --target install-editable
```

The target uses the absolute source directory, so it works from any build
location. Dependency upgrades and development checks remain explicit targets.

Task field headings in terminal list output use consistent bold emphasis; values
retain their normal text and semantic colors. Risks repeat an unnumbered Risk
heading for each entry, including configured and scoped list views.

Terminal Risk headers use severity colors: green for low, yellow for medium,
orange for high, and red for extreme. Headers remain bold and unnumbered; risk
values keep normal text and their existing colors. Color controls still apply.

`portfolios`, `managers`, and `pocs` share ordered-list formatting. A single
value prints beside a bold heading with a bold value; multiple values print
beneath a bold heading as normal, indented bullets. Empty collections are
omitted from document exports. Explicit terminal queries still show `None`.
Values can use YAML sequences, scalar text, or Markdown lists with `-`, `*`,
or `+` in literal (`|`) or folded (`>`) blocks. Commas and slashes remain text:

```yaml
portfolios:
  - Flight Research
  - Aircraft Systems
managers: Program Lead
pocs: >
  - Engineering Lead
  - Research Lead
```

In export and list configuration, `layout.context_colors: false` disables
automatic status, risk, priority, and budget colors (including table completion
shading). Explicit field colors and fixed heading/link styles remain available;
terminal `--color` and `NO_COLOR` still control ANSI output. Set metadata styles
independently of content selection:

```yaml
export:
  layout:
    context_colors: true
    metadata:
      portfolios:
        heading: true
        heading_bold: true
        bold: false
```

The same `layout` settings are supported under `list`. All three metadata fields
accept these boolean controls. Omit `bold` to use the single/multiple-value rule.
ASC profiles preserve their required metadata labels. Activity headings include
the letter and label, such as `Activity A: Aircraft Systems`; task numbering
remains unchanged. Automatic fiscal funding summaries use `Funding Totals` in
Word, SVG, and PowerPoint when fiscal metadata and task funding are selected.

Execution descriptions support the same heading control in export and list
configuration. Use ordered instructions when customizing the heading:

```yaml
export:
  elements:
    execution:
      - description:
        heading: false
      - activities:
```

Omit `heading` or set it to `true` to show the description heading. Keep the
`activities` entry to include activity definitions. The standard's top-level
Execution heading is independent. The same syntax works under `list.elements`;
existing mapping selections remain supported.

For a concise mapping, use `description: {heading: false}` under `execution`,
with a sibling `activities:` entry if activity definitions should be included.
This form also works under both export and list elements.

Export spacing can be customized per element while inheriting the document's
default. Both selection mappings and ordered instructions support `normal` and
`tight`:

```yaml
export:
  layout:
    spacing: normal
  elements:
    tasks:
      - spacing: tight
      - line: [number, label, status]
      - description:
    milestones:
      spacing: tight
    deliverables:
      spacing: normal
```

A spacing-only entry keeps the element's default content. Explicit field
selections retain their usual omission rules. Execution and its description and
activities, summary/background, resourcing prose, portfolios, managers, POCs and
contacts also support overrides. Omitted spacing inherits the nearest parent
or document setting. Task-table cells and terminal list spacing remain
independent. `planner fields config` includes more examples.

Generated task and activity heading numbers use a colon before the label,
including multipart children: `Task A.1.1: Child label`. Custom
`line: [number, label, status]` instructions and short number formats use the same
rule. Number-only table cells retain the number alone, and Word import still
accepts older period-separated headings.

Use `planner list tasks plan.yaml --parents` to collapse multipart tasks to
one parent summary while keeping standalone tasks. `planner list plan.yaml
--parents` also works for a full planning document. Filters apply to original
parts first; summaries show only matching parts and mark partial selections
(e.g. `[partial selection: 1/3 parts]`). Mixed values are indicated, and
funding totals and readiness retain their source-task rules. The flag also
works with positional fields, configured lists and `--ignore-config`. It is
independent of `export.layout.multipart` and applies only to task list views.

Task funding in list output uses dollar-prefixed values such as `$50K`, colored
green when terminal colors are enabled. Field-selected and configured lists use
the same convention; closed and unfunded tasks retain their muted colors.

Activity funding summaries also display dollar-prefixed green amounts, including
activities nested within execution and plan views.
