Planning

The planning phase reads classifier output and generates a complete move/rename plan. No files are touched. The plan is a proposal that requires human review before execution.

What planning produces

The planner reads classifier_output.csv from the most recent classification job and produces two outputs:

1. plan.csv — machine-readable plan with one row per proposed operation
2. plan_preview.md — human-readable dry-run summary for review

Both are written to the job directory. Neither modifies the filesystem.

---

plan.csv format

Each row in plan.csv describes a single proposed operation:

Column	Description
source_path	Current absolute path of the file
destination_path	Proposed absolute path after reorganization
proposed_name	New filename (following naming convention)
operation_type	move, rename, move_rename, or skip
confidence	Confidence score for this operation (0.0—1.0)
reason	Why this operation was proposed

Files marked skip remain in place. The reason column explains why: Tier 1 manual-only, already in correct location, or insufficient confidence.

---

Schema-driven destinations

The planner reads schema.yaml to compute destination paths. Each file’s proposed category (from classification) maps to a directory in the schema. The schema defines the target directory structure:

version: 1
categories:
  financial:
    path: "financial/records"
  medical:
    path: "medical"
  projects:
    path: "projects/{entity}"

If a file was classified with category financial, the planner proposes moving it to financial/records/ under the target root. Entity tokens in the schema path are resolved from the classifier’s entity extraction.

---

Naming convention

The planner applies the naming pattern defined in fialr.toml to generate proposed filenames:

[naming]
pattern = "{date}_{entity}_{descriptor}_{version}.{ext}"

The pattern follows fialr’s naming convention: YYYY-MM-DD_[entity]_[descriptor]_[version].[ext]. Tokens are sourced from classifier metadata, filesystem timestamps, and path heuristics. See Naming Convention for the full specification.

---

Conflict detection

The planner flags three categories of conflicts:

• Naming conflicts — two files would receive the same proposed name. The planner appends a disambiguation suffix and flags the conflict in the reason column.
• Path collisions — a proposed destination already contains a file at the target path. The operation is marked skip with the collision noted.
• Tier 1 manual-only — Tier 1 files are never included in automated plans. They appear in plan.csv with operation type skip and reason tier-1-manual-only.

All conflicts are surfaced in plan_preview.md in a dedicated section.

---

Running the planner

fialr plan ~/Documents

The planner reads the most recent classifier output for the target directory and writes the plan to the job directory:

jobs/2026-03-11_plan_a1b2c3d4/
  plan.csv
  plan_preview.md
  log.json
  report.md

Terminal output summarizes the plan:

2,847 files planned.
  Move: 1,204
  Rename: 389
  Move + rename: 847
  Skip: 407
  Conflicts: 12

---

Review workflow

The plan must be reviewed before execution. This is enforced, not optional.

1. Open plan_preview.md for a human-readable summary of proposed operations
2. Inspect plan.csv directly if you need to verify individual files
3. Edit plan.csv if any operations should be changed — modify destination paths, change operation types to skip, or adjust proposed names
4. Set the reviewed flag to mark the plan as approved

Until the reviewed flag is set, the executor refuses to run. There is no override.

# Mark the plan as reviewed after inspection
fialr plan ~/Documents --reviewed

---

What comes next

An approved plan is the input for reorganization, where files are actually moved and renamed according to the plan.

For the full command reference, see fialr plan.