heph.nvim: task views — next/list/capture/attention/state/log (slice 11b)

Backend: enrich `list` to return titled RankedTask rows (title +
canonical_context_id, via a shared ranked_from_row with `next`), so the
Organizational view needs no N+1 node.get. TDD: query_surface test asserts
list rows carry title + context id.

Plugin:
- view.lua: Tactical `next` + Organizational `list` rendered scratch buffers;
  <CR> opens the row's canonical-context doc. Narrowed the node autocmd to
  heph://node/* so view buffers (heph://next, heph://list) don't trip it.
- task.lua: capture, set-attention, done/drop, skip, per-task log append, all
  resolving "the current task" from the buffer (a task node, or a context doc
  via its canonical-context backlink).
- picker.lua: vim.ui.select with Telescope auto-upgrade (headless-safe).
- command.lua: :Heph next/list/capture/attention/done/drop/skip/log/search.

e2e: capture→next→open context→add/check checklist→done; recurring
fresh-checklist (complete rolls forward in place, next occurrence all-unchecked
— the §4.4 hard requirement). 6 specs green via `mise run test-nvim`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

heph.nvim/lua/heph/command.lua

@@ -4,8 +4,11 @@
 
 local M = {}
 
+local ATTENTIONS = { "white", "orange", "red", "blue" }
+
 --- subcommand -> handler(args: string[])
 M.subs = {
+  -- knowledge base
   today = function()
     require("heph.journal").open()
   end,
@@ -20,6 +23,66 @@ M.subs = {
       require("heph.node").open(args[1])
     end
   end,
+  search = function(args)
+    local query = table.concat(args, " ")
+    if #query == 0 then
+      require("heph.util").notify("usage: :Heph search <query>", vim.log.levels.WARN)
+      return
+    end
+    local nodes = require("heph.rpc").call("search", { query = query })
+    require("heph.picker").select(nodes, {
+      prompt = "heph search: " .. query,
+      format = function(n)
+        return string.format("[%s] %s", n.kind, n.title)
+      end,
+    }, function(choice)
+      if choice then
+        require("heph.node").open(choice.id)
+      end
+    end)
+  end,
+
+  -- tasks
+  next = function(args)
+    require("heph.view").next({ scope = args[1] })
+  end,
+  list = function(args)
+    require("heph.view").list({ attention = args[1] })
+  end,
+  capture = function(args)
+    local title = table.concat(args, " ")
+    if #title == 0 then
+      require("heph.util").notify("usage: :Heph capture <title>", vim.log.levels.WARN)
+      return
+    end
+    require("heph.picker").select(ATTENTIONS, { prompt = "attention for: " .. title }, function(attention)
+      require("heph.task").capture(title, { attention = attention })
+      require("heph.util").notify("captured: " .. title)
+    end)
+  end,
+  attention = function(args)
+    if args[1] then
+      require("heph.task").set_attention_current(args[1])
+    else
+      require("heph.picker").select(ATTENTIONS, { prompt = "attention" }, function(choice)
+        if choice then
+          require("heph.task").set_attention_current(choice)
+        end
+      end)
+    end
+  end,
+  done = function()
+    require("heph.task").set_state_current("done")
+  end,
+  drop = function()
+    require("heph.task").set_state_current("dropped")
+  end,
+  skip = function()
+    require("heph.task").skip_current()
+  end,
+  log = function(args)
+    require("heph.task").log_append_current(table.concat(args, " "))
+  end,
 }
 
 --- `:Heph` entry point.

heph.nvim/lua/heph/config.lua

@@ -33,7 +33,15 @@ function M.apply_keymaps(opts)
   map("n", "<leader>hj", function()
     require("heph.journal").open()
   end, { desc = "heph: today's journal" })
-  -- Task/agenda maps are added with their views in slice 11b.
+  map("n", "<leader>hn", function()
+    require("heph.view").next()
+  end, { desc = "heph: what is next (Tactical)" })
+  map("n", "<leader>hl", function()
+    require("heph.view").list()
+  end, { desc = "heph: task list (Organizational)" })
+  map("n", "<leader>hd", function()
+    require("heph.task").set_state_current("done")
+  end, { desc = "heph: mark current task done" })
 end
 
 return M

heph.nvim/lua/heph/picker.lua

@@ -0,0 +1,56 @@
+--- A single selection primitive. Uses built-in `vim.ui.select` so headless e2e
+--- needs no plugins; auto-upgrades to Telescope when it is installed and not
+--- explicitly disabled. Tests set `vim.g.heph_force_ui_select` and stub
+--- `vim.ui.select`, so a picker never blocks in `--headless`.
+
+local M = {}
+
+local function telescope_available()
+  return pcall(require, "telescope")
+end
+
+--- Select one of `items`. `opts.prompt`, `opts.format(item)->string`.
+--- `on_choice(item|nil, index|nil)` — nil when cancelled.
+function M.select(items, opts, on_choice)
+  opts = opts or {}
+  if not vim.g.heph_force_ui_select and telescope_available() then
+    -- Telescope path: a thin wrapper so fuzzy UX is available when present.
+    -- (The dropdown is intentionally minimal; richer pickers can come later.)
+    local pickers = require("telescope.pickers")
+    local finders = require("telescope.finders")
+    local conf = require("telescope.config").values
+    local actions = require("telescope.actions")
+    local action_state = require("telescope.actions.state")
+    pickers
+      .new({}, {
+        prompt_title = opts.prompt or "heph",
+        finder = finders.new_table({
+          results = items,
+          entry_maker = function(item)
+            local display = opts.format and opts.format(item) or tostring(item)
+            return { value = item, display = display, ordinal = display }
+          end,
+        }),
+        sorter = conf.generic_sorter({}),
+        attach_mappings = function(bufnr)
+          actions.select_default:replace(function()
+            actions.close(bufnr)
+            local sel = action_state.get_selected_entry()
+            on_choice(sel and sel.value or nil)
+          end)
+          return true
+        end,
+      })
+      :find()
+    return
+  end
+
+  vim.ui.select(items, {
+    prompt = opts.prompt,
+    format_item = opts.format,
+  }, function(choice, idx)
+    on_choice(choice, idx)
+  end)
+end
+
+return M

heph.nvim/lua/heph/task.lua

@@ -0,0 +1,90 @@
+--- Task actions (tech-spec §8): capture, attention, state, skip, log. Actions
+--- that operate on "the current task" resolve it from the buffer — either the
+--- buffer is a `task` node, or it is a task's canonical-context doc, in which
+--- case we follow the `canonical-context` backlink to its owning task.
+
+local rpc = require("heph.rpc")
+local util = require("heph.util")
+
+local M = {}
+
+--- Capture a committed task. `opts`: attention, do_date, late_on, recurrence,
+--- project. Returns the created task.
+function M.capture(title, opts)
+  opts = opts or {}
+  return rpc.call("task.create", {
+    title = title,
+    attention = opts.attention,
+    do_date = opts.do_date,
+    late_on = opts.late_on,
+    recurrence = opts.recurrence,
+    project_id = opts.project,
+  })
+end
+
+--- The committed task id associated with the current buffer, or nil.
+function M.current_task_id()
+  local buf = vim.api.nvim_get_current_buf()
+  local id = vim.b[buf].heph_node_id
+  if not id then
+    return nil
+  end
+  if vim.b[buf].heph_node_kind == "task" then
+    return id
+  end
+  -- A canonical-context doc: its owning task is the src of the
+  -- canonical-context link pointing here.
+  for _, l in ipairs(rpc.call("links.backlinks", { id = id })) do
+    if l.link_type == "canonical-context" then
+      return l.src_id
+    end
+  end
+  return nil
+end
+
+local function with_task(action, what)
+  local id = M.current_task_id()
+  if not id then
+    util.notify("no task associated with this buffer", vim.log.levels.WARN)
+    return nil
+  end
+  action(id)
+  if what then
+    util.notify(what)
+  end
+  return id
+end
+
+--- Mark the current task done/dropped (recurring tasks roll forward on done).
+function M.set_state_current(state)
+  return with_task(function(id)
+    rpc.call("task.set_state", { id = id, state = state })
+  end, "task " .. state)
+end
+
+--- Set the current task's attention.
+function M.set_attention_current(attention)
+  return with_task(function(id)
+    rpc.call("task.set_attention", { id = id, attention = attention })
+  end, "attention → " .. attention)
+end
+
+--- Skip the current recurring task's occurrence (advance without logging).
+function M.skip_current()
+  return with_task(function(id)
+    rpc.call("task.skip", { id = id })
+  end, "occurrence skipped")
+end
+
+--- Append a line to the current task's log (the resumption breadcrumb).
+function M.log_append_current(text)
+  if not text or #text == 0 then
+    util.notify("nothing to log", vim.log.levels.WARN)
+    return nil
+  end
+  return with_task(function(id)
+    rpc.call("log.append", { task_id = id, text = text })
+  end, "logged")
+end
+
+return M

heph.nvim/lua/heph/view.lua

@@ -0,0 +1,89 @@
+--- Task list views (tech-spec §8): Tactical `next` (the "what is next?" ranking)
+--- and Organizational `list` (the whole outstanding set). Both render the same
+--- titled rows the daemon returns into a scratch buffer; `<CR>` opens the task
+--- under the cursor's canonical-context doc (the one-keystroke jump).
+
+local rpc = require("heph.rpc")
+
+local M = {}
+
+-- buf -> { tasks = <RankedTask[]> }; line N maps to tasks[N].
+M._views = {}
+
+local function row(t)
+  local tag = t.attention and ("[" .. t.attention .. "]") or "[ ]"
+  return string.format("%s %s", tag, t.title)
+end
+
+-- Find or create the named scratch buffer and fill it with task rows.
+local function render(name, tasks)
+  local buf
+  for _, b in ipairs(vim.api.nvim_list_bufs()) do
+    if vim.api.nvim_buf_get_name(b) == name then
+      buf = b
+      break
+    end
+  end
+  if not buf then
+    buf = vim.api.nvim_create_buf(false, true) -- unlisted scratch
+    vim.api.nvim_buf_set_name(buf, name)
+  end
+  vim.bo[buf].buftype = "nofile"
+  vim.bo[buf].bufhidden = "hide"
+  vim.bo[buf].swapfile = false
+
+  local lines = {}
+  for _, t in ipairs(tasks) do
+    lines[#lines + 1] = row(t)
+  end
+  if #lines == 0 then
+    lines = { "(nothing here)" }
+  end
+  vim.bo[buf].modifiable = true
+  vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
+  vim.bo[buf].modifiable = false
+
+  M._views[buf] = { tasks = tasks }
+  vim.keymap.set("n", "<CR>", function()
+    M.open_under_cursor(buf)
+  end, { buffer = buf, desc = "heph: open task context" })
+  vim.api.nvim_set_current_buf(buf)
+  return buf
+end
+
+--- Open the canonical-context doc of the task on the cursor line.
+function M.open_under_cursor(buf)
+  buf = buf or vim.api.nvim_get_current_buf()
+  local view = M._views[buf]
+  if not view then
+    return
+  end
+  local lnum = vim.api.nvim_win_get_cursor(0)[1]
+  local t = view.tasks[lnum]
+  if not t then
+    return
+  end
+  require("heph.node").open(t.canonical_context_id or t.node_id)
+end
+
+--- Tactical "what is next?" — render the ranking, return the rows.
+function M.next(opts)
+  opts = opts or {}
+  local tasks = rpc.call("next", { scope = opts.scope, limit = opts.limit or 5 })
+  render("heph://next", tasks)
+  return tasks
+end
+
+--- Organizational survey — render the outstanding set, return the rows.
+function M.list(opts)
+  opts = opts or {}
+  local tasks = rpc.call("list", {
+    scope = opts.scope,
+    attention = opts.attention,
+    include_blue = opts.include_blue ~= false,
+  })
+  render("heph://list", tasks)
+  return tasks
+end
+
+return M