From 84447d1d2cbe05f1d3f47452586e4e1a6ff79ecf Mon Sep 17 00:00:00 2001
From: Frank Schwenk <frank@frank-schwenk.de>
Date: Sat, 18 Jul 2026 17:34:12 +0200
Subject: [PATCH] docs: add cleanup roadmap for quality pass

Phase 0 analysis and prioritized roadmap for the cleanup/quality-pass branch.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLEANUP_PLAN.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 CLEANUP_PLAN.md

diff --git a/CLEANUP_PLAN.md b/CLEANUP_PLAN.md
new file mode 100644
index 0000000..5412203
--- /dev/null
+++ b/CLEANUP_PLAN.md
@@ -0,0 +1,57 @@
+# Cleanup Plan — imagepipeline quality pass
+
+Branch: `cleanup/quality-pass`  
+Started: 2026-07-18
+
+## Phase 0 findings (summary)
+
+| Area | Risk | Notes |
+|------|------|-------|
+| Core (runner, resume, pipeline) | Medium | Solid tests; `xcf_stack` special-case in runner — defer refactor |
+| Modules | Low–Medium | `gmic_grayscale` missing `finalize_gmic_output` (resume parity) |
+| Dependencies | High | `dependencies = []` but Pillow/numpy imported at module load |
+| Pipelines | Low | Machine-local paths intentional (SOUL); stale `CONTINUE_FROM` left as-is |
+| Tests | Medium | 87/88 pass; watermark integration fails on darktable-cli 5.6 |
+| Tooling | Safe | No linter/formatter/CI |
+
+## Roadmap
+
+### Phase 1 — Low-risk quick wins
+- [x] Add Ruff (lint + format) and apply once
+- [x] Expand `.gitignore`
+- [x] Remove dead duplicate branch in `imagemagick_grayscale`
+- [x] Fix flaky `test_watermark_pipeline` (darktable probe skip)
+
+### Phase 2 — Structure & config
+- [x] Explicit `import imagepipeline.modules` in `pipeline.py`
+- [x] `gmic_grayscale`: call `finalize_gmic_output` (parity with `gmic`)
+- [ ] Pipeline `CONTINUE_FROM` reset — **skipped** (machine-local resume state)
+- [ ] `xcf_stack` runner hook — **deferred** (medium refactor risk)
+
+### Phase 3 — Code quality
+- [x] Pytest markers (`integration`, `slow`)
+- [ ] Broad dedup of pipeline scripts — **deferred** (domain-specific, RECIPES first)
+
+### Phase 4 — Dependencies & CI
+- [x] Declare Pillow in core; numpy in dev for import-time ai_tone_map
+- [x] Add Ruff to dev extras
+- [x] Gitea Actions: pytest on push
+
+### Phase 5 — Docs
+- [x] README sync (resume, `.env`, `[ai]`, external tools)
+- [x] `docs/ARCHITECTURE.md`, `CONTRIBUTING.md`
+- [x] `LICENSE` (MIT, matches pyproject)
+
+## Known bugs (not fixed — behavior change or out of scope)
+
+1. **darktable-cli 5.6** — integration test fails locally; style file exists but CLI exits 1 on PNG export (possible upstream CLI change).
+2. **Eager module imports** — `ai_tone_map` pulls numpy at import; mitigated via dev dep, not lazy-import refactor.
+
+## Verification
+
+```bash
+pip install -e ".[dev,ai]"
+ruff check .
+ruff format --check .
+pytest
+```