1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
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"
```
|
