Add Org refile configuration

1 files changed, 108 insertions, 0 deletions

diff --git a/docs/plans/2026-04-10-org-refile-implementation.md b/docs/plans/2026-04-10-org-refile-implementation.md
new file mode 100644
index 0000000..687e86d
--- /dev/null
+++ b/docs/plans/2026-04-10-org-refile-implementation.md
@@ -0,0 +1,108 @@
+# Org Refile Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Configure Org refile so entries can be moved to any heading in `org-agenda-files` with a clearer Vertico-friendly path-based prompt.
+
+**Architecture:** Reuse the existing agenda discovery helper to keep `org-agenda-files` current before refile, then configure built-in Org refile variables in `lisp/ss-org.el`. Add narrow ERT coverage for the helper and settings, and update `README.md` so the documented workflow matches the configuration.
+
+**Tech Stack:** Emacs Lisp, Org mode, ERT, Vertico, Orderless, Marginalia
+
+---
+
+## Chunk 1: Refile Configuration
+
+### Task 1: Add refile refresh helper and Org settings
+
+**Files:**
+- Modify: `lisp/ss-org.el`
+- Reference: `lisp/ss-agenda.el`
+
+- [ ] **Step 1: Write the failing test**
+
+Add ERT coverage that loads `ss-org`, stubs agenda refresh behavior, runs the
+new setup helper, and asserts:
+
+- `org-refile-targets` points at `org-agenda-files`
+- unlimited heading depth is enabled
+- outline-path completion is enabled
+- the direct path completion flow is selected
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `emacs --batch -Q -L lisp -l tests/ss-org-tests.el -f ert-run-tests-batch-and-exit`
+Expected: FAIL because the refile helper and settings do not exist yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+- Add a small helper in `lisp/ss-org.el` that refreshes `org-agenda-files`
+  before refile, reusing `ss-refresh-org-agenda-files` when available.
+- Configure Org refile variables during `ss-org-setup`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `emacs --batch -Q -L lisp -l tests/ss-org-tests.el -f ert-run-tests-batch-and-exit`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Wait for verification and user approval before creating a commit.
+
+## Chunk 2: Documentation and Startup Verification
+
+### Task 2: Document the refile workflow
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Write the failing test**
+
+The failing condition is documentation drift: the README currently does not
+describe refile behavior.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Review `README.md` and confirm it lacks refile documentation.
+
+- [ ] **Step 3: Write minimal implementation**
+
+- Add a short note describing that Org refile targets any heading in
+  `org-agenda-files` and uses path-based minibuffer completion.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Review the updated text against the code for accuracy.
+
+- [ ] **Step 5: Commit**
+
+Wait for verification and user approval before creating a commit.
+
+### Task 3: Verify the full startup path
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Write the failing test**
+
+Use the repository's normal startup verification path in addition to the new
+targeted ERT coverage.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Not applicable before implementation.
+
+- [ ] **Step 3: Write minimal implementation**
+
+No code changes in this task.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `emacs --batch -Q --load ./init.el`
+Expected: exits successfully.
+
+Run: `emacs --batch -Q -L lisp -l tests/ss-org-tests.el -f ert-run-tests-batch-and-exit`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Wait for verification and user approval before creating a commit.
\ No newline at end of file