Metadata-Version: 2.4
Name: tuxfan-planner
Version: 0.2.22
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
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 Word plans,
SVG diagrams, and fiscal-month Gantt charts in SVG or editable PowerPoint format.

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

## 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 tasks data/tasks.yaml
planner export data/tasks.yaml /tmp/plan.docx --export-options planner/examples/export-options.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

- [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)
- [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 KIND` | Show concise task details grouped by activity. |
| `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 execution section and milestone, plus funding totals. |
| `schedule` | Show tasks in dependency order and their readiness. |
| `export` | Write a Word (`.docx`) or SVG (`.svg`) plan. |
| `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` for arguments and examples, or see the
[CLI reference](docs/cli.rst).

The legacy `tuxfan-planner` command remains available as an alias.
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
tasks:
  - id: DraftDesign
    label: Draft aircraft design
    description: Produce the initial airframe design.
    start: M1Q1FY27
    expected: 2
    priority: high
    status: pending
    risk:
      - type: schedule
        level: low
        mitigation: Review progress weekly.
```

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

`id` identifies the task for dependency references; `label` is its display name.
`execution_section` links tasks to the corresponding entry in `execution.sections`. 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 `expected`. For example:

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

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:

- `portfolio`: portfolio or parent program name.
- `project`: high-level project name.
- `managers`: list of manager names.
- `pocs`: list of point-of-contact names.
- `summary`: high-level plan summary.
- `fiscal_range_begin` and `fiscal_range_end`: optional fiscal year range covered by the plan, for example `27` through `31`.
- `execution`: execution metadata. It can be a mapping with `overview` text and `sections`, where each section has `label`, `description`, and an optional stable `id` for task links. The older flat list of sections is still accepted.

### Planning placeholders

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

```yaml
tasks:
  - id: FUTURE_DESIGN
    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 defaults to `low` and risks to an empty list. A start or duration
may be supplied individually, but timing remains `Unscheduled` until both `start`
and `expected` 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`, and `status: closed`
and display `CLOSED` in schedules. Execution section, timing, priority, and risk are optional;
supplied values are validated. Without both `start` and `expected`, timing remains
`Unscheduled` and no Gantt bar is drawn. They use the same gray styling as unfunded tasks. 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 `execution_section` 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. `start`, `expected`, `priority`, and `risk`
are optional for closed tasks, [planning placeholders](#planning-placeholders),
[ongoing tasks](#ongoing-tasks-and-funding), and complete
tasks with a `completed` period:

- `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 site or institution label.
- `bnr`: optional budget and reporting identifier.
- `type`: optional task type label.
- `tags`: optional comma-separated string or list of task tags. Omitted or null values mean no tags.
- `execution_section`: optional ID of a section under `execution.sections`. Linked tasks use that section'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`: required positive whole number of months for the task duration. The end month is computed from `start`, counting the start month as month one.
- `completed`: optional fiscal period string for work that is already complete. A task with `status: complete` and `completed` may omit planning-only fields: `start`, `expected`, `priority`, and `risk`. 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`: required string priority label such as `low`, `medium`, `high`, or `urgent`.
- `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`: required risk entry or list of risk entries. Each entry has `type`, `level`, and `mitigation`, and may include `description`; `level` must be `low`, `medium`, `high`, or `extreme`.
- `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
    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

Top-level can be either a list of tasks or a mapping with a `tasks` key. The mapping form can also include plan-level metadata such as `portfolio`, `project`, `managers`, `pocs`, `summary`, `fiscal_range_begin`, `fiscal_range_end`, and `execution`.

```yaml
portfolio: 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:
  overview: >
    Overall execution context for the plan.
  sections:
    - 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
    label: Draft architecture
    bnr: EXAMPLE-001
    site: Example Works
    type: labor
    tags:
      - architecture
    execution_section: deliverable_a
    description: Produce the first architecture draft.
    start: M1Q3FY26
    expected: 2
    milestones: [Design]
    priority: high
    status: complete
    dependencies: []
    risk:
      - type: scope
        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
    label: Build parser
    description: Load task definitions from YAML and Python files.
    start: M2Q3FY26
    expected: 1
    milestones: [Implementation]
    priority: high
    status: pending
    dependencies:
      - DraftArchitecture
    risk:
      - type: integration
        level: medium
        mitigation: Add schema validation tests for both YAML and Python task sources.

  - id: MultiYearDelivery
    label: Multi-year delivery
    site: Example Works
    parts:
      - id: A
        label: First phase
        funding: {fy27: 50K}
        description: Complete the first phase.
        start: M1Q1FY27
        expected: 6
        milestones: [Phase_A]
        priority: high
        status: active
        dependencies: []
        risk:
          - type: schedule
            level: low
            mitigation: Review progress monthly.
      - id: B
        label: Second phase
        funding: {fy28: 100K}
        description: Complete the second phase.
        start: M1Q3FY27
        expected: 18
        milestones: [Phase_B]
        priority: medium
        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

Use `planner list KIND [task_file] [FIELD ...]` to select the objects to display.
With `TUXFAN_PLANNER_DATAFILE` configured, omit `task_file`.

| 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 execution section, including empty sections, 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 overview/sections, and relationship summaries |

```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`, `sections`, `tags`,
`milestones`, `deliverables`, or `workitems`. Relationship targets accept IDs or
labels (workitems use their IDs). Singular aliases work, and `producers`/`producer`
aliases `tasks`. Targeted values match whole values; bare values match literal
substrings. 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
```

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 magenta so they stand out from labels and prose. Closed/unfunded entries
keep their gray color, with bold IDs. Plain and redirected automatic output
remain uncolored; `--color always` can explicitly enable the highlighting.

`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.
All divider lines end at column 82, including indented dividers between parts.

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 `Total Funding:` line at the bottom shows every year in thousands of dollars, including `$0K` years. Linked activity headings also show their execution section descriptions. Activity/task descriptions and notes wrap at 80 terminal columns, accounting for wide characters, combining marks, and styling. A gray block line separates tasks within an activity. Darker gray double rules align with activity headings before each activity and between its description and first task. 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` or `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.

prints the full task details in calculated end-month order, including the start and end fiscal periods and duration in months.

### 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,
execution-section 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 sections=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`, `sections`, `tags`, `milestones`, and `deliverables`; singular names
also work. Activities match an activity name, section 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 sections=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
```

Types are `plan`, `task`, `workitem`, `risk`, `milestone`, `deliverable`, `execution`, and
`section`; plural names `tasks`, `workitems`, `milestones`, `deliverables`, and `sections` are
also accepted, as is `execution.sections`. 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.

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

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, and `level` means risk levels.
Risk levels print in severity order: `low`, `medium`, `high`, `extreme`.
Priorities print in order: `low`, `medium`, `high`, `urgent`.
Task statuses are alphabetical with `closed` last; work item statuses print `open`, then `closed`.
Only `status`, `priority`, `level`, `deliverables.type`, and `deliverables.status`
are accepted by `avail`.
`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 execution section 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`.

## Exporting

The output filename selects the format. `export` requires an options path from
`--export-options` or `TUXFAN_PLANNER_EXPORT_OPTIONS`; the following examples
configure the supplied sample. `export-gantt` does not use export options.

```bash
export TUXFAN_PLANNER_EXPORT_OPTIONS=planner/examples/export-options.yaml
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
```

All Word, plan SVG, and Gantt SVG/PowerPoint exports include centered, bold
`CUI//SP-BDGT` headers and footers. Word repeats them on every page; PowerPoint
includes them on every slide.

### Word and SVG 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. Add `--include-note` or set `include_note: true` in export options to show an italic `Note:` line after each task description. Use `--export-options PATH` or `TUXFAN_PLANNER_EXPORT_OPTIONS` 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 and alignment apply only to Word.

### 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 gray unfunded entries,
are preserved. Other CLI commands and `export-gantt` retain their original text.
Notes in exports still require
`--include-note` or `include_note: true` to appear.

### Export options

Export options files can be YAML, YML, or Python. The supported settings are `task_table_attributes`, `task_table_columns`, and `include_note`. The first two control the optional task attribute columns included in the Word export summary table and the attributes shown on SVG task cards. Custom labels and alignment apply only to Word. The `.docx` table always starts with an unlabeled column containing generated task numbers; it does not include a Project column. An `Activity A`, `Activity B`, etc. row precedes each activity's tasks, which appear in numeric task order. When tasks link to execution sections, the activity row includes the section label and its letter follows section order (for example, `Activity B: Specialization Work` with `Task B.1`). Unlinked tasks appear together under Unassigned. Each activity label occupies one left-aligned cell spanning the table. The column header repeats only when the table continues onto another page; Activity rows appear at their normal group transitions. All table cells center their content vertically. Fiscal-year columns are added automatically when plan fiscal years are configured, with a final `Total Funding` row that counts parent budgets once when present, otherwise summing included part amounts. For completed tasks, those columns become one green-filled cell labeled with the completion year (for example, `Completed FY26`) when a `completed` period is available, or `Completed` otherwise; the other cells remain black on white. The optional task metadata columns are limited to the attributes listed here. Word task descriptions do not append parenthesized attributes or funding details.

Set `include_note: true` in an export options file, or pass `--include-note` to `export`, to show italic notes, including the `Note:` label, after task descriptions. Task note lines are hidden by default. Select `note` as a table attribute when you also want a Note column in the Word summary table.

In the Word risk mitigation section, the bold risk label is green for `low`, yellow for `medium`, orange for `high`, and deep red for `extreme`. Mitigation text remains black.

Top-level Word section labels, including `Tasks:`, are bold and underlined.

Supported attribute names:

- `bnr`
- `funding`
- `note`
- `workitems`
- `site`
- `type`
- `tags`

Simple YAML:

```yaml
task_table_attributes:
  - site
  - bnr
  - tags
```

Shorthand YAML with custom labels:

```yaml
task_table_attributes:
  - bnr: BNR
  - tags: Keywords
```

Recommended explicit YAML when you need labels or alignment:

```yaml
task_table_columns:
  - attribute: bnr
    label: BNR
  - attribute: tags
    label: Keywords
```

Supported column alignment values:

- `left`
- `center`
- `right`

`alignment` is optional and defaults to `center`.

Example CLI usage:

```bash
planner export planner/examples/tasks.yaml /tmp/plan.docx --export-options planner/examples/export-options.yaml
```

## 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
    label: Tool maintenance
    description: Maintain the planning tool.
    status: ongoing
    funding: {fy27: 50K}
```

The three 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.
Without defaults, `site`, `bnr`, and `type` 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 defaults to `low`; 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 `execution_section`, `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:
  sections:
    - !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
export-options 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` and `spell-check` reject composite plans before
tools, prompts, or changes. They can operate on individual fragments without
includes or on the standalone output. 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 = {
    "portfolio": "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": {
        "overview": "Overall execution context for the plan.",
        "sections": [
            {
                "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",
            "label": "Draft architecture",
            "bnr": "EXAMPLE-001",
            "site": "Example Works",
            "type": "labor",
            "tags": ["architecture"],
            "execution_section": "deliverable_a",
            "description": "Produce the first architecture draft.",
            "start": "M1Q3FY26",
            "expected": 2,
            "milestones": ["Design"],
            "priority": "high",
            "status": "complete",
            "dependencies": [],
            "risk": [
                {
                    "type": "scope",
                    "level": "medium",
                    "mitigation": "Review the architecture with stakeholders before implementation starts.",
                }
            ],
            "funding": {"fy27": "50K", "fy29": "100K"},
        }
    ],
}
```

## Configuration and optional tools

Environment variables provide input and export defaults. Formatting, spell
checking, and shell completion are optional conveniences.

### Environment variables

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
export TUXFAN_PLANNER_EXPORT_OPTIONS=planner/examples/export-options.yaml
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.

If you set `TUXFAN_PLANNER_EXPORT_OPTIONS`, the Word and SVG plan exports use that file by default:

```bash
export TUXFAN_PLANNER_EXPORT_OPTIONS=planner/examples/export-options.yaml
planner export planner/examples/tasks.yaml /tmp/plan.docx
```

`export` fails with exit status 1 if neither the environment variable nor
`--export-options` provides a non-empty path. Empty values are treated as unset.
A non-empty environment value takes precedence over the option, with a warning
when both paths are supplied. To use default export settings, provide a YAML
file containing `{}`. Relative options paths use the current directory.

### 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)
```

The generated completion supports the basic planner subcommands, the
`tuxfan-planner` alias, file path completion for task and output arguments, and
`--export-options` 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`.

### 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 Google's
[yamlfmt](https://github.com/google/yamlfmt), installed separately from pip:

```bash
brew install yamlfmt
# Alternatively, with Go installed:
go install github.com/google/yamlfmt/cmd/yamlfmt@latest
```

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. Only that file is formatted;
Python inputs are never executed. The formatter runs from the data file's
parent directory and uses its normal configuration discovery. YAML comments,
quotes, anchors, and block strings are handled by yamlfmt. Source encoding and
line-ending convention are retained. YAML structure and values are checked
before saving; formatter failures leave the source untouched.

Changed files receive a numbered `.bak` backup and are replaced atomically.
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. 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.

Spelling checks cover prose: plan/project names, managers/contacts, summaries,
execution narratives, task and milestone labels/descriptions, notes,
deliverable labels/descriptions, risk descriptions/mitigations/types, and task site/type/tags.
Schema keys, IDs/references, fiscal periods, status/priority/risk-level 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 checks. Concurrent source changes stop saving; symbolic
links require running on the resolved target. 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 use Aspell's standard personal
dictionary or the path specified by `--personal` and are saved only after the
final prompt. Other planner commands work without Aspell.

## 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, execution sections, 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.
