Reorganization

Reorganization is where files actually move. The executor reads an approved plan.csv and carries out each operation with hash verification at every step. This is the first phase that modifies the filesystem.

Reviewed flag requirement

The executor refuses to run against a plan that has not been explicitly reviewed. If the reviewed flag is not set, execution halts immediately with an error. There is no --force flag. There is no override.

This is a deliberate gate. The planning phase produces the plan. A human reviews it. Only then does execution proceed.

---

Hash verification discipline

Every file operation follows the same sequence:

1. Hash before. Compute BLAKE3 hash of the file at its current location.
2. Execute. Perform the move, rename, or move-and-rename.
3. Hash after. Compute BLAKE3 hash of the file at its new location.
4. Compare. If hashes do not match, the operation is logged as a failure and the file is restored to its original location.

Both hashes (before and after) are written to the operation log. This creates an auditable chain of custody for every file. A hash mismatch during reorganization halts the job. No subsequent operations execute until the mismatch is resolved.

---

Provenance preservation

Before any file is modified, its original identity is recorded in two places:

Storage	Attribute	Value
XATTR	com.fialr.original_name	Filename before rename
XATTR	com.fialr.original_path	Full path before move
XATTR	com.fialr.job_uuid	UUID of the job that performed the operation
SQLite	paths table	Historical path record linked to content hash
SQLite	operations table	Append-only audit entry with before/after state

The operations table is append-only. It is never modified or deleted. Every operation that has ever been performed on a file is recoverable from this ledger. See Job Execution Model for the full lifecycle.

---

Checkpoint and resume

The executor writes a checkpoint after every N files (configurable in fialr.toml):

[executor]
checkpoint_interval = 50

The checkpoint records the index of the last completed operation. If the job is interrupted — by crash, power loss, or user cancellation — it resumes from the last checkpoint:

jobs/2026-03-11_organize_a1b2c3d4/
  plan.csv
  checkpoint.json    ← last completed operation index
  log.json
  report.md

Resuming a job re-verifies the hash of the last checkpointed file before continuing. No operations are repeated. No files are left in an intermediate state.

---

Rename engine

The rename engine applies the naming pattern from fialr.toml to generate filenames:

YYYY-MM-DD_[entity]_[descriptor]_[version].[ext]

Token sources:

Token	Primary Source	Fallback
date	Document subject date (from classifier metadata)	mtime
entity	Entity extraction from classifier	Directory name heuristic
descriptor	Semantic descriptor from classifier or enrichment	Original filename, cleaned
version	Version detection (v1, v2, draft, final, signed)	Omitted if no version detected
ext	MIME-derived canonical extension	Original extension, lowercased

Filenames are lowercased. Hyphens separate words within tokens. Underscores separate tokens. Spaces, parentheses, brackets, and special characters are removed. Generic names (scan001, untitled, document, copy-of) are rejected and replaced with descriptors from the classification or enrichment output.

---

Organize module

The organize command coordinates the executor and rename engine in a single operation. It reads the approved plan, applies the schema-driven directory structure, and executes all moves and renames:

fialr organize ~/Documents

This is the primary command for reorganization. It wraps the executor and rename engine into a single job with unified logging, checkpointing, and hash verification.

Output:

jobs/2026-03-11_organize_a1b2c3d4/
  plan.csv
  checkpoint.json
  log.json
  report.md

Terminal output reports progress and final results:

1,204 files moved. 389 renamed. 847 moved and renamed.
0 hash mismatches. 0 failures.
407 files skipped (23 Tier 1, 384 already in place).

---

What comes next

After reorganization, run deduplication to identify and resolve duplicate files in the reorganized structure. Or run validation to verify the integrity of all moved files against the manifest.

For the full command reference, see fialr organize.