2 files changed, 178 insertions, 0 deletions
diff --git a/docs/plans/2026-04-10-org-refile-design.md b/docs/plans/2026-04-10-org-refile-design.md
new file mode 100644
index 0000000..ae7e881
--- /dev/null
+++ b/docs/plans/2026-04-10-org-refile-design.md
@@ -0,0 +1,70 @@
+# Org Refile Design
+
+## Context
+
+The configuration already has the core minibuffer completion stack in place:
+
+- `lisp/ss-ui.el` enables Vertico, Orderless, and Marginalia globally.
+- `lisp/ss-org.el` owns base Org configuration.
+- `lisp/ss-agenda.el` already discovers `org-agenda-files` from the journal and
+  PARA directories.
+
+The missing piece is Org refile configuration. The requested behavior is to
+refile Org entries to any heading in the current `org-agenda-files`, using a
+single, path-oriented prompt that works well with the existing Vertico-based
+completion UI.
+
+## Options Considered
+
+### 1. Recommended: configure built-in Org refile against `org-agenda-files`
+
+- Use Org's standard `org-refile` command and target machinery.
+- Refresh `org-agenda-files` before refile so the target set stays aligned with
+  the existing agenda discovery rules.
+- Configure path-based completion so Vertico and Orderless present the target
+  list cleanly.
+
+This keeps the workflow conventional, reuses existing repository structure, and
+avoids maintaining a parallel refile implementation.
+
+### 2. Add a custom wrapper command with richer target formatting
+
+- Build a custom candidate list for headings across agenda files.
+- Pass the chosen destination back into Org's refile internals.
+
+This could show more custom metadata, but it duplicates behavior Org already
+provides and increases maintenance cost for little practical gain.
+
+### 3. Add more completion packages just for refile
+
+- Introduce a Vertico extension or a separate package to alter refile prompts.
+
+This adds package surface area without first exhausting the built-in Org and
+completion capabilities already present in the config.
+
+## Chosen Design
+
+Use option 1.
+
+- Configure `org-refile-targets` to use `org-agenda-files` with unrestricted
+  heading depth.
+- Enable outline-path completion so identically named headings are
+  distinguishable by their parent path.
+- Use the direct, path-based completion flow rather than an additional outline
+  navigation step.
+- Refresh `org-agenda-files` before refile by reusing the existing agenda file
+  discovery helper instead of copying the directory rules.
+- Keep the change inside the existing module boundaries: Org behavior in
+  `lisp/ss-org.el`, with a UI tweak in `lisp/ss-ui.el` only if the current
+  completion categories need one.
+
+## Verification
+
+- Add focused ERT coverage for the refile setup helper and variable values.
+- Run `emacs --batch -Q --load ./init.el` from the repository root.
+
+## Documentation Impact
+
+`README.md` should be updated to describe that Org refile targets any heading in
+`org-agenda-files` and uses the configured minibuffer completion stack for
+path-based target selection.
+\ No newline at end of file
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