# Navigation History Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add small, browser-style back and forward navigation commands for note and mark-based movement across Org, agenda, CRM, and Denote workflows.

**Architecture:** Keep the navigation state and restoration helpers in `lisp/ss-org.el`, using marker-based location records plus a simple back stack and forward stack. Record only significant jumps by wiring the repo's custom note commands and advising common built-in jump commands after they move, while skipping same-location noise and clearing forward history on fresh navigation.

**Tech Stack:** Emacs Lisp, ERT, batch Emacs verification, interactive `emacs -nw` sanity check

---

### Task 1: Add failing navigation tests

**Files:**
- Modify: `tests/ss-capture-tests.el`
- Modify: `lisp/ss-org.el`

**Step 1: Write the failing tests**

```elisp
(ert-deftest ss-jump-back-restores-previous-location-and-enables-forward ()
  ...)

(ert-deftest ss-navigation-push-current-location-clears-forward-on-fresh-jump ()
  ...)
```

**Step 2: Run test to verify it fails**

Run: `emacs --batch -Q -L . -L lisp -l tests/ss-capture-tests.el -f ert-run-tests-batch-and-exit`
Expected: FAIL because the navigation stack commands and helper functions do not exist yet.

**Step 3: Write minimal implementation**

```elisp
(defvar ss-navigation-back-stack nil)
(defvar ss-navigation-forward-stack nil)
...
```

**Step 4: Run test to verify it passes**

Run: `emacs --batch -Q -L . -L lisp -l tests/ss-capture-tests.el -f ert-run-tests-batch-and-exit`
Expected: PASS for the new stack behavior tests.

**Step 5: Commit**

```bash
git add tests/ss-capture-tests.el lisp/ss-org.el
git commit -m "Add navigation history stack"
```

### Task 2: Wire note and jump commands into history

**Files:**
- Modify: `lisp/ss-org.el`
- Modify: `lisp/ss-keys.el`

**Step 1: Write the failing test**

```elisp
(ert-deftest ss-navigation-jump-wrapper-records-pre-jump-location ()
  ...)
```

**Step 2: Run test to verify it fails**

Run: `emacs --batch -Q -L . -L lisp -l tests/ss-capture-tests.el -f ert-run-tests-batch-and-exit`
Expected: FAIL because custom navigation commands and advised jump commands do not record history yet.

**Step 3: Write minimal implementation**

```elisp
(defun ss-navigation-record-before-command (&rest _)
  ...)

(advice-add 'org-open-at-point :before #'ss-navigation-record-before-command)
```

**Step 4: Run test to verify it passes**

Run: `emacs --batch -Q -L . -L lisp -l tests/ss-capture-tests.el -l tests/ss-crm-tests.el -f ert-run-tests-batch-and-exit`
Expected: PASS, with the navigation helpers loaded cleanly beside the existing CRM and capture tests.

**Step 5: Commit**

```bash
git add lisp/ss-org.el lisp/ss-keys.el tests/ss-capture-tests.el
git commit -m "Wire note jumps into navigation history"
```

### Task 3: Update docs and verify startup behavior

**Files:**
- Modify: `README.md`
- Review: `AGENTS.md`

**Step 1: Update docs**

Add the new `C-c b` and `C-c f` bindings plus a short explanation of what participates in navigation history.

**Step 2: Run verification**

Run: `emacs --batch -Q --load ./init.el`
Expected: PASS with the updated navigation code loaded through the normal startup path.

**Step 3: Run interactive sanity check**

Run: `emacs -nw`
Expected: manual verification that MOC, journal, and note jumps can go back and forward, and that a fresh jump clears forward history.

**Step 4: Commit**

```bash
git add README.md
git commit -m "Document navigation history bindings"
```