# 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.