Add back and forward note navigation

1 files changed, 118 insertions, 0 deletions

diff --git a/docs/plans/2026-04-10-navigation-history-implementation.md b/docs/plans/2026-04-10-navigation-history-implementation.md
new file mode 100644
index 0000000..0d58756
--- /dev/null
+++ b/docs/plans/2026-04-10-navigation-history-implementation.md
@@ -0,0 +1,118 @@
+# 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"
+```