hephaestus/docs/changelog.d/v1-prototype.feature.md

Begin the v1 prototype (Phase 1, tech-spec §11.1), built in TDD slices:

• Cargo workspace + heph-core crate; migration-run SQLite schema (§4.5); clock-injected Store trait + LocalStore node create/get; single local-user bootstrap.
• Markdown extraction (§5): [[wiki-links]] and GFM - [ ] checkbox context-items derived purely and idempotently from a body, skipping code blocks.
• Committed tasks (§4.3, §6): task.create auto-creates the canonical context doc + canonical-context link; attention/do-date/late-on/state/recurrence columns; set-state/set-attention. Links CRUD (outgoing/backlinks). A body update reconciles wiki links (diff-based, resolved by alias/title, idempotent).
• "What is next?" ranking (§7): pure, clock-injected, two-stage engine — candidacy filter (do-date as a boolean gate only) then a reorderable list of named dimensions (past-late-on → overdue-amount → attention band → FIFO). late_on is the sole urgency signal; blue hidden; red always shown. Proptest-checked total order. Store::next surfaces it over SQLite.
• Recurrence — roll-forward in place (§4.4): completing a recurring task resets its checklist to all-unchecked, logs the occurrence, and advances the do-date to the next RRULE instance after now (skipping misses) — completion never carries forward (proptest-checked). Per-task append-only logs (log-of) with log.append/log.tail; skip advances without logging.
• hephd daemon, local mode (§3, §6): exclusive file lock (handoff-ready), line-delimited JSON-RPC over a unix socket exposing the node/task/next/links/log methods, with DB work on tokio's blocking pool. Synchronous client for surfaces/CLI. Model types are serde-serializable.
• heph CLI (§1) — a thin client of the daemon: next, task, doc, get, export. Export materializes the store to a <kind>/<id>.md tree with YAML frontmatter + body (§5), one-way, tombstones excluded.
• Sync engine, local-only (§12): real hybrid logical clock + persistent device origin; an append-only op-log per mutation; an idempotent, order-independent merge/apply engine — last-writer-wins task scalars (discards surfaced in a conflicts queue), OR-set links, monotonic tombstones. Two-replica convergence proven.
• Body text CRDT (§5, §12, slice 8d): node bodies now merge through the yrs text CRDT (body_crdt) instead of last-writer-wins — whole-buffer writes are diffed into the doc and the yrs delta rides the op, so concurrent edits to different regions both survive and never enqueue a conflict.
• Network sync over HTTP (§6.1, §12, slice 9a): hephd --mode server exposes a sync hub (POST /sync/push, GET /sync/pull?after=<hlc>, axum) over the same store; hephd --mode local --hub-url <url> becomes a spoke that background-syncs its op-log with that hub (and on demand via the sync.now/sync.status RPC). Exchange is incremental by HLC cursor (sync_state) and idempotent. The merge engine is heph-core's, unchanged. Unauthenticated/single-owner for now (auth lands with OIDC). conflicts.list/conflicts.resolve are now reachable over the daemon socket.
• Client mode (§3.1, slice 9b): hephd --mode client --server-url <url> runs with no local replica, proxying every store call to a server's POST /rpc endpoint (the full daemon API over HTTP). The daemon is now backend-agnostic (local/server front a LocalStore, client a RemoteStore), so surfaces see the same unix-socket API in every mode.
• Hub authentication (§13, slice 10a): the sync hub now verifies an OIDC bearer token on /sync/* and /rpc — RS256-pinned JWT validation with exact issuer/audience, expiry, and a required subject; JWKS discovered and cached, refetched on key rotation (jsonwebtoken). Enabled with hephd --mode server --oidc-issuer <url> --oidc-audience <client-id> (open when unset, for local dev). A single-tenant owner gate binds the hub to the first authenticated identity and rejects any other. Verification sits behind a TokenVerifier trait, so it's tested entirely offline (stub middleware + an adversarial battery against an in-process mock IdP).
• Client authentication (§13, slice 10b): heph auth login --hub-url <url> --issuer <url> --client-id <id> runs the OAuth 2.0 device-code flow and caches the token in the OS keyring; spokes and client mode attach it to hub requests, refreshing on expiry (--oidc-issuer/--oidc-client-id). Offline-tested against a mock OAuth server and a full spoke-to-authenticated-hub loop. (Auth/proxy HTTP uses the runtime-free ureq, since reqwest::blocking is unsafe inside the async daemon.)
• CI runs the Rust suite (fmt/clippy/test) via the project build hook.
• heph.nvim slice 11a (§8) — the primary surface begins: a Neovim plugin that is a thin client of the local hephd over its unix socket. A vim.uv JSON-RPC client (blocking call via vim.wait, id-demuxed, partial-line buffered, JSON null→Lua nil); buffer-backed nodes (heph://node/<id> with BufReadCmd→node.get / BufWriteCmd→node.update, whole-buffer body round-tripping exactly through the CRDT); [[wiki-link]] follow on <CR> via a new exact node.resolve {title} RPC (alias-then-title, the same mapping that materializes wiki links — unresolved links allowed); the daily journal (:Heph today); and the :Heph command surface. Headless e2e (§9) drives the plugin against a real daemon over a temp socket with a self-contained busted-style runner (no external plugins, no network): journal round-trip, follow-link, and link-two-docs/backlink.
• heph.nvim slice 11b (§8) — task views: list is enriched to return titled rows (the same shape as next, with the canonical-context id) so the Organizational survey needs no per-row node.get. The plugin gains the Tactical :Heph next and Organizational :Heph list views (<CR> opens a task's canonical-context doc), task capture, set-attention, done/drop, skip, and per-task log append — each resolving "the current task" from the buffer (a task node, or a context doc via its canonical-context backlink). A vim.ui.select picker (Telescope auto-upgrade when installed) backs :Heph search/capture/attention. Headless e2e adds the capture→next→context→checklist→done workflow and the recurring fresh-checklist workflow (completing a recurring task rolls it forward and the next occurrence presents an all-unchecked checklist).
• heph.nvim slice 11c (§8) — promotion + CI: task.promote mints a committed task from a - [ ] context-item line (addressed by its 1-based index) and rewrites that line into a [[link]] to the new task; :Heph promote does this for the line under the cursor. Wiki-link resolution now excludes a task's canonical-context doc, so [[Task Title]] resolves to the task itself (not its identically-titled context doc). The headless e2e suite runs in CI via a Dagger function that bakes a pinned, arch-detected Neovim onto a Rust image and runs the same self-contained suite developers run natively with mise run test-nvim; the runner fails on a zero-spec discovery so a misconfigured path can't pass silently.
• heph.nvim managed daemon — plug-and-play by default: require("heph").setup({}) spawns and supervises a local hephd against the default paths when none is running, kills only the daemon it spawned on exit, and self-heals (respawns + reconnects if the daemon dies mid-session). A daemon you started yourself (a server/client architecture, or a service) is always respected — the plugin only spawns when nothing is serving the socket; with autostart = false it connects only and warns if unreachable. $HEPH_SOCKET / $HEPH_DB isolate a development Neovim onto a separate daemon + DB.
• heph.nvim follow-or-create: pressing <CR> on a [[wiki-link]] whose target doesn't exist yet now creates a doc with that title and opens it (the zettelkasten gesture), materializing the source's backlink — so you can link a journal entry to a brand-new note in one keystroke. Plus :Heph doc <title> to create a standalone wiki entry, and :Heph home — a single designated landing/index page (open-or-create by title, configurable via opts.home) to grow a map of content around. :Heph journals opens a recent-days picker (preview existing days, @create for new ones; count via opts.journal_days, default 7) — the dailies workflow. Pickers (Telescope) now support a preview pane. The :Heph next/list views are interactive: <CR> opens a task's context, a adds a task (prompt title + attention), d marks the task under the cursor done, r refreshes — with a dimmed key hint shown above the list.
• Dev/installed isolation tooling: a mise run dev task runs the working-tree hephd on isolated .dev/ paths, and a how-to (install-heph) covers installing heph/hephd from the forge (build-from-source), the lazy.nvim plugin setup, and pointing a dev Neovim at the dev daemon via $HEPH_SOCKET/$HEPH_DB so it never touches the installed store.
• CLI as a complete task surface (§1, §6.2.1): heph now implements the entire daemon API and is the task capture/scripting surface. Structured fields are flags with human dates (--do-date tomorrow|+3d|fri|YYYY-MM-DD, shown back compactly in next/list) and recurrence (--recur presets/natural-language like "every 3 days", or a raw --rrule). New verbs: list, done/drop/skip, attention, edit (reschedule do-date/late-on/recurrence, re-attention, re-file — backed by the new task.set_schedule RPC), promote, show, log (append or tail), health, node update/rm, resolve, links/backlinks, link add, project add [--parent], sync [--status], conflicts [resolve]. Projects are referenced by name. Date/recurrence parsing is unit-tested; the new verbs have real-socket process tests.
• Daemon lifecycle is now an explicit OS service, and all surfaces are connect-only (no more auto-spawn). heph daemon start/stop/restart/status/uninstall idempotently manages a launchd agent (macOS) or systemd user service (Linux) that runs hephd on your default store; heph.nvim no longer spawns or supervises a daemon — it just connects and points you at heph daemon start if none is running. Rationale: once the CLI became a first-class surface, a daemon owned by one surface couldn't be shared (see run-the-daemon, design §4).
• Filter views (§8.2) — saved agenda slices, so the agenda isn't one flat list. heph view <name> runs a built-in view (tom Top of Mind, ondeck On Deck, chores, work Work Tasks, tasks) seeded from the owner's Todoist filter queries; heph view with no name lists them, and :Heph view <name> does the same in Neovim. Under the hood, list now takes a ListFilter predicate-as-data (attention include/exclude sets, project-subtree scope, project exclusions, an actionable do-date gate), and views resolve project names to ids and expand each to its parent-link subtree. The Schedule view is intentionally omitted (time-of-day isn't modeled on date-grained do-dates).
• heph-tui (§8.1) — a terminal task agenda/triage UI, the primary surface for working a large task set (the §6.2.1 Todoist study showed triage, not single edits, dominates). A ratatui app, thin client of the daemon socket. Three panes: a sidebar of the five filter views + your projects, an attention-colored task list with compact human do/late dates, and a preview of the highlighted task's context doc + recent log. Triage from the keyboard: a add (guided title → attention → do-date, filed under the selected project), x done, s skip, d drop, A cycle attention, b push to On Deck, e reschedule the do-date; o opens the task's context doc in your nvim (live, via heph.nvim) and returns. j/k move, Tab/h/l switch panes, r refresh, q quit. Run it with heph-tui (honors --socket / $HEPH_SOCKET). a is a Todoist-style single-line quick-add: Buy milk tomorrow p2 #Work every week parses into title + attention (p1–p4) + do-date + recurrence + project (multi-word project names match greedily; an unresolved #tag just stays in the title). / runs a full-text search whose results overlay the task list; Enter opens a hit (a task at its context doc) in nvim.
• Move-to-project (§8.1): a new task.set_project RPC re-files a task under another project (or unfiles it) with OR-set link semantics — the old in-project link is tombstoned and a new one added, so a task is never filed under two projects at once. In heph-tui, m opens a list-pick overlay ("(Unfile)" then every project) on the highlighted task. heph edit <task> --project <name> now routes through the same RPC (fixing a bug where re-filing piled on a duplicate link), and --project none unfiles the task. This closes the last Todoist-parity capture gap.
• heph-tui task-list visuals (§8.1): each row now leads with an attention flag (⚑, colored red/orange/blue; blank for white) and a project-colored bullet — the bullet's color is derived stably from the project id (so it survives projects being added/removed), letting you scan a mixed list by project at a glance. The list also grows a scrollbar and keeps the selected task scrolled into view when there are more tasks than fit.
• heph-tui: <Enter> opens the selected task's context editor in nvim (from the sidebar it first drills into the task list); the old o binding is retired. The view sidebar / heph view order is now Top of Mind, Tasks, Work Tasks, Chores, On Deck.
• heph-tui sort toggle (§8.1): s flips the task list between two orders — default (attention → most-overdue → project → creation) and by-project (grouped under dimmed ──── Project ──── separators, then the same sub-order). The view's filter still applies first. (To free s, skip moved to S.)
• heph.nvim task-view rows (§8): :Heph next/:Heph list rows now show a compact do/late date chip (and a recurrence ↻), so you can see scheduling at a glance; <CR> still jumps to a task's context doc.
• Wiki-links by node id (§8.4): node resolution is now id-first ([[NODEID]] resolves to its node ahead of any name match, so links can't be shadowed by a like-named node), and heph.nvim grows a [[ picker — type [[ (or :Heph link) to pick a node and insert a canonical [[NODEID]] link. With Telescope it's a live fuzzy filter over your linkable nodes with a preview pane (the node's body, or a task's context doc) — the list shows first-class targets only (a task appears once; its internal context/log docs and tag nodes are hidden, via the new node.linkable query) — type to narrow, Enter to insert, <C-x> to create a doc named what you've typed; without Telescope it falls back to a search-then-select prompt. Following such a link (<CR>) jumps straight by id. Those id links are kept readable: on read a bare [[NODEID]] is expanded to [[NODEID|Current Name]] (so it follows renames, in both the nvim buffer and the TUI preview), and on save it collapses back to the canonical bare id — a custom |label you write is preserved as an override. In the editor the id is concealed — a link renders as just its name, styled like a hyperlink, with the raw [[id|Name]] revealed on the line your cursor is on. Legacy [[Name]] links keep working, and heph migrate-links rewrites them to the canonical id form in one pass when you're ready (idempotent).
• Frontmatter editing in heph.nvim (§8.3): opening a node now shows an editable YAML frontmatter block on top of the body (id/kind/title/tags, and for a task or its context doc the task's state/attention/do_date/late_on/recurrence/project). On save, the plugin diffs the block and issues the right RPC per changed field — rename, set-attention, reschedule (dates as YYYY-MM-DD), move-to-project (by name), and tag add/remove — then saves the body; the store strips the block so it never persists. A mistyped state surfaces a validation error; a buffer with no block changes no metadata (so deleting the block can't wipe your tags). Inline #hashtags typed in the body are also added as tags on save (a # heading doesn't count) and are rendered in italics so they stand out. Link-follow and promotion are unaffected (they're content-relative, not line-absolute).
• Frontmatter projection (§8.3): a node can now be fetched with an editable YAML frontmatter block prepended — node.get {frontmatter: true} renders id/kind/title/tags, and for a task (or its context doc) the owning task's state/attention/do_date/late_on/recurrence/project plus a task: ref. Dates are local YYYY-MM-DD. On write, the store strips and ignores any leading frontmatter (conservatively — a real --- hrule in prose survives) before the CRDT diff, so frontmatter never persists and an unchanged read→write is a no-op; a naive editor can't corrupt metadata. This is the read/write groundwork for editing a node's metadata as frontmatter in heph.nvim (the diff-into-RPCs layer is next).
• Tags (§4, §8.3): nodes can now be tagged. A tag is a tag-kind node whose id is deterministic in (owner, name), so the same name is one canonical tag shared across everything it's applied to (and replicas converge — no duplicate tags). Tagging is an OR-set link, so adding/removing is idempotent and merge-safe. Surfaced as tag.add/tag.remove/tag.list RPCs and heph tag add|rm|list (list a node's tags, or every tag with no node). Tag names are trimmed; a canonical case/spelling normalization is deferred to the future zk import. This is the groundwork for the tags: line of the upcoming frontmatter edit surface.