1 files changed, 239 insertions, 0 deletions
diff --git a/docs/plans/2026-04-07-people-rolodex-implementation.md b/docs/plans/2026-04-07-people-rolodex-implementation.md
new file mode 100644
index 0000000..16578f8
--- /dev/null
+++ b/docs/plans/2026-04-07-people-rolodex-implementation.md
@@ -0,0 +1,239 @@
+# People Rolodex Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the old roster and name-dictionary setup with a lightweight `~/org/people.org` rolodex that powers lookup, completion, reports, and dynamic people abbrevs from one Org file.
+
+**Architecture:** Keep a single cached parser for top-level headings in `~/org/people.org`, treat each heading as one person card, and build all lookup and insertion commands from that cache. Use explicit Org commands for overview/card mode, a small CAPF for Corfu, Marginalia annotations for minibuffer completion, dynamic buffer-local abbrevs sourced from the parsed cards, and a dedicated interactive add-person command that writes a compact subtree directly into `people.org`.
+
+**Tech Stack:** Emacs Lisp, Org mode, Vertico, Orderless, Marginalia, Corfu, CAPF, abbrev
+
+---
+
+### Task 1: Replace the old name dictionary and roster model in `config.org`
+
+**Files:**
+- Modify: `config.org`
+
+**Step 1: Write the failing test**
+
+Define the expected end state as code-level checks while editing:
+
+- there is no reference to `name-dictionary.el`
+- there is no reference to `ss/people-roster-file`
+- there is no capture template that writes a roster entry
+- the rolodex source file points to `~/org/people.org`
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "name-dictionary|people-roster|roster.org" config.org README.md`
+
+Expected: FAIL by finding the legacy model still present.
+
+**Step 3: Write minimal implementation**
+
+In the “Name shortcuts” section:
+
+- rewrite the prose to describe the lightweight rolodex
+- remove the legacy dictionary variables and functions
+- remove the old roster parsing code
+- add a single `ss/people-file` constant consumer model
+- add entry parsing helpers for:
+  - canonical name
+  - abbrev
+  - aliases
+  - role
+  - location
+  - engagement
+  - relationship
+  - current focus
+  - team
+- cache entries by `file-attribute-modification-time`
+- parse only level-1 headlines
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "name-dictionary|people-roster|roster.org" config.org`
+
+Expected: PASS with no remaining legacy implementation references.
+
+**Step 5: Commit**
+
+Do not commit yet. Verification and README updates are still pending.
+
+### Task 2: Implement rolodex overview, card view, lookup, insertion, reports, and add-person flow
+
+**Files:**
+- Modify: `config.org`
+
+**Step 1: Write the failing test**
+
+List the required commands before coding:
+
+- `ss/people-open`
+- `ss/people-find`
+- `ss/people-overview`
+- `ss/people-insert-name`
+- `ss/people-insert-summary`
+- `ss/people-report-by-relationship`
+- `ss/people-report-by-engagement`
+- `ss/people-report-by-role`
+- `ss/people-report-by-location`
+- `ss/people-add`
+
+Also require:
+
+- aliases match but insert canonical names
+- reports group under Org headings in a read-only buffer
+- opening `people.org` always restores overview mode
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "defun ss/(people-open|people-find|people-overview|people-insert-name|people-insert-summary|people-report-by-relationship|people-report-by-engagement|people-report-by-role|people-report-by-location|people-add)" config.org`
+
+Expected: FAIL because some or all required commands do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add:
+
+- file creation helper for `~/org/people.org`
+- overview-mode helper that widens, jumps to start, and shows top-level headings only
+- entry-open helper that widens, jumps, narrows to subtree, and reveals subtree
+- minibuffer completion metadata and Marginalia annotator
+- CAPF that returns canonical names and single-line annotations
+- insertion helpers for canonical name and compact summary
+- grouped report renderer
+- interactive prompts for add-person, including default abbrev generation and constrained choices for engagement/relationship
+- direct Org insertion for a compact starter card with `Context` and `TODOs` sections
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "defun ss/(people-open|people-find|people-overview|people-insert-name|people-insert-summary|people-report-by-relationship|people-report-by-engagement|people-report-by-role|people-report-by-location|people-add)" config.org`
+
+Expected: PASS with all commands present.
+
+**Step 5: Commit**
+
+Do not commit yet. Generated files and docs still need verification.
+
+### Task 3: Rewire Org directories, keybindings, and capture flow to the new people model
+
+**Files:**
+- Modify: `config.org`
+
+**Step 1: Write the failing test**
+
+Define the required workflow changes:
+
+- `ss/org-people-directory` should no longer point to `areas/people/`
+- there should be a `ss/people-file` under `~/org/`
+- keybindings should point at the new rolodex commands
+- `org-capture` should no longer include the old roster template
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "areas/people|nR|people-roster|C-c n r" config.org`
+
+Expected: FAIL by showing the old path and capture/binding behavior.
+
+**Step 3: Write minimal implementation**
+
+- update Org path constants so people notes are no longer treated as a PARA subdirectory
+- make `people.org` part of the created note roots where appropriate
+- keep Denote people-note capture removed or re-scoped so the rolodex remains distinct from narrative notes
+- bind the new commands to sensible keys, including a way to open `people.org` and add/find people
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "areas/people|nR|people-roster" config.org`
+
+Expected: PASS with the roster model removed.
+
+**Step 5: Commit**
+
+Do not commit yet. Documentation and generated output still need verification.
+
+### Task 4: Update the README to reflect the new rolodex end state
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Write the failing test**
+
+Identify stale statements to remove:
+
+- references to `name-dictionary.el`
+- references to `~/org/areas/people/roster.org`
+- manager/email/employee-time roster fields
+- capture docs for the old roster template
+
+Add the new documented state:
+
+- `~/org/people.org` is the only source of truth
+- commands, keybindings, reports, and overview/card behavior
+- people-specific abbrevs come dynamically from `people.org`
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "name-dictionary|roster.org|manager|employee time|email" README.md`
+
+Expected: FAIL because the README still documents the old roster.
+
+**Step 3: Write minimal implementation**
+
+Edit the README sections for:
+
+- note layout
+- completion setup
+- abbrevs
+- capture flow
+- note creation and linking
+
+Make the current workflow truthful and concise.
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "name-dictionary|roster.org|employee time" README.md`
+
+Expected: PASS with stale docs removed.
+
+**Step 5: Commit**
+
+Do not commit yet. Final verification still needs to run.
+
+### Task 5: Tangle and verify the generated configuration
+
+**Files:**
+- Modify indirectly via tangling: `init.el`
+
+**Step 1: Write the failing test**
+
+Require two checks:
+
+- `config.org` tangles without Lisp errors
+- generated `init.el` loads under batch Emacs
+
+**Step 2: Run test to verify it fails**
+
+Run: `emacs --batch -Q --eval '(progn (require (quote ob-tangle)) (org-babel-tangle-file "config.org"))'`
+
+Expected: If there are syntax or tangle issues, this fails and guides fixes.
+
+**Step 3: Write minimal implementation**
+
+Fix any syntax, quoting, or load-order issues reported by the tangle or load checks.
+
+**Step 4: Run test to verify it passes**
+
+Run: `emacs --batch -Q --eval '(progn (require (quote ob-tangle)) (org-babel-tangle-file "config.org"))'`
+
+Expected: `init.el` and `early-init.el` are regenerated successfully.
+
+Run: `emacs --batch -Q --load ./init.el`
+
+Expected: Emacs exits successfully after loading the generated main config.
+
+**Step 5: Commit**
+
+Stop after verification and summarize the verified unit to the user before any commit.