clutterxp 1.1.0__tar.gz

clutterxp-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not perf" --cov=clutterxp --cov-fail-under=90
+
+  crossfs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest -m crossfs
+
+  perf:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest -m perf
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install pip-audit && pip install -e .
+      - run: pip-audit
+
+  wheel-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --wheel
+      - name: Install and verify wheel in clean environment
+        run: |
+          python -m venv /tmp/clean_env
+          /tmp/clean_env/bin/pip install dist/*.whl
+          export PATH="/tmp/clean_env/bin:$PATH"
+          clutterxp --version
+          cxp --version
+          bash scripts/smoke_readme.sh
+

clutterxp-1.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.hypothesis/
+clutterxp.schema.json
+*.clutterxp-partial
+history.db*
+cache.db*
+.worktrees/

clutterxp-1.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes are recorded here. Format: Keep a Changelog; versions: SemVer.
+
+## [Unreleased]
+
+## [1.1.0] - 2026-11-06
+
+### Added
+- Complete PySide6 desktop GUI application launched via `clutterxp gui` with single-instance lock (`src/clutterxp/gui/`).
+- Seven dedicated GUI tabs: Dashboard (watcher state, summary stats, quick actions, event feed), Folders (watch folder configuration), Rules (rule list, interactive add/edit dialog, live trace test panel), Preview (interactive scan plan table with status filters and execute), History (operations journal with per-file and batch undo and refusal diagnosis), Duplicates (staged duplicate scanner with progress, cancellation, and quarantine action), Settings (global settings editor).
+- Engine duplicate quarantine service (`src/clutterxp/duplicates/quarantine.py`) moving redundant exact duplicates into timestamped isolation directories with full journal logging and undo capability.
+- Offscreen test suite verifying GUI views, models, background threading, cancellation guarantees, and CLI/Qt import isolation (`tests/gui/`).
+
+## [1.0.0] - 2026-11-06
+
+### Added
+- Configuration engine with YAML round-trip preservation, strict schema validation, and atomic writer (`src/clutterxp/config/`).
+- Rule engine with tokenization, prefix/token/substring/glob/regex matching, priority ambiguity resolution, and collision handling (`src/clutterxp/rules/`).
+- Safe mover implementing atomic same-filesystem `renameat2(RENAME_NOREPLACE)` and verified copy-then-unlink across filesystems (`src/clutterxp/mover/`).
+- History service with SQLite journal, transactional logging, single and batch undo, and crash recovery (`src/clutterxp/history/`).
+- Watch daemon with inotify event stream, settling and debouncing, self-event suppression, and loop prevention (`src/clutterxp/watch/`).
+- On-demand duplicate scanner with staged hashing (size, prefix hash, full sha256), caching, and safe quarantine (`src/clutterxp/duplicates/`).
+- Complete CLI application with `init`, `rules`, `organize`, `undo`, `history`, `watch`, `duplicates`, `service`, `doctor` commands and `--json` support (`src/clutterxp/cli/`).
+- Systemd user service installation, uninstallation, status inspection, and journal log viewing (`src/clutterxp/service_install.py`).
+- Automated smoke verification script for README quickstart (`scripts/smoke_readme.sh`).
+- CI workflows testing Python 3.10 through 3.13, cross-filesystem operations, linting, typechecking, vulnerability auditing, and clean wheel installation.
+- Packaging metadata with console scripts `clutterxp` and `cxp`, wheel package data inclusion (`schema.sql`, `py.typed`, `config.example.yaml`, `packaging/clutterxp.service`), and optional CPython acceleration via `ruamel.yaml.clib`.
+

clutterxp-1.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: clutterxp
+Version: 1.1.0
+Summary: Configurable, safe, lightweight file organizer: rules, preview, undo, watch, duplicates.
+Keywords: automation,cli,downloads,file-organizer,linux
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: ruamel-yaml-clib>=0.2.12; platform_python_implementation == 'CPython'
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: pyside6>=6.6; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# ClutterXP
+
+> **Tired of a messy Downloads folder?** ClutterXP quietly tidies your files into the right place—on your terms, without ever losing a single file.
+
+---
+
+Whether your `Downloads` folder is buried under months of receipts, PDFs, wallpapers, installers, and screenshots, or you just want your desktop kept neat, **ClutterXP** does the heavy lifting for you.
+
+Use the **clean visual desktop app** or run quick commands from your terminal.
+
+---
+
+## Why you can actually trust it
+
+Most file cleanup tools feel risky—what if they delete something important or move a file you didn't want touched? We built ClutterXP with ironclad safety guarantees:
+
+- 🛡️ **Never deletes or overwrites**: Files only move if the destination is safe. If a file with the same name already exists, ClutterXP renames the new one (e.g. `report (1).pdf`) or skips it. Your existing files are never replaced or destroyed.
+- 🎯 **Only moves what you tell it to**: If a file doesn't match a rule you created, it stays exactly where it is. No surprise moves, no mystery "unsorted" dump folders.
+- ↩️ **One-click instant undo**: Every action is saved in a local journal. If you ever change your mind, `clutterxp undo` (or a single click in the app) puts every file right back where it was originally.
+- 🔒 **100% private and offline**: Runs completely on your machine. No accounts, no cloud sync, no tracking, and zero internet requests.
+
+---
+
+## Getting Started
+
+### 1. Installation
+
+Install ClutterXP with Python (3.10+):
+
+```bash
+# Recommended: install with desktop app (GUI) support
+pip install "clutterxp[gui]"
+
+# Or on Kali Linux / Debian using pipx:
+pipx install .
+```
+
+### 2. Choose how you want to use it
+
+#### Option A: The Desktop App
+Just run:
+```bash
+clutterxp gui
+```
+You'll get an intuitive dashboard where you can:
+- **Preview moves before they happen** with a clear interactive table.
+- **Set up simple rules** with live matching tests (type a filename and see which rule catches it instantly).
+- **Find duplicate files** and safely quarantine them without risking accidental deletion.
+- **Undo any batch** with a single button.
+
+#### Option B: The Terminal (Fast & Scriptable)
+Prefer working from the command line? Use `clutterxp` or the short alias `cxp`:
+
+```bash
+# 1. Create your default starter config
+clutterxp init
+
+# 2. Test which rule matches a filename
+clutterxp rules test "invoice_march.pdf"
+
+# 3. Preview what would be organized (dry-run, touches nothing)
+clutterxp organize ~/Downloads --dry-run
+
+# 4. Organize your Downloads folder
+clutterxp organize ~/Downloads --yes
+
+# 5. Changed your mind? Undo the entire batch instantly!
+clutterxp undo --yes
+```
+
+---
+
+## Features that make life easier
+
+### 📁 Set it and forget it (Background Watcher)
+Turn on automatic sorting. Whenever a new download finishes, ClutterXP waits until it's completely written to disk, then quietly sorts it into place.
+```bash
+clutterxp watch
+```
+You can even enable it as a system background service:
+```bash
+clutterxp service install
+clutterxp service status
+```
+
+### 🔍 Find and clean duplicate downloads
+Downloaded the same PDF or installer three times? ClutterXP safely identifies duplicate files taking up storage, shows you where they live, and lets you isolate them safely.
+```bash
+clutterxp duplicates scan ~/Downloads
+```
+
+### ✏️ Customize your rules in seconds
+Rules are dead simple. Group by keywords, file extensions, size, or age:
+- *"Move anything with `invoice` or `receipt` to `~/Documents/Invoices`"*
+- *"Move `.png` and `.jpg` with `wallpaper` to `~/Pictures/Wallpapers`"*
+- *"Move `.deb`, `.iso`, `.rpm` to `~/Downloads/Installers`"*
+
+You can edit them directly in the visual app or via `clutterxp rules add`.
+
+---
+
+## Cheat Sheet
+
+| What you want to do | Command |
+|:---|:---|
+| Open the visual desktop app | `clutterxp gui` |
+| Preview organization without moving files | `cxp organize ~/Downloads --dry-run` |
+| Organize a folder | `cxp organize ~/Downloads` |
+| Undo the last batch of moves | `cxp undo` |
+| Watch a folder and sort new files automatically | `cxp watch` |
+| Install background watcher service | `cxp service install` |
+| Scan for duplicate files | `cxp duplicates scan ~/Downloads` |
+| Check system health and file integrity | `cxp doctor` |
+| View organization history | `cxp history` |
+
+---
+
+## License
+
+MIT

clutterxp-1.1.0/README.md

@@ -0,0 +1,120 @@
+# ClutterXP
+
+> **Tired of a messy Downloads folder?** ClutterXP quietly tidies your files into the right place—on your terms, without ever losing a single file.
+
+---
+
+Whether your `Downloads` folder is buried under months of receipts, PDFs, wallpapers, installers, and screenshots, or you just want your desktop kept neat, **ClutterXP** does the heavy lifting for you.
+
+Use the **clean visual desktop app** or run quick commands from your terminal.
+
+---
+
+## Why you can actually trust it
+
+Most file cleanup tools feel risky—what if they delete something important or move a file you didn't want touched? We built ClutterXP with ironclad safety guarantees:
+
+- 🛡️ **Never deletes or overwrites**: Files only move if the destination is safe. If a file with the same name already exists, ClutterXP renames the new one (e.g. `report (1).pdf`) or skips it. Your existing files are never replaced or destroyed.
+- 🎯 **Only moves what you tell it to**: If a file doesn't match a rule you created, it stays exactly where it is. No surprise moves, no mystery "unsorted" dump folders.
+- ↩️ **One-click instant undo**: Every action is saved in a local journal. If you ever change your mind, `clutterxp undo` (or a single click in the app) puts every file right back where it was originally.
+- 🔒 **100% private and offline**: Runs completely on your machine. No accounts, no cloud sync, no tracking, and zero internet requests.
+
+---
+
+## Getting Started
+
+### 1. Installation
+
+Install ClutterXP with Python (3.10+):
+
+```bash
+# Recommended: install with desktop app (GUI) support
+pip install "clutterxp[gui]"
+
+# Or on Kali Linux / Debian using pipx:
+pipx install .
+```
+
+### 2. Choose how you want to use it
+
+#### Option A: The Desktop App
+Just run:
+```bash
+clutterxp gui
+```
+You'll get an intuitive dashboard where you can:
+- **Preview moves before they happen** with a clear interactive table.
+- **Set up simple rules** with live matching tests (type a filename and see which rule catches it instantly).
+- **Find duplicate files** and safely quarantine them without risking accidental deletion.
+- **Undo any batch** with a single button.
+
+#### Option B: The Terminal (Fast & Scriptable)
+Prefer working from the command line? Use `clutterxp` or the short alias `cxp`:
+
+```bash
+# 1. Create your default starter config
+clutterxp init
+
+# 2. Test which rule matches a filename
+clutterxp rules test "invoice_march.pdf"
+
+# 3. Preview what would be organized (dry-run, touches nothing)
+clutterxp organize ~/Downloads --dry-run
+
+# 4. Organize your Downloads folder
+clutterxp organize ~/Downloads --yes
+
+# 5. Changed your mind? Undo the entire batch instantly!
+clutterxp undo --yes
+```
+
+---
+
+## Features that make life easier
+
+### 📁 Set it and forget it (Background Watcher)
+Turn on automatic sorting. Whenever a new download finishes, ClutterXP waits until it's completely written to disk, then quietly sorts it into place.
+```bash
+clutterxp watch
+```
+You can even enable it as a system background service:
+```bash
+clutterxp service install
+clutterxp service status
+```
+
+### 🔍 Find and clean duplicate downloads
+Downloaded the same PDF or installer three times? ClutterXP safely identifies duplicate files taking up storage, shows you where they live, and lets you isolate them safely.
+```bash
+clutterxp duplicates scan ~/Downloads
+```
+
+### ✏️ Customize your rules in seconds
+Rules are dead simple. Group by keywords, file extensions, size, or age:
+- *"Move anything with `invoice` or `receipt` to `~/Documents/Invoices`"*
+- *"Move `.png` and `.jpg` with `wallpaper` to `~/Pictures/Wallpapers`"*
+- *"Move `.deb`, `.iso`, `.rpm` to `~/Downloads/Installers`"*
+
+You can edit them directly in the visual app or via `clutterxp rules add`.
+
+---
+
+## Cheat Sheet
+
+| What you want to do | Command |
+|:---|:---|
+| Open the visual desktop app | `clutterxp gui` |
+| Preview organization without moving files | `cxp organize ~/Downloads --dry-run` |
+| Organize a folder | `cxp organize ~/Downloads` |
+| Undo the last batch of moves | `cxp undo` |
+| Watch a folder and sort new files automatically | `cxp watch` |
+| Install background watcher service | `cxp service install` |
+| Scan for duplicate files | `cxp duplicates scan ~/Downloads` |
+| Check system health and file integrity | `cxp doctor` |
+| View organization history | `cxp history` |
+
+---
+
+## License
+
+MIT

clutterxp-1.1.0/config.example.yaml

@@ -0,0 +1,76 @@
+# yaml-language-server: $schema=./clutterxp.schema.json
+# ClutterXP example configuration. Copy to ~/.config/clutterxp/config.yaml
+# (or run `clutterxp init`). Every name, keyword and folder below is an EXAMPLE:
+# nothing is built in. Edit, delete and add your own.
+
+version: 1
+
+settings:
+  collision: skip              # skip | rename   (what to do if the destination file name exists)
+  create_destinations: leaf    # never | leaf | all
+  match: token                 # default keyword mode: token | prefix | substring
+  case_sensitive: false
+  skip_hidden: true
+  follow_symlinks: false
+  confirm_threshold: 10        # ask before moving more than this many files at once
+  settle_seconds: 3            # how long a file must be quiet before the watcher moves it
+  verify_copy: size            # size | hash (only matters for cross-filesystem moves)
+  record_hash: false
+  history:
+    retention_days: 365
+    log_no_match: false
+  ignore: []                   # extra patterns to ignore everywhere
+  allow_chain: false           # keep false: destinations must not live inside watched folders
+
+# Folders to watch (and process with `clutterxp organize` when no path is given).
+# ANY folder works; Downloads is just an example.
+watch:
+  - path: ~/Downloads
+    recursive: false
+    settle_seconds: 3
+    rules: all                 # or a list of rule names that apply to this folder
+    initial_scan: false
+  - path: ~/Desktop
+    recursive: false
+    rules: [Screenshots, Invoices]
+    ignore: ["*.log"]
+
+rules:
+  - name: ProjectAlpha
+    priority: 10               # lower number wins
+    keywords: [alpha, pa, alpha-ctf]   # short aliases like "pa" match whole tokens only
+    destination: ~/Projects/ProjectAlpha
+    collision: rename
+
+  - name: Invoices
+    priority: 20
+    keywords: [invoice, inv, bill, receipt]
+    exclude: [draft]
+    extensions: [pdf, png, jpg]
+    destination: ~/Documents/Invoices/{year}/{month}
+
+  - name: College
+    priority: 30
+    keywords: [assignment, semester, lab, lecture]
+    destination: ~/College
+
+  - name: Screenshots
+    priority: 40
+    keywords: ["regex:^screenshot[ _-]"]
+    extensions: [png]
+    destination: ~/Pictures/Screenshots/{mtime:%Y-%m}
+
+  - name: Installers
+    priority: 50
+    extensions: [deb, appimage, run, rpm]
+    conditions:
+      min_size: 1MB
+    destination: ~/Software/Installers
+
+  - name: OldArchives
+    priority: 90
+    extensions: [zip, tar.gz, 7z]
+    conditions:
+      older_than: 30d
+    destination: ~/Archive/{year}
+    collision: rename

clutterxp-1.1.0/docs/00_PROJECT_PLAN.md

@@ -0,0 +1,135 @@
+# ClutterXP: Project Plan v0.2
+
+| | |
+|---|---|
+| Tool name | **ClutterXP** (command: `clutterxp`, short alias `cxp`, Python package `clutterxp`) |
+| Supersedes | `Clutter` plan v0.1 |
+| Platform | Linux first (developed and tested on Kali; nothing is Kali-specific), portable design |
+| Interfaces | CLI first (full product), GUI second (v1.1) |
+| Language | Python 3.10+ |
+
+## 1. Purpose
+
+ClutterXP is a configurable, lightweight, local file organizer. The user defines **rules** (keywords, aliases, extensions, size/age conditions, destinations). ClutterXP then sorts files from **any folders the user chooses** (Downloads is only the most common one) either on demand or automatically in the background.
+
+Nothing is built in. No category, keyword, or folder is hardcoded. Names such as "SecLeaf", "ThunderCipher" or "College" are only examples a user may configure.
+
+## 2. Non-negotiable principles
+
+1. **Explicit match or nothing.** A file moves only when a configured rule explicitly matches. No match: the file stays exactly where it is. No automatic "Unsorted" folder.
+2. **Never guess.** Equal-priority conflicts are reported as *ambiguous*, not resolved silently.
+3. **Never lose data.** No automatic deletion. A move never overwrites. The source is removed only after the destination is verified.
+4. **Reversible.** Every move is journaled and can be undone, singly or per batch.
+5. **Preview first.** Anything bulk can be previewed; bulk applies ask for confirmation.
+6. **Cheap.** No content reading or hashing during sorting. Event-driven watching, no polling or periodic full scans.
+7. **Local and private.** No network access, no telemetry, DB and logs are `0600`.
+8. **One engine.** CLI, watcher and GUI all call the same `Organizer` facade.
+
+## 3. Folders are fully custom
+
+- Any folder can be organized or watched: `clutterxp organize ~/Desktop`, `clutterxp watch /mnt/data/inbox`.
+- Folders can be listed in config (`watch:` section) with **per-folder settings**: recursive on/off, extra ignore patterns, settle time, and an optional **subset of rules** that apply to that folder.
+- Files can arrive in a folder by download, copy, drag-and-drop, or being moved in by another program. The watcher handles `created`, `moved-in` and `closed-after-write` events uniformly.
+- Ad-hoc folders never need to be in config: a path argument always wins.
+
+## 4. What changed from v0.1 (review findings, all adopted)
+
+| # | Finding | Resolution in v0.2 |
+|---|---|---|
+| 1 | Token matching undefined | Precise tokenizer, match modes, test vectors: `docs/02_RULE_ENGINE.md` |
+| 2 | `priority` contradicts "ambiguous" | Lower number wins; ambiguity only at equal best priority with different destinations |
+| 3 | Move atomicity and cross-filesystem safety | No-clobber atomic primitive and verified copy protocol: `docs/04_SAFE_MOVER.md` |
+| 4 | Download completion vague, and not only Downloads | Settle algorithm for any folder, moved-in files, open-for-write check: `docs/06_WATCHER.md` |
+| 5 | Undo/history integrity | Journal-first protocol, crash recovery, batches, verification: `docs/05_HISTORY_UNDO.md` |
+| 6 | Config validation | Pydantic schema, strict keys, comment-preserving edits, JSON Schema export: `docs/03_CONFIG.md` |
+| 7 | Safety gaps | Invariants, loop prevention, root refusal, lock, system-dir denylist: `docs/09_SAFETY.md` |
+
+## 5. Feature set (prioritized for efficiency)
+
+**P0: core product (v1.0 cannot ship without these)**
+
+| Feature | Why it earns its place |
+|---|---|
+| Rules: keywords, `all_of`, `exclude`, extensions, size, age | Covers real sorting needs with metadata that is already in `stat()` (free) |
+| Safe token matching + `glob:` / `regex:` escape hatches | Avoids the `sl` matches `slides` class of bugs |
+| Priority + ambiguity detection | Predictable, explainable outcomes |
+| `rules test <filename>` | Debug rules in seconds; pure function, almost free to build |
+| `scan` / `organize --dry-run` / `organize` | Preview before acting |
+| Safe mover (no-clobber, verified cross-FS) | The riskiest code; gets the most tests |
+| History, batch IDs, `undo` (op / batch / file) | Trust: everything reversible |
+| `watch` with settle detection | Automatic sorting for any folder |
+| Config validation + `config validate` + `doctor` | Fail early with clear messages |
+| Lock file + root refusal + system-dir denylist | Safety invariants |
+
+**P1: included in v1.0 (cheap, high value)**
+
+| Feature | Notes |
+|---|---|
+| Destination templates `{year}` `{month}` `{ext}` `{mtime:%Y-%m}` | Sub-sorting without extra rules |
+| Per-folder watch config + rule subsets | Makes "any folder" real |
+| Built-in + custom ignore patterns | Browser temp files, torrent clients, dotfiles |
+| Collision policy per rule: `skip` / `rename` | Defined behavior instead of "don't overwrite" |
+| `--json` output on every command | Scripting; also the GUI test oracle |
+| Duplicate scan: size, then partial hash, then full SHA-256, with hash cache | Fast on re-runs; never runs during sorting |
+| `service install` (systemd `--user`) | Real background operation |
+| `init`, `config schema`, shell completion | Onboarding; editor autocomplete via JSON Schema |
+| Crash recovery (`doctor --fix`) | Pending journal reconciliation |
+
+**P2: after v1.0**
+
+| Feature | Release |
+|---|---|
+| PySide6 GUI (same engine) | v1.1 |
+| `duplicates quarantine` (move, never delete, undoable, confirmed) | v1.1 |
+| Desktop notifications (`notify-send`) | v1.2 |
+| Rule import/export packs | v1.2 |
+| Optional magic-byte type detection (opt-in, reads first bytes only) | v1.2 |
+| Other OS support (macOS first) | v2.0 |
+
+**Rejected on purpose:** AI/content classification, fuzzy filename matching, auto-delete, cloud sync, telemetry. Each adds cost or risk that contradicts the principles above.
+
+## 6. Milestones
+
+See `docs/13_ROADMAP.md`. Short form:
+
+| Milestone | Delivers |
+|---|---|
+| M1 Core | config, rule engine, scanner, planner, safe mover, `scan/organize/rules` |
+| M2 History | SQLite journal, `history`, `undo`, batches, recovery |
+| M3 Watch | watcher, settle detection, per-folder config, reload |
+| M4 Duplicates | staged hashing, cache, reports |
+| M5 Product | CLI polish, `--json`, service, `doctor`, packaging |
+| M6 Hardening | QA, fault injection, security review, perf budgets. **v1.0** |
+| M7 GUI | PySide6 app. **v1.1** |
+
+## 7. Document map
+
+```
+README.md                  what is in this package and how to start
+STARTER_PROMPT.md          paste-ready multi-agent kickoff prompt
+AGENTS.md / CLAUDE.md      standing rules for every AI agent
+docs/00_PROJECT_PLAN.md    this file
+docs/01_ARCHITECTURE.md    layers, data flow, threading, contracts
+docs/02_RULE_ENGINE.md     matching semantics and test vectors
+docs/03_CONFIG.md          schema, validation, locations, edits
+docs/04_SAFE_MOVER.md      atomic move and cross-FS protocol
+docs/05_HISTORY_UNDO.md    SQLite schema, journaling, undo, recovery
+docs/06_WATCHER.md         events, settle, loop prevention, signals
+docs/07_DUPLICATES.md      staged duplicate detection
+docs/08_CLI.md             every command, flag, output, exit code
+docs/09_SAFETY.md          invariants, threat model, denylist
+docs/10_TESTING.md         strategy, fixtures, fault injection, CI
+docs/11_PACKAGING.md       pyproject, pipx, systemd, Kali notes
+docs/12_GUI.md             PySide6 design (v1.1)
+docs/13_ROADMAP.md         milestones, waves, backlog
+docs/14_DECISIONS.md       decision log with rationale
+docs/15_ACCEPTANCE.md      numbered acceptance criteria per milestone
+docs/16_RISKS.md           risk register
+prompts/                   orchestrator + one prompt per agent
+src/clutterxp/models.py    FROZEN data contracts
+src/clutterxp/interfaces.py FROZEN module interfaces
+src/clutterxp/config/schema.py  FROZEN config field names/types (Pydantic)
+src/clutterxp/units.py     size/duration parsing shared by config and rules
+config.example.yaml        annotated example configuration
+packaging/, .github/       systemd unit template, CI workflow
+```