From 86ecdc39944c14ec7175a4a578397035f92f7d6b Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 12 Jun 2026 02:06:18 -0500 Subject: chore(todo): move palette-columns VERIFY to section end --- todo.org | 6984 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 3492 insertions(+), 3492 deletions(-) diff --git a/todo.org b/todo.org index 2731c8c5d..33959ccd0 100644 --- a/todo.org +++ b/todo.org @@ -41,9 +41,65 @@ Tags are additive. For example, a small wrong-behavior fix can be =:bug:quick:=, and a feature that requires internal restructuring can be =:feature:refactor:=. * Emacs Open Work -** VERIFY Palette-columns spec review :theme-studio: -SCHEDULED: <2026-06-12 Fri> -Read [[file:docs/theme-studio-palette-columns-spec.org][docs/theme-studio-palette-columns-spec.org]] (Draft, from the 2026-06-10 design discussion) and bless or amend. Decisions 9 and 10 are the two session calls awaiting your word: strips flip to lightest→darkest top→bottom to match the dropdown, and each dropdown column run places the base at its natural lightness position (vs bg/fg bases leading before any steps). On "spec's good": mark Ready, file the phase breakdown, cancel the [#C] hint-override task, start Phase 1. +** TODO [#A] Calibre Open Work :calibre: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: +Parent grouping the open Calibre / ebook-workflow issues; close each child independently. The EPUB reading-width tasks were already resolved (2026-05-12/14). + +*** DOING Calibre bookmark title format :feature:solo:quick: +When I hit m in calibre, I'm making my place in the book with a bookmark. +While sometimes, the books look fine: "The A.B.C. Murders - Agatha Christie.epub" +Sometimes they look not so good: Engines of Logic_ Mathematicians and the O - Martin Davis.pdf or Software Architecture_ The Hard Parts _ Mo - Neal Ford.pdf + +What I would like to do is to have the bookmarks be saved in the following format: + +Author, Title [no extension]. Underscores should be stripped. + +Root cause: in a nov buffer =m= is =bookmark-set= (rebound at calibredb-epub-config.el:311); nov's =nov-bookmark-make-record= names the record =(buffer-name)= -- the EPUB filename. + +Implemented 2026-06-06. Source decision: parse the *filename*, not the embedded EPUB metadata -- under Calibre's " - <Author>.epub" naming the filename is more complete (the embedded metadata had truncated titles, author-sort "Last, First" forms, and lost punctuation; see the separate metadata-cleanup task). A =:filter-return= advice on =nov-bookmark-make-record= rebuilds the name from the record's filename: split on the last " - " into title/author, restore the colon Calibre sanitized to "_ " (-> ": "), reorder to "Author, Title". Pure helpers =cj/--nov-clean-title= + =cj/--nov-bookmark-name-from-file= in =modules/calibredb-epub-config.el=; 10 ERT tests in =tests/test-calibredb-epub-config--bookmark-name.el=. Live in the daemon. + +Existing bookmarks: the 3 nov bookmarks in =~/sync/org/emacs_bookmarks= were renamed by hand (one-pass, in the daemon + saved; backup at =emacs_bookmarks.bak-2026-06-06=): "Edward Kanterian, Frege: A Guide for the Perplexed", "Agatha Christie, The A.B.C. Murders", "Edward Abbey, The Fool's Progress: An Honest Novel". + +Awaiting Craig's manual confirm: make a NEW bookmark (open an EPUB, hit m) and check the default name is "Author, Title" from the filename. + +*** DOING [#A] Reconsider Calibre keybindings :feature:ux: +Relocated from the global capture inbox 2026-06-06. Want a discoverable set of keybindings (visible in which-key) for the most frequent calibredb workflows: +- Switch to a library (e.g. Literature), sort by last name, scroll the list. +- Scope/filter the list in place, keeping the current library scope: + - by format (e.g. epubs only) + - by author last name (exact == or ^begins-with some text) + - sort by title, publication date, or group by format +- One key pops up the selected book's description in a bottom-30% buffer, dismissed with q (same display pattern as the signel chat dock). +- RET opens the book in the appropriate viewer. +Survey finding 2026-06-06: calibredb already binds almost all of this in calibredb-search-mode-map (S/L library, g filter [f format, a author, t tag, d date], o sort [t title, a author, p pubdate, f format], RET open) and even ships transient menus (? = calibredb-dispatch, g, o). The real problem was discoverability -- they are top-level single keys (which-key never pops up) and Craig didn't know ? opened a menu. calibredb-quick-look is macOS-only; the detail view (v -> *calibredb-entry*, q quits) is the description but opens full-window. + +Implemented 2026-06-06 in =modules/calibredb-epub-config.el=: +- A curated transient =cj/calibredb-menu= (library switch; filter format/author/reset; sort author/title/pubdate/format; open; describe; H = full calibredb-dispatch) bound to =?= in calibredb-search-mode-map. calibredb's own full dispatch moved to =H=. Defined in the use-package =:config= (needs the elpa transient, which batch doesn't load) -- the "? brings up a curated help menu" convention. +- Bottom-30% description dock: =calibredb-show-entry-switch= -> =pop-to-buffer= + a =display-buffer-alist= rule for =*calibredb-entry*= (display-buffer-at-bottom, height 0.3); =cj/calibredb-describe-at-point= shows the entry without switching focus so q dismisses it. Same pattern as the signel chat dock. +1 ERT test (the describe command; the transient/bindings/dock need the elpa transient + live calibredb, verified in the daemon). Author "begins-with" is covered well enough by g a's completing-read over "Last, First"; a true regex filter was not built. Awaiting Craig's manual verify (M-B -> ? menu; d/v docked description; H full menu). + +*** TODO Embed Calibre DB metadata into the EPUB files :data:maintenance: +Surfaced 2026-06-06 while building the bookmark naming: the metadata embedded in the EPUB files' OPF is worse than Calibre's database metadata. nov reads the embedded OPF and got truncated titles ("Frege" vs the filename's "Frege: A Guide for the Perplexed"), author-sort "Last, First" forms ("Christie, Agatha"), and lost punctuation ("A.B.C." -> "A B C"). The filenames (from Calibre's curated DB) are the good copy. Fix on the Calibre side: select all (or by library), run "Edit metadata -> Embed metadata into book files" so the DB metadata is written into each EPUB's OPF. Consider auditing author vs author_sort first. After embedding, the in-file metadata matches the library and any tool reading the files (nov, other readers, re-imports) gets the good data. Not an Emacs task; Calibre-side bulk maintenance. + +** TODO [#A] Lock screen silently fails — slock is X11-only :bug: +=modules/system-commands.el:105= binds the lockscreen command to =slock=, which can't grab a Wayland session; =cj/system-cmd= launches it detached with output silenced, so C-; ! l does nothing and the screen never locks. Security issue: Craig believes the screen locks when it doesn't. Fix: =hyprlock= (or =swaylock=), ideally resolved per session type via =env-wayland-p= so an X11 fallback survives for other machines. From the 2026-06 config audit. + +** TODO [#A] mu4e: cmail can't trash, no account can refile :bug: +=modules/mail-config.el:217-220= — the cmail context (primary account) sets only drafts/sent, so D falls back to default "/trash" which doesn't exist under ~/.mail (=/cmail/Trash= does); and NO context sets =mu4e-refile-folder=, so r targets nonexistent "/archive" everywhere. Accepting mu4e's offer to create the maildir strands mail in a directory mbsync never syncs — messages silently vanish from the server's view. Add =mu4e-trash-folder= to cmail + per-context =mu4e-refile-folder=. From the 2026-06 config audit. + +** TODO [#A] calendar-sync drops final occurrences and resurrects cancelled meetings :bug:solo: +RFC 5545 conformance holes in =modules/calendar-sync.el=, all agenda-visible (from the 2026-06 config audit): +- =:973,1015,1024= — UNTIL treated as exclusive (strict =calendar-sync--before-date-p=); RFC and Google make it inclusive, so the LAST instance of every UNTIL-bounded series vanishes. Tests assert loose count ranges, so it's unpinned. Allow equality. +- =:578= — comma-separated EXDATE lists (Google emits them) never parse; the exclusion drops silently and cancelled occurrences reappear on the agenda. Split on "," before parsing; no comma-case test exists. +- =:902= — timed events without DTEND render as all-day (time lost); multi-day all-day spans collapse to one day (end date unused, exclusive-DTEND unhandled). Emit start-time-only stamps and org date ranges. + +** TODO [#A] Native compilation disabled config-wide; GC at stock 800KB :bug: +From the 2026-06 config audit (verified against the live daemon). =early-init.el:69= =(setq native-comp-deferred-compilation nil)= — the obsolete alias of =native-comp-jit-compilation= — turns JIT native compilation OFF entirely, not "synchronous" as the comment claims: 19 .eln files exist for 184 packages, ~100 of 121 modules run interpreted for the daemon's lifetime, and system-defaults.el:42-44's speed-3/8-jobs/always-compile settings are dead. Plus =early-init.el:113-116= restores =gc-cons-threshold= to the captured STOCK default (800000, verified) post-startup — frequent small GC pauses forever. Together these plausibly feed the filed org-capture 15-20s task more than anything in the capture path itself. Actions: retest the old "Selecting deleted buffer" race on 30.2 and re-enable JIT (or AOT sweep); set a deliberate 16-64MB threshold (or gcmh). Check both before burning time on the capture-perf debug task. + +** TODO [#A] Global yes-or-no-p fset defeats every strong confirmation :bug:quick: +=modules/system-defaults.el:203= =(fset 'yes-or-no-p 'y-or-n-p)= — verified live. Several modules deliberately chose yes-or-no-p as the strong tier for irreversible actions: shutdown/reboot (=system-commands.el:74=, whose comment explicitly says "so a stray RET/space can't trigger them"), "permanently destroy files" (=dwim-shell-config.el:804=), file overwrites (=custom-buffer-file.el:159,199=, =music-config.el:374=). The fset makes all of them single-keystroke — the two-tier design is dead. Drop the fset, or provide a real =cj/confirm-strong= (typed "yes") for the irreversible set. From the 2026-06 config audit. ** TODO [#B] theme-studio preview face mislinks (org, erc, flycheck) :bug:theme-studio:quick:solo: :PROPERTIES: @@ -57,36 +113,12 @@ Found by Craig 2026-06-11 during the manual-test walk (org case), then a full au Pin with a browser-gate assertion that these preview elements link the right faces (e.g. the org headline-todo span sits after an org-todo span; the erc my-message line uses input-face). -** TODO [#C] theme-studio picker panel blends into the page :bug:theme-studio:ux:quick:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-11 -:END: -Craig, 2026-06-11 manual-test walk: the color picker's background is hard to distinguish from the page background. Give the picker panel a visibly distinct background or a highlighted border so it stands out. Pin with a gate asserting the picker element carries the distinct style. - -** TODO [#C] theme-studio Rust + Zig language previews :feature:theme-studio:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-11 -:END: -Requested by Craig 2026-06-11: add Rust and Zig code samples to the language previews (samples.py currently carries Elisp, Go, Python, TypeScript, Java, C, C++, Shell). Each sample should exercise the treesit token categories distinctive to its language (Rust: lifetimes, macros, attributes, traits; Zig: comptime, builtins, error unions), then regenerate theme-studio.html and extend the test surface. - ** TODO [#B] Split window opens the dashboard in the other window :feature:ux:windows:quick:solo: :PROPERTIES: :LAST_REVIEWED: 2026-06-10 :END: When splitting with C-x 2 (=split-window-below=) or C-x 3 (=split-window-right=), the new/other window should default to the =*dashboard*= buffer instead of mirroring the current buffer. Advise =split-window-below= / =split-window-right= (or rebind the keys) to select the dashboard in the freshly-created window. Keep point in the original window. -** TODO [#C] theme-studio face-consistency check :feature:theme-studio: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-10 -:END: -Rule taxonomy captured in [[file:docs/design/theme-studio-face-rules.org][docs/design/theme-studio-face-rules.org]] (Design Rules vs Fidelity Rules). The two checks below map to those two rule kinds. Both surface structural-attribute (weight/slant/underline/box/overline/height) issues; color is the theme's design and out of scope. - -1. Theme cross-cutting consistency (primary, per Craig 2026-06-09): the theme has deliberate cross-cutting rules — e.g. headings/titles are bold, links are underlined, errors/warnings/success are bold. Flag where the theme BREAKS ITS OWN rule (a heading that isn't bold, a link that isn't underlined). The designer declares the rules; the check finds the violators. This is the "tell me where I broke the rule" guardrail. - -2. defface-baseline divergence (secondary): flag where a face's structural attrs differ from its package =defface= so each divergence is deliberate, not an accidental drop. Would have caught the dropped underline/bold defaults and the contradictions (shr-h3 bold-vs-italic, erc-action italic-vs-bold) from the package-face audit as they were introduced. - -Bake into the tool (a lint surfaced in the UI) or run as a build-time check (seeds vs live deffaces via emacsclient). - ** TODO [#B] theme-studio palette ramps + contrast safety v1 :feature:theme-studio: :PROPERTIES: :LAST_REVIEWED: 2026-06-10 @@ -127,24 +159,6 @@ Phase 5 (commit =9daeff15=). Editing a family base recolors the whole family (sh *** 2026-06-10 Wed @ 01:17:45 -0500 Warnings, seeding, export, README close-out landed Phase 6 (commit =c175e2be=). Export stays a flat palette and import needs no reconstruction (#roundtriptest: export→import→export byte-identical). =seedPkgmap= reads the flat palette unchanged. The too-similar warning stays on the full palette — the planned ramp-step exemption was dropped after analysis: ramp steps are a stepL apart (well above the ΔE threshold) so they never warn, and exempting same-family pairs would hide genuine near-duplicates (caught by #deltatest). README documents families, the ground strip, the count control/regenerate, removed-step references, and the ramp-panel removal. -** TODO [#C] Color-family per-hex hint override :feature:theme-studio: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-11 -:END: -For the ~1 color per palette that sits on a ramp-collision point (e.g. yellow+2 on the distinguished palette, which by every hex signal belongs to the olive ramp though its name says gold), automatic grouping cannot recover the designer's intent. Add a per-hex family override: drag a swatch to a different column, store the override keyed by hex (never the name, so renaming is still free), consult it after the LCCL clustering, and drop/mark-stale it when the hex changes substantially. Export stays mostly flat; only overrides are extra metadata. Both reviews recommend this exact shape; details in =~/color-sorting-fable.org= (§ "The irreducible case") and =~/color-sorting-codex.org= (§ "What to store"). - -** TODO [#C] Internet radio now-playing song :feature:music:emms:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-11 -:END: -Show the currently-playing song while streaming an internet radio station. Lives in =modules/music-config.el= (EMMS + MPV backend, M3U radio stations). The track title comes from the stream's ICY metadata — EMMS exposes it via =emms-track-description= / =emms-playing-time= and updates it on the metadata-change hook; MPV reports the ICY title too. Add an option to show the song in the minibuffer (e.g. echo on track change, or an on-demand command). Consider also a mode-line indicator as a second surface. - -** TODO [#C] Evaluate jamescherti essential-emacs-packages list :packages:research:quick:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-11 -:END: -Review [[https://www.jamescherti.com/essential-emacs-packages/][James Cherti's essential Emacs packages]] for anything worth installing. Cross-check each candidate against what is already in the config (=modules/= + =init.el=), skip the ones already present, and shortlist the genuinely new ones with a one-line rationale. Future-installation research, not a commitment to install. - ** TODO [#B] Dupre diff-changed / diff-refine-changed legibility :bug:dupre: :PROPERTIES: :LAST_REVIEWED: 2026-06-11 @@ -171,64 +185,6 @@ Decided 2026-06-11 (Craig): #0d0b0a is the canonical background — the three dr *** TODO org-todo color mismatch: test expects #ff2a00, theme renders #a7502d =dupre-theme-org-todo= (test:130) asserts the org-todo foreground is "#ff2a00" (intense-red), but the theme renders "#a7502d" (red-1). Design call: should org-todo be the bright intense-red or the muted red-1? Fix whichever side loses the decision. -** TODO [#C] dupre-clear theme — contrast-first AAA sibling :feature:theme:dupre: -Build a new theme (working name "dupre-clear", final name TBD) that takes dupre's color identity and rebuilds it Prot's way: contrast-first, targeting WCAG AAA (~7:1 on the ground), where the in-progress dupre revision is mood/depth-first and lands at AA. Same hues (dupre blue, emerald, gold, terracotta, regal violet, mint) brightened to clear the AAA floor; same modus-style role mapping (blue keywords bold, gold functions, violet types, emerald strings, terracotta constants, silver default, warm-grey comments, metallic greys, navy + regal fills). Build the dupre revision first; this reuses its hue choices as the starting point. - -Full design + methodology + starting palette + open questions in the spec: [[file:docs/design/dupre-clear-theme.org][docs/design/dupre-clear-theme.org]]. Key prerequisite/context: the dupre-redesign entry in =.ai/session-context.org= (the AA palette this brightens). Hardest slot: blue keywords (a deep dupre blue can't be AAA on near-black — decide brighten vs keep-AA-exception vs lift-the-ground). -** TODO Manual testing and validation :verify:theme-studio: -Exercised once the phases above land. -*** 2026-06-11 Thu @ 18:29:39 -0500 Verified UI-face preview and contrast survive a ground bg change -Craig walked the repro: mode-line with its own fg/bg kept its preview bg and ratio through a ground change; ground-dependent rows re-rated; package-faces contrast column updated. Pass. Closed the [#A] contrast-cell and [#B] preview-bg parents. -*** 2026-06-11 Thu @ 18:29:39 -0500 Verified seeded package-face defaults, with steel tuning -Craig read org/magit/elfeed against the ground. Pass with tuning: steel reads a bit dark — flipped to steel+1 on magit (better), but org wanted darker; these are updated selections, NOT final — he expects to adjust many more before the theme ships. His export saved to scripts/theme-studio/theme.json (replaced the 2026-06-09 state, prior version in git at 4f2d00eb). Side find: the org preview's heading-three ↔ headline-todo flash linkage is cross-wired — filed as its own bug task. -*** 2026-06-11 Thu @ 18:29:39 -0500 Verified large face tables stay usable -Craig scrolled the org table, filtered on "agenda", reassigned a face — grouping, narrowing, and live preview update all behaved. Pass. -*** 2026-06-11 Thu @ 18:29:39 -0500 Verified perceptual readouts in the picker -Craig validated the readouts against computed reference values (default fg #f0fef0 on ground #000000: APCA Lc -104.7 / WCAG 20.14; keyword blue #67809c: Lc -33.7 / WCAG 5.14 — negative polarity correct for light-on-dark). Legible, uncrowded. Pass. Side find filed separately: the picker panel itself blends into the page background ([#C] picker-visibility task). -*** 2026-06-11 Thu @ 18:29:39 -0500 Verified ΔE warnings read clearly -Craig built a near-duplicate pair and a well-spread palette: the close pair was named with its ΔE, sorted closest-first with the cap behaving; no warning on the spread palette. Pass. -*** TODO OKLCH editor feels right -What we're verifying: the OKLCH sliders / C×L plane edit cleanly and clamping is visible. -- Switch the picker to OKLCH mode and drag L, then C, then H -- Push chroma past the sRGB gamut, then toggle the AA/AAA mask -Expected: each axis moves independently; the C×L plane (once 4b lands) opens on the current color; "chroma clamped to sRGB" shows on clamp; toggling the mask does not reset OKLCH mode. -*** TODO Generated ramp harmonizes -What we're verifying: a ramp generated from a base color reads as one family, not a grab-bag (the aesthetic the math is meant to produce). -- Open =scripts/theme-studio/theme-studio.html= in Chrome -- Pick a mid-lightness base swatch (e.g. a blue) and generate its ramp at the defaults -- Read the row of steps left to right, then try a near-black and a near-white base -Expected: the steps share an obvious hue and step evenly in lightness; the chroma-ease keeps the extreme steps from going muddy or garish; nothing looks like it belongs to a different color. -*** TODO Safe-lightness guidance reads clearly -What we're verifying: the L_max marker and unsafe-band shade are legible and land in the right place when editing a covered face. -- Open the picker in OKLCH mode on region (or hl-line), with syntax colors assigned -- Read the L_max marker and the shaded unsafe band on the lightness slider -- Drag lightness up toward and past the marker -Expected: the marker is visible and correctly placed, the band above it reads as "unsafe," and crossing it is obvious; an out-of-scope face shows no marker. -*** TODO Safe tint actually reads in real Emacs -What we're verifying: a background tint the tool calls safe really keeps every token readable behind real syntax-colored text — the whole point of the worst-case floor. -- In the tool, set a covered face (e.g. region) to a tint at or just below its L_max with the worst-case readout showing PASS -- Build the theme and load it in Emacs, open a code buffer with varied syntax, and select a region spanning many token colors -- Read every token through the region highlight, paying attention to the limiting foreground the tool named -Expected: every token stays readable over the tint, including the limiting one; a tint pushed just past L_max (readout FAIL) shows a visibly strained or unreadable token, confirming the floor matches reality. -*** TODO Color families group the way the eye reads them -What we're verifying: the OKLCH hue clustering (25° gap) splits and merges families the way you'd expect, and renaming never moves a color. -- Open =scripts/theme-studio/theme-studio.html= in Chrome and load a real theme (e.g. sterling) -- Read the strips top to bottom: are "the blues" one strip, "the greens" another, neutrals and ground pinned at the top -- Find a pair you'd consider one family that landed in two strips (or two you'd consider separate that merged) -- Rename any swatch to something absurd and confirm it stays in the same strip -Expected: families match your mental grouping; the few that don't are the cue to revisit the 25° gap; renaming never regroups. -*** TODO Regenerate-replace reads as deliberate -What we're verifying: the count control clearly signals it rewrites the whole family, so replacing hand-added same-hue colors isn't a surprise. -- Add two unrelated colors at a similar hue so they share a strip -- Set that strip's count to 2 -- Watch what happens to the two colors -Expected: the strip becomes a clean base±2 ramp, the two loose colors are gone, and the control made it obvious that's what it would do before you committed. -*** TODO Removed-step references read clearly as "(gone)" -What we're verifying: lowering a family's count leaves a referencing face visibly stale, not silently re-pointed. -- Assign a UI or syntax element to an outer step of a family (e.g. region = a blue+3) -- Lower that family's count to 2 so blue+3 disappears -- Read the assignment's dropdown -Expected: the dropdown shows "(gone)" for the removed step, never a silent jump to a different color; re-pointing it is a deliberate choice. ** TODO [#B] theme-studio guide-support features :feature:theme-studio: From the color-assignment guide work (2026-06-08): make the tool support the guide without mandating it — everything a seed, an advisory, or a view, never a gate. Two specs to write, both deriving from the rewritten guide and its seed table ([[file:scripts/theme-studio/theme-coloring-guide.org][theme-coloring-guide.org]]). *** 2026-06-08 Mon @ 19:08:00 -0500 Seeding-engine spec written and Ready @@ -243,67 +199,11 @@ Phase 1. Palette anchors + OKLCH shade generation (reusing colormath.js), the RO Phase 2. Initial state from seed() plus seedPkgmap for the non-org packages; all-tier reseed button with a scope-named overwrite warning, resetting non-org to their APPS defaults; regenerate dupre-revised.json. Gate: #selftest PASS; default-on-open equals seed(); artifact round-trip (regenerated dupre-revised.json imports back to the same seeded state); Chrome eyeball. *** TODO Seeding-engine test surface :solo:tests: Keep #seedtest, #selftest, the default-on-open check, the dupre-revised round-trip, node --check, and Chrome validation green. -** TODO [#C] theme-studio terminal/ANSI colors :feature:theme-studio: -theme-studio represents GUI faces only; terminal colors aren't surfaced at all. Scope decided 2026-06-09: GUI-first faces, NOT full per-face display-class fallback. Two pieces: - -1. ANSI-16 panel. Map the 16 ANSI slots (black/red/green/yellow/blue/magenta/cyan/white + bright variants) to palette colors, with a preview, and export them so =build-theme.el= emits the =ansi-color-*= / =term-color-*= faces. This matters even in pure-GUI Emacs: colored shell output, compilation buffers, eshell, and vterm/eat all draw from these. Signals must line up with their ANSI slot (error red→ansi red, success→green, warning→yellow, info/link→blue) so a signal reads the same in a terminal. - -2. Core-face 16-color fallback. Only the ~10 faces that decide console legibility get a =(((class color) (min-colors 16)) ...)= clause plus a =(t ...)= floor: default/fg, bg, keyword, string, comment, constant, error, warning, region, mode-line, line-number. Tune these for contrast — push it UP, legibility over fidelity, because the only 16-color target is the bare Linux virtual console (an occasional emergency context). The long tail stays GUI-first and auto-approximates. - -Why this scope: the GUI and the normal terminal (foot + tmux, truecolor / ≥256-color) both render the GUI hexes fine; GUI-first is correct there. Only the Linux VT is 16-color, and a low-contrast palette approximates badly down to 16 — so a few core faces get a deliberately higher-contrast 16-color fallback rather than every face carrying a multi-spec. Tool work: the ANSI-16 panel + a flag on the core faces to also capture a 16-color value; =build-theme.el= emits multi-spec only for those. Full per-face fallback is revisited only if console work becomes regular. -** TODO [#D] theme-studio per-tier reseed controls :feature:theme-studio: -Deferred from the seeding-engine spec (vNext). V1 reseeds all three guide-owned tiers at once; later consider separate "reseed syntax", "reseed UI", and "reseed package/org" controls if all-at-once proves too blunt. Spec: [[file:docs/design/theme-studio-seeding-engine-spec.org][spec]] (vNext; review folded in 2026-06-08). -** TODO [#D] theme-studio low-contrast preset/mask mode :feature:theme-studio: -Deferred from the perceptual color metrics spec (vNext). After raw OKLCH/APCA/DeltaE readouts exist, decide whether to add a named low-contrast workflow: APCA Lc bands, a contrast ceiling/floor mask, or a "soft" sibling to the existing any/AA+/AAA picker mask. Spec: [[file:docs/design/theme-studio-perceptual-color-metrics-spec.org][spec]] (vNext candidates; review folded in 2026-06-08). -** TODO [#D] theme-studio CIEDE2000 DeltaE option :feature:theme-studio: -Deferred from the perceptual color metrics spec (vNext). v1 uses DeltaE-OK on its native scale with a 0.02 threshold (decided); revisit CIEDE2000 only if the native OKLab scale proves too unfamiliar or poorly calibrated for palette distinguishability. Spec: [[file:docs/design/theme-studio-perceptual-color-metrics-spec.org][spec]] (vNext candidates; review folded in 2026-06-08). ** TODO [#B] Dashboard keybinding changes :quick: :PROPERTIES: :LAST_REVIEWED: 2026-06-06 :END: pressing g has should refresh. find another binding for Telegram. -** TODO [#A] Calibre Open Work :calibre: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-06 -:END: -Parent grouping the open Calibre / ebook-workflow issues; close each child independently. The EPUB reading-width tasks were already resolved (2026-05-12/14). - -*** DOING Calibre bookmark title format :feature:solo:quick: -When I hit m in calibre, I'm making my place in the book with a bookmark. -While sometimes, the books look fine: "The A.B.C. Murders - Agatha Christie.epub" -Sometimes they look not so good: Engines of Logic_ Mathematicians and the O - Martin Davis.pdf or Software Architecture_ The Hard Parts _ Mo - Neal Ford.pdf - -What I would like to do is to have the bookmarks be saved in the following format: - -Author, Title [no extension]. Underscores should be stripped. - -Root cause: in a nov buffer =m= is =bookmark-set= (rebound at calibredb-epub-config.el:311); nov's =nov-bookmark-make-record= names the record =(buffer-name)= -- the EPUB filename. - -Implemented 2026-06-06. Source decision: parse the *filename*, not the embedded EPUB metadata -- under Calibre's "<Title> - <Author>.epub" naming the filename is more complete (the embedded metadata had truncated titles, author-sort "Last, First" forms, and lost punctuation; see the separate metadata-cleanup task). A =:filter-return= advice on =nov-bookmark-make-record= rebuilds the name from the record's filename: split on the last " - " into title/author, restore the colon Calibre sanitized to "_ " (-> ": "), reorder to "Author, Title". Pure helpers =cj/--nov-clean-title= + =cj/--nov-bookmark-name-from-file= in =modules/calibredb-epub-config.el=; 10 ERT tests in =tests/test-calibredb-epub-config--bookmark-name.el=. Live in the daemon. - -Existing bookmarks: the 3 nov bookmarks in =~/sync/org/emacs_bookmarks= were renamed by hand (one-pass, in the daemon + saved; backup at =emacs_bookmarks.bak-2026-06-06=): "Edward Kanterian, Frege: A Guide for the Perplexed", "Agatha Christie, The A.B.C. Murders", "Edward Abbey, The Fool's Progress: An Honest Novel". - -Awaiting Craig's manual confirm: make a NEW bookmark (open an EPUB, hit m) and check the default name is "Author, Title" from the filename. - -*** DOING [#A] Reconsider Calibre keybindings :feature:ux: -Relocated from the global capture inbox 2026-06-06. Want a discoverable set of keybindings (visible in which-key) for the most frequent calibredb workflows: -- Switch to a library (e.g. Literature), sort by last name, scroll the list. -- Scope/filter the list in place, keeping the current library scope: - - by format (e.g. epubs only) - - by author last name (exact == or ^begins-with some text) - - sort by title, publication date, or group by format -- One key pops up the selected book's description in a bottom-30% buffer, dismissed with q (same display pattern as the signel chat dock). -- RET opens the book in the appropriate viewer. -Survey finding 2026-06-06: calibredb already binds almost all of this in calibredb-search-mode-map (S/L library, g filter [f format, a author, t tag, d date], o sort [t title, a author, p pubdate, f format], RET open) and even ships transient menus (? = calibredb-dispatch, g, o). The real problem was discoverability -- they are top-level single keys (which-key never pops up) and Craig didn't know ? opened a menu. calibredb-quick-look is macOS-only; the detail view (v -> *calibredb-entry*, q quits) is the description but opens full-window. - -Implemented 2026-06-06 in =modules/calibredb-epub-config.el=: -- A curated transient =cj/calibredb-menu= (library switch; filter format/author/reset; sort author/title/pubdate/format; open; describe; H = full calibredb-dispatch) bound to =?= in calibredb-search-mode-map. calibredb's own full dispatch moved to =H=. Defined in the use-package =:config= (needs the elpa transient, which batch doesn't load) -- the "? brings up a curated help menu" convention. -- Bottom-30% description dock: =calibredb-show-entry-switch= -> =pop-to-buffer= + a =display-buffer-alist= rule for =*calibredb-entry*= (display-buffer-at-bottom, height 0.3); =cj/calibredb-describe-at-point= shows the entry without switching focus so q dismisses it. Same pattern as the signel chat dock. -1 ERT test (the describe command; the transient/bindings/dock need the elpa transient + live calibredb, verified in the daemon). Author "begins-with" is covered well enough by g a's completing-read over "Last, First"; a true regex filter was not built. Awaiting Craig's manual verify (M-B -> ? menu; d/v docked description; H full menu). - -*** TODO Embed Calibre DB metadata into the EPUB files :data:maintenance: -Surfaced 2026-06-06 while building the bookmark naming: the metadata embedded in the EPUB files' OPF is worse than Calibre's database metadata. nov reads the embedded OPF and got truncated titles ("Frege" vs the filename's "Frege: A Guide for the Perplexed"), author-sort "Last, First" forms ("Christie, Agatha"), and lost punctuation ("A.B.C." -> "A B C"). The filenames (from Calibre's curated DB) are the good copy. Fix on the Calibre side: select all (or by library), run "Edit metadata -> Embed metadata into book files" so the DB metadata is written into each EPUB's OPF. Consider auditing author vs author_sort first. After embedding, the in-file metadata matches the library and any tool reading the files (nov, other readers, re-imports) gets the good data. Not an Emacs task; Calibre-side bulk maintenance. - ** TODO [#B] TTY-accessible personal C-; keymap :feature:ux:solo:quick: :PROPERTIES: :LAST_REVIEWED: 2026-06-05 @@ -319,4194 +219,4294 @@ Easy prefix candidates (home-row-leaning, TTY-safe), same leaf keys under each: While in here, audit individual leaf chords for other non-TTY keys (any =C-RET=, super/hyper bindings — terminals can't send super/hyper either) and note or remap them. Verify the result in an actual =emacs -nw= / =emacsclient -nw= frame, not just GUI. Relates to the standing "org-mode keybinding consolidation" reminder. -** DOING [#B] Signel Client Open Work +** TODO [#B] F-key Completion :feature: :PROPERTIES: -:LAST_REVIEWED: 2026-06-06 +:LAST_REVIEWED: 2026-06-02 :END: -Parent task for the Emacs Signal client. Engine: signal-cli (linked secondary device). Front end: a fork of signel at =~/code/signel=, wired through =modules/signal-config.el=. Design: [[file:docs/design/signal-client.org][docs/design/signal-client.org]]. Child issues below. -*** 2026-05-26 Tue @ 20:06:58 -0500 Decided: fork signel rather than depend on it -signel is on MELPA but stale (one-author v0.1, all commits in a Jan-2026 burst, unattended tracker, no PRs). The spec needs internal edits (notify behavior, input-clobber fix), which are clean in a fork and hacky via advice, and a dead upstream means no divergence cost. Rejected: adopt-from-MELPA + advice, build-from-scratch, signal-cli-rest-api (Docker), MCP-tool, ERC bridge. Full rationale in the design doc. +The L546 ticket "Rework dev F-keys" landed roughly 75% as of the 2026-05-27 audit. F4 (compile+run dispatcher, project-type detection, clean-rebuild, projectile cache revert), F7 (coverage), and the format-key migration off F6 are all shipped with ERT coverage. F6 ships Phase 2a only — "All tests" and "Current file's tests" via plain F6 and C-F6. -*** 2026-05-26 Tue @ 20:06:58 -0500 Linked as secondary device; contact parser verified against live shape -Installed signal-cli 0.14.4.1 (AUR; imported AsamK's signing key FA10826A... to clear the makepkg verification). Linked the account via QR. Built and unit-tested the pure helper layer in =modules/signal-config.el= (contact-list parsing, notify-when-not-viewing predicate) with =tests/test-signal-config.el=. Confirmed the live =listContacts= shape: givenName/familyName are top-level in 0.14, not under profile as first assumed; corrected the parser and verified it produces a picker entry for all 94 real contacts. Sent a request to archsetup to add signal-cli to the standard install. +Phase 2b remains: per-language test discovery, the "Run a test..." menu entry, M-F6 fast path, buffer-local last-test memory, and the spec-mandated "No tests found for <buffer>" error. The =dev-fkeys.el= header (L35–46) already sketches the tree-sitter capture-then-filter pattern needed to work around Emacs bug #79687 on the emacs-30 branch. -*** 2026-05-27 Wed @ 22:08:40 -0500 Shipped initiate-message workflow: picker + Note-to-Self + keymap -=cj/signel-message= (=C-; M m=) names contacts via =completing-read= over the cj-owned =cj/signel--contact-cache=, with "Note to Self" pinned first. =cj/signel-message-self= (=C-; M s=) sends straight to =signel-account=. Daemon guard =cj/signel--ensure-started= auto-starts the daemon when =signel-account= is set and =user-error='s with the remedy when it isn't; on start it pre-warms the cache. =cj/signel--fetch-contacts= rides the new RPC callback contract (=signel--send-rpc= with success-callback), the result feeds =cj/signal--parse-contacts=, and =cj/signel-refresh-contacts= (=C-; M no leaf=) clears + refetches. Cold-cache invocations =accept-process-output= up to =cj/signel-fetch-timeout= seconds (3s default) and =user-error= on timeout so a wedged daemon can't hang Emacs. Prefix keymap =cj/signel-prefix-map= bound under =C-; M= via =keybindings.el='s =cj/custom-keymap=: m / s / d / q / SPC. 15 new ERT tests in =tests/test-signal-config.el= cover ensure-started branches, fetch contract, cache empty-vs-failure, refresh, picker happy-path + cold-cache resolves + cold-cache timeout, message-self, and the prefix map bindings. +Two smaller cleanups also fall out: the header comment claims TS/JS is "punted for v1" while the cmd-builder at =dev-fkeys.el:384= actually emits a vitest/jest command, and the cmd-builder is a likely home for =cj/--tests-in-buffer= once it lands. -*** 2026-05-27 Wed @ 21:55:57 -0500 Added JSON-RPC success-result dispatch in the signel fork -Fork commit 4740d97 added =signel--request-handler-map= (id → success callback), extended =signel--send-rpc= with an optional =success-callback= that registers under the new request id, and gave =signel--dispatch= a result branch that invokes the callback and removes the handler. Error responses also remhash the handler entry, and =signel-start= / =signel-stop= both =clrhash= the map so reconnect is reliably empty. Backward-compatible: existing callers that don't pass a callback hit the same code path as before. Five ERT tests in this project (=tests/test-signel-rpc-dispatch.el=, dotemacs commit bfec0eab) lock the contract: Normal (result invokes callback + cleanup, send-rpc registers), Boundary (unknown id is a no-op), Error (error response cleans up handler), reconnect (=signel-stop= empties the map). Refactor audit surfaced a separate pre-existing leak in =signel--handle-error= (request-buffer-map entries aren't removed on error); filed as the [#C] follow-up below. +Open: helper home — keep =cj/--tests-in-buffer= in =dev-fkeys.el= (per L546 spec) or push it into =test-runner.el= (per the parallel "Fix up test runner" thread). Elisp "Run a test..." — drill into individual =ert-deftest= names, or keep the current regex-aggregate (=make test-name TEST=^test-<stem>-=). -*** TODO [#C] signel--handle-error leaks request-buffer-map entries :bug:no-sync: -Surfaced during the JSON-RPC dispatch refactor audit. =signel--handle-error= reads =signel--request-buffer-map= by id but never =remhash='es the entry, so every error response leaves the request-id → buffer-name mapping behind for the life of the process. Low impact (the map clears on stop/start, and id collisions are unlikely at the counter scale), but unbounded growth in a long-lived session and inconsistent with how the new request-handler-map is cleaned up on error. +*** TODO [#B] Per-language test discovery helper :feature:tests: +Build =cj/--tests-in-buffer= returning a list of test names; tree-sitter capture-then-filter for python/go/ts/js per the bug #79687 workaround in =dev-fkeys.el= L35–46; sexp scan for elisp =ert-deftest= forms. -*** DOING [#B] Notify only for the unviewed conversation :feature: -Wire =cj/signal--should-notify-p= (done) into signel's =signel--handle-receive= notify block (signel.el:277), route through Craig's notify script instead of bare =notifications-notify=, and gate sound behind a defcustom that defaults off. Spec addendum (the four notify details + wiring architecture) accepted 2026-06-11 — see [[file:docs/design/signal-client.org][signal-client.org]] "Notification slice". +*** TODO [#B] F6 Run-a-test menu entry :feature:tests: +Add "Run a test..." to =cj/f6-test-runner= candidates; pre-select =cj/--last-test-run=; signal =user-error= "No tests found for <buffer>" when discovery returns nil. -Built 2026-06-11 (TDD; fork commit e263367, dotemacs 9afc6128): =signel-notify-function= customization point in the fork; =cj/signel--notify= + =cj/signal--format-notify-body= + =cj/signel-notify-sound= in signal-config.el, wired in =:config= with a load-time =cj/executable-find-or-warn=. 17 new ERT tests green; full launch smoke clean; live-reloaded into the daemon and a synthetic toast fired through the script path. Stays DOING until the two manual checks below pass. +*** TODO [#B] M-F6 fast path :feature:tests: +Bind =M-<f6>= to a thin wrapper that calls the same "Run a test..." path directly; release the reservation comment at =dev-fkeys.el:541=. -**** Signel: real incoming message raises a toast through the notify script -What we're verifying: the full receive path (signal-cli → signel --handle-receive → cj/signel--notify → notify script) fires on a real message. -- Make sure you are NOT viewing the sender's chat buffer. -- Have a real message sent to you on Signal (or send one from your phone to a second device thread that lands here). -Expected: a transient info toast titled "Signal: <sender>" with the message text (one line, truncated if long), no sound. +*** TODO [#B] Buffer-local cj/--last-test-run :feature:tests: +Add the buffer-local var, set it on each "Run a test..." selection, use it as the completing-read default so a bare RET re-runs the last test. -**** Signel: actively-viewed chat stays quiet -What we're verifying: the suppression predicate gates the toast when you're reading that chat. -- Open the sender's chat buffer (=C-; M m=) and keep it the selected window in a focused frame. -- Have the same sender message you again. -Expected: the message renders in the buffer, but no desktop toast appears. - -*** 2026-05-27 Wed @ 22:08:40 -0500 Shipped clobber fix for both insert paths -Fork commit 5ec56c0 added =signel--pending-input= (capture from input-marker to point-max) and =signel--restore-input= (re-insert after the redrawn prompt; nil-safe), and wired both into =signel--insert-msg= (the receive path) and =signel--insert-system-msg= (the error path). A mid-type send now survives both an incoming message and a system-error insertion. Four ERT tests in =tests/test-signel-input-preservation.el= cover the helpers (typed text, empty) and both insert paths via a temp =signel-chat-mode= buffer. - -*** TODO [#B] Link command with QR :feature: -=cj/signel-link= wrapping =signal-cli link -n NAME=, capturing the =sgnl://linkdevice= URI and rendering it as a scannable QR (qrencode). Convenience for re-linking; the first link was done by hand this session. - -*** 2026-05-27 Wed @ 22:08:40 -0500 use-package wired with C-; M keymap and local account config -=use-package signel :load-path "~/code/signel" :ensure nil= already wired earlier with =signel-auto-open-buffer nil=. Account source is =signel-account= set from =cj/signal-private-config-file= (=signal-config.local.el=, gitignored) loaded in =:config=, decided in the workflow spec. Keymap prefix =C-; M= attached via =with-eval-after-load 'keybindings= so the binding survives load-order. - -*** TODO [#D] Include Signal groups in the picker :feature:no-sync: -vNext after the 1:1 initiate-message flow is stable. Merge =listGroups= with =listContacts=, label groups distinctly, and preserve the current v1 behavior where the picker is contacts-only. - -*** 2026-06-06 Sat @ 12:29:24 -0500 Fixed C-; M load-order bug via canonical register-prefix-map -Root cause: signal-config.el was the only feature module that violated the prefix-registration contract documented in =keybindings.el:41-45=. Every other prefix map uses =(require 'keybindings)= + a top-level =(cj/register-prefix-map "X" map)=; signal-config had neither, mutating =cj/custom-keymap= directly through a =(with-eval-after-load 'keybindings (when (boundp 'cj/custom-keymap) ...))= form. The =boundp= guard turned a load-order miss into a SILENT no-op — no error, the binding just never happened — which is why a live-reload (keybindings definitely loaded by then) papered over it. -Fix: added =(require 'keybindings)= at the top of signal-config.el and replaced the guarded form with =(cj/register-prefix-map "M" cj/signel-prefix-map "signal messages")=, matching the 25+ other prefix maps. -Verified: (1) new contract test =test-signal-config-prefix-map-registered-under-c-semi-m= asserts =C-; M= resolves to =cj/signel-prefix-map= (35/35 green); (2) full =emacs --batch= init.el launch — the exact failing scenario — now shows =C-; M= bound; (3) clean byte-compile; (4) live-reloaded into the daemon, binding confirmed. No unit-level red was possible: the =boundp= guard is robust under all standard test timings, which is the CLAUDE.md launch-only-failure class. - -*** 2026-05-28 Thu @ 03:09:18 -0500 Chat buffer docks bottom 30% and C-c C-k cancels -=display-buffer-alist= entry in =modules/signal-config.el= matches =^\*Signel: = chat buffers and routes them through =display-buffer-at-bottom= with =window-height . 0.3=, so the chat docks to the bottom 30% of the frame. The signel fork's =signel-chat= switched from =switch-to-buffer= to =pop-to-buffer= so the rule can apply (=switch-to-buffer= ignores =display-buffer-alist=). =C-c C-c= was already bound to =signel--send-input= in the mode; =C-c C-k= now binds =signel--cancel-input=, a new fork helper that clears the editable region between =signel--input-marker= and =point-max= and then calls =quit-window=. Buffer stays alive so chat history above the marker survives revisits; cleared input means the next visit lands on a fresh prompt. Five ERT tests in =tests/test-signel-cancel-input.el= (clears pending, empty-area no-op, quit-window called, buffer preserved, keymap binding) and two new tests in =tests/test-signal-config.el= (entry shape + regex match set). Dotemacs commit 998e9c7a, fork commit df02d79. +*** TODO [#B] TS/JS coverage status sync :docs:cleanup: +Update the =dev-fkeys.el= header comment (L33) — TS/JS is no longer punted; the cmd-builder at L384 emits vitest/jest. Document the prefer-vitest fallback. -** DOING [#B] Migrate All Terminals From Vterm to Ghostel :terminal:ghostel: +** TODO [#B] Fix up test runner :bug: :PROPERTIES: -:LAST_REVIEWED: 2026-06-04 +:LAST_REVIEWED: 2026-06-06 :END: -Replace vterm with ghostel (libghostty-vt) as the single terminal engine across every workflow, and rename ai-vterm → ai-term. References: [[file:docs/2026-05-25-emacs-terminal-comparison.org][docs/2026-05-25-emacs-terminal-comparison.org]] (vterm vs eat vs ghostel research); migration spec [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] (READY; external review incorporated 2026-06-04, D1-D7 agreed). Build in 5 phases (0-4); see the spec's Implementation tasks block. - -Decisions D1-D7 are settled in the spec's Agreed-decisions section. Build order below; each phase stays green (suite + byte-compile) at every step. - -*** 2026-06-04 Thu @ 23:57:09 -0500 Phase 0 done: characterization baseline green -=make test= green except the 5 documented pre-existing failures (4 test-dupre-theme, 1 test-init-module-headers), none terminal-related. Characterization coverage already present + green for all six must-survive behaviors: vterm-toggle--dispatch/display/buffer-filter, vterm-tmux-history, ai-vterm--show-or-create/launch-command/f9-in-vterm, ui-config--buffer-cursor-state + vterm-copy-mode-cursor, dashboard-config-launchers. Add a characterization test before any behavior change in later phases if a gap appears. +*** 2026-05-16 Sat @ 11:15:51 -0500 Ideas +**** Current State +=modules/test-runner.el= is a solid first pass for an Emacs-config-specific ERT +workflow: +- project-scoped focus lists +- run all vs focused mode +- run ERT test at point +- load all test files +- clear ERT tests from other project roots +- keybindings under =C-; t= -*** 2026-06-05 Fri @ 00:38:34 -0500 Phase 1 done: ghostel + term-config.el -=modules/term-config.el= written (full port of vterm-config: tmux history/copy-mode-dwim preserved via process-tty-name + ghostel-send-string; F12 toggle + display rule + geometry; cj/term-map C-; x menu → ghostel commands; which-key "terminal menu"; ghostel-max-scrollback 10MB; C-; added to ghostel-keymap-exceptions; F12 + C-; in ghostel-mode-map; use-package ghostel guarded per D6). Dropped: mouse-wheel SGR forwarding, vterm-timer-delay hacks, copy-mode cursor hook, goto-address hook. ghostel installed into elpa (MELPA + auto-downloaded native module). Tests: test-term-toggle--{dispatch,display,buffer-filter} + test-term-tmux-history (16) ported with a ghostel stub in testutil-ghostel-buffers; all green. +The universal test-running direction is currently split across modules: +- =test-runner.el= owns ERT focus/state/UI. +- =dev-fkeys.el= owns F6 language detection and command generation for Elisp, + Python, Go, and partial TypeScript. -*** 2026-06-05 Fri @ 00:38:34 -0500 Phase 2 done: ai-vterm→ai-term on ghostel -=modules/ai-vterm.el= → =modules/ai-term.el=: 6 vterm call sites swapped to ghostel (buffer named via let-bound ghostel-buffer-name + pinned ghostel-buffer-name-function so OSC titles don't rename agent buffers); F9/C-F9/M-F9 on global + ghostel-mode-map; refuse-in-terminal guard removed (D4 — F9 launches in TTY frames); tmux-suppression invariant preserved (cj/--ai-term-suppress-tmux). 23 ai-vterm tests renamed → test-ai-term--* (terminal-guard test deleted, obsolete); show-or-create + f9-in-term rewritten for ghostel; all green. ui-config cursor-state ported (ghostel-mode + ghostel--input-mode; copy/emacs = read-only, else writeable) + its test. init.el now requires term-config + ai-term; vterm-config.el + ai-vterm.el deleted. Full suite green except the 5 documented pre-existing failures (4 dupre-theme, 1 init-module-headers/popper-config-missing — both unrelated). validate-modules ✓; full early-init+init smoke clean (no ghostel/term/ai-term errors). vterm package still installed (Phase 4) — dashboard "Launch VTerm" + dormant auto-dim still reference it until Phase 3/4. Restart Emacs to pick up ghostel (load-order + use-package :config change). +That split is the biggest architectural pressure point. The test runner should +eventually own runner discovery, scopes, command construction, result handling, +and UI. F6 should become a thin entry point into the runner. -*** TODO [#B] Phase 2: rename ai-vterm→ai-term on ghostel :terminal:ghostel: -Swap the 6 vterm call sites; F9 family on global + ghostel-mode-map; drop refuse-in-terminal guard (D4); preserve the tmux-suppression invariant. Rename engine-agnostic tests after green; rework coupled tests; add D4 + F12-excludes-agent regression tests. +**** Critical Design Issues +***** Too ERT-specific at the core +The current state model is named generically, but most operations assume: +- test files live in =test/= or =tests/= +- files match =test-*.el= +- tests are ERT forms +- individual tests can be selected by ERT selector regex +- loading tests into the current Emacs process is acceptable -*** 2026-06-05 Fri @ 00:50:58 -0500 Phase 3 done: satellites ported to ghostel -Deleted auto-dim's vterm color-advice + redraw integration (~165 lines; D1 — terminals don't dim, ghostel bakes its palette per-terminal so there's no per-window color hook); dashboard launcher → =(ghostel)= + "Launch Terminal" label; cj-window-geometry/toggle-lib doc comments; module-inventory + init-load-graph doc refs. (ui-config cursor-state + init.el requires landed in Phase 2.) Trimmed test-auto-dim-config (dropped the 6 vterm tests) + updated the dashboard-launcher test stub. Incidental: removed the stale =popper-config= entry from the test-init-module-headers allowlist (the file doesn't exist + isn't required) — fixes the long-standing pre-existing test failure. +This makes the module hard to extend cleanly to pytest, Jest, Vitest, Go, Rust, +or shell test runners. The common abstraction should be "test run request" and +"test runner adapter", not "ERT file list". -*** 2026-06-05 Fri @ 00:50:58 -0500 Phase 4 done: vterm + vterm-toggle removed -=package-delete='d vterm + vterm-toggle from elpa. No vterm refs remain in modules/init except intentional historical comments. Suite green except the 4 pre-existing dupre-theme failures (the popper-config one is now fixed). validate-modules ✓; full early-init+init batch smoke = INIT-SMOKE-OK. The migration parent stays DOING until Craig restarts Emacs and walks the ghostel manual-verify matrix under "Emacs Manual Testing and Validation". +***** In-process ERT causes state contamination +=cj/test-load-all= and focused runs load test files into the current Emacs +session. This is fast and ergonomic, but it can leak: +- global variables +- advice +- loaded features +- overridden functions +- ERT test definitions +- load-path mutations -*** TODO [#B] Follow-up: theme ghostel ANSI faces in dupre :terminal:ghostel:dupre: -D2 — set the 16 ghostel-color-* + ghostel-default faces in dupre-faces/palette. +The runner should support two ERT execution modes: +- =interactive= / in-process for fast local TDD +- =isolated= / batch Emacs for reliable verification -*** TODO [#B] Follow-up: evaluate ghostel-eshell + ghostel-compile :terminal:ghostel:eval: -D3 — ghostel-eshell as eshell visual backend; ghostel-compile against F4 dev-fkeys. +The isolated path should be preferred for "before commit", CI parity, and +agent-driven verification. -*** 2026-06-05 Fri @ 14:24:02 -0500 Auto-dim revisit cancelled — current no-dim behavior is fine -Craig confirmed the shipped auto-dim setup works fine as-is: terminal buffers don't participate in unfocused-window dimming (D1), and the rest of auto-dim behaves. That is the measured decision the original task asked for — option (a), keep no-dim — so no rework (the focus-loss palette-blend in option (b) or an upstream per-window hook in option (c)) is needed. Closing without further investigation. Context: [[file:docs/design/vterm-to-ghostel-migration-spec.org][migration spec]] D1. +***** Test discovery is regex-based and fragile +=cj/test--extract-test-names= scans files with a regex for =ert-deftest=. +That misses or mishandles: +- macro-generated tests +- commented forms in unusual shapes +- multiline or reader-conditional forms +- non-ERT Elisp tests such as Buttercup +- stale ERT tests already loaded in the session -*** TODO [#B] Investigate ghostel selection/highlight color :terminal:ghostel: -Look at how selected text is highlighted in a ghostel buffer — the region face in =ghostel-copy-mode= and any live selection — surfaced during the copy-mode debugging. Check whether the highlight is legible against the dupre background and consistent with the rest of the config; if it needs theming, fold it in with D2 (theming the ghostel faces in dupre). +Better approach: +- for ERT in isolated mode, let ERT discover tests after loading files +- for source navigation, use syntax-aware forms where possible +- store discovered tests as structured records with file, line, name, framework, + tags, and runner -*** 2026-05-26 Tue @ 15:15:43 -0500 Direction confirmed; Claude Code in eat needs a caveat -Craig confirmed the consolidation: one terminal engine everywhere — eat for standalone terminal buffers (replacing vterm) plus =eat-eshell-mode= as eshell's visual backend, keeping eshell as the shell. Not dropping eshell for eat + zsh. +***** Path containment has at least one suspicious edge +=cj/test--do-focus-add-file= checks: -Researched whether Claude Code runs cleanly in eat (Craig runs it in his Emacs terminal). Verdict: mostly, with caveats. eat is the default backend for claude-code.el and renders the TUI with color and full key handling, but there is an eat-specific bug where Claude Code's input handling makes the buffer scroll-pop to the top on window-buffer changes and the input box can get stuck mid-buffer (recoverable, but it does not happen in vterm or ghostel), and eat runs about 1.5x slower than vterm on heavy streaming output. claude-code.el's own docs name ghostel as the most faithful Claude TUI renderer. +#+begin_src elisp +(string-prefix-p (file-truename testdir) (file-truename filepath)) +#+end_src -Recommendation: consolidate everyday terminals onto eat, but keep ghostel (or vterm) for the Claude Code workflow specifically — the scroll-pop / stuck-input bug and the slower heavy-stream handling are exactly what bites a long Claude session. Sources: [[https://github.com/cpoile/claudemacs][claudemacs]], [[https://github.com/stevemolitor/claude-code.el][claude-code.el]], [[https://codeberg.org/akib/emacs-eat][emacs-eat]]. +That should use =cj/test--file-in-directory-p= or ensure the directory has a +trailing slash. Otherwise sibling paths with a shared prefix are a recurring +class of bug. -Eval plan (from the research doc): install EAT alongside vterm, run the same workloads through both, decide. Test matrix: Claude Code TUI, lazygit, htop/btop, yazi, a heavy-output build, ssh to a remote, and eshell with =eat-eshell-mode=. Assess rendering fidelity, stability under heavy output, and Emacs-native line editing. Switch only if it covers every workflow without regression. +***** Runner commands are shell strings too early +=cj/--f6-test-runner-cmd-for= returns shell command strings. That makes it +harder to: +- inspect command parts +- safely quote arguments +- offer command editing +- run via =make-process= / =compilation-start= without shell ambiguity +- attach metadata +- rerun exact invocations +- convert commands into UI labels -*** 2026-06-02 Tue @ 14:12:48 -0500 Audit: eval plan not yet run; back to TODO -Task audit found no eval work recorded since the 2026-05-26 direction-confirmed note. The test matrix above is unrun, so the task isn't actively in progress — moved DOING back to TODO until the eval starts. +Prefer a structured command object: -*** 2026-06-04 Thu @ 22:40:27 -0500 Pivot: ghostel as the single engine (not eat) -Direction changed from eat-everyday + ghostel-for-Claude to ghostel-for-everything, and the task is now a migration rather than an eval. Rationale: ghostel is claude-code.el's most-faithful Claude TUI renderer and the fastest engine (81 vs vterm 34 vs eat 4.9 MB/s), and an audit confirmed it exposes an analog for every vterm primitive this config uses (=ghostel-send-string=, =ghostel-keymap-exceptions=, =ghostel-copy-mode=, =ghostel-clear-scrollback=, =ghostel-send-next-key=, =ghostel-next-prompt= / =ghostel-previous-prompt=, =ghostel-max-scrollback=, =ghostel-kill-buffer-on-exit=). eat's washed colors, the scroll-pop / stuck-input bug under Claude Code, and slowest throughput made it the weaker single-engine pick; one engine beats running two. Surface audited: 2 main modules (=vterm-config.el=, =ai-vterm.el=) + 4 satellites (=auto-dim-config.el= is the heavy one) + ~35 test files + init.el. Next: spike ghostel read-only to answer the open migration questions (auto-dim rework — ARCHITECTURE.md forbids the around-redraw color advice vterm uses; tmux pane-id via =process-tty-name= on a ghostel process; buffer naming; TTY-frame behavior; copy-mode keybinding parity), then write the migration spec under =docs/design/= and review it. +#+begin_src elisp +(:program "pytest" + :args ("tests/test_foo.py" "-q") + :default-directory "/project/" + :env (("PYTHONPATH" . "...")) + :runner pytest + :scope file) +#+end_src -*** 2026-06-04 Thu @ 23:17:54 -0500 Spec review: not ready until decisions and handoff shape are closed -Ran the spec-review workflow against [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] and wrote a companion review file (incorporated and deleted 2026-06-04). Verdict: =Not ready=. Direction is sound, but the draft still has open D1-D5 decisions, lacks the workflow-required =Implementation phases= section and acceptance criteria, and needs explicit ghostel package/native-module failure behavior before implementation tasks can be emitted. +Render to a shell string only at the final compilation boundary. -*** 2026-06-04 Thu @ 23:24:28 -0500 Spec-response: review incorporated, raised to READY -Folded the external review via spec-response. Craig accepted D1-D5; baked them plus D6 (module-failure = degrade-with-warning, modifying the reviewer's fail-loud) and D7 (=ghostel-max-scrollback= 10 MB) into a new Agreed-decisions section. Added Implementation phases (0-4), Acceptance criteria, Dependency/module-failure behavior, Test strategy, per-phase key/menu ownership, the tmux-suppression contract, and an Implementation-tasks drop-in block. Status DRAFT → READY; review file deleted. Build is now unblocked. +***** F6 and =C-; t= workflows duplicate the same domain +F6 already handles "all tests" and "current file's tests" for multiple +languages. =C-; t= handles ERT-only focus and run state. These should converge +on one runner service: +- F6: quick entry point +- =C-; t=: full runner menu +- both call the same scope/adapter engine -*** 2026-06-04 Thu @ 23:30:18 -0500 External re-review: ready -Re-reviewed [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] after incorporation. Verdict: =Ready=. No further blocking review notes; implementation can start from the phase plan and acceptance criteria in the spec. +***** Test directory discovery is too narrow +Current discovery prefers =test/= then =tests/=, with a global fallback. Real +projects often need: +- Python: =tests/=, package-local =test_*.py=, =pytest.ini=, =pyproject.toml= +- JS/TS: =package.json= scripts, =vitest.config.*=, =jest.config.*=, + =*.test.ts=, =*.spec.ts= +- Go: package directories, =go.mod= +- Rust: =Cargo.toml=, integration tests under =tests/= +- Elisp packages: =Makefile=, =Eask=, =ert-runner=, Buttercup, =tests/= -** PROJECT [#B] Implement ai-kb :feature:ai:kb: -Build v1 of the AI knowledge base per [[file:docs/design/ai-kb.org][docs/design/ai-kb.org]] (Ready; six reviews incorporated, all decisions resolved 2026-05-24). Step 1 splits into 1a (the safe write path — minimum usable) and 1b (retrieval, maintenance, push), since =remember= depends on =index=+=lint= and the adapter depends on =remember=. Step 2 is the Emacs layer: a full org-roam profile on switch, the human-edit safety model (same write path as the agent), and the browsing surface. Step 3 and the LLM-Wiki layer are vNext. Children are ordered by build sequence; the server bootstrap is the prerequisite. +Discovery should be adapter-specific and project-config-aware. -*** TODO [#B] ai-kb bare repo on cjennings.net :ai-kb: -Prerequisite, one-time server bootstrap (not doable by the local script): =sudo git init --bare /var/git/ai-kb.git= + chown on cjennings.net. Leave the github-mirror hook OFF — this repo is private. Required before every per-machine clone. +***** No structured result model +=cj/test-last-results= exists but is not meaningfully populated. A powerful +runner needs a normalized result model: +- run id +- started/finished timestamps +- status: passed/failed/errored/cancelled/skipped/xfail/xpass +- command +- runner adapter +- scope +- exit code +- duration +- failed test records +- file/line locations +- raw output buffer +- coverage artifact paths -*** TODO [#B] ai-kb store + contract + seed :ai-kb: -Step 1a. Clone =git@cjennings.net:ai-kb.git= to =~/.local/share/ai-kb=. Author =AGENT_CONTRACT.org= (canonical repo-resident contract: node format, write protocol, operations, routing) and seed =index.org= + a README/index node with a generated =:ID:=. Node format per spec — a *required* one-line =:SUMMARY:= (the index/query read it straight, no inference/LLM), provenance (=:CREATED_BY:/:CONFIDENCE:/:VISIBILITY:/:SOURCE:/:STATUS:=), =:PROJECTS:= slugs, type filetags, relation labels. Define the durable external-pointer format as *ID-first*: =ai-kb: <Title> (<UUID>)=, resolved by ID with title fallback (filenames can change in curation). +This enables last-failed, failures-first, summaries, dashboards, and AI-assisted +failure explanation. -*** TODO [#B] ai-kb CLI 1a: index, lint, remember, doctor :ai-kb: -Step 1a. Shell wrapper calling Emacs for org work — =emacsclient= when a daemon is up, =emacs --batch= fallback, lint+index in *one* invocation per =remember=. =index= regenerates =index.org= from node properties incl. =:SUMMARY:= (never hand-maintained); the index references nodes as plain =Title (UUID)= text, never =[[id:]]= links, and is excluded from the scan so it can't manufacture backlinks or hide orphans. =lint= = org-lint fatal checks + duplicate IDs + broken id-links (excl =raw/= + index) + missing required props (incl =:SUMMARY:=) + bad project slugs + stale/incomplete index + credential scan of nodes *and* =raw/= text files (binaries skipped). =remember= = the write protocol: fetch + =pull --ff-only= (abort on diverge/dirty), write, regenerate index, then run the *full =ai-kb lint=* over the change as the commit gate (not just node org-lint — this is the safety boundary), commit locally, =flock=; no push. =doctor= / =status= = health + push-state + raw-dir-size report (repo, private remote, CLI on PATH, =graphviz= if the map needs it, adapter linked, db buildable, no secrets, "ahead N"/"push failed"/"diverged"); =status= is the fast non-diagnostic mode for the dashboard/nudge. +***** No failure parser / navigation layer +Compilation buffers are useful, but the runner should parse common failure +formats and provide: +- next/previous failure +- jump to source line +- failure summary buffer +- copy failure context +- rerun failed test at point +- annotate failing tests in source buffers -*** TODO [#B] claude-rules/ai-kb.md adapter :ai-kb: -Step 1a. Global L1 rule in rulesets pointing at the repo-resident =AGENT_CONTRACT.org=: path, routing (T1/T2/T3 tiers; per-project =MEMORY.md= shrinks to ID-first pointers into ai-kb), proactive + contradiction rules, concrete "read the index first" triggers, link-grep recipes, "use =ai-kb remember=, never bypass =ai-kb lint=", one-line nudge on unpushed commits / recorded push rejection. =make install= symlinks it into =~/.claude/rules/=. +Adapters can provide regexes/parsers for ERT, pytest, Jest/Vitest, Go, Rust, +and shell. -*** TODO [#B] ai-kb provisioning: setup-ai-kb.sh + make ai-kb-init :ai-kb: -Step 1a (core; the timer-install line is added with 1b). Idempotent =scripts/setup-ai-kb.sh=: clone (or init+add-remote on first machine), seed, install the CLI on PATH, =ai-kb index=, =ai-kb doctor=. =make ai-kb-init= wraps it. The one-time server bootstrap stays a separate documented step. +***** Missing watch/rerun modes +Modern test runners optimize the feedback loop: +- pytest supports selecting tests, markers, last-failed, failures-first, + stepwise, fixtures, xfail/skip, plugins, and cache state. +- Jest/Vitest support watch workflows, changed-file selection, coverage, + snapshots, and rich interactive filtering. Vitest also defaults to watch in + development and run mode in CI. +- Go and Rust runners commonly support package-level runs, regex selection, + race/coverage flags, and cached test behavior. -*** TODO [#B] ai-kb Step-1a tests :ai-kb:tests: -Write-path: a write with the remote unreachable still commits locally and does not error; =flock= serializes concurrent =remember=; each org-lint *fatal* check (malformed drawer, missing/dup =:ID:=, invalid required property, missing =#+title:=, unparseable org) rejects the commit, a style warning does not; a node missing =:SUMMARY:= fails lint; =remember= aborts the commit when the *full* lint fails (stale index, broken link, secret in a node or =raw/= text file); the credential scan skips binaries. Index: regen from a fixture produces expected entries; an out-of-band node appears only after regen; a node referenced only by =index.org= still reports as an orphan (the index is not a backlink source). Link recipes: backlink (excl =raw/= + index) + forward correct. Provisioning (bats): idempotent, valid =:ID:= + =:SUMMARY:=, =doctor= passes. +The Emacs runner should expose the subset that maps well to editor workflows: +- current test +- current file +- related test file +- focused set +- last failed +- failed first +- changed since git base +- watch current scope +- full project +- coverage for current scope -*** TODO [#B] ai-kb CLI 1b: query, curate, sync :ai-kb: -Step 1b. =query <context>= with a *testable contract*: plain-text default + =--json=; fields title/ID/summary/projects/status/updated/path + *match reason*; searches index rows + title/tags/properties/body; ranks by lexical score — sum of each matched field's weight, counted once per field: title 100, tag/project/status 50 each, summary 20, body 5; no term-frequency weighting in v1 — with most-recently-updated (=:UPDATED:=) only as the *tie-break* on equal scores (recency alone buries stable old preferences); default max-results; =raw/= paths only as source references; exit codes for no-match / invalid KB / lint-index failure. =show <id-or-title>= (resolve ID-first, print the node) and =backlinks <id>= (excl =raw/= + index) as the inspection primitives the Emacs commands wrap. =curate --dry-run= (four buckets; also flags orphan =raw/= captures and any =raw/= file over 256 KB; destructive ops human-only). =sync= (=org-roam-db-sync= against ai-kb) only when the db is missing/stale or forced. +**** Proposed Architecture +***** Core Types +Use plain plists initially; promote to =cl-defstruct= only if helpful. -*** TODO [#B] ai-kb push timer + failure observability :ai-kb: -Step 1b. =ai-kb-push.timer= + =ai-kb-push.service= =systemd --user= units: push only if ahead, ~15 min; installed + =enable --now= by the setup script (add this line to =setup-ai-kb.sh=). A failed push is logged to a state file (=$XDG_STATE_HOME/ai-kb=), never fatal; surfaced by =ai-kb doctor= and the adapter's startup nudge. +#+begin_src elisp +;; Test runner adapter +(:id pytest + :name "pytest" + :languages (python) + :detect cj/test-pytest-detect + :discover cj/test-pytest-discover + :build-command cj/test-pytest-build-command + :parse-results cj/test-pytest-parse-results + :capabilities (:current-test :file :project :last-failed :coverage :watch)) -*** TODO [#B] ai-kb-curate workflow in rulesets :ai-kb: -Step 1b. =~/code/rulesets/.ai/workflows/ai-kb-curate.org= — human-gated curation: the four buckets, node-count trigger (nudge at 150 nodes, re-fire every +50), =:LAST_CURATED:= rotation, pointer-integrity (merge/supersede changes the canonical ID, so grep inbound =[[id:]]= + =MEMORY.md= =ai-kb: ... (UUID)= refs and repoint before deleting). Surfaced by =ai-kb doctor= + session startup when due. +;; Test run request +(:project-root "/repo/" + :language python + :framework pytest + :scope file + :file "/repo/tests/test_api.py" + :test-name "test_create_user" + :extra-args ("-q") + :profile default) -*** TODO [#B] ai-kb Step-1b tests :ai-kb:tests: -=query --json= returns the specified fields (incl. match reason)/exit-codes on a fixture KB and =raw/= appears only as a source ref; a title match outranks a body-only match with recency only breaking ties (an old preference is not buried under a newer body-only hit); a simulated push failure is recorded to the state file and surfaced by =ai-kb doctor= / =status=. Performance (=:perf= tag): 100- and 1,000-node fixtures keep =index=/=query=/=lint=/=remember= under a stated time budget (catches an accidental per-check Emacs startup or an O(n²) scan). - -*** TODO [#B] Emacs: org-roam ai-kb profile + switch :ai-kb: -Step 2. -=org-roam-config.el=: =cj/org-roam-switch-to-ai-kb= / =cj/org-roam-switch-to-personal= install a full org-roam *profile*, not a two-variable swap — dir + =org-roam-ai.db= + =org-roam-file-exclude-regexp= (=raw/= + =index*.org=), and dailies, capture templates, topic/project/recipe find wrappers, and the agenda/refile + completed-task→daily hooks all rescoped or neutralized so ai-kb nodes never leak into personal journals/agenda. Restore everything exactly on exit; re-assert personal state at startup (abnormal-exit safety). =cj/ai-kb-db-sync= syncs only when the db is missing/stale or forced, with a status indicator. - -*** TODO [#B] Emacs: ai-kb edit safety (same write path) :ai-kb: -Step 2. An =ai-kb= minor mode whose =after-save-hook= runs the agent's post-write sequence under =flock= — =ai-kb index=, full =ai-kb lint=, commit, push-state update — so a human Emacs edit can't bypass index/lint/commit. One write path for both agent and human. Failure UX: the save always writes to disk and the buffer stays editable (never read-only/blocked); on lint failure it does *not* commit, pops findings to a =*ai-kb-lint*= buffer (no focus steal), and shows the uncommitted-failing state in the modeline + dashboard — Craig fixes and re-saves, a clean save commits. Recursion guard, two layers: the mode's activation predicate excludes =index*.org= + =raw/=, and the pipeline binds a re-entrancy flag (=cj/ai-kb--in-pipeline=) the hook early-returns on; index regen prefers =write-region= over =save-buffer=. +;; Test run result +(:run-id "..." + :status failed + :exit-code 1 + :duration 2.14 + :failures (...) + :output-buffer "*test pytest*" + :artifacts (...)) +#+end_src -*** TODO [#B] Emacs: ai-kb browsing surface :ai-kb: -Step 2. =cj/ai-kb-dashboard= (status banner: active KB, node count, unpushed commits, push-failure state, curation due, last index/sync), =cj/ai-kb-find-node= (=org-roam-node-find= in the ai-kb profile), =cj/ai-kb-search= (=ai-kb query= or scoped =consult-ripgrep=), =cj/ai-kb-show-node= (resolve ID-first, open), =cj/ai-kb-backlinks= (excl =raw/= + index), =cj/ai-kb-map= (built-in =org-roam-graph= *first* — the profile's exclude regexp already keeps =raw/= + index out of the db, so the graph inherits the right scope; custom DOT export only if project/tag/status filtering proves necessary; =graphviz= dep). Simple wrappers over the CLI primitives where possible. +***** Adapter Registry +Create a registry like: -*** TODO [#B] Emacs: ai-kb keybindings + which-key :ai-kb: -Bind the switch + sync + browsing commands under the =C-c n= roam prefix (e.g. =C-c n a= → ai-kb, =C-c n A= → personal, a small transient for the browsing commands), avoiding the dense existing set; which-key labels. +#+begin_src elisp +(defvar cj/test-runner-adapters nil) +(cj/test-register-adapter 'pytest ...) +(cj/test-register-adapter 'ert ...) +(cj/test-register-adapter 'vitest ...) +#+end_src -*** TODO [#B] Emacs: ai-kb Step-2 ERT tests :ai-kb:tests: -Profile: switch installs the ai-kb dir + db + exclude regexp and switch-back restores personal *exactly* — completed-task hook, agenda/refile finalize hook, dailies, and capture templates all untouched by ai-kb while switched; startup re-asserts personal state after a simulated abnormal exit. Edit path: a save in an ai-kb buffer runs index+lint+commit (a bad save surfaces the lint failure rather than committing). Sync runs only when stale. +Runner selection should consider: +- buffer file extension +- project files +- explicit user override +- available executables +- package manager scripts +- existing Makefile targets -** PROJECT [#B] Architecture review follow-up from 2026-05-03 :refactor:nosync: +***** Scope Model +Make scopes explicit and shared across languages: +- =test-at-point= +- =current-file= +- =related-file= +- =focused-files= +- =last-failed= +- =changed= +- =package/module= +- =project= +- =coverage= +- =watch= -High-level pass over =init.el=, =early-init.el=, and all 104 files in -=modules/=. The main theme: the config works, but load order, startup side -effects, credentials, and test measurement are more implicit than they should -be. Use this project as the parent tracker; each child below should land as a -small, reviewable change. +Each adapter can say which scopes it supports. Unsupported scopes should produce +clear user-errors with suggestions. -Review snapshot: -- =modules/= has 104 files and about 24k lines including =init.el= and - =early-init.el=. -- =init.el= eagerly =require=s nearly every module. -- =make coverage= passed when allowed to write the test scratch directory. -- Coverage report: =3240/4952= executable lines, =65.43%=, across 49 module - files. Caveat: 55 module files do not appear in the report at all, so the - real project confidence is lower than the raw percentage suggests. +***** Command Builder Pipeline +1. Detect project. +2. Detect language/framework candidates. +3. Resolve user-requested scope. +4. Build structured command object. +5. Optionally let user edit command. +6. Run via =compilation-start= or =make-process=. +7. Parse output/result artifacts. +8. Store normalized result. +9. Update UI/modeline/messages/failure buffer. -*** 2026-05-15 Fri Consolidate shared utility helpers :architecture:refactor: -CLOSED: [2026-05-15 Fri] +***** Keep Makefile Support But Do Not Require It +For this Emacs config, =make test-file= and =make test-name= are useful and +should remain the default Elisp isolated path. But adapter detection should +support: +- direct =emacs --batch= ERT invocation +- =make test= +- =make test-file= +- =make test-name= +- Eask +- Buttercup -Helpers are scattered across feature modules where they were first needed. -Some are duplicated, and some private helpers are generic enough to belong in a -shared foundation library. This is adjacent to the load-graph refactor because -central helper ownership reduces hidden inter-module dependencies, but it -should remain a sibling project so load-order batches stay small and -reviewable. +**** Elisp-Specific Improvements +***** Add isolated ERT runs +Support batch commands for: +- all project tests +- one test file +- one test name +- focused files +- last failed, once result parsing exists -Guidance: -- Do not extract a helper until at least two callers are clearly the same - shape. -- Prefer growing =system-lib.el= first; split into topic libraries only if it - becomes too broad or starts pulling coarse dependencies into foundation - startup. -- Keep one helper extraction per commit. -- Move unit tests with the helper. Consumers should keep behavior/integration - coverage. -- Do not add heavy package dependencies to foundation helpers. +Use the same Makefile targets in this repo, but design the adapter so other +Elisp projects can run without this Makefile. -**** DONE [#B] Write full utility consolidation design spec :architecture:refactor: -CLOSED: [2026-05-04 Mon] +***** Support Buttercup/Eask Later +Buttercup uses BDD-style =describe= / =it= suites and is common in Elisp +package testing. Eask is often used to run package tests. Add adapter slots +for these instead of hard-coding ERT forever. -Create a design document that inventories candidate helper extractions, -recommends grouping and naming, explains how the helpers fit into existing -library modules, defines migration phases, and identifies testing/rollback -rules. +***** Avoid unnecessary global ERT deletion +=cj/ert-clear-tests= is a pragmatic fix for project contamination, but the +stronger long-term answer is isolated runs plus project-scoped discovery. Keep +the cleanup command, but do not make correctness depend on deleting global ERT +state. -Spec: [[file:docs/design/utility-consolidation.org][docs/design/utility-consolidation.org]] +**** Python / pytest Ideas +- Detect pytest by =pyproject.toml=, =pytest.ini=, =tox.ini=, =setup.cfg=, or + presence of =tests/=. +- Build commands for: + - project: =pytest= + - file: =pytest path/to/test_file.py= + - test at point: =pytest path/to/test_file.py::test_name= + - class method: =pytest path::TestClass::test_method= + - marker: =pytest -m marker= + - last failed: =pytest --lf= + - failed first: =pytest --ff= + - stop after first: =pytest -x= + - coverage: =pytest --cov=...= +- Parse output for failing node ids and =file:line= references. +- Read pytest cache for last-failed where useful. +- Offer marker completion by parsing =pytest --markers= or config files. +- Surface xfail/skip separately from hard failures. -Verify 2026-05-04: -- Added [[file:docs/design/utility-consolidation.org][docs/design/utility-consolidation.org]]. -- Spec includes framing questions, existing library fit, proposed grouping, - concrete pull/rename table, migration phases, test strategy, acceptance - criteria, risks, open questions, and recommended first commits. -- Parsed the spec and =todo.org= with =org-element=. -- Committed the tracked spec as =3ea4707=. -- Incorporated complete review feedback in =dd77ebd=, including API behavior - contracts, speculative-extraction rules, =system-lib= dependency budget, - inventory/audit artifacts, test relocation policy, commit type guidance, - =use-package :if= load-order policy, and Phase 5 cache-design addendum - requirement. +**** TypeScript / JavaScript Ideas +***** Detection +Detect runner by project files and scripts: +- =vitest.config.ts/js/mts/mjs= +- =jest.config.ts/js/mjs/cjs= +- =package.json= scripts: =test=, =test:watch=, =vitest=, =jest= +- lockfile/package manager: =pnpm-lock.yaml=, =yarn.lock=, =package-lock.json=, + =bun.lockb= -**** DONE [#B] Inventory private helpers across modules :refactor: -CLOSED: [2026-05-10 Sun] +Prefer project scripts over raw =npx= when present: +- =pnpm test -- path= +- =npm test -- path= +- =yarn test path= +- =bun test path= -Walk every module and tag private helpers as genuinely module-specific, -generic-but-trapped, or duplicated. Capture likely consumers and any dependency -cost before extracting. +***** Scopes +- current file: =vitest run path= or =jest path= +- test at point: use nearest =it= / =test= / =describe= string and pass =-t= +- watch current file +- changed tests where runner supports it +- coverage current file/project +- update snapshots -Candidate families: -- shell argument formatting, -- executable lookup with user-visible warnings, -- argv-based process runners, -- path containment/safe-base predicates, -- Org-safe heading/property/body text sanitizers, -- cache-with-TTL plus invalidation hooks, -- warning/message wrappers. +***** Result Parsing +Parse: +- failing test names +- file paths and line numbers +- snapshot failures +- coverage summary -Verify 2026-05-10: -- Added [[file:docs/design/utility-inventory.org][docs/design/utility-inventory.org]] covering the 30 entries in the spec's - Candidate Extraction Table grouped by family (executable discovery, shell - quoting, process runner, file/path, external-open, Org-safe text, cache, - logging, macros/debug, theme I/O, string). -- For each helper recorded: visibility, dependencies, side effects, callers - (production + test), test files, priority, decision (Migrate / Leave / Defer) - with rationale. -- Decisions Summary: 11 Migrate, 3 Leave, 13 Defer. -- Concrete next-action list groups Migrate items by Phase (2 = foundation - helpers, 3 = Org-safe text, 4 = external-open consolidation) for the order - the spec recommends. -- Discoveries: =cj/log-silently= has 10 production callers (more than the - spec's table suggested -- defer is the right call); =cj/--file-manager-program-for= - shipped today in =dirvish-config.el= is the new form of OS-dispatch - consolidation and should fold into =cj/external-open-command= during Phase 4. +Treat snapshot updates as an explicit command, not an automatic side effect. -**** DONE [#B] Extract executable lookup with warning helper :refactor: -CLOSED: [2026-05-10 Sun] +**** Go Ideas +- Detect =go.mod=. +- Current file/source: run package =go test ./pkg=. +- Test at point: nearest =func TestXxx= and run =go test ./pkg -run '^TestXxx$'=. +- Bench at point: nearest =BenchmarkXxx= and run =go test -bench '^BenchmarkXxx$'=. +- Add toggles for =-race=, =-cover=, =-count=1=, =-v=. +- Parse =file.go:line:= output and package failure summaries. -Create a generic helper such as =cj/find-executable-or-warn= from the useful -=mail-config= pattern. It should return the executable path or nil and produce -a clear warning when the executable is missing. +**** Rust Ideas +- Detect =Cargo.toml=. +- Use =cargo test= by default, optionally =cargo nextest run= when available. +- Current test at point: nearest =#[test]= function. +- Current file/module where possible. +- Integration test file: =cargo test --test name=. +- Support =-- --nocapture= toggle. +- Parse compiler/test failures and =file:line= links. -Done 2026-05-10: -- Shipped as =cj/executable-find-or-warn= in =modules/system-lib.el= - (commit =c75e36f4=, extracted from =mail-config=). -- First consumer rewired in =12c2cb14= (=cj/set-wallpaper= in - =dirvish-config.el=). +**** Shell / Generic Ideas +- Adapter for Makefile targets: + - detect =make test=, =make check=, =make coverage= + - expose project-level commands even when language-specific detection fails +- Adapter for arbitrary project command configured in dir-locals or a project + config plist. +- Let users register custom command templates per project: -**** DONE [#B] Extract argv-based process runner helper :refactor: -CLOSED: [2026-05-10 Sun] +#+begin_src elisp +((:name "unit" + :command ("npm" "run" "test:unit" "--" "{file}")) + (:name "integration" + :command ("pytest" "tests/integration" "-q"))) +#+end_src -Generalize the =coverage-core= process pattern into a dependency-light helper -that captures output and signals a clear =user-error= with command/status/output -on failure. Consider a small git wrapper only after the generic runner exists. - -Done 2026-05-10: -- Shipped =cj/process-output-or-error= plus the =cj/git-output-or-error= - wrapper in =modules/system-lib.el= (commit =57e558ce=, extracted from - =coverage-core=). +**** UI Ideas +***** Transient Menu +Replace or complement the raw keymap with a =transient= menu: +- scope: current test/file/focused/last failed/project +- runner: auto/ert/pytest/vitest/jest/go/cargo/make +- toggles: watch, coverage, debug, fail-fast, verbose, update snapshots +- actions: run, rerun, edit command, show failures, open report -**** DONE [#B] Extract Org-safe text sanitizers :refactor: -CLOSED: [2026-05-10 Sun] +***** Result Buffer +Create a normalized =*Test Results*= buffer: +- latest status per project +- command and duration +- pass/fail/skip counts +- failure list with clickable =file:line= +- actions to rerun failed/current/all +- links to coverage artifacts -Move heading/property/body sanitization into a shared helper once at least one -non-calendar consumer is ready. Keep behavior explicit so external text cannot -accidentally create headings or malformed properties. +***** Modeline / Headerline Signal +Show the last run status for the current project: +- green passed +- red failed +- yellow running +- gray no run -Done 2026-05-10: -- Shipped =modules/cj-org-text-lib.el= (renamed to its final =-lib= form in - commit =0f9e3087=) with three sanitizers: =cj/org-sanitize-body-text=, - =cj/org-sanitize-property-value=, =cj/org-sanitize-heading=. +Keep it quiet and optional. -*** 2026-05-15 Fri Make coverage reporting account for untracked modules :tests: -CLOSED: [2026-05-15 Fri] +***** History +Store recent run requests per project: +- rerun last +- rerun last failed +- choose previous command +- compare duration/status against previous run -The current coverage result is useful but easy to overread. =make coverage= -reported =65.43%= for files that undercover saw, but only 49 of 104 module -files appeared in =.coverage/simplecov.json=. +**** Configuration Ideas +- =cj/test-runner-default-scope= +- =cj/test-runner-prefer-isolated-elisp= +- =cj/test-runner-project-overrides= +- =cj/test-runner-known-adapters= +- =cj/test-runner-enable-watch= +- =cj/test-runner-result-retention= +- per-project override through =.dir-locals.el= -Definition: in this task, "untracked modules" means repository-owned -=modules/*.el= files that should be part of the Emacs configuration coverage -universe but have no entry in =.coverage/simplecov.json= after =make coverage= -runs. These files may be missing because no test required them, because loading -was skipped due to package/environment guards, or because instrumentation did -not see them. They are distinct from tracked modules with 0% covered lines, -which already appear in SimpleCov and can be scored directly. +Example: -Completed 2026-05-15: -- Both child tasks are done. -- =make coverage-summary= reports missing modules explicitly and also reports a - separate project-module score where missing modules count as 0%. -- Focused summary tests and byte-compilation of the summary helper passed. +#+begin_src elisp +((nil . ((cj/test-runner-project-overrides + . (:adapter pytest + :default-args ("-q") + :coverage-args ("--cov=src")))))) +#+end_src -**** 2026-05-15 Fri Teach the coverage report to list modules missing from SimpleCov -CLOSED: [2026-05-15 Fri] +**** Safety And Robustness +- Use structured commands until the final boundary. +- Quote only at render time. +- Avoid shell when =make-process= / =process-file= is sufficient. +- Keep command preview/editing available for surprising cases. +- Detect missing executables before running. +- Add timeouts/cancel commands for long-running or hung tests. +- Do not silently fall back from a missing runner to a different runner unless + the fallback is visible in the command preview. +- Avoid mutating global =load-path= permanently. +- Keep remote/TRAMP behavior explicit; do not accidentally run local commands + for remote projects. -Expected outcome: -- Compare =modules/*.el= against paths present in =.coverage/simplecov.json=. -- Show a separate "not in report" section. -- Do not silently fold those files into the percentage until we decide the - semantics. A visible missing-file count is enough for v1. +**** Coverage Integration +Tie this into the existing coverage work: +- run coverage for current file/scope +- open latest coverage report +- summarize uncovered lines for current file +- support Elisp SimpleCov/Undercover, pytest-cov, Vitest coverage, Go cover, + and Rust coverage later +- store coverage artifact paths in the normalized run result -Done 2026-05-15: -- =make coverage-summary= now compares direct =modules/*.el= files on disk - against the module paths present in =.coverage/simplecov.json=. -- The terminal report appends a =Not in SimpleCov report= section with a count - and the missing module paths. -- Missing modules are explicitly excluded from the displayed percentage for - now; the policy question below remains open. -- Added focused tests in =tests/test-coverage-summary.el= for missing-module - reporting and for ignoring =.elc= files and nested paths outside direct - =modules/*.el= ownership. +**** AI-Assisted Debugging Ideas +- Summarize failing tests from the parsed failure records and raw output. +- Include command, changed files, failure snippets, and relevant source/test + locations. +- Redact env vars, tokens, Authorization headers, and secrets before sending to + =gptel=. +- Add commands: + - =cj/test-runner-explain-failure= + - =cj/test-runner-suggest-related-tests= + - =cj/test-runner-summarize-coverage-gap= -**** 2026-05-15 Fri Decide whether unreported modules count as 0% coverage -CLOSED: [2026-05-15 Fri] +**** Migration Plan +***** Phase 1: Internal cleanup +- Fix the task typo and rename current ERT-specific functions or wrap them under + an ERT adapter. +- Move F6 language detection/command construction from =dev-fkeys.el= into + =test-runner.el= or a new =test-runner-core.el=. +- Replace shell-string command builders with structured command plists. +- Fix path containment in =cj/test--do-focus-add-file=. +- Make =cj/test-last-results= real for ERT runs. -This is a policy decision: -- Counting missing modules as 0% gives a more honest project-level number. -- Keeping the current number is useful for "instrumented executable lines only". +***** Phase 2: ERT adapter +- Implement adapter registry. +- Add ERT adapter with in-process and isolated modes. +- Preserve all current keybindings by routing them through the adapter. +- Add failure/result normalization for ERT. +- Add "rerun last" and "rerun failed" for ERT. -Recommendation: display both: -- Instrumented coverage: current SimpleCov percentage. -- Project module coverage: includes unreported module files as 0% or reports - them separately with an explicit caveat. +***** Phase 3: Python and JS/TS adapters +- Add pytest adapter. +- Add Vitest/Jest adapter with package-manager/script detection. +- Support current file and test-at-point for both. +- Add parser/navigation for common failures. -Decision 2026-05-15: -- Keep the existing SimpleCov percentage as the line-weighted - =instrumented coverage= number. It only covers modules that SimpleCov saw and - has real executable-line denominators for. -- Also display a separate module-weighted =project module coverage= score over - all direct =modules/*.el= files. Modules present in SimpleCov contribute their - per-file coverage percentage; modules absent from SimpleCov count as 0%. -- Do not pretend missing modules have known executable-line counts. Counting - them as 0% at the module level is honest about risk without inventing a line - denominator. +***** Phase 4: UI and watch modes +- Add transient menu. +- Add result buffer. +- Add cancellation and rerun history. +- Add watch commands where supported. -Done 2026-05-15: -- =make coverage-summary= now prints both the existing line-weighted summary - and a separate =Project module coverage= line that includes missing modules - as 0%. -- The missing-module section now states that missing modules count as 0% in the - project-module score. -- Updated =tests/test-coverage-summary.el= to assert the policy and the - displayed project-module percentage. +***** Phase 5: Coverage and AI +- Connect coverage commands to adapter capabilities. +- Add failure summarization with redaction. +- Add coverage-gap summarization. -*** 2026-05-15 Fri Add a lightweight architecture smoke test for startup contracts :tests: -CLOSED: [2026-05-15 Fri] +**** Acceptance Criteria For First Fix-Up Pass +- Existing ERT workflow still works. +- F6 and =C-; t= use the same underlying runner API. +- Current-file test command generation is covered for Elisp, Python, Go, + TypeScript, and JavaScript. +- At least one isolated ERT command path exists. +- Path containment checks are robust against sibling-prefix paths and symlinks. +- Runner requests and results are represented as data, not only messages. +- Missing runner/tool errors are clear and actionable. +- Tests cover adapter detection, command building, scope resolution, result + storage, and key interactive paths. -After the above refactors start, add one or two smoke tests that protect the -architecture instead of individual functions. +** TODO [#B] Add Signal to the dashboard :quick: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +** TODO [#B] Messenger window/key unification :feature:ux: +Spec: [[file:docs/design/messenger-unification-spec.org][messenger-unification-spec.org]] (Draft, 2026-06-11). One library (=cj-messenger-lib.el=) gives every messenger the same shape: chat windows rise from the bottom (the signel rule, generalized), C-c C-c confirms, C-c C-k cancels, C-c C-a attaches — dispatched per backend through a registry + minor mode. Signel already conforms (reference backend); telega and slack join in phases 2-3; ERC later. All eight decisions settled 2026-06-11 (cancel closes an idle window; telega's filter-cancel shadow accepted; slack rooms join the bottom rule). Spec held open — Craig has more ideas to fold in before it's marked Ready. -Candidate checks: -- All modules can be loaded directly with only =modules/= on =load-path=, or - skipped with a clear external package reason. -- No module other than =keybindings.el= binds =C-;= itself. -- Startup-only modules do not run timers in batch test mode. +** TODO [#B] cj/undo-kill-buffer off-by-one on plain invocation :bug:quick:solo: +=modules/ui-navigation.el:181= — =(interactive "p")= makes arg always ≥1, and the body does =(if arg (nth arg list) (car list))=, so the nth branch always runs and plain M-S-z reopens the SECOND-most-recently-killed file. The existing test passes 0 explicitly, masking it. Fix the indexing (=(interactive "P")= + =prefix-numeric-value=, or =nth (1- arg)=) and fix the test to cover the no-prefix path. From the 2026-06 config audit. -Keep this small. The goal is to catch accidental return to hidden load-order -coupling, not to build a full static analyzer. +** TODO [#B] reconcile-open-repos skips any repo with a dot in its name :bug:solo: +=modules/reconcile-open-repos.el:174= — discovery regexp ="^[^.]+$"= matches only dot-free names, so =~/code/mcp.el=, =capture.el=, =google-contacts.el=, =auto-dim-other-buffers.el= etc. are never reconciled while M-P still reports "Complete." Replace with =directory-files-no-dot-files-regexp= + a hidden-dir check; add a regression test with a dotted repo name. From the 2026-06 config audit. -Done 2026-05-15: -- Added =tests/test-architecture-startup-contracts.el= with two source-level - smoke checks: - - only =keybindings.el= may globally own the exact =C-;= prefix; - - top-level timer scheduling forms must be guarded by =noninteractive= so - batch/test loads do not schedule startup timers. -- Gated existing startup timers in =org-agenda-config.el=, - =org-refile-config.el=, =quick-video-capture.el=, and =wrap-up.el=. -- Focused tests passed for the new architecture smoke file and the affected - agenda/refile helpers. +** TODO [#B] jumper: register collisions and dead-marker errors :bug:solo: +Two related defects from the 2026-06 config audit: +- =modules/jumper.el:155= — removal shifts the vector without renumbering registers, so a later store allocates a register still held by a surviving location and silently overwrites it. Allocate the first free register char in the live slice; =set-register nil= on removal so freed markers don't pin buffers. +- =modules/jumper.el:117,132= — guards check =(markerp marker)= but not =(buffer-live-p (marker-buffer marker))=; after killing a buffer holding a location, M-SPC SPC and M-SPC j signal wrong-type errors. Treat dead entries as skippable/removable. +Also =jumper.el:178= — the promised single-location toggle never toggles back ('already-there branch should =jump-to-register= z when set). -*** PROJECT [#A] Un tangle the eager =init.el= load graph :architecture:refactor: +** TODO [#B] C-s C-s vertico-repeat path never works :bug:quick:solo: +=modules/selection-framework.el:263= — =cj/consult-line-or-repeat= calls =vertico-repeat= on the second consecutive C-s, but nothing adds =vertico-repeat-save= to =minibuffer-setup-hook= (grep: zero hits config-wide), so it always signals "No Vertico session". Add the hook next to the vertico use-package block. From the 2026-06 config audit. -=init.el= currently functions as the dependency graph by eagerly requiring -almost every module in a fixed order. That makes modules harder to test in -isolation and hides real dependencies behind "loaded earlier in init.el" -assumptions. +** TODO [#B] dashboard-config setq wipes recentf-exclude list :bug:quick:solo: +=modules/dashboard-config.el:199= =(setq recentf-exclude '("/emms/history"))= discards the five exclusions system-defaults.el:239-243 added earlier in init order (bookmarks, elpa, recentf, ElfeedDB, airootfs). Change to =add-to-list=. From the 2026-06 config audit. -Spec: [[file:docs/design/init-load-graph.org][docs/design/init-load-graph.org]] +** TODO [#B] auth-config: unguarded gpg-connect-agent call + compile-time require :bug:quick:solo: +From the 2026-06 config audit. =modules/auth-config.el:88= — bare =(call-process "gpg-connect-agent" ...)= in a =:demand t= :config signals file-missing and aborts init on machines without the binary; guard with =cj/executable-find-or-warn=. =auth-config.el:36= — =user-constants= is required only =eval-when-compile= but =authinfo-file= is read at load time; works from .el source, fails from standalone .elc. Use a runtime require (system-defaults.el:32-35 documents this exact trap). -**** 2026-05-25 Mon @ 07:59:20 -0500 Wrote full design spec for the =init.el= load-graph refactor :architecture:refactor: +** TODO [#B] system-defaults: top-level server-start unguarded in batch :bug:quick:solo: +=modules/system-defaults.el:140= — raw module load under =--batch= (make validate-modules on a machine with no daemon socket) starts a server from a batch process; the suite only passes because the testutil stubs it. Wrap in =(unless noninteractive ...)= — the repo's established guard for this defect class; same guard stops the =custom-file= =make-temp-file= at line 104 littering temp files per batch load. From the 2026-06 config audit. -Create a design document that defines the target architecture, module -categories, migration phases, test strategy, acceptance criteria, and risk -controls for untangling the eager =init.el= load graph. +** TODO [#B] markdown live preview clobbered by markdown-mode :bug:quick:solo: +=modules/markdown-config.el:54= defines bare =markdown-preview=, which markdown-mode redefines the moment the first .md loads — the impatient-mode live preview is dead and F2 silently runs the package command (agent verified in the live daemon). Also =:61= guards on =(boundp 'httpd-process)=, a variable that doesn't exist in simple-httpd — use =(httpd-running-p)=. And the =:config= =(setq imp-set-user-filter 'markdown-html)= at line 41 is doubly dead (function-not-variable, symbol names nothing) — delete. Rename to =cj/markdown-preview=, rebind F2. From the 2026-06 config audit. -Review incorporation: -- Treat helper consolidation as adjacent architecture work, not a direct - acceptance criterion for the load-graph refactor. -- Mention utility extraction guardrails in the spec so Phase 2 dependency work - has a clear rule for duplicated helpers found along the way. +** TODO [#B] org-roam dailies template writes FILETAGS and TITLE on one line :bug:quick:solo: +=modules/org-roam-config.el:42= — the "d" dailies head is ="#+FILETAGS: Journal #+TITLE: %<%Y-%m-%d>"= with no newline, so every C-c n d daily is malformed: no parsed #+TITLE, FILETAGS value "Journal #+TITLE: ...". The journal-copy template (lines 213-216) has it right. Add the newline; consider a sweep of existing dailies for the malformed first line. From the 2026-06 config audit. -Verify 2026-05-04: -- Added [[file:docs/design/init-load-graph.org][docs/design/init-load-graph.org]]. -- Incorporated review feedback by making utility consolidation an explicit - sibling project with guardrails and candidate helper families. -- Parsed the spec and =todo.org= with =org-element=. -- Committed the tracked spec as =0528475=. +** TODO [#B] agenda sources: roam Projects missing, no existence filtering :bug:solo: +From the 2026-06 config audit, =modules/org-agenda-config.el=: +- =:182-191= — commentary and docstrings promise org-roam nodes tagged "Project" as agenda sources, but =cj/--org-agenda-scan-files= never scans them, and files added by the roam finalize-hook are wiped on the next =cj/build-org-agenda-list= cache rebuild (≤1h). Add a roam Project pass (mirror =org-refile-config.el:101-109=) or correct the docs. +- =:186,456= — agenda file list built unconditionally (inbox/calendars may not exist on a fresh machine) and =org-agenda-skip-unavailable-files= is unset — the exact interactive-prompt class that once hung the chime daemon. Filter with =file-exists-p= + set the var as backstop. -**** 2026-05-24 Sun @ 17:07:03 -0500 Classified modules by role and startup requirement -Built [[file:docs/design/module-inventory.org][docs/design/module-inventory.org]] across 9 batches: 101 of 102 init.el-required modules annotated with the load-graph header contract (Layer, Category, Load shape, Eager reason, Top-level side effects, Runtime requires, Direct test load) and tabulated in the inventory. Added =tests/test-init-module-headers.el= to enforce the contract on each classified module. Retired the three vague =init.el= comments (latex-config WIP, prog-shell "combine elsewhere", "Modules In Test" banner) into real tasks. Recorded seven hidden =cj/custom-keymap= / cross-module dependencies for the Phase 2 dependency pass. Tagged the span =load-graph-classify-start..load-graph-classify-end=. elfeed-config is the one module left, pulled to its own task below. +** TODO [#B] org-roam :config triggers the 15-20s refile scan synchronously at first idle :bug:solo: +=modules/org-roam-config.el:78-79= — org-roam is =:defer 1=, so its :config calls =cj/build-org-refile-targets= at 1s idle, BEFORE the 5s background timer (=org-refile-config.el:144-151=); on a cold cache the 30k-file scan runs inline and freezes Emacs at first idle. Drop the call — org-roam is loaded long before the 5s timer fires. Likely a player in the filed org-capture 15-20s perf task (=[#B] Optimize org-capture target building performance=) — check both together. From the 2026-06 config audit. -**** 2026-05-25 Mon @ 08:35:33 -0500 Annotated elfeed-config load-graph header -Added the load-graph header to elfeed-config (Layer 4, O/D/P, current load shape eager with an eager reason, target command-loaded; runtime requires user-constants, system-lib, media-utils), added it to the header-contract allowlist in =tests/test-init-module-headers.el= (Batch 8), and moved it in =docs/design/module-inventory.org= from the Deferred/Pending sections into the Batch 8 table. Inventory now 102 of 102 classified. The header's "Load shape" records the current shape (eager, required in init.el) per the weather-config/games-config convention; "command-loaded" is the target, in the inventory's Target column. Shipped as a522e553. +** TODO [#B] heavy-box comment inserts non-comment lines :bug:solo: +=modules/custom-comments.el:427= — =cj/--comment-heavy-box= interior/empty lines carry no comment prefix, so in line-comment languages (elisp, Python) C-; C h injects syntax-breaking bare =*...= lines. The existing test characterizes the broken output (asserts =^\*.*\*$=). Prefix interiors like =cj/--comment-box= does; add the missing min-length validation (negative width hits make-string with a raw error); fix the test to assert corrected output. From the 2026-06 config audit. -**** 2026-05-24 Sun @ 18:35:06 -0500 Made hidden module dependencies explicit -Fixed the seven hidden dependencies the classification surfaced: system-defaults now requires host-environment and user-constants at runtime (was eval-when-compile); custom-buffer-file, dev-fkeys, calendar-sync, and video-audio-recording require keybindings and drop their =(when (boundp 'cj/custom-keymap) ...)= shims; flycheck-config and mail-config require keybindings for their cj/custom-keymap bindings. Removed a dead =eval-when-compile (defvar cj/custom-keymap)= in transcription-config (the var was never used). +** TODO [#B] calendar-sync robustness: atomic writes, curl --fail, zero-event false errors :bug:solo: +From the 2026-06 config audit, =modules/calendar-sync.el=: +- =:1309= — agenda file written via =with-temp-file= directly on the target (truncate-in-place); org-agenda/chime reading mid-write sees a partial calendar, hourly. Write temp + =rename-file= (atomic same-fs). Same for =--save-state= :258. +- =:1284= — curl runs without =--fail=: an HTTP 404/500 error page exits 0 and the HTML proceeds into conversion. +- =:1229-1233= — =--parse-ics= returns nil for both garbage and a valid calendar with zero in-window events, so healthy near-empty calendars report "parse failed" in =calendar-sync-status=. Distinguish the cases. -No init.el load-order change — keybindings and the foundation modules already load before these, so the explicit requires are no-ops at startup and only fix standalone/test loading. +** TODO [#B] drill-refile clobbers global org-refile-targets with an invalid spec :bug:quick:solo: +=modules/org-drill-config.el:95-98= — =setq org-refile-targets= replaces the session-wide value, so after one drill refile every org-refile everywhere offers only drill targets until restart; and the =(drill-dir :maxlevel . 1)= spec names a directory-path variable where org expects files, so the drill side yields nothing usable. Let-bind around the call with =((directory-files drill-dir t "\\.org$") :maxlevel . 1)=. From the 2026-06 config audit. -Verified each fix with a fresh =emacs --batch (require 'X)=, then swept all ~100 modules standalone: every one loads or fails only with a clear missing-package message (the spec's Phase 2 exit bar). Full =make test=, =make validate-modules=, and an init smoke all pass. Module headers and the inventory's hidden-dependency section updated to mark the seven resolved. +** TODO [#B] ERC: double mention notifications + tautological server list :bug:quick:solo: +From the 2026-06 config audit, =modules/erc-config.el=: +- =:281= — =erc-modules= includes the built-in =notifications= module AND :config adds =cj/erc-notify-on-mention= to the same hook — every mention fires two desktop notifications. Pick one path (keep the custom one, slated for messenger unification). +- =:100= — =cj/erc-connected-servers=: inside =with-current-buffer=, the free =erc-server-process= is the buffer's own local value, so the eq test is tautologically true — returns ALL ERC buffers (channels, dead connections). Use =erc-server-buffer-p= + =erc-server-process-alive=. +- =:238= — =user-whole-name= read at load but =user-constants= only required at compile time (same trap as auth-config/keyboard-macros). -**** TODO [#B] Defer feature modules behind autoloads, hooks, and commands :refactor: +** TODO [#B] slack-config lifecycle gaps :bug:quick:solo: +From the 2026-06 config audit, =modules/slack-config.el=: +- =:265= — w / @ / # bound to commands neither autoloaded nor in :commands — void-function before slack loads. Add to :commands. +- =:246= — =cj/slack-close-all-buffers= reads =slack-current-buffer= (declared but unbound) without the boundp guard its sibling has — void-variable on C-; S Q before slack loads. +- =:259= — raw =global-set-key= for C-; S bypasses =cj/register-prefix-map= (signal/erc use it); invisible to the keybindings registry and the planned unification enumeration. -Once dependencies are explicit, reduce the number of modules required at -startup. Start with lower-risk feature modules: -- Entertainment and optional integrations: =games-config=, =music-config=, - =weather-config=, =slack-config=, =erc-config=. -- Heavy document/media modules: =pdf-config=, =calibredb-epub-config=, - =video-audio-recording=, =transcription-config=. -- AI/rest tooling: =ai-config=, =restclient-config=, =ai-conversations=. +** TODO [#B] erc-yank silently publishes >5-line pastes as public gists :bug: +=modules/erc-config.el:345= — C-y in any ERC buffer auto-creates a public gist for anything over 5 lines: clipboard content goes to a public URL with no confirmation, and no executable-find guard for =gist= (errors mid-send if absent). Privacy trap. Add a =yes-or-no-p= gate or drop the package for plain C-y. From the 2026-06 config audit. -Do this incrementally. After each batch: -- Restart Emacs interactively. -- Run =make test= or at least targeted tests. -- Check that keybindings still resolve and which-key labels still appear. +** TODO [#B] F7 diff-aware coverage classifies every changed file "not tracked" :bug:solo: +=modules/coverage-core.el:252= — =cj/--coverage-intersect= joins covered×changed by exact string key, but simplecov.json keys are ABSOLUTE paths while the git-diff parser returns repo-RELATIVE ones — zero matches ever, so working-tree/staged/branch scopes report ":tracked nil" for everything and F7's main feature is inert (whole-project scope works, same-source keys). Unit tests hand-build matching keys so they pass; add one integration test feeding a real undercover report + real diff. Normalize both sides to repo-relative. From the 2026-06 config audit. -**** 2026-05-24 Sun @ 19:59:01 -0500 Centralized custom keymap registration -Added cj/register-prefix-map and cj/register-command to keybindings.el (commit 47f222f6) with test-init-keymap-registration.el, then migrated all 31 cj/custom-keymap registration sites across 24 modules onto the API. Consumers no longer reference cj/custom-keymap directly — keybindings.el is the sole owner of the prefix, and modules require keybindings to reach the API. +** TODO [#B] eshell: visual-commands nested-list + xterm-color dead hook :bug:quick:solo: +=modules/eshell-config.el:104= — =add-to-list= pushes one LIST into the flat string list =eshell-visual-commands=, so lf/ranger/htop/top never get a visual terminal (and the r→ranger alias garbles). dolist the strings. =:166= — =:hook (eshell-before-prompt-hook . ...)= gets "-hook" appended → registers on nonexistent =eshell-before-prompt-hook-hook=; and =xterm-color-filter= is never added to =eshell-preoutput-filter-functions= anyway while TERM advertises xterm-256color. Wire xterm-color fully per its README or drop it + the TERM override. From the 2026-06 config audit. -Verified behavior-preserving by dumping every C-; binding before and after: identical, 279 bindings, each resolving to the same command. Byte-compiled all 24 migrated files (no new free-variable warnings — the cj/custom-keymap coupling is gone), and full make test, validate-modules, and an init load all pass. which-key label blocks were left intact; they use string key descriptions and never assumed cj/custom-keymap existed. +** TODO [#B] dirvish M (mark all files) marks every other file :bug:quick:solo: +=modules/dirvish-config.el:218= — =dired-mark= advances point to the next line itself; the loop's extra =forward-line 1= then skips it, so consecutive files are marked alternately. Live mis-marking on a key that feeds batch operations (delete/copy on marked files) — data-loss adjacent. Drop the manual forward-line when a mark was made (or =dired-unmark-all-marks= + mark dirs + =dired-toggle-marks=). The trivial line-predicate helper is tested; the loop isn't — add the marked-count test. From the 2026-06 config audit. -Related existing task: [#B] "Review and rebind M-S- keybindings". +** TODO [#B] dwim-shell: zip overwrites its own name, backup timestamp never expands, dired menu key dead :bug:quick:solo: +From the 2026-06 config audit, =modules/dwim-shell-config.el=: +- =:338= — single-file zip is =zip -r '<<fne>>.<<e>>' '<<f>>'= — reconstructs the input filename as the archive ("Zip file structure invalid"; directories produce =foo.=). Should be ='<<fne>>.zip'= like the tar-gzip sibling. +- =:549= — backup destination single-quotes =$(date ...)= so the substitution is literal: =foo.txt.$(date +%Y%m%d_%H%M%S).bak=. Move it outside the quotes or format-time-string in Elisp. +- =:932= — dired-mode binding "M-S-d" is unreachable (Meta+Shift+d generates M-D); the dirvish binding two lines down is correctly "M-D". Fix + the stale commentary at dirvish-config.el:30. -*** PROJECT [#A] Move package bootstrap out of =early-init.el= where possible :startup:refactor: +** TODO [#B] Go: format key void-functions, go-mode :config never runs :bug:quick:solo: +=modules/prog-go.el:99,113-118= — .go maps to go-ts-mode so the go-mode package never loads, and =gofmt= isn't autoloaded in go-mode 1.6.0 — C-; f signals void-function, and the :config (exec-path += ~/go/bin, =gofmt-command "goimports"=) never executes. Wrapper that requires go-mode first (or autoload gofmt), move the setup to top level. From the 2026-06 config audit. -=early-init.el= currently handles package archives, package refresh, installing -=use-package=, and =use-package-always-ensure=. That is more than early startup -needs and can make startup network-sensitive. +** TODO [#B] prog hooks mutate global state per buffer :bug:quick:solo: +From the 2026-06 config audit: =prog-go.el:64=, =prog-c.el:73=, =prog-shell.el:77= call global =(electric-pair-mode t)= from buffer setup hooks — one Go/C/shell buffer turns on pairing in org/text everywhere (python/webdev correctly use =electric-pair-local-mode=). =prog-general.el:79-80= — =display-line-numbers-type 'relative= setq/setq-default run from the hook AFTER the mode is enabled, so the first prog buffer of a session gets absolute numbers. Local-mode for the three; move the line-number setqs to top level. -**** TODO [#B] Split early startup from package bootstrap :refactor: +** TODO [#B] M-S- launcher keys dead: eww, elfeed, calibredb unreachable :bug:quick:solo: +=eww-config.el:70= (M-S-e), =elfeed-config.el:36= (M-S-r), =calibredb-epub-config.el:115= (M-S-b) — Meta+Shift+letter generates the uppercase event (M-E/M-R/M-B), which never matches an explicit S- spec on a lowercase letter; verified dead in the live daemon (chord falls through to M-r move-to-window-line etc.). Same class as the text-config M-S-i finding. Write them as "M-E"/"M-R"/"M-B". Weather's M-S-w works only via the keyboard-compat translation layer — audit that layer's coverage while here. From the 2026-06 config audit. -Keep =early-init.el= focused on things that must happen before package and UI -startup: -- GC/file-name-handler startup tuning. -- =load-prefer-newer=. -- frame/UI suppression. -- minimal debug behavior. +** TODO [#B] ai-rewrite: chosen directive never reaches the request :bug:solo: +=modules/ai-rewrite.el:64= — the directive is let-bound around =(call-interactively #'gptel-rewrite)=, but gptel-rewrite is a transient prefix that returns when the menu shows; the send resolves the directive AFTER the binding unwound (verified against ~/code/gptel/gptel-rewrite.el:780-799). The picker's choice is silently dropped — the module's core feature is inert. Set =gptel--rewrite-directive= buffer-locally (restore via =gptel-post-rewrite-functions=) or use a self-removing global hook entry. From the 2026-06 config audit. -Move package archive setup and =use-package= installation to a normal module or -bootstrap command, unless there is a specific reason it must run in -=early-init.el=. +** TODO [#B] ai-conversations: dead-buffer load, role flattening, non-atomic writes :bug:solo: +From the 2026-06 config audit, =modules/ai-conversations.el=: +- =:324= — load in a fresh session does =get-buffer-create "*AI-Assistant*"= (plain fundamental-mode buffer); =--ensure-ai-buffer= then sees it exists and never calls =(gptel)=. Sending doesn't work, autosave self-cancels (requires gptel-mode). Use =get-buffer= for the check; let ensure create. The browser RET/l path inherits this. +- =:240= — persistence drops gptel's =response= text properties, so a reloaded history replays to the model as ONE user message (model re-reads its own answers as Craig's words). Adopt gptel's native bounds persistence or re-mark on load from the "* Backend:" headings. +- =:248= — =write-region= straight at the target; crash mid-write truncates the only copy of the history (autosave hits this constantly). Temp + rename. +- =:140= — three overlapping autosave mechanisms (after-send advice that fires before the response exists, post-response hook, 60s timer). Keep the hook; drop the advice (and likely the timer). -Acceptance criteria: -- Fresh install/bootstrap still works from a documented command or script. -- Normal startup does not refresh archives or install packages unexpectedly. -- Offline startup remains quiet and predictable. +** TODO [#B] cj/gptel-switch-backend reintroduces the string-model crash :bug:quick:solo: +=modules/ai-config.el:272= — =(setq gptel-model model)= with the raw completing-read STRING — the documented wrong-type-argument-symbolp modeline hang (CLAUDE.md gotcha), reachable from C-; a B today. =cj/gptel-change-model= (C-; a m) already does backend+model switching and interns correctly. Intern here, or delete switch-backend and keep one command. From the 2026-06 config audit. -**** TODO [#A] Revisit package signature policy +** TODO [#B] transcription: stderr never reaches the log, video transcripts stranded in /tmp :bug:solo: +From the 2026-06 config audit, =modules/transcription-config.el=: +- =:210= — =make-process :stderr= with a file PATH creates a BUFFER named like the path (verified by probe); the "Errored. Logs in <file>" notification points at a log without the error text, and the hidden stderr buffer leaks per transcription. Route stderr into the process buffer or write it out in the sentinel. +- =:370-374= — video path derives txt/log from the temp mp3's /tmp path; the transcript lands in /tmp and dies on reboot, contradicting the "alongside the source" docstring. Pass the video's path as the output base. -=package-check-signature= is disabled. Decide whether that is still necessary -for the localrepo/mirror workflow. +** TODO [#B] ledger-config is orphaned — ledger-mode never configured :bug:quick: +Nothing requires =modules/ledger-config.el= (verified by grep), so .dat/.ledger/.journal open without ledger-mode, reports, or flycheck-ledger. The module looks finished, not staged (unlike duet-config, which documents its pre-alpha orphaning). Decide: wire into init.el (+ =cj/executable-find-or-warn= for the ledger binary) or delete. From the 2026-06 config audit. -Expected outcome: -- Prefer signatures on by default. -- If signatures must be disabled for local mirrors, scope that exception and - document why. -- Add a note to the local repository docs so future package failures do not - lead to permanent insecure defaults. +** TODO [#B] eww quick-add bookmarks split the store and break the default file :bug:quick:solo: +=modules/eww-config.el:116-126= — quick-add let-binds =eww-bookmarks-directory= to ~/.emacs.d/eww-bookmarks/ (creating a DIRECTORY at the path where the daemon's default store expects a FILE ~/.emacs.d/eww-bookmarks). After one quick-add, B reads an unreadable path and quick-added bookmarks are invisible post-restart. Drop the let-binding or setq the directory once in :config so both commands share one store. From the 2026-06 config audit. -** TODO [#B] F-key Completion :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +** TODO [#B] help-config: three defects in one small file :bug:quick:solo: +From the 2026-06 config audit, =modules/help-config.el=: +- =:67= — =cl-return-from= inside a plain =defun= (no cl-block): declining the save prompt signals "No catch for tag" instead of canceling. =cl-defun= or restructure. +- =:108= — =:hook (info-mode . info-persist-history-mode)= is dead twice: Info's hook is =Info-mode-hook= (capital I), and =info-persist-history-mode= doesn't exist anywhere. Implement the intent or delete. +- =:111= — auto-mode-alist maps .info to an interactive command that KILLS the buffer mid find-file — programmatic =find-file-noselect= of any .info destroys buffers and pops Info windows. Drop the entry; keep the explicit command. Zero test coverage on this module (the two broken paths are exactly the untested ones). -The L546 ticket "Rework dev F-keys" landed roughly 75% as of the 2026-05-27 audit. F4 (compile+run dispatcher, project-type detection, clean-rebuild, projectile cache revert), F7 (coverage), and the format-key migration off F6 are all shipped with ERT coverage. F6 ships Phase 2a only — "All tests" and "Current file's tests" via plain F6 and C-F6. +** TODO [#B] modeline runs synchronous git on the redisplay path, unguarded :bug:solo: +=modules/modeline-config.el:173,154,145= — the mode-line :eval calls vc-backend/vc-state/vc-working-revision (synchronous git) on TTL expiry; a slow or unmounted filesystem stalls ALL redisplay. The cache key computes =file-truename= on every render (the "one stat per refresh" comment is wrong), and nothing is condition-case-wrapped, so a signal lands inside the mode-line eval. Defer the truename behind the TTL check; wrap the fetch in condition-case caching nil. From the 2026-06 config audit. -Phase 2b remains: per-language test discovery, the "Run a test..." menu entry, M-F6 fast path, buffer-local last-test memory, and the spec-mandated "No tests found for <buffer>" error. The =dev-fkeys.el= header (L35–46) already sketches the tree-sitter capture-then-filter pattern needed to work around Emacs bug #79687 on the emacs-30 branch. +** TODO [#B] Stale elpa gptel shadows the local fork — likely the gptel-magit root :bug:quick:solo: +=elpa/gptel-0.9.8.5= is still installed alongside the =~/code/gptel= fork (=ai-config.el:383=); package activation puts the elpa dir + autoloads on load-path, so which copy wins depends on ordering, and a mixed load (fork .el + elpa .elc) produces "impossible" bugs. =gptel-magit= (elpa) declares gptel as a dependency, so IT may be pulling the stale copy — check this first when working the open "[#B] Investigate gptel-magit not working properly" task. Fix: =package-delete= the elpa gptel + remove from .localrepo so the fork is the only copy on disk. From the 2026-06 config audit. -Two smaller cleanups also fall out: the header comment claims TS/JS is "punted for v1" while the cmd-builder at =dev-fkeys.el:384= actually emits a vitest/jest command, and the cmd-builder is a likely home for =cj/--tests-in-buffer= once it lands. +** TODO [#B] vertico-prescient clobbers orderless filtering :bug:quick:solo: +=modules/selection-framework.el:250= — =vertico-prescient-mode= defaults =vertico-prescient-enable-filtering t=, overriding =completion-styles= to prescient inside vertico sessions; the orderless config at :151 is dead exactly where it matters. Set =vertico-prescient-enable-filtering nil= — orderless matches, prescient sorts (and this resolves the dead =vertico-sort-function= finding in the buffer/window-libs child the other way around). From the 2026-06 config audit. -Open: helper home — keep =cj/--tests-in-buffer= in =dev-fkeys.el= (per L546 spec) or push it into =test-runner.el= (per the parallel "Fix up test runner" thread). Elisp "Run a test..." — drill into individual =ert-deftest= names, or keep the current regex-aggregate (=make test-name TEST=^test-<stem>-=). +** TODO [#B] 2026-06 full config audit — findings backlog :refactor: +Module-by-module review of all 121 modules + init/early-init, holistic passes (startup/perf, stability, UX consistency, package strategy), and spin-offs into pearl, chime, emacs-wttrin. Method: parallel read-only review agents per module group; key claims spot-verified (incl. against the live daemon) before filing. Run 2026-06-11/12, COMPLETE. Tally: ~165 module findings + ~40 holistic + 30 spin-off ≈ 235 total; 40 high-impact bugs filed as standalone tasks above this parent; the rest live in the group children below. Spin-off findings delivered as inbox handoffs to pearl, chime, and emacs-wttrin (2026-06-12-0057). Start with the synthesis child below for the recommended attack order. -*** TODO [#B] Per-language test discovery helper :feature:tests: -Build =cj/--tests-in-buffer= returning a list of test names; tree-sitter capture-then-filter for python/go/ts/js per the bug #79687 workaround in =dev-fkeys.el= L35–46; sexp scan for elisp =ert-deftest= forms. +*** Synthesis: the overall picture and attack order +Six cross-cutting themes, then the order I'd work them. -*** TODO [#B] F6 Run-a-test menu entry :feature:tests: -Add "Run a test..." to =cj/f6-test-runner= candidates; pre-select =cj/--last-test-run=; signal =user-error= "No tests found for <buffer>" when discovery returns nil. +Themes: +1. Performance has one systemic lever, not many small ones: native-comp is accidentally OFF config-wide and GC sits at the stock 800KB ([#A] task). Daemon init itself is healthy (1.11s measured). Fix the lever before any micro-deferral work, and before burning time on the org-capture-perf debug. +2. A "dangerous defaults" safety cluster: yes-or-no-p fset (single-keystroke shutdown/file-destruction), the silently-failing Wayland lock screen, erc-yank's public gists, mu4e's broken trash/refile on the primary account. All four are [#A]/[#B] standalones; do these first — they're where the config can actually hurt you. +3. Calendar/agenda data correctness: calendar-sync's RFC trio (vanishing final occurrences, resurrected cancelled meetings, collapsed multi-day events) + agenda sources missing roam Projects. Meetings are missed over this. +4. Recurring mechanical defect classes worth sweeping as one commit each, config-wide: use-package :hook "-hook" suffix trap (org-babel, eshell, latex); eval-when-compile-only requires read at runtime (auth-config, keyboard-macros, erc-config); M-S-<letter> bindings vs uppercase events (4 dead keys + 1 asymmetry); raw C-; entries bypassing cj/register-prefix-map (8 modules); unreachable modules (prog-lsp, ledger-config, show-kill-ring, mu4e-org-contacts-setup); config for package versions long gone (mu4e 1.7 block, dashboard override, org timeline, checkdoc-arguments). +5. The test suite has a blind-spot class: characterization tests asserting BROKEN output (reverse-lines, heavy-box, undo-kill's explicit 0), unit tests hand-building data that hides integration mismatches (F7 coverage paths), and an integration gate that prints green over "Ran 0 tests" (chime). When fixing any standalone bug above, fix its test to assert correct behavior — and consider extending the architecture smoke test to mechanically pin the class-4 sweeps (hooks must be bound after load, no raw C-; binds, no M-S-<letter> specs, no eval-when-compile requires of runtime vars). +6. Consistency wants conventions, not patches: one notification facade (cj/notify — messenger spec addendum already covers the messenger half), one confirmation tier (the fset fix), one prefix-registration mechanism with labels, one buffer-naming shape. The messenger-unification registry mindset generalizes. -*** TODO [#B] M-F6 fast path :feature:tests: -Bind =M-<f6>= to a thin wrapper that calls the same "Run a test..." path directly; release the reservation comment at =dev-fkeys.el:541=. +Attack order: (a) the three [#A]s + gptel-shadow (it's blocking the filed gptel-magit investigation); (b) the daily-data pair — mail trash/refile + calendar RFC trio; (c) the :quick:solo: standalone sweep — roughly 20 one-to-five-line fixes, a satisfying solo batch; (d) the class-4 mechanical sweeps, one commit per class, each with its smoke-test guard; (e) the consistency conventions, opportunistically as those modules get touched. -*** TODO [#B] Buffer-local cj/--last-test-run :feature:tests: -Add the buffer-local var, set it on each "Run a test..." selection, use it as the completing-read default so a bare RET re-runs the last test. +*** TODO Findings: foundation/system group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [BUG] =keyboard-compat.el:121= — terminal arrow-key fix runs once on emacs-startup-hook; =input-decode-map= is terminal-local, so =emacsclient -t= frames under the daemon never get it. Register on =tty-setup-hook= (GUI half already uses =server-after-make-frame-hook=). +- [BUG] =config-utilities.el:142= — =cj/recompile-emacs-home=: =(boundp 'native-compile-async)= is always nil (it's a function — needs =fboundp=), so native compilation is never selected; and the helper deletes =<dir>/eln= when the real cache is =eln-cache/= (derive from =native-comp-eln-load-path=). Extend the existing test. +- [BUG] =system-utils.el:94= — success message args swapped: prints "Running notes.txt on mpv...". Trivial; wired into dirvish (O) and calibredb so it shows regularly. +- [REMOVE] =local-repository.el:51= — =localrepo-initialize=, its three defcustoms, and unprefixed =car-member= are dead; early-init owns archive setup with its own divergent path constant. Shrink to =cj/update-localrepo-repository= pointed at early-init's =localrepo-location=. +- [REMOVE] =keybindings.el:146-147= — C-x C-f unset/reset is a no-op (already find-file); comment wrong. Delete or retarget. +- [COVERAGE] =local-repository.el= — only module in the group with no test file. -*** TODO [#B] TS/JS coverage status sync :docs:cleanup: -Update the =dev-fkeys.el= header comment (L33) — TS/JS is no longer punted; the cmd-builder at L384 emits vitest/jest. Document the prefer-vitest fallback. +*** TODO Findings: UI core group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [BUG] =font-config.el:262= — emojify =:defer 1= means :config runs before any daemon GUI frame exists; =env-gui-p= picks ='unicode= permanently, GUI frames never get image emojis. Compute per-frame (=server-after-make-frame-hook=) or test =(daemonp)=. +- [BUG] =font-config.el:283= — =cj/display-available-fonts= errors on second invocation: first call's =special-mode= sets read-only; next call's erase/insert signals. Wrap in =inhibit-read-only=. (Also [COVERAGE]: untested — a call-twice test catches it.) +- [UX] =undead-buffers.el:82= — =cj/kill-other-window= in a single-window frame kills the buffer you're looking at (other-window no-ops; only delete-window is guarded). Add the sibling's =(user-error "No other window")= guard. +- [UX] =undead-buffers.el:48= — C-u C-x k silently marks a buffer undead (then it refuses to die with no explanation later). Undocumented mode-switch inside a core-command remap; document or split into its own command. +- [ENHANCE] =ui-theme.el:87= — theme persistence silently fails on a fresh machine until =persist/= exists; =make-directory= before the writability check. +- [REMOVE] =dashboard-config.el:32-58= — =dashboard-insert-bookmarks= override is dead code: the :demand t require lets upstream dashboard-widgets.el redefine it; behavior survives only because upstream natively honors the settings now. Delete. +- [REMOVE] =font-config.el:199-220= — all-the-icons stack (2 =:demand t= packages + unprompted network font install on fresh machines) likely redundant with nerd-icons everywhere; verify keyboard-compat's reference then drop. +- [REMOVE] =ui-config.el:185= — duplicate =(use-package nerd-icons :defer t)= stanza; nerd-icons-config owns it. Delete stanza + stale Commentary bullet. -** TODO [#B] Fix up test runner :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-06 -:END: -*** 2026-05-16 Sat @ 11:15:51 -0500 Ideas -**** Current State -=modules/test-runner.el= is a solid first pass for an Emacs-config-specific ERT -workflow: -- project-scoped focus lists -- run all vs focused mode -- run ERT test at point -- load all test files -- clear ERT tests from other project roots -- keybindings under =C-; t= +*** TODO Findings: buffer/window libs group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [REMOVE] =show-kill-ring.el= — loaded by nothing (init require deliberately removed in b785a19d), so its M-S-k binding is dead; =keyboard-compat.el:177= still installs the M-K → M-S-k translation whose only purpose was this module. Re-add or delete module + stale translation/comment (consult-yank-pop largely supersedes it). +- [UX] =selection-framework.el:38= — =vertico-sort-function= custom is dead config: =vertico-prescient-mode= (line 250) replaces sorting when it activates. Pick one policy (drop the custom, or =vertico-prescient-enable-sorting nil=). +- [BUG] =custom-buffer-file.el:486= — =cj/view-email-in-buffer= leaks MIME handles when no displayable part: =user-error= fires before =mm-destroy-parts=. unwind-protect. +- [ENHANCE] =custom-buffer-file.el:49= — eager =(require 'mm-decode)= at startup only for macro expansion; runtime require already exists at line 481. Make it =eval-when-compile=. +- [UX] =custom-buffer-file.el:221= — =cj/copy-link-to-buffer-file= is a silent no-op in non-file buffers while siblings signal =user-error=. Match them. -The universal test-running direction is currently split across modules: -- =test-runner.el= owns ERT focus/state/UI. -- =dev-fkeys.el= owns F6 language detection and command generation for Elisp, - Python, Go, and partial TypeScript. +*** TODO Findings: editing helpers group +From agents 2026-06-11; spot-verified sample (jump-paren, sortable-time confirmed). Beyond the standalone heavy-box task: +- [BUG] =custom-misc.el:48= — jump-to-matching-paren with point ON a closer lands at the last inner sexp, not the opener (batch-verified). =(forward-char)= before =(backward-sexp)= in the char-after-closer case; the test only covers the after-closer position. +- [BUG] =custom-datetime.el:71= — "sortable" time format is 12-hour ="%I:%M:%S %p %Z"= — "01:00:00 PM" sorts before "09:00:00 AM". Should be ="%H:%M:%S"=. +- [BUG] =custom-comments.el:82= — =cj/comment-reformat= prints "No region was selected" even on success (message outside the if-else), and the fill-column shrink/restore isn't unwind-protected — an error leaves fill-column permanently -3. Use let-binding + =user-error=; also =mark-active= vs the config's usual =use-region-p=. +- [BUG] =custom-line-paragraph.el:52= — join-line-or-region without region inserts a spurious blank line mid-buffer (verified); only insert the newline at eobp. +- [BUG] =custom-line-paragraph.el:77= — duplicate-line-or-region splits a mid-line-ending region via open-line and duplicates an extra empty line when the region ends at bol. Normalize bounds to whole lines. +- [BUG] =custom-ordering.el:158= — reverse-lines and number-lines mishandle the trailing newline ("a\nb\n" → "\nb\na"); the trailing-newline test asserts the broken output. =cj/--arrayify= (line 43) has the correct pattern — apply it; fix the characterization test. +- [BUG] =custom-comments.el:152= — inline-border lines come out 2 chars short for even-length or empty text (parity computed from text length instead of remaining width); stacked dividers misalign. +- [UX] =custom-text-enclose.el:216= — indent-lines =(interactive "p\nP")= couples COUNT and USE-TABS to one prefix arg — multi-column space indent is impossible interactively; docstrings claim "default 4" but "p" defaults to 1 (same in dedent :256). +- [REMOVE] =custom-ordering.el:90= — =cj/arrayify-python= is byte-identical to =cj/arrayify-json= (two bindings, same output). Delete one or differentiate (single quotes for Python). +- [UX] =custom-case.el:66= — title-case contradicts its docstring: "is" is in word-skip despite "linking verbs are major words"; no sentence-restart capitalization after periods; no capitalize-last-word rule. Align list + docstring. -That split is the biggest architectural pressure point. The test runner should -eventually own runner discovery, scopes, command construction, result handling, -and UI. F6 should become a thin entry point into the runner. +*** TODO Findings: text/prose tools group +From agents 2026-06-11. Beyond the standalone markdown/latex tasks: +- [BUG] =text-config.el:72= — "M-S-i" for edit-indirect-region is unreachable: Meta+Shift+i generates the event M-I, not M-S-i, so the keypress falls back to M-i tab-to-tab-stop. Rebind as "M-I" (the "was M-I" comment thought the rename was a no-op; it wasn't). +- [BUG] =keyboard-macros.el:46= — user-constants required only =eval-when-compile= but =macros-file= is read at runtime; works only because init.el loads user-constants first. Plain require (same trap as auth-config). +- [BUG] =keyboard-macros.el:137= — kill-emacs-hook fires =y-or-n-p= + an interactive name prompt whenever any last-kbd-macro exists — hazardous for daemon/systemd shutdown (no one to answer) and noisy for throwaway macros. Guard =(and last-kbd-macro (not noninteractive))= minimum; consider dropping the prompt (M-F3 already persists named macros). +- [BUG] =lorem-optimum.el:221= — empty Markov chain (missing assets/liber-primus.txt) makes =cj/lipsum-insert= do =(insert nil)= — cryptic wrong-type error far from cause. Signal =user-error= naming the fix; also Commentary advertises "M-x cj/lipsum" but it has no interactive spec. +- [UX] =flyspell-and-abbrev.el:230= — every C-' press re-runs =flyspell-buffer= over the whole buffer while flyspell-mode is off (the documented word-by-word workflow = O(buffer) per keypress in large files). Call =cj/flyspell-on-for-buffer-type= so the mode sticks and the scan runs once. +- [ENHANCE] =text-config.el:121= — accent is wired to the company backend (=accent-company=); the filed Company→Corfu migration task doesn't list it, so C-` breaks silently post-migration. Add to the migration scope or switch to =accent-menu= now. -**** Critical Design Issues -***** Too ERT-specific at the core -The current state model is named generically, but most operations assume: -- test files live in =test/= or =tests/= -- files match =test-*.el= -- tests are ERT forms -- individual tests can be selected by ERT selector regex -- loading tests into the current Emacs process is acceptable +*** TODO Findings: org core group +From agents 2026-06-11; spot-verified sample (dailies head, babel hook, void bindings confirmed). Beyond the standalone tasks: +- [BUG] =org-babel-config.el:27= — =:hook (org-babel-after-execute-hook . org-redisplay-inline-images)= gets a second "-hook" appended (symbol unbound at expansion, doesn't end in -mode) → registers on nonexistent =org-babel-after-execute-hook-hook=; inline dot-graph images never refresh after C-c C-c. Write =(org-babel-after-execute . ...)= or add-hook in :config. +- [BUG] =org-roam-config.el:67,71= — C-c n p / C-c n w bound (and which-key-labeled) to =cj/org-roam-find-node-project= / =-webclip=, defined nowhere — keypress errors "autoloading failed to define function". Define via =cj/org-roam-find-node= (a project template exists) or drop bindings + labels. +- [BUG] =org-export-config.el:74-81= — ox-texinfo block can never run (=:defer t=, no trigger, excluded from line-47 dolist and =org-export-backends=); commentary still advertises Texinfo. Add to the dolist or delete; also commentary says "subtree default scope" vs actual ='buffer= (line 61). +- [UX] =org-roam-config.el:50-63= — two parallel template dirs drift: :custom templates read =~/.emacs.d/org-roam-templates/= while find-node-topic/recipe read =roam-dir/templates/= — overlapping recipe/topic/v2mom files, edits don't propagate. Pick one canonical dir. +- [REMOVE] =org-agenda-config.el:84= — dead =timeline= entry in org-agenda-prefix-format (removed in org 9.1). Also =org-config.el:47-48= — the TASK note claiming =org-indent-indentation-per-level= "doesn't exist" is wrong (real org-indent defcustom); restore the setq or fix the comment. +- [REMOVE] =org-babel-config.el:161= — =org-html-footnote-separator= is an ox-html setting parked in the babel module with a wrong comment; =org-roam-config.el:76= similarly hides =org-agenda-timegrid-use-ampm= in roam's :config (only takes effect after roam loads). Move both to their owning modules. +- [REMOVE] =org-roam-config.el:363-390= — 28-line commented consult-org-roam block on a TASK comment; its proposed C-c n l / C-c n r now collide with live bindings, so it can't ship as written. Decide + delete (git keeps the draft). +- [COVERAGE] =org-agenda-config.el:423= cj/add-timestamp-to-org-entry (defvar-inside-defun smell), =org-roam-config.el:115,185= node-insert-immediate + finalize-hook — untested. -This makes the module hard to extend cleanly to pytest, Jest, Vitest, Go, Rust, -or shell test runners. The common abstraction should be "test run request" and -"test runner adapter", not "ERT file list". +*** TODO Findings: org apps + calendar-sync group +From agents 2026-06-11/12; spot-verified sample (UNTIL comparisons, EXDATE regex, drill setq confirmed). Beyond the standalone tasks: +- [BUG] =org-reveal-config.el:241= — seven raw =global-set-key= "C-; p ..." calls carry a hidden load-order dependency on keybindings.el (signals "non-prefix key" otherwise); every sibling uses =defvar-keymap= + =cj/register-prefix-map=. Convert. +- [BUG] =org-drill-config.el:131= — =:load-path "~/code/org-drill"= dev checkout breaks drill on machines without it (velox already diverges per the gptel-magit task). Guard with =file-directory-p= fallback to :vc. +- [UX] =org-contacts-config.el:146= — =cj/org-contacts-find= visits the file BEFORE prompting (C-g strands you at point-min) and plain =search-forward= can match body text in another entry. Collect heading positions in org-map-entries, goto after prompt. +- [REMOVE] =calendar-sync.el:1240= — =calendar-sync--fetch-ics= (buffer-string variant) is dead; the sync path uses the temp-file variant exclusively. 30 lines of duplicate curl/sentinel logic that will drift. +- [REMOVE] =org-webclipper.el:216-241= dead commented keymap blocks; =org-contacts-config.el:118-124= commented duplicate capture template flagged "TASK: duplicate?!?". Delete both (git keeps drafts). +- [COVERAGE] =calendar-sync.el:1274= — fetch sentinel branches (curl failure, temp-file cleanup, signal exit) untested; dispatch tests stub above this layer. -***** In-process ERT causes state contamination -=cj/test-load-all= and focused runs load test files into the current Emacs -session. This is fast and ergonomic, but it can leak: -- global variables -- advice -- loaded features -- overridden functions -- ERT test definitions -- load-path mutations +*** TODO Findings: mail group +From agents 2026-06-12; spot-verified sample (cmail trash gap, no refile folders, gmail-first contexts confirmed). Beyond the standalone [#A] task: +- [BUG] =mail-config.el:392-407= — C-; e account nav lambdas call =mu4e-search=, not autoloaded — void-function before first mu4e launch. Add to :commands or require first. +- [BUG] =mail-config.el:481-484= — unconditional =org-msg-edit-mode= :after advice on replies defeats the =(reply-to-text . (text))= alternative at :459 and re-runs a major mode org-msg already set up. Gate or remove. +- [BUG] =mu4e-attachments.el:222= — the *mu4e attachments* selection buffer saves through stale MIME handles if the view changed before s — errors or saves the wrong message's parts. Check =buffer-live-p= per handle at save. +- [BUG] =mail-config.el:329= — "save attachment" in =mu4e-headers-actions= can't work from headers (MIME vars are view-buffer-local, nil in headers-mode). Drop it there. +- [BUG] =mail-config.el:282-305= — HTML view block sets variables obsolete since mu4e 1.7 (installed 1.14.1): =mu4e-view-prefer-html=, =mu4e-html2text-command= (also set twice: 186, 285), =mu4e-view-show-images=, =mu4e-view-image-max-width=. The pandoc/w3m selection never runs; shr renders regardless. Delete the dead block (image/privacy reconciliation already filed separately). +- [BUG] =mail-config.el:45-49,80-89= — top-level =(defvar message-send-mail-function nil)= pre-empts message.el's defcustom default; with msmtp absent the fallback leaves it nil → "invalid function: nil" on first send. Explicit =smtpmail-send-it= fallback or descriptive user-error. +- [UX] =mail-config.el:171,196-199= — =pick-first= + gmail listed first makes gmail the startup context though cmail reads as primary everywhere else — quiet wrong-account hazard for the first compose. Reorder contexts. +- [REMOVE] =mu4e-org-contacts-setup.el= — unreachable (nothing requires it; mail-config calls activation directly) and its featurep gate would be nil at init anyway. Delete or fold its two setqs into mail-config. +- [REMOVE] =mail-config.el:208,232= — =mu4e-starred-folder= isn't a mu4e variable (invented, no effect); =:174= =mu4e-maildir= is the obsolete alias of root-maildir set on the previous line. Drop all three. +- [REMOVE] =mu4e-org-contacts-integration.el:158,171-172= — hook surgery on =mu4e--compose-setup-completion= is a no-op on mu4e 1.14 (called directly, not via hook; already gated by the var activation sets). Delete both hook calls. +- [COVERAGE] =mu4e-attachments.el:101-105= — mid-batch save-failure path and stale-handle scenario untested. -The runner should support two ERT execution modes: -- =interactive= / in-process for fast local TDD -- =isolated= / batch Emacs for reliable verification +*** TODO Findings: messengers group +From agents 2026-06-12. Beyond the standalone tasks; several feed the messenger-unification spec: +- [BUG] =signal-config.el:201= — contact cache docstring claims "cleared on signel-stop/restart"; nothing clears it (grep: fork never references it). Stale list after relink/reconnect. Advise =signel-stop= or clear on start. +- [BUG] =signal-config.el:298= — fetched-and-empty contact list is indistinguishable from cold cache (nil), so a zero-contact account re-runs the blocking fetch (up to fetch-timeout) on every C-; M m. Cache a sentinel. +- [UX] =slack-config.el:208= — =cj/slack-notify= lacks signel's hardening: no truncation (giant toasts), no sound gating, no notifications-notify fallback when the script is absent. Unification-relevant: extract a shared =cj/messenger-notify= (title prefix, truncation, sound flag, script-with-fallback) — noted in the unification spec. +- [ENHANCE] =telega-config.el:52= — telega has NO notification path (=telega-notifications-mode= not enabled); incoming Telegram messages invisible unless the buffer is on screen. Enable, or route through the shared notifier. Unification-relevant. +- [COVERAGE] — =cj/erc-join-channel-with-completion= (erc:148, four-way reconnect branching), =cj/erc-connected-servers= (would have caught the tautology), =cj/slack-notify= predicates, =cj/signel--ensure-started= branches — all untested. -The isolated path should be preferred for "before commit", CI parity, and -agent-driven verification. +*** TODO Findings: programming group +From agents 2026-06-12; spot-verified sample (prog-lsp unreachable confirmed by grep). Beyond the standalone tasks: +- [BUG→FOLD] =prog-lsp.el= — the module is UNREACHABLE: nothing requires it, so its entire LSP policy (TRAMP guard, file-watch ignores, read-process-output-max, idle-delay 0.5) is dead while prog-general.el:388-416's older conflicting block wins (idle 0.1, lsp-ui-doc on). Fold this fact into the filed "Make prog-lsp.el the single owner of generic LSP policy" task — it doesn't currently record that prog-lsp never loads. +- [BUG] =flycheck-config.el:68-70= — =checkdoc-arguments= isn't a real variable (invented name + invented format); the intended checkdoc suppression has never worked. Use =flycheck-emacs-lisp-checkdoc-variables= or drop. +- [BUG] =prog-json.el:87-90= — C-c C-q → jq-interactively binding defers to eval-after-load of jq-mode, which nothing loads — dead key. Bind in =cj/json-setup= via local-set-key (jq-interactively IS autoloaded). +- [BUG] =prog-python.el:129-132= — lsp-pyright's :hook lambda calls =lsp-deferred= unguarded on the same hook as the guarded =cj/python-setup= — pyright-absent machines still get the LSP attach prompt the guard exists to prevent. Move the require into the guarded branch; delete the hook. +- [BUG] =prog-lisp.el:122-125= — =:after (flycheck package-lint)= waits for a manual M-x to load package-lint, so =flycheck-package-setup= effectively never runs. Hook on flycheck load + require inside. +- [UX] =prog-python.el:111-115=, =prog-go.el:111-114=, =prog-webdev.el:128-147= — setup hooks attach to ts-modes only (C/shell hook both variants); grammar-unavailable fallback to classic modes silently loses indent/keys/formatter/LSP. Add classic-mode hooks. +- [UX] =prog-webdev.el:165-173= — web-mode gets the format key but none of the promised setup (no company/flyspell/LSP in HTML buffers). Add to the setup hook or fix the Commentary. +- [ENHANCE] gopls, clangd, bash-language-server, shfmt, shellcheck lack the =cj/executable-find-or-warn= load-time warnings pyright/prettier have; prog-shell's =:if (executable-find ...)= evaluates once at startup and silently disables shfmt/flycheck setup forever. +- [REMOVE] =prog-training.el:36-37= — =(url-debug t)= turns on GLOBAL url.el debug logging once leetcode loads. Debugging leftover; delete. +- [REMOVE] =prog-webdev.el:85=, =prog-json.el:44=, =prog-yaml.el:39= — three byte-identical format-region helpers. Extract one shared tested helper (system-lib). -***** Test discovery is regex-based and fragile -=cj/test--extract-test-names= scans files with a regex for =ert-deftest=. -That misses or mishandles: -- macro-generated tests -- commented forms in unusual shapes -- multiline or reader-conditional forms -- non-ERT Elisp tests such as Buttercup -- stale ERT tests already loaded in the session +*** TODO Findings: dev tooling group +From agents 2026-06-12; spot-verified sample. Beyond the standalone F7 task: +- [BUG] =vc-config.el:138-144= — =cj/goto-git-gutter-diff-hunks= (C-; v d) never did what it claims: consult-line over "^[+\\-]" matches source text, not gutter hunks. Build candidates from =git-gutter:diffinfos= or drop the binding (C-; v n/p covers it). +- [BUG] =dev-fkeys.el:116-122= — F4 compile+run one-shot hook installs on GLOBAL =compilation-finish-functions= before the prompt; C-g leaves it armed and the next unrelated compile triggers projectile-run-project. Use the buffer-local pattern the module already uses for cache-revert (same in =--f4-clean-rebuild-impl=:143). +- [BUG] =test-runner.el:84,222= — documented ~/.emacs.d/tests fallback doesn't exist (=cj/test-global-directory= defvar'd nil, never set); outside a project =(file-directory-p nil)= crashes in three commands. Initialize the defvar or guard with user-error. (Adds specifics to the open "Fix up test runner" task — fold.) +- [BUG] =test-runner.el:288= — focus-add prefix check lacks the trailing slash so =tests-scratch/= passes the "inside tests/" check; the correct helper =cj/test--file-in-directory-p= exists at :168 — use it. +- [BUG] =vc-config.el:217-219= — difftastic blame map binds D and S to the same command (show); D should be diff per the transient four lines down. +- [UX] =diff-config.el:37= — =ediff-diff-options "-w"= ignores ALL whitespace in every ediff session — indentation-only Python changes compare as identical. Drop the default; toggle per-session. +- [UX] =restclient-config.el:64-65= — raw global-set-key "C-; R n" hides a load-order dependency (header claims "Runtime requires: none"); use defvar-keymap + =cj/register-prefix-map= like siblings (same class as org-reveal, slack). +- [UX] =vc-config.el:196= — clipboard clone via synchronous =call-process= freezes every emacsclient frame for the whole clone. make-process + sentinel. +- [REMOVE] =vc-config.el:80-82= — phantom autoload =git-timemachine-show-selected-revision= (no such function in the package) appears in M-x and errors. Drop from :commands. +- [REMOVE] =httpd-config.el:19-30= — pointless =:defer 1= (impatient-mode loads simple-httpd on demand) + unprefixed eager globals =wwwdir=/=check-or-create-wwwdir= creating www/ on every startup. =:defer t=, prefix, or fold into markdown-config. +- [COVERAGE] — intersect/parse unit tests hand-build matching keys (the F7 bug's escape route); =--coverage-elisp-run='s compilation-finish wiring, goto-git-gutter-diff-hunks, timemachine candidate round-trip untested. F-key sweep clean: no collisions; F5 free for the debug-backend task. -Better approach: -- for ERT in isolated mode, let ERT discover tests after loading files -- for source navigation, use syntax-aware forms where possible -- store discovered tests as structured records with file, line, name, framework, - tags, and runner +*** TODO Findings: shell/term/files group +From agents 2026-06-12; spot-verified sample (eshell nested list confirmed). Beyond the standalone tasks: +- [BUG] =dirvish-config.el:37= — =cj/xdg-open= attributed to system-utils in the require-comment but defined in external-open.el; neither dirvish-config nor dwim-shell-config (caller at :876) requires it — "Direct test load: yes" headers are false. Require external-open (or move the fn into external-open-lib) + fix comment. +- [UX] =tramp-config.el:73= — =revert-without-query '(".*")= kills revert confirmation for EVERY file in Emacs, buried in the TRAMP module. Scope to =tramp-file-name-regexp= or move deliberately to an editing module. +- [UX] =dirvish-config.el:403= — quick-access entries lx (~/archive/lectures), phl (~/projects/homelab), pn (~/projects/nextjob) point at directories that don't exist on this machine. Prune or create. +- [REMOVE] =dwim-shell-config.el:474,507= — open-externally (raw xdg-open) and open-file-manager (thunar/nautilus probe chain) duplicate cj/xdg-open (dirvish o) and cj/dirvish-open-file-manager-here (f); ascii-art references jp2a, the module's only absent binary. Delete the two duplicates; install jp2a or drop ascii-art. +- [REMOVE] =tramp-config.el:115= — custom =sshfast= method referenced nowhere (everything uses sshx); =tramp-own-remote-path= added twice (:39,:128); =dirtrack-list= and =magit-git-executable "/usr/bin/git"= are unrelated globals hiding here. Prune/relocate. +- [COVERAGE] — eshell visual-commands/xterm-color wiring and the dirvish mark-all loop had no load-and-assert tests (both standalone bugs above); TRAMP perf settings look sound for the DUET latency concern (attr caching, no remote VC, direct-async + controlmaster). -***** Path containment has at least one suspicious edge -=cj/test--do-focus-add-file= checks: +*** TODO Findings: AI group +From agents 2026-06-12; spot-verified sample (string-model setq confirmed). Beyond the standalone tasks: +- [BUG] =ai-term.el:875= — close derives the tmux session name from =default-directory=, which ghostel retargets via OSC 7; after a cd the kill-session misses (orphaned agent session) or name-collides with a different aiv- session. Derive from the buffer name's immutable basename. +- [UX] =ai-term.el:827= — multi-window F9 toggle-off unconditionally delete-windows, never restoring the displaced edge-window buffer the Commentary (:24) and reuse-edge docstring (:521) promise. Restore when quit-restore still matches, or fix the docs to describe delete-window reality. +- [UX] =ai-conversations-browser.el:191= — browser load stubs =y-or-n-p= to nil, silently discarding an unsaved in-progress conversation (the direct C-; a l path offers to save). Give ai-conversations a file-arg internal instead of puppeting the interactive command via cl-letf; also the =(caar cands)= fallback loads the newest conversation on a filename mismatch — fail loudly. +- [ENHANCE] =ai-quick-ask.el:103= — dismiss mid-stream kills the buffer without =gptel-abort= — request keeps streaming to a dead buffer (wasted tokens). +- [NOTE] =ai-mcp.el= — unreachable from init, consistent with the paused Phase 1.5; add a one-line Commentary note ("not wired until Phase 2") so future audits don't re-flag, and revisit =cj/mcp-enabled-servers= defaulting to all nine servers before wiring. +- [COVERAGE] — load/autosave lifecycle untested (fresh-session load, timer self-cancel, close-buffer session-name derivation). -#+begin_src elisp -(string-prefix-p (file-truename testdir) (file-truename filepath)) -#+end_src +*** TODO Findings: media/reading group +From agents 2026-06-12; spot-verified sample (M-S- bindings, eww store split confirmed). Beyond the standalone tasks: +- [BUG] =music-config.el:585= — =cj/music-add-dired-selection= gates =dired-get-marked-files= on =(use-region-p)= — but dired marks aren't a region; marked files are ignored, + adds only file-at-point. Drop the conditional (the function already falls back correctly). Note for the EMMS-free rewrite: dirvish + shadows =dired-create-directory= — deliberate decision needed before carrying it over. +- [UX] =media-utils.el:195-204= — =cj/yt-dl-it= watches tsp (which enqueues and exits), so "Finished downloading" fires immediately while yt-dlp may fail later, silently; also affects elfeed d. Message "queued" honestly or watch the real job (tsp -f). +- [UX] =browser-config.el:34-47,171= — first-run fallback picks EWW (first, "always available") over installed real browsers; fresh machines get org links in a text browser until cj/choose-browser runs. Prefer the first external match. +- [REMOVE] =video-audio-recording.el:442-488= — =cj/recording-group-devices-by-hardware= is dead code (nothing calls it) carrying a hardcoded "Jabra SPEAK 510 USB" branch. Delete + its test file. +- [REMOVE] =calibredb-epub-config.el:198-212= — =set-auto-mode= :around advice for .epub is redundant with nov's :mode registration (auto-mode-alist wins before magic-fallback); overhead + failure surface on every file visit. Remove and verify. +- [COVERAGE] — eww interactive commands (switch-search-engine, bookmark-quick-add, copy-url) and =cj/nov-center-images= untested. -That should use =cj/test--file-in-directory-p= or ensure the directory has a -trailing slash. Otherwise sibling paths with a shared prefix are a recurring -class of bug. +*** TODO Findings: apps/misc group +From agents 2026-06-12. Beyond the standalone tasks: +- [BUG] =hugo-config.el:49= — =cj/hugo-new-post= void-functions on =org-hugo-slug= in a fresh session (ox-hugo is :after ox, which loads on first export); =cj/hugo-export-post= already requires ox-hugo — do the same here. +- [BUG] =help-utils.el:73= — arch-wiki search signals raw file-missing when the docs dir is absent; the friendly install hint at :81 is unreachable. Guard with =file-directory-p= + user-error up front. +- [UX] =hugo-config.el:244= — eight raw global-set-key C-; h calls + hand-rolled which-key mutate cj/custom-keymap directly, against keybindings.el's own instruction. Convert to defvar-keymap + =cj/register-prefix-map= (same class as org-reveal, restclient, slack). +- [ENHANCE] =games-config.el:25= — =:defer 1= pulls malyon + 2048 into every session for nothing; use =:commands=. Also :config references =org-dir= without requiring user-constants (free-variable warning at byte-compile). +- [REMOVE] =wrap-up.el:29= — =elisp-compile-mode= doesn't exist (real mode emacs-lisp-compilation-mode derives from compilation-mode, already covered at :27); dead line. (The prior unguarded-timer fix is intact.) +- [REMOVE] =help-config.el:99-106= — stray empty :preface + dead commented Info-directory-list block. Delete. +- [NOTE] =duet-config.el= — orphaned BY DESIGN (Commentary documents pre-alpha staging; Stage 1 is the wire-in trigger). Audit record only. +- [COVERAGE] — help-config and help-utils have zero test files; the two broken paths above are exactly the untested branches. -***** Runner commands are shell strings too early -=cj/--f6-test-runner-cmd-for= returns shell command strings. That makes it -harder to: -- inspect command parts -- safely quote arguments -- offer command editing -- run via =make-process= / =compilation-start= without shell ambiguity -- attach metadata -- rerun exact invocations -- convert commands into UI labels +*** TODO Findings: holistic — startup & performance +From the 2026-06-12 holistic pass; daemon init measured at 1.11s (healthy). Beyond the standalone [#A] native-comp/GC task: +- [BUG→FOLD] the eager-org chain: =org-config.el:352= org-appear has no defer trigger (only :custom) → requires all of org at init; org-agenda (=:after org :demand t=) cascades; chime's =:demand t= pulls it anyway. org-config is the most expensive require (0.229s of 1.11s). Decide fully-eager vs fully-deferred — and =init.el:146='s "calendar-sync must come after org-agenda" contract exists only as a comment (three uncoordinated writers of =org-agenda-files=). Both facts belong in the filed defer-modules task before that refactor starts. +- [PERF] =dirvish-config.el:385-387= — =:defer 0.5= defeated by :init calling autoloaded =dirvish-override-dired-mode= → dirvish fully loads at init (0.072s, third most expensive; trace-confirmed). Own the eager load or defer the override to a dired-mode-hook shim. +- [PERF] timed =:defer N= loads unused packages into every start: simple-httpd (:1s + startup mkdir despite the defer), malyon, 2048-game, emojify (may hit network), ligature. Convert to :commands/mode hooks. +- [UX] =early-init.el:235-256= — synchronous =package-refresh-contents= on the startup path when any archive cache is >7 days old (MELPA ~6MB) — multi-second network-bound start, fires in batch too. Make async post-startup or push into the localrepo update script (distinct from the filed bootstrap-relocation task). +- [PERF] =early-init.el:228= — no =package-quickstart= with 184 packages; activation walks every package dir each start (~0.3s of early-init). Free win; regenerate after package ops. +- [PERF] =prog-general.el:298= — =yas-reload-all= immediately before =yas-global-mode= scans snippet dirs twice per start (doubled "[yas] Prepared..." message). Delete the line. +- [REMOVE] cross-ref: the all-the-icons stack (already in UI core findings) is 2 of the :demand t packages plus a per-frame install-check hook. -Prefer a structured command object: +*** TODO Findings: holistic — daemon stability +From the 2026-06-12 holistic pass. Architecture-level verdict good (timers cancelled/guarded, calendar-sync async well-contained, advice mostly named + guarded). Residual: +- [STABILITY] =transcription-config.el:293= — sentinel chain has no unwind-protect; =--append-to-log='s =insert-file-contents= signals if the log is missing → process buffer leaks, entry stuck 'running in the modeline forever, no notification. Extends the filed transcription standalone — fix together. +- [STABILITY] =calendar-sync.el:1646= — hourly timer body: fetch/parse guarded but the timezone check and =--require-calendars= run bare — any signal repeats hourly forever (the exact class fixed in four modules once). Condition-case the body; demote the hourly echo-area message to the silent log. +- [STABILITY] =music-config.el:865= — four anonymous-lambda advice in :config stack per live reload (verified: lambdas don't dedupe) and can't be advice-removed. Name the function. +- [STABILITY] =system-defaults.el:69= — =display-warning= advice appends to comp-warnings-log with no condition-case (unwritable path → every async comp warning signals from inside display-warning) and the log grows unbounded. Guard + cap. +- [STABILITY] =media-utils.el:164= — playback sentinel assumes the process buffer is alive (user killed *player:...* → sentinel error, diagnostics lost); sibling yt-dl sentinel shares the kill-buffer gap. buffer-live-p guards. +- [ENHANCE] =system-commands.el:86= — =#'ignore= sentinel + output to /dev/null makes failing lock/suspend indistinguishable from success — the user walks away from an unlocked machine. Message on nonzero exit. (Compounds the [#A] slock task: the broken lock currently fails through exactly this silent path.) +- [ENHANCE] =ui-config.el:153= — post-command cursor hook unguarded: any future signal self-removes it silently (cursor stops signaling modified/read-only until restart); frame-hook lambda also accumulates per reload. with-demoted-errors + name it. +- (kill-emacs-hook y-or-n-p prompt independently re-found here — already filed in the text/prose child; convergence noted.) -#+begin_src elisp -(:program "pytest" - :args ("tests/test_foo.py" "-q") - :default-directory "/project/" - :env (("PYTHONPATH" . "...")) - :runner pytest - :scope file) -#+end_src +*** TODO Findings: holistic — UX consistency +From the 2026-06-12 holistic pass. Verdict: more coherent than most 120-module configs (~85% prefix-helper adoption, M-S translation fully covers its 18 bindings, F-keys collision-free, DEF-arg prompts dominate). Beyond the standalone [#A] fset task: +- [BUG] notification env gate: =transcription-config.el:169-171= gates desktop notifications on =(getenv "DISPLAY")= — an X11 predicate that works only because XWayland exports it. Use =env-gui-p= (host-environment.el provides it). +- [UX] four notification stacks beyond the messenger split (notify script ± fallback, alert.el, raw notifications-notify, echo-only for calendar-sync/recording completions). Proposed: one cj/notify facade (transcription's =cj/--notify= is the right shape) — config-wide companion to the messenger-notify addendum in the unification spec. +- [UX] five more C-; entries bypass the register helpers or lack labels: =browser-config.el:182= (C-; B, no label), =org-babel-config.el:51= (C-; k, no label), =flycheck-config.el:62-64= (:bind into cj/custom-keymap), =pearl-config.el:43= (:bind-keymap C-; L, no label), =dev-fkeys.el:533= (helper but no label). Sweep onto cj/register-prefix-map with labels. +- [UX] user-error vs message inconsistent for "nothing to act on" config-wide (examples: =custom-whitespace.el:190=, =jumper.el:202=, =chrono-tools.el:99= message; =mu4e-attachments.el:112=, =ai-rewrite.el:79= user-error; =test-runner.el:392/394= mixes both 2 lines apart). Convention: user-error when the command can't proceed; message when it ran and found nothing. +- [ENHANCE] M-S translation layer: complete for GUI (18/18) but installs only on env-gui-p paths — terminal frames have no M-uppercase route; and =dwim-shell-config.el:932/934= binds M-S-d (dired) vs raw M-D (dirvish) asymmetrically. Feeds the filed M-S review task with the concrete map. +- [ENHANCE] which-key labels: register-helper's LABEL arg used by exactly 1 of 23 registrants (rest use separate with-eval-after-load blocks); label style drifts ("X menu" vs bare nouns). Adopt LABEL arg + one style. +- [ENHANCE] "?" curated-menu candidates (for the filed convention task): elfeed search/show, dirvish, signel chat/dashboard, music playlist, ai-conversations-browser, mu4e-attachments, transcription status, pearl. calibredb remains the model. +- [UX] ="(Cancel)"= pseudo-candidate in =music-config.el:253-256= vs C-g everywhere else (90+ prompts). Drop it. +- [UX] buffer-naming drifts across three conventions (*AI-Assistant* / *Kill Ring* / *dashboard*); pick Title Case + "*Name: param*", lowercase for process logs. +- [ENHANCE] C-; f formatter shadowing implemented 3 ways (:bind :map vs local-set-key in hooks); unify on :bind. Also =keybindings.el:21= commentary still says "C-c j" for the jump prefix the code binds at C-; j. +- [ENHANCE] initial-input anti-pattern at =dwim-shell-config.el:661,680= and =erc-config.el:176-177= against the config's DEF-arg norm. -Render to a shell string only at the final compilation boundary. +*** TODO Findings: holistic — package strategy +From the 2026-06-12 holistic pass (184 elpa dirs). Core stack modern (vertico/consult/embark/orderless, treesit-auto, built-in which-key, current magit/forge/telega/slack). Beyond the standalone gptel/prescient tasks: +- [REMOVE] true orphans, nothing references them: js2-mode, tide, json-mode (pre-treesit JS stack). package-delete + drop from .localrepo. +- [REMOVE] emojify: 2021 snapshot, dormant upstream, crashes in lui (slack disabled it), Emacs 30 renders emoji natively. Drop the use-package + hooks (=font-config.el:253=, =erc-config.el:211=); it stays on disk only as slack's declared dep. +- [BUG] legacy-mode hooks miss the ts modes: =prog-general.el:91-92= hooks =yaml-mode-hook=/=toml-mode-hook= but the config runs yaml-ts/toml-ts — general prog settings silently don't apply in YAML/TOML buffers. Rehook; delete toml-mode + eldoc-toml + yaml-mode packages (superseded by treesit). +- [RISK→FOLD] localrepo priority 200 is absolute, so package-upgrade silently no-ops on everything mirrored — the engine that fossilized emojify@2021/toml-mode@2016/js2@2023. The filed refresh-script task at [#D] deserves [#B] + a quarterly cadence, else every orphan finding regrows. +- [RISK] fork fleet sync-back stories: org-drill flip back to :vc when done (filed dev-checkout finding); auto-dim-other-buffers local checkout with :vc commented — decide its home; org-msg pins =:rev :newest= (unpinned moving target) — pin a known rev. signel/duet/pearl/wttrin/gloss/chime self-owned remotes are fine. +- [UPGRADE] wiki-summary (2018, dead upstream, predates Wikipedia's REST API; sole caller help-utils) — the audit's one write-your-own: ~30-line url-retrieve against the REST summary endpoint. Delete the package, inline the helper. +- [UPGRADE] xterm-color droppable in eshell on Emacs 30's native ansi-color (its only use; also doubly-broken per the eshell standalone task — fixing by deletion is an option). +- [ENHANCE] Python tier: poetry.el (sluggish) + pyvenv (2021) keep only if Poetry projects are still real; blacken fine until ruff-format (reformatter.el already installed). lsp-pyright current. +- [DECIDED] projectile, lsp-mode, dirvish: keep (wired into 10/7/many modules, maintained, migration cost > benefit). On the record so future audits don't relitigate. -***** F6 and =C-; t= workflows duplicate the same domain -F6 already handles "all tests" and "current file's tests" for multiple -languages. =C-; t= handles ERT-only focus and run state. These should converge -on one runner service: -- F6: quick entry point -- =C-; t=: full runner menu -- both call the same scope/adapter engine +*** TODO Findings: spin-off repos (pearl, chime, emacs-wttrin) +Full findings delivered as handoffs to each repo's inbox/ (2026-06-12-0057-from-.emacs.d-handoff-*.org); each repo's next session files them through its own value gate. Highlights: +- pearl (10 findings; suite green, 66 ERT files): auth-source negative-cache trap in pearl-clear-cache (the 2026-06-01 incident class, unfixed); sync wrapper ignores pearl-request-timeout + async has no timeout; mutation errors discard Linear's GraphQL reason; no RATELIMITED handling; dead legacy API layer (~150 lines). +- chime (10 findings; suite green; the 2026-06-11 watchdog handoff VERIFIED landed in full): lookahead vars never injected into the async child (documented feature silently capped at 8 days — one-line fix); days-until-event nil crash on mixed timed/all-day events; stale-callback race after watchdog interrupt (generation counter needed); default test run prints green integration banner over "Ran 0 tests". +- emacs-wttrin (10 findings; ~56 ERT files, CI; the face-flood reminder VERIFIED resolved — test 8f3c770 + fix c5e5e1d, reminder cleared from notes.org): no network timeouts (wttr.in stalls hang the loading buffer); error-path response-buffer leak; non-favorite cache never expires; 17 unreleased commits incl. two features — tag v0.4.0. -***** Test directory discovery is too narrow -Current discovery prefers =test/= then =tests/=, with a global fallback. Real -projects often need: -- Python: =tests/=, package-local =test_*.py=, =pytest.ini=, =pyproject.toml= -- JS/TS: =package.json= scripts, =vitest.config.*=, =jest.config.*=, - =*.test.ts=, =*.spec.ts= -- Go: package directories, =go.mod= -- Rust: =Cargo.toml=, integration tests under =tests/= -- Elisp packages: =Makefile=, =Eask=, =ert-runner=, Buttercup, =tests/= +** PROJECT [#B] Implement ai-kb :feature:ai:kb: +Build v1 of the AI knowledge base per [[file:docs/design/ai-kb.org][docs/design/ai-kb.org]] (Ready; six reviews incorporated, all decisions resolved 2026-05-24). Step 1 splits into 1a (the safe write path — minimum usable) and 1b (retrieval, maintenance, push), since =remember= depends on =index=+=lint= and the adapter depends on =remember=. Step 2 is the Emacs layer: a full org-roam profile on switch, the human-edit safety model (same write path as the agent), and the browsing surface. Step 3 and the LLM-Wiki layer are vNext. Children are ordered by build sequence; the server bootstrap is the prerequisite. -Discovery should be adapter-specific and project-config-aware. +*** TODO [#B] ai-kb bare repo on cjennings.net :ai-kb: +Prerequisite, one-time server bootstrap (not doable by the local script): =sudo git init --bare /var/git/ai-kb.git= + chown on cjennings.net. Leave the github-mirror hook OFF — this repo is private. Required before every per-machine clone. -***** No structured result model -=cj/test-last-results= exists but is not meaningfully populated. A powerful -runner needs a normalized result model: -- run id -- started/finished timestamps -- status: passed/failed/errored/cancelled/skipped/xfail/xpass -- command -- runner adapter -- scope -- exit code -- duration -- failed test records -- file/line locations -- raw output buffer -- coverage artifact paths +*** TODO [#B] ai-kb store + contract + seed :ai-kb: +Step 1a. Clone =git@cjennings.net:ai-kb.git= to =~/.local/share/ai-kb=. Author =AGENT_CONTRACT.org= (canonical repo-resident contract: node format, write protocol, operations, routing) and seed =index.org= + a README/index node with a generated =:ID:=. Node format per spec — a *required* one-line =:SUMMARY:= (the index/query read it straight, no inference/LLM), provenance (=:CREATED_BY:/:CONFIDENCE:/:VISIBILITY:/:SOURCE:/:STATUS:=), =:PROJECTS:= slugs, type filetags, relation labels. Define the durable external-pointer format as *ID-first*: =ai-kb: <Title> (<UUID>)=, resolved by ID with title fallback (filenames can change in curation). -This enables last-failed, failures-first, summaries, dashboards, and AI-assisted -failure explanation. +*** TODO [#B] ai-kb CLI 1a: index, lint, remember, doctor :ai-kb: +Step 1a. Shell wrapper calling Emacs for org work — =emacsclient= when a daemon is up, =emacs --batch= fallback, lint+index in *one* invocation per =remember=. =index= regenerates =index.org= from node properties incl. =:SUMMARY:= (never hand-maintained); the index references nodes as plain =Title (UUID)= text, never =[[id:]]= links, and is excluded from the scan so it can't manufacture backlinks or hide orphans. =lint= = org-lint fatal checks + duplicate IDs + broken id-links (excl =raw/= + index) + missing required props (incl =:SUMMARY:=) + bad project slugs + stale/incomplete index + credential scan of nodes *and* =raw/= text files (binaries skipped). =remember= = the write protocol: fetch + =pull --ff-only= (abort on diverge/dirty), write, regenerate index, then run the *full =ai-kb lint=* over the change as the commit gate (not just node org-lint — this is the safety boundary), commit locally, =flock=; no push. =doctor= / =status= = health + push-state + raw-dir-size report (repo, private remote, CLI on PATH, =graphviz= if the map needs it, adapter linked, db buildable, no secrets, "ahead N"/"push failed"/"diverged"); =status= is the fast non-diagnostic mode for the dashboard/nudge. -***** No failure parser / navigation layer -Compilation buffers are useful, but the runner should parse common failure -formats and provide: -- next/previous failure -- jump to source line -- failure summary buffer -- copy failure context -- rerun failed test at point -- annotate failing tests in source buffers +*** TODO [#B] claude-rules/ai-kb.md adapter :ai-kb: +Step 1a. Global L1 rule in rulesets pointing at the repo-resident =AGENT_CONTRACT.org=: path, routing (T1/T2/T3 tiers; per-project =MEMORY.md= shrinks to ID-first pointers into ai-kb), proactive + contradiction rules, concrete "read the index first" triggers, link-grep recipes, "use =ai-kb remember=, never bypass =ai-kb lint=", one-line nudge on unpushed commits / recorded push rejection. =make install= symlinks it into =~/.claude/rules/=. -Adapters can provide regexes/parsers for ERT, pytest, Jest/Vitest, Go, Rust, -and shell. +*** TODO [#B] ai-kb provisioning: setup-ai-kb.sh + make ai-kb-init :ai-kb: +Step 1a (core; the timer-install line is added with 1b). Idempotent =scripts/setup-ai-kb.sh=: clone (or init+add-remote on first machine), seed, install the CLI on PATH, =ai-kb index=, =ai-kb doctor=. =make ai-kb-init= wraps it. The one-time server bootstrap stays a separate documented step. -***** Missing watch/rerun modes -Modern test runners optimize the feedback loop: -- pytest supports selecting tests, markers, last-failed, failures-first, - stepwise, fixtures, xfail/skip, plugins, and cache state. -- Jest/Vitest support watch workflows, changed-file selection, coverage, - snapshots, and rich interactive filtering. Vitest also defaults to watch in - development and run mode in CI. -- Go and Rust runners commonly support package-level runs, regex selection, - race/coverage flags, and cached test behavior. +*** TODO [#B] ai-kb Step-1a tests :ai-kb:tests: +Write-path: a write with the remote unreachable still commits locally and does not error; =flock= serializes concurrent =remember=; each org-lint *fatal* check (malformed drawer, missing/dup =:ID:=, invalid required property, missing =#+title:=, unparseable org) rejects the commit, a style warning does not; a node missing =:SUMMARY:= fails lint; =remember= aborts the commit when the *full* lint fails (stale index, broken link, secret in a node or =raw/= text file); the credential scan skips binaries. Index: regen from a fixture produces expected entries; an out-of-band node appears only after regen; a node referenced only by =index.org= still reports as an orphan (the index is not a backlink source). Link recipes: backlink (excl =raw/= + index) + forward correct. Provisioning (bats): idempotent, valid =:ID:= + =:SUMMARY:=, =doctor= passes. -The Emacs runner should expose the subset that maps well to editor workflows: -- current test -- current file -- related test file -- focused set -- last failed -- failed first -- changed since git base -- watch current scope -- full project -- coverage for current scope +*** TODO [#B] ai-kb CLI 1b: query, curate, sync :ai-kb: +Step 1b. =query <context>= with a *testable contract*: plain-text default + =--json=; fields title/ID/summary/projects/status/updated/path + *match reason*; searches index rows + title/tags/properties/body; ranks by lexical score — sum of each matched field's weight, counted once per field: title 100, tag/project/status 50 each, summary 20, body 5; no term-frequency weighting in v1 — with most-recently-updated (=:UPDATED:=) only as the *tie-break* on equal scores (recency alone buries stable old preferences); default max-results; =raw/= paths only as source references; exit codes for no-match / invalid KB / lint-index failure. =show <id-or-title>= (resolve ID-first, print the node) and =backlinks <id>= (excl =raw/= + index) as the inspection primitives the Emacs commands wrap. =curate --dry-run= (four buckets; also flags orphan =raw/= captures and any =raw/= file over 256 KB; destructive ops human-only). =sync= (=org-roam-db-sync= against ai-kb) only when the db is missing/stale or forced. -**** Proposed Architecture -***** Core Types -Use plain plists initially; promote to =cl-defstruct= only if helpful. +*** TODO [#B] ai-kb push timer + failure observability :ai-kb: +Step 1b. =ai-kb-push.timer= + =ai-kb-push.service= =systemd --user= units: push only if ahead, ~15 min; installed + =enable --now= by the setup script (add this line to =setup-ai-kb.sh=). A failed push is logged to a state file (=$XDG_STATE_HOME/ai-kb=), never fatal; surfaced by =ai-kb doctor= and the adapter's startup nudge. -#+begin_src elisp -;; Test runner adapter -(:id pytest - :name "pytest" - :languages (python) - :detect cj/test-pytest-detect - :discover cj/test-pytest-discover - :build-command cj/test-pytest-build-command - :parse-results cj/test-pytest-parse-results - :capabilities (:current-test :file :project :last-failed :coverage :watch)) +*** TODO [#B] ai-kb-curate workflow in rulesets :ai-kb: +Step 1b. =~/code/rulesets/.ai/workflows/ai-kb-curate.org= — human-gated curation: the four buckets, node-count trigger (nudge at 150 nodes, re-fire every +50), =:LAST_CURATED:= rotation, pointer-integrity (merge/supersede changes the canonical ID, so grep inbound =[[id:]]= + =MEMORY.md= =ai-kb: ... (UUID)= refs and repoint before deleting). Surfaced by =ai-kb doctor= + session startup when due. -;; Test run request -(:project-root "/repo/" - :language python - :framework pytest - :scope file - :file "/repo/tests/test_api.py" - :test-name "test_create_user" - :extra-args ("-q") - :profile default) +*** TODO [#B] ai-kb Step-1b tests :ai-kb:tests: +=query --json= returns the specified fields (incl. match reason)/exit-codes on a fixture KB and =raw/= appears only as a source ref; a title match outranks a body-only match with recency only breaking ties (an old preference is not buried under a newer body-only hit); a simulated push failure is recorded to the state file and surfaced by =ai-kb doctor= / =status=. Performance (=:perf= tag): 100- and 1,000-node fixtures keep =index=/=query=/=lint=/=remember= under a stated time budget (catches an accidental per-check Emacs startup or an O(n²) scan). -;; Test run result -(:run-id "..." - :status failed - :exit-code 1 - :duration 2.14 - :failures (...) - :output-buffer "*test pytest*" - :artifacts (...)) -#+end_src +*** TODO [#B] Emacs: org-roam ai-kb profile + switch :ai-kb: +Step 2. +=org-roam-config.el=: =cj/org-roam-switch-to-ai-kb= / =cj/org-roam-switch-to-personal= install a full org-roam *profile*, not a two-variable swap — dir + =org-roam-ai.db= + =org-roam-file-exclude-regexp= (=raw/= + =index*.org=), and dailies, capture templates, topic/project/recipe find wrappers, and the agenda/refile + completed-task→daily hooks all rescoped or neutralized so ai-kb nodes never leak into personal journals/agenda. Restore everything exactly on exit; re-assert personal state at startup (abnormal-exit safety). =cj/ai-kb-db-sync= syncs only when the db is missing/stale or forced, with a status indicator. -***** Adapter Registry -Create a registry like: +*** TODO [#B] Emacs: ai-kb edit safety (same write path) :ai-kb: +Step 2. An =ai-kb= minor mode whose =after-save-hook= runs the agent's post-write sequence under =flock= — =ai-kb index=, full =ai-kb lint=, commit, push-state update — so a human Emacs edit can't bypass index/lint/commit. One write path for both agent and human. Failure UX: the save always writes to disk and the buffer stays editable (never read-only/blocked); on lint failure it does *not* commit, pops findings to a =*ai-kb-lint*= buffer (no focus steal), and shows the uncommitted-failing state in the modeline + dashboard — Craig fixes and re-saves, a clean save commits. Recursion guard, two layers: the mode's activation predicate excludes =index*.org= + =raw/=, and the pipeline binds a re-entrancy flag (=cj/ai-kb--in-pipeline=) the hook early-returns on; index regen prefers =write-region= over =save-buffer=. -#+begin_src elisp -(defvar cj/test-runner-adapters nil) -(cj/test-register-adapter 'pytest ...) -(cj/test-register-adapter 'ert ...) -(cj/test-register-adapter 'vitest ...) -#+end_src +*** TODO [#B] Emacs: ai-kb browsing surface :ai-kb: +Step 2. =cj/ai-kb-dashboard= (status banner: active KB, node count, unpushed commits, push-failure state, curation due, last index/sync), =cj/ai-kb-find-node= (=org-roam-node-find= in the ai-kb profile), =cj/ai-kb-search= (=ai-kb query= or scoped =consult-ripgrep=), =cj/ai-kb-show-node= (resolve ID-first, open), =cj/ai-kb-backlinks= (excl =raw/= + index), =cj/ai-kb-map= (built-in =org-roam-graph= *first* — the profile's exclude regexp already keeps =raw/= + index out of the db, so the graph inherits the right scope; custom DOT export only if project/tag/status filtering proves necessary; =graphviz= dep). Simple wrappers over the CLI primitives where possible. -Runner selection should consider: -- buffer file extension -- project files -- explicit user override -- available executables -- package manager scripts -- existing Makefile targets +*** TODO [#B] Emacs: ai-kb keybindings + which-key :ai-kb: +Bind the switch + sync + browsing commands under the =C-c n= roam prefix (e.g. =C-c n a= → ai-kb, =C-c n A= → personal, a small transient for the browsing commands), avoiding the dense existing set; which-key labels. -***** Scope Model -Make scopes explicit and shared across languages: -- =test-at-point= -- =current-file= -- =related-file= -- =focused-files= -- =last-failed= -- =changed= -- =package/module= -- =project= -- =coverage= -- =watch= +*** TODO [#B] Emacs: ai-kb Step-2 ERT tests :ai-kb:tests: +Profile: switch installs the ai-kb dir + db + exclude regexp and switch-back restores personal *exactly* — completed-task hook, agenda/refile finalize hook, dailies, and capture templates all untouched by ai-kb while switched; startup re-asserts personal state after a simulated abnormal exit. Edit path: a save in an ai-kb buffer runs index+lint+commit (a bad save surfaces the lint failure rather than committing). Sync runs only when stale. -Each adapter can say which scopes it supports. Unsupported scopes should produce -clear user-errors with suggestions. +** PROJECT [#B] Architecture review follow-up from 2026-05-03 :refactor:nosync: -***** Command Builder Pipeline -1. Detect project. -2. Detect language/framework candidates. -3. Resolve user-requested scope. -4. Build structured command object. -5. Optionally let user edit command. -6. Run via =compilation-start= or =make-process=. -7. Parse output/result artifacts. -8. Store normalized result. -9. Update UI/modeline/messages/failure buffer. +High-level pass over =init.el=, =early-init.el=, and all 104 files in +=modules/=. The main theme: the config works, but load order, startup side +effects, credentials, and test measurement are more implicit than they should +be. Use this project as the parent tracker; each child below should land as a +small, reviewable change. -***** Keep Makefile Support But Do Not Require It -For this Emacs config, =make test-file= and =make test-name= are useful and -should remain the default Elisp isolated path. But adapter detection should -support: -- direct =emacs --batch= ERT invocation -- =make test= -- =make test-file= -- =make test-name= -- Eask -- Buttercup +Review snapshot: +- =modules/= has 104 files and about 24k lines including =init.el= and + =early-init.el=. +- =init.el= eagerly =require=s nearly every module. +- =make coverage= passed when allowed to write the test scratch directory. +- Coverage report: =3240/4952= executable lines, =65.43%=, across 49 module + files. Caveat: 55 module files do not appear in the report at all, so the + real project confidence is lower than the raw percentage suggests. -**** Elisp-Specific Improvements -***** Add isolated ERT runs -Support batch commands for: -- all project tests -- one test file -- one test name -- focused files -- last failed, once result parsing exists +*** 2026-05-15 Fri Consolidate shared utility helpers :architecture:refactor: +CLOSED: [2026-05-15 Fri] -Use the same Makefile targets in this repo, but design the adapter so other -Elisp projects can run without this Makefile. +Helpers are scattered across feature modules where they were first needed. +Some are duplicated, and some private helpers are generic enough to belong in a +shared foundation library. This is adjacent to the load-graph refactor because +central helper ownership reduces hidden inter-module dependencies, but it +should remain a sibling project so load-order batches stay small and +reviewable. -***** Support Buttercup/Eask Later -Buttercup uses BDD-style =describe= / =it= suites and is common in Elisp -package testing. Eask is often used to run package tests. Add adapter slots -for these instead of hard-coding ERT forever. +Guidance: +- Do not extract a helper until at least two callers are clearly the same + shape. +- Prefer growing =system-lib.el= first; split into topic libraries only if it + becomes too broad or starts pulling coarse dependencies into foundation + startup. +- Keep one helper extraction per commit. +- Move unit tests with the helper. Consumers should keep behavior/integration + coverage. +- Do not add heavy package dependencies to foundation helpers. -***** Avoid unnecessary global ERT deletion -=cj/ert-clear-tests= is a pragmatic fix for project contamination, but the -stronger long-term answer is isolated runs plus project-scoped discovery. Keep -the cleanup command, but do not make correctness depend on deleting global ERT -state. +**** DONE [#B] Write full utility consolidation design spec :architecture:refactor: +CLOSED: [2026-05-04 Mon] -**** Python / pytest Ideas -- Detect pytest by =pyproject.toml=, =pytest.ini=, =tox.ini=, =setup.cfg=, or - presence of =tests/=. -- Build commands for: - - project: =pytest= - - file: =pytest path/to/test_file.py= - - test at point: =pytest path/to/test_file.py::test_name= - - class method: =pytest path::TestClass::test_method= - - marker: =pytest -m marker= - - last failed: =pytest --lf= - - failed first: =pytest --ff= - - stop after first: =pytest -x= - - coverage: =pytest --cov=...= -- Parse output for failing node ids and =file:line= references. -- Read pytest cache for last-failed where useful. -- Offer marker completion by parsing =pytest --markers= or config files. -- Surface xfail/skip separately from hard failures. +Create a design document that inventories candidate helper extractions, +recommends grouping and naming, explains how the helpers fit into existing +library modules, defines migration phases, and identifies testing/rollback +rules. -**** TypeScript / JavaScript Ideas -***** Detection -Detect runner by project files and scripts: -- =vitest.config.ts/js/mts/mjs= -- =jest.config.ts/js/mjs/cjs= -- =package.json= scripts: =test=, =test:watch=, =vitest=, =jest= -- lockfile/package manager: =pnpm-lock.yaml=, =yarn.lock=, =package-lock.json=, - =bun.lockb= +Spec: [[file:docs/design/utility-consolidation.org][docs/design/utility-consolidation.org]] -Prefer project scripts over raw =npx= when present: -- =pnpm test -- path= -- =npm test -- path= -- =yarn test path= -- =bun test path= +Verify 2026-05-04: +- Added [[file:docs/design/utility-consolidation.org][docs/design/utility-consolidation.org]]. +- Spec includes framing questions, existing library fit, proposed grouping, + concrete pull/rename table, migration phases, test strategy, acceptance + criteria, risks, open questions, and recommended first commits. +- Parsed the spec and =todo.org= with =org-element=. +- Committed the tracked spec as =3ea4707=. +- Incorporated complete review feedback in =dd77ebd=, including API behavior + contracts, speculative-extraction rules, =system-lib= dependency budget, + inventory/audit artifacts, test relocation policy, commit type guidance, + =use-package :if= load-order policy, and Phase 5 cache-design addendum + requirement. -***** Scopes -- current file: =vitest run path= or =jest path= -- test at point: use nearest =it= / =test= / =describe= string and pass =-t= -- watch current file -- changed tests where runner supports it -- coverage current file/project -- update snapshots +**** DONE [#B] Inventory private helpers across modules :refactor: +CLOSED: [2026-05-10 Sun] -***** Result Parsing -Parse: -- failing test names -- file paths and line numbers -- snapshot failures -- coverage summary +Walk every module and tag private helpers as genuinely module-specific, +generic-but-trapped, or duplicated. Capture likely consumers and any dependency +cost before extracting. -Treat snapshot updates as an explicit command, not an automatic side effect. +Candidate families: +- shell argument formatting, +- executable lookup with user-visible warnings, +- argv-based process runners, +- path containment/safe-base predicates, +- Org-safe heading/property/body text sanitizers, +- cache-with-TTL plus invalidation hooks, +- warning/message wrappers. -**** Go Ideas -- Detect =go.mod=. -- Current file/source: run package =go test ./pkg=. -- Test at point: nearest =func TestXxx= and run =go test ./pkg -run '^TestXxx$'=. -- Bench at point: nearest =BenchmarkXxx= and run =go test -bench '^BenchmarkXxx$'=. -- Add toggles for =-race=, =-cover=, =-count=1=, =-v=. -- Parse =file.go:line:= output and package failure summaries. +Verify 2026-05-10: +- Added [[file:docs/design/utility-inventory.org][docs/design/utility-inventory.org]] covering the 30 entries in the spec's + Candidate Extraction Table grouped by family (executable discovery, shell + quoting, process runner, file/path, external-open, Org-safe text, cache, + logging, macros/debug, theme I/O, string). +- For each helper recorded: visibility, dependencies, side effects, callers + (production + test), test files, priority, decision (Migrate / Leave / Defer) + with rationale. +- Decisions Summary: 11 Migrate, 3 Leave, 13 Defer. +- Concrete next-action list groups Migrate items by Phase (2 = foundation + helpers, 3 = Org-safe text, 4 = external-open consolidation) for the order + the spec recommends. +- Discoveries: =cj/log-silently= has 10 production callers (more than the + spec's table suggested -- defer is the right call); =cj/--file-manager-program-for= + shipped today in =dirvish-config.el= is the new form of OS-dispatch + consolidation and should fold into =cj/external-open-command= during Phase 4. -**** Rust Ideas -- Detect =Cargo.toml=. -- Use =cargo test= by default, optionally =cargo nextest run= when available. -- Current test at point: nearest =#[test]= function. -- Current file/module where possible. -- Integration test file: =cargo test --test name=. -- Support =-- --nocapture= toggle. -- Parse compiler/test failures and =file:line= links. +**** DONE [#B] Extract executable lookup with warning helper :refactor: +CLOSED: [2026-05-10 Sun] -**** Shell / Generic Ideas -- Adapter for Makefile targets: - - detect =make test=, =make check=, =make coverage= - - expose project-level commands even when language-specific detection fails -- Adapter for arbitrary project command configured in dir-locals or a project - config plist. -- Let users register custom command templates per project: +Create a generic helper such as =cj/find-executable-or-warn= from the useful +=mail-config= pattern. It should return the executable path or nil and produce +a clear warning when the executable is missing. -#+begin_src elisp -((:name "unit" - :command ("npm" "run" "test:unit" "--" "{file}")) - (:name "integration" - :command ("pytest" "tests/integration" "-q"))) -#+end_src +Done 2026-05-10: +- Shipped as =cj/executable-find-or-warn= in =modules/system-lib.el= + (commit =c75e36f4=, extracted from =mail-config=). +- First consumer rewired in =12c2cb14= (=cj/set-wallpaper= in + =dirvish-config.el=). -**** UI Ideas -***** Transient Menu -Replace or complement the raw keymap with a =transient= menu: -- scope: current test/file/focused/last failed/project -- runner: auto/ert/pytest/vitest/jest/go/cargo/make -- toggles: watch, coverage, debug, fail-fast, verbose, update snapshots -- actions: run, rerun, edit command, show failures, open report +**** DONE [#B] Extract argv-based process runner helper :refactor: +CLOSED: [2026-05-10 Sun] -***** Result Buffer -Create a normalized =*Test Results*= buffer: -- latest status per project -- command and duration -- pass/fail/skip counts -- failure list with clickable =file:line= -- actions to rerun failed/current/all -- links to coverage artifacts +Generalize the =coverage-core= process pattern into a dependency-light helper +that captures output and signals a clear =user-error= with command/status/output +on failure. Consider a small git wrapper only after the generic runner exists. -***** Modeline / Headerline Signal -Show the last run status for the current project: -- green passed -- red failed -- yellow running -- gray no run +Done 2026-05-10: +- Shipped =cj/process-output-or-error= plus the =cj/git-output-or-error= + wrapper in =modules/system-lib.el= (commit =57e558ce=, extracted from + =coverage-core=). -Keep it quiet and optional. +**** DONE [#B] Extract Org-safe text sanitizers :refactor: +CLOSED: [2026-05-10 Sun] -***** History -Store recent run requests per project: -- rerun last -- rerun last failed -- choose previous command -- compare duration/status against previous run +Move heading/property/body sanitization into a shared helper once at least one +non-calendar consumer is ready. Keep behavior explicit so external text cannot +accidentally create headings or malformed properties. -**** Configuration Ideas -- =cj/test-runner-default-scope= -- =cj/test-runner-prefer-isolated-elisp= -- =cj/test-runner-project-overrides= -- =cj/test-runner-known-adapters= -- =cj/test-runner-enable-watch= -- =cj/test-runner-result-retention= -- per-project override through =.dir-locals.el= +Done 2026-05-10: +- Shipped =modules/cj-org-text-lib.el= (renamed to its final =-lib= form in + commit =0f9e3087=) with three sanitizers: =cj/org-sanitize-body-text=, + =cj/org-sanitize-property-value=, =cj/org-sanitize-heading=. -Example: +*** 2026-05-15 Fri Make coverage reporting account for untracked modules :tests: +CLOSED: [2026-05-15 Fri] -#+begin_src elisp -((nil . ((cj/test-runner-project-overrides - . (:adapter pytest - :default-args ("-q") - :coverage-args ("--cov=src")))))) -#+end_src +The current coverage result is useful but easy to overread. =make coverage= +reported =65.43%= for files that undercover saw, but only 49 of 104 module +files appeared in =.coverage/simplecov.json=. -**** Safety And Robustness -- Use structured commands until the final boundary. -- Quote only at render time. -- Avoid shell when =make-process= / =process-file= is sufficient. -- Keep command preview/editing available for surprising cases. -- Detect missing executables before running. -- Add timeouts/cancel commands for long-running or hung tests. -- Do not silently fall back from a missing runner to a different runner unless - the fallback is visible in the command preview. -- Avoid mutating global =load-path= permanently. -- Keep remote/TRAMP behavior explicit; do not accidentally run local commands - for remote projects. +Definition: in this task, "untracked modules" means repository-owned +=modules/*.el= files that should be part of the Emacs configuration coverage +universe but have no entry in =.coverage/simplecov.json= after =make coverage= +runs. These files may be missing because no test required them, because loading +was skipped due to package/environment guards, or because instrumentation did +not see them. They are distinct from tracked modules with 0% covered lines, +which already appear in SimpleCov and can be scored directly. -**** Coverage Integration -Tie this into the existing coverage work: -- run coverage for current file/scope -- open latest coverage report -- summarize uncovered lines for current file -- support Elisp SimpleCov/Undercover, pytest-cov, Vitest coverage, Go cover, - and Rust coverage later -- store coverage artifact paths in the normalized run result +Completed 2026-05-15: +- Both child tasks are done. +- =make coverage-summary= reports missing modules explicitly and also reports a + separate project-module score where missing modules count as 0%. +- Focused summary tests and byte-compilation of the summary helper passed. -**** AI-Assisted Debugging Ideas -- Summarize failing tests from the parsed failure records and raw output. -- Include command, changed files, failure snippets, and relevant source/test - locations. -- Redact env vars, tokens, Authorization headers, and secrets before sending to - =gptel=. -- Add commands: - - =cj/test-runner-explain-failure= - - =cj/test-runner-suggest-related-tests= - - =cj/test-runner-summarize-coverage-gap= +**** 2026-05-15 Fri Teach the coverage report to list modules missing from SimpleCov +CLOSED: [2026-05-15 Fri] -**** Migration Plan -***** Phase 1: Internal cleanup -- Fix the task typo and rename current ERT-specific functions or wrap them under - an ERT adapter. -- Move F6 language detection/command construction from =dev-fkeys.el= into - =test-runner.el= or a new =test-runner-core.el=. -- Replace shell-string command builders with structured command plists. -- Fix path containment in =cj/test--do-focus-add-file=. -- Make =cj/test-last-results= real for ERT runs. +Expected outcome: +- Compare =modules/*.el= against paths present in =.coverage/simplecov.json=. +- Show a separate "not in report" section. +- Do not silently fold those files into the percentage until we decide the + semantics. A visible missing-file count is enough for v1. -***** Phase 2: ERT adapter -- Implement adapter registry. -- Add ERT adapter with in-process and isolated modes. -- Preserve all current keybindings by routing them through the adapter. -- Add failure/result normalization for ERT. -- Add "rerun last" and "rerun failed" for ERT. +Done 2026-05-15: +- =make coverage-summary= now compares direct =modules/*.el= files on disk + against the module paths present in =.coverage/simplecov.json=. +- The terminal report appends a =Not in SimpleCov report= section with a count + and the missing module paths. +- Missing modules are explicitly excluded from the displayed percentage for + now; the policy question below remains open. +- Added focused tests in =tests/test-coverage-summary.el= for missing-module + reporting and for ignoring =.elc= files and nested paths outside direct + =modules/*.el= ownership. -***** Phase 3: Python and JS/TS adapters -- Add pytest adapter. -- Add Vitest/Jest adapter with package-manager/script detection. -- Support current file and test-at-point for both. -- Add parser/navigation for common failures. +**** 2026-05-15 Fri Decide whether unreported modules count as 0% coverage +CLOSED: [2026-05-15 Fri] -***** Phase 4: UI and watch modes -- Add transient menu. -- Add result buffer. -- Add cancellation and rerun history. -- Add watch commands where supported. +This is a policy decision: +- Counting missing modules as 0% gives a more honest project-level number. +- Keeping the current number is useful for "instrumented executable lines only". -***** Phase 5: Coverage and AI -- Connect coverage commands to adapter capabilities. -- Add failure summarization with redaction. -- Add coverage-gap summarization. +Recommendation: display both: +- Instrumented coverage: current SimpleCov percentage. +- Project module coverage: includes unreported module files as 0% or reports + them separately with an explicit caveat. -**** Acceptance Criteria For First Fix-Up Pass -- Existing ERT workflow still works. -- F6 and =C-; t= use the same underlying runner API. -- Current-file test command generation is covered for Elisp, Python, Go, - TypeScript, and JavaScript. -- At least one isolated ERT command path exists. -- Path containment checks are robust against sibling-prefix paths and symlinks. -- Runner requests and results are represented as data, not only messages. -- Missing runner/tool errors are clear and actionable. -- Tests cover adapter detection, command building, scope resolution, result - storage, and key interactive paths. +Decision 2026-05-15: +- Keep the existing SimpleCov percentage as the line-weighted + =instrumented coverage= number. It only covers modules that SimpleCov saw and + has real executable-line denominators for. +- Also display a separate module-weighted =project module coverage= score over + all direct =modules/*.el= files. Modules present in SimpleCov contribute their + per-file coverage percentage; modules absent from SimpleCov count as 0%. +- Do not pretend missing modules have known executable-line counts. Counting + them as 0% at the module level is honest about risk without inventing a line + denominator. -** DOING [#B] Module-by-module hardening :harden:nosync: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-05 -:END: +Done 2026-05-15: +- =make coverage-summary= now prints both the existing line-weighted summary + and a separate =Project module coverage= line that includes missing modules + as 0%. +- The missing-module section now states that missing modules count as 0% in the + project-module score. +- Updated =tests/test-coverage-summary.el= to assert the policy and the + displayed project-module percentage. -Review every file in =modules/= and capture concrete bugs, tests, refactors, -and design improvements as child tasks. This is intentionally separate from the -top-level architecture review: the architecture project tracks cross-cutting -load/startup/test structure, while this project tracks module-specific work. +*** 2026-05-15 Fri Add a lightweight architecture smoke test for startup contracts :tests: +CLOSED: [2026-05-15 Fri] -Audit reconciliation 2026-05-27: four sessions between 2026-05-23 and -2026-05-26 drained the umbrella significantly. Roughly 24 of the original -~89 sub-task findings remain open (TODO/DOING/VERIFY) across all six tracks. -Notable shipped work since the 2026-05-22 review: user-constants -filesystem-init split, system-defaults smoke tests, env-desktop-p doc fix, -popper-config removal, UI/navigation runtime smoke coverage, mu4e -org-contacts coverage, prog-lisp smoke coverage, Org export tool guards. -The six =***= track tasks are all still DOING (track status unchanged); -the change is mass of completed sub-work, not track status. +After the above refactors start, add one or two smoke tests that protect the +architecture instead of individual functions. -Re-review pass 2026-05-15: -- Each of the six existing review tracks (foundation, custom editing, UI / - navigation, Org workflow, programming workflow, integrations and - applications) was re-walked as if it had not been reviewed before. -- 32 new sub-task findings filed across the tracks above (foundation 5, - custom editing 6, UI / navigation 9, Org workflow 3, programming 6, - integrations 2). Findings already covered by an existing sub-task were - dropped during consolidation. -- A separate =Review newly added modules= task lists the 24 modules that - were either added after the parent task was written (post-2026-04) or - fell outside the original scope lists. Each is routed to its target - track; module-specific findings are filed under the relevant track. +Candidate checks: +- All modules can be loaded directly with only =modules/= on =load-path=, or + skipped with a clear external package reason. +- No module other than =keybindings.el= binds =C-;= itself. +- Startup-only modules do not run timers in batch test mode. -Review protocol for each module: -- Read the module directly, not just the test names. -- Check runtime dependencies, top-level side effects, keybindings, timers, - external executable assumptions, secrets, host-specific paths, and user-data - writes. -- Check existing test coverage and whether tests protect the highest-risk - behavior. -- Promote larger findings into child =PROJECT= tasks with phases. Keep small - fixes as plain =TODO= tasks. +Keep this small. The goal is to catch accidental return to hidden load-order +coupling, not to build a full static analyzer. -Priority scheme: use the top-level =Priority Scheme= section in this file. +Done 2026-05-15: +- Added =tests/test-architecture-startup-contracts.el= with two source-level + smoke checks: + - only =keybindings.el= may globally own the exact =C-;= prefix; + - top-level timer scheduling forms must be guarded by =noninteractive= so + batch/test loads do not schedule startup timers. +- Gated existing startup timers in =org-agenda-config.el=, + =org-refile-config.el=, =quick-video-capture.el=, and =wrap-up.el=. +- Focused tests passed for the new architecture smoke file and the affected + agenda/refile helpers. -Suggested review order: -1. Foundation: =system-lib=, =user-constants=, =host-environment=, - =system-defaults=, =keybindings=, =config-utilities=, =early-init=, - =init=. -2. Custom editing utilities: =custom-*=, =external-open=, =media-utils=. -3. UI and navigation: =ui-*=, =font-config=, =modeline-config=, - =selection-framework=, =mousetrap-mode=, =popper-config=. -4. Org workflow: =org-*=, =calendar-sync=, =hugo-config=, =gloss-config=. -5. Programming workflow: =prog-*=, =dev-fkeys=, =test-runner=, - =coverage-*=, =vc-config=. -6. Integrations and applications: mail, Slack, ERC, Elfeed, EWW, Dirvish, - PDF, Calibre, music, recording/transcription, AI/rest tooling. +*** PROJECT [#A] Un tangle the eager =init.el= load graph :architecture:refactor: -*** DOING [#B] Harden foundation modules :harden: +=init.el= currently functions as the dependency graph by eagerly requiring +almost every module in a fixed order. That makes modules harder to test in +isolation and hides real dependencies behind "loaded earlier in init.el" +assumptions. -Scope: -- =system-lib.el= -- =user-constants.el= -- =host-environment.el= -- =system-defaults.el= -- =keybindings.el= -- =config-utilities.el= -- =early-init.el= -- =init.el= +Spec: [[file:docs/design/init-load-graph.org][docs/design/init-load-graph.org]] -Expected output: -- Add one child task for each actionable finding. -- Note "no action" only when the module has been reviewed and no task is - needed. -- Cross-reference existing architecture tasks instead of duplicating them. +**** 2026-05-25 Mon @ 07:59:20 -0500 Wrote full design spec for the =init.el= load-graph refactor :architecture:refactor: -Review progress: -- =system-lib.el=: reviewed 2026-05-03. No immediate action beyond the existing - [#B] system-lib extraction task. -- =host-environment.el=: reviewed 2026-05-03. See child tasks below. -- =user-constants.el=: reviewed 2026-05-03. See child tasks below. -- =system-defaults.el=: reviewed 2026-05-03. See child tasks below. -- =keybindings.el=: reviewed during architecture pass. No new module-specific - action beyond the load-order/keymap architecture tasks. -- =config-utilities.el=: reviewed 2026-05-03. No new module-specific action; - profiling extraction is already tracked by [#B] "Build debug-profiling.el - module". -- =early-init.el=: reviewed 2026-05-10. See child tasks below and the existing - [#B] "Split early startup from package bootstrap" task. -- =init.el=: reviewed 2026-05-10. See child tasks below and the existing - eager load-graph architecture tasks. +Create a design document that defines the target architecture, module +categories, migration phases, test strategy, acceptance criteria, and risk +controls for untangling the eager =init.el= load graph. -Completion review 2026-05-15: -- Re-read the parent =Module-by-module review and hardening= context and the - adjacent architecture follow-up so this review stays module-specific. -- Re-checked all scoped files against the review protocol. Existing child - tasks below still cover the actionable module findings for - =user-constants.el=, =host-environment.el=, =system-defaults.el=, and - =early-init.el=. -- =system-lib.el=, =keybindings.el=, =config-utilities.el=, and =init.el= do - not need additional module-specific child tasks from this pass; remaining - concerns are already tracked by the utility-consolidation, keymap - registration, debug-profiling, and eager-load-graph architecture tasks. +Review incorporation: +- Treat helper consolidation as adjacent architecture work, not a direct + acceptance criterion for the load-graph refactor. +- Mention utility extraction guardrails in the spec so Phase 2 dependency work + has a clear rule for duplicated helpers found along the way. -**** 2026-05-25 Mon @ 19:12:02 -0500 Split path constants from filesystem init in user-constants.el +Verify 2026-05-04: +- Added [[file:docs/design/init-load-graph.org][docs/design/init-load-graph.org]]. +- Incorporated review feedback by making utility consolidation an explicit + sibling project with guardrails and candidate helper families. +- Parsed the spec and =todo.org= with =org-element=. +- Committed the tracked spec as =0528475=. -=(require 'user-constants)= used to create ~8 directories and ~10 org/calendar -files at load — the source of the stray =sync/org/= tree that appeared in the -repo during test runs. Both load-time forms are gone now; the path defconsts -stay pure, and init.el calls =cj/initialize-user-directories-and-files= on real -startup (guarded by =(unless noninteractive)=) so a bare require is -side-effect-free. Verified end-to-end: a require creates nothing, and the -interactive guard creates the backbone dirs and files. Landed in two commits on -the =refactor/user-constants-defer-fs-init= branch. +**** 2026-05-24 Sun @ 17:07:03 -0500 Classified modules by role and startup requirement +Built [[file:docs/design/module-inventory.org][docs/design/module-inventory.org]] across 9 batches: 101 of 102 init.el-required modules annotated with the load-graph header contract (Layer, Category, Load shape, Eager reason, Top-level side effects, Runtime requires, Direct test load) and tabulated in the inventory. Added =tests/test-init-module-headers.el= to enforce the contract on each classified module. Retired the three vague =init.el= comments (latex-config WIP, prog-shell "combine elsewhere", "Modules In Test" banner) into real tasks. Recorded seven hidden =cj/custom-keymap= / cross-module dependencies for the Phase 2 dependency pass. Tagged the span =load-graph-classify-start..load-graph-classify-end=. elfeed-config is the one module left, pulled to its own task below. -***** 2026-05-25 Mon @ 19:12:02 -0500 Extracted pure path definitions from startup writes +**** 2026-05-25 Mon @ 08:35:33 -0500 Annotated elfeed-config load-graph header +Added the load-graph header to elfeed-config (Layer 4, O/D/P, current load shape eager with an eager reason, target command-loaded; runtime requires user-constants, system-lib, media-utils), added it to the header-contract allowlist in =tests/test-init-module-headers.el= (Batch 8), and moved it in =docs/design/module-inventory.org= from the Deferred/Pending sections into the Batch 8 table. Inventory now 102 of 102 classified. The header's "Load shape" records the current shape (eager, required in init.el) per the weather-config/games-config convention; "command-loaded" is the target, in the inventory's Target column. Shipped as a522e553. -Removed the top-level calendar =dolist= and the top-level initializer call, and -folded gcal/pcal/dcal into =cj/initialize-user-directories-and-files=. init.el -now calls it right after the require, guarded by =(unless noninteractive)=. -Added =tests/test-user-constants.el= (loading creates nothing; the initializer -creates the configured paths) and updated the module header — top-level side -effects are now none and it's safe to load in tests. +**** 2026-05-24 Sun @ 18:35:06 -0500 Made hidden module dependencies explicit +Fixed the seven hidden dependencies the classification surfaced: system-defaults now requires host-environment and user-constants at runtime (was eval-when-compile); custom-buffer-file, dev-fkeys, calendar-sync, and video-audio-recording require keybindings and drop their =(when (boundp 'cj/custom-keymap) ...)= shims; flycheck-config and mail-config require keybindings for their cj/custom-keymap bindings. Removed a dead =eval-when-compile (defvar cj/custom-keymap)= in transcription-config (the var was never used). -***** 2026-05-25 Mon @ 19:12:02 -0500 Made initialization failures actionable +No init.el load-order change — keybindings and the foundation modules already load before these, so the explicit requires are no-ops at startup and only fix standalone/test loading. -=cj/verify-or-create-dir=/=-file= took an optional =required= flag routed -through =cj/--report-path-failure=: required failures raise a prominent -=display-warning=, optional ones are logged. The initializer groups paths by -that split — required: the sync/org/roam dirs and the gcal/pcal/dcal stubs; -optional: the secondary dirs and content files. Chose a warning over a -=user-error= so a directory hiccup surfaces loudly without aborting init. Added -error-path tests for the optional-logs and required-warns behavior. +Verified each fix with a fresh =emacs --batch (require 'X)=, then swept all ~100 modules standalone: every one loads or fails only with a clear missing-package message (the spec's Phase 2 exit bar). Full =make test=, =make validate-modules=, and an init smoke all pass. Module headers and the inventory's hidden-dependency section updated to mark the seven resolved. -**** 2026-05-23 Sat @ 03:33:30 -0500 Fixed env-desktop-p doc and normalized the X predicates -Corrected =env-desktop-p='s docstring (it described a laptop; the function returns t for the desktop/no-battery case). Switched =env-x-p= from =(string= (window-system) "x")= to =(eq (window-system) 'x)= to match =env-x11-p='s style, and documented the difference: =env-x-p= is any X display incl. XWayland, =env-x11-p= is a real X11 session with no WAYLAND_DISPLAY. Behavior unchanged, existing display-predicate tests stay green. Fixed in 14ec32b2. +**** TODO [#B] Defer feature modules behind autoloads, hooks, and commands :refactor: -Left =cj/match-localtime-to-zoneinfo= caching alone — it was a "consider if this runs during startup" note, not an acceptance item, and it doesn't run at startup. File a separate task if it ever shows up in a profile. +Once dependencies are explicit, reduce the number of modules required at +startup. Start with lower-risk feature modules: +- Entertainment and optional integrations: =games-config=, =music-config=, + =weather-config=, =slack-config=, =erc-config=. +- Heavy document/media modules: =pdf-config=, =calibredb-epub-config=, + =video-audio-recording=, =transcription-config=. +- AI/rest tooling: =ai-config=, =restclient-config=, =ai-conversations=. -**** 2026-05-25 Mon @ 16:59:37 -0500 Added system-defaults settings smoke tests +Do this incrementally. After each batch: +- Restart Emacs interactively. +- Run =make test= or at least targeted tests. +- Check that keybindings still resolve and which-key labels still appear. -Added =tests/test-system-defaults.el= with three settings assertions the -existing files didn't cover: custom-file is redirected to a temp trashbin -(not the repo), backups land under =user-emacs-directory/backups=, and the -minibuffer GC hooks are wired onto the minibuffer hooks. The module's -functions were already covered by =test-system-defaults-functions.el= and the -=vc-follow-symlinks= default by its own file, so this stayed narrow to the -settings gap. Extracted the shared sandbox loader into -=tests/testutil-system-defaults.el= so both the new file and the -vc-follow-symlinks test use one copy. The backups test clears -=cj/backup-directory= first because it's a defvar that only recomputes when -unbound. +**** 2026-05-24 Sun @ 19:59:01 -0500 Centralized custom keymap registration +Added cj/register-prefix-map and cj/register-command to keybindings.el (commit 47f222f6) with test-init-keymap-registration.el, then migrated all 31 cj/custom-keymap registration sites across 24 modules onto the API. Consumers no longer reference cj/custom-keymap directly — keybindings.el is the sole owner of the prefix, and modules require keybindings to reach the API. -**** TODO [#B] Move package bootstrap policy out of =early-init.el= :startup:refactor: +Verified behavior-preserving by dumping every C-; binding before and after: identical, 279 bindings, each resolving to the same command. Byte-compiled all 24 migrated files (no new free-variable warnings — the cj/custom-keymap coupling is gone), and full make test, validate-modules, and an init load all pass. which-key label blocks were left intact; they use string key descriptions and never assumed cj/custom-keymap existed. -=early-init.el= currently handles performance/debug setup, package archive -construction, archive refresh policy, =use-package= installation, package -signature policy, and Unicode defaults. That makes early startup do network- and -package-manager-adjacent work before the regular module system exists. +Related existing task: [#B] "Review and rebind M-S- keybindings". -This overlaps with the existing [#B] "Split early startup from package -bootstrap" task; keep the implementation there if that task is already active. -This foundation review finding is the module-level acceptance detail. +*** PROJECT [#A] Move package bootstrap out of =early-init.el= where possible :startup:refactor: -Expected outcome: -- =early-init.el= keeps only settings that must happen before normal init: - startup GC/file-handler tuning, debug flag setup, native-comp workaround, - =load-prefer-newer=, site-start suppression, and package startup suppression. -- Package archive setup, refresh/install policy, and =use-package= bootstrap - live in a normal module or bootstrap helper that can be tested directly. -- Offline and missing-package states produce actionable errors without doing an - unexpected package refresh during early startup. -- Existing local repo and ELPA mirror behavior is preserved. +=early-init.el= currently handles package archives, package refresh, installing +=use-package=, and =use-package-always-ensure=. That is more than early startup +needs and can make startup network-sensitive. -Pitfalls: -- Do not break first-run bootstrap on a clean machine. -- Keep local repositories higher priority than online archives. -- Avoid prompting or refreshing archives during batch tests. +**** TODO [#B] Split early startup from package bootstrap :refactor: -**** TODO [#B] Decide and test package signature policy :security:startup: +Keep =early-init.el= focused on things that must happen before package and UI +startup: +- GC/file-name-handler startup tuning. +- =load-prefer-newer=. +- frame/UI suppression. +- minimal debug behavior. -=early-init.el= sets =package-check-signature= to =nil= after package setup, with -an earlier commented emergency toggle for expired signatures. That may be -intentional for local mirrors, but it is security-sensitive enough to make the -policy explicit. +Move package archive setup and =use-package= installation to a normal module or +bootstrap command, unless there is a specific reason it must run in +=early-init.el=. -Expected outcome: -- Document when signatures should be disabled, if ever. -- Prefer signatures on for online archives unless a local-mirror workflow - requires otherwise. -- If signatures stay disabled, add a clear comment explaining the trust model. -- Add a small test or validation helper around the computed package policy if - package bootstrap is extracted. +Acceptance criteria: +- Fresh install/bootstrap still works from a documented command or script. +- Normal startup does not refresh archives or install packages unexpectedly. +- Offline startup remains quiet and predictable. -**** 2026-05-16 Sat @ 02:34:22 -0500 Consolidated user-home-dir into early-init as canonical +**** TODO [#A] Revisit package signature policy -Canonical defconst in =early-init.el= kept (the package-archive paths -need it during package bootstrap, before normal modules load). -=modules/user-constants.el= switched to a `defvar` with the identical -=(getenv "HOME")= expression and a comment explaining the pattern: -defvar is a no-op at runtime (early-init's defconst wins, defvar -doesn't reassign a bound symbol), but it lets the module load / -byte-compile standalone when early-init hasn't run. Drift risk is -mitigated by both expressions being =(getenv "HOME")= literally; the -comment flags the requirement to keep them identical. +=package-check-signature= is disabled. Decide whether that is still necessary +for the localrepo/mirror workflow. -**** 2026-05-16 Sat @ 02:34:22 -0500 Dropped redundant autoload alongside compile-time require in system-defaults.el +Expected outcome: +- Prefer signatures on by default. +- If signatures must be disabled for local mirrors, scope that exception and + document why. +- Add a note to the local repository docs so future package failures do not + lead to permanent insecure defaults. -Kept the =eval-when-compile= requires for =host-environment= and -=user-constants= (they silence free-variable / free-function warnings -during byte-compile in isolation) and dropped the -=(autoload 'env-bsd-p ...)= line — both modules are loaded earlier in -init.el at runtime, and the eval-when-compile already exposes -=env-bsd-p= to the byte-compiler. Added a comment documenting the -chosen boundary. +** DOING [#B] Signel Client Open Work +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: +Parent task for the Emacs Signal client. Engine: signal-cli (linked secondary device). Front end: a fork of signel at =~/code/signel=, wired through =modules/signal-config.el=. Design: [[file:docs/design/signal-client.org][docs/design/signal-client.org]]. Child issues below. -**** 2026-05-16 Sat @ 02:34:22 -0500 Converted cj/debug-modules and cj/use-online-repos to defcustom +*** TODO [#C] signel--handle-error leaks request-buffer-map entries :bug:no-sync: +Surfaced during the JSON-RPC dispatch refactor audit. =signel--handle-error= reads =signel--request-buffer-map= by id but never =remhash='es the entry, so every error response leaves the request-id → buffer-name mapping behind for the life of the process. Low impact (the map clears on stop/start, and id collisions are unlikely at the counter scale), but unbounded growth in a long-lived session and inconsistent with how the new request-handler-map is cleaned up on error. -Both toggles now live as =defcustom= with explicit =:type= and -=:group 'cj=. =cj/debug-modules='s type is the natural choice form: -either =t= (all modules) or a list of module symbols. -=cj/use-online-repos='s type is boolean. Added a top-level -=(defgroup cj ...)= in early-init.el so the group exists for both, -plus the package-priority constants below it. +*** TODO [#B] Link command with QR :feature: +=cj/signel-link= wrapping =signal-cli link -n NAME=, capturing the =sgnl://linkdevice= URI and rendering it as a scannable QR (qrencode). Convenience for re-linking; the first link was done by hand this session. -**** 2026-05-25 Mon @ 18:29:40 -0500 Made the Customize-save discard non-silent +*** TODO [#D] Include Signal groups in the picker :feature:no-sync: +vNext after the 1:1 initiate-message flow is stable. Merge =listGroups= with =listContacts=, label groups distinctly, and preserve the current v1 behavior where the picker is contacts-only. -Took the display-warning option. =cj/--warn-customize-discarded= advises -=custom-save-all= (the chokepoint both =customize-save-variable= and the -Customize "Save for Future Sessions" button funnel through) with a one-shot -=:before= warning that explains the edit won't persist and points at the Elisp -init files. The advice removes itself after firing, so it warns once per -session, and the body never runs at load, so startup stays quiet. Kept the -throwaway =custom-file= as-is. Test added in =tests/test-system-defaults.el=. +*** DOING [#B] Notify only for the unviewed conversation :feature: +Wire =cj/signal--should-notify-p= (done) into signel's =signel--handle-receive= notify block (signel.el:277), route through Craig's notify script instead of bare =notifications-notify=, and gate sound behind a defcustom that defaults off. Spec addendum (the four notify details + wiring architecture) accepted 2026-06-11 — see [[file:docs/design/signal-client.org][signal-client.org]] "Notification slice". -**** 2026-05-16 Sat @ 02:34:22 -0500 Named the package archive priorities in early-init.el +Built 2026-06-11 (TDD; fork commit e263367, dotemacs 9afc6128): =signel-notify-function= customization point in the fork; =cj/signel--notify= + =cj/signal--format-notify-body= + =cj/signel-notify-sound= in signal-config.el, wired in =:config= with a load-time =cj/executable-find-or-warn=. 17 new ERT tests green; full launch smoke clean; live-reloaded into the daemon and a synthetic toast fired through the script path. Stays DOING until the two manual checks below pass. -Nine =defconst= entries replace the magic numbers: -=cj/package-priority-localrepo= (200) for the project-pinned repo, -four =cj/package-priority-mirror-*= entries for the local ELPA -mirrors (125 / 120 / 115 / 100), four =cj/package-priority-online-*= -entries for the online archives (25 / 20 / 15 / 5). A header comment -above the block explains the local-first ordering and the -gnu > nongnu > melpa > melpa-stable trust ranking within each tier. +**** Signel: real incoming message raises a toast through the notify script +What we're verifying: the full receive path (signal-cli → signel --handle-receive → cj/signel--notify → notify script) fires on a real message. +- Make sure you are NOT viewing the sender's chat buffer. +- Have a real message sent to you on Signal (or send one from your phone to a second device thread that lands here). +Expected: a transient info toast titled "Signal: <sender>" with the message text (one line, truncated if long), no sound. -**** 2026-05-16 Sat @ 02:34:22 -0500 Deleted dead world-clock block in chrono-tools.el +**** Signel: actively-viewed chat stays quiet +What we're verifying: the suppression predicate gates the toast when you're reading that chat. +- Open the sender's chat buffer (=C-; M m=) and keep it the selected window in a focused frame. +- Have the same sender message you again. +Expected: the message renders in the buffer, but no desktop toast appears. -The 19-line commented-out =use-package time= block is gone. The -=time-zones= use-package directly above it is the active replacement; -git history preserves the old config if anyone needs to dig it back up. +*** 2026-05-26 Tue @ 20:06:58 -0500 Decided: fork signel rather than depend on it +signel is on MELPA but stale (one-author v0.1, all commits in a Jan-2026 burst, unattended tracker, no PRs). The spec needs internal edits (notify behavior, input-clobber fix), which are clean in a fork and hacky via advice, and a dead upstream means no divergence cost. Rejected: adopt-from-MELPA + advice, build-from-scratch, signal-cli-rest-api (Docker), MCP-tool, ERC bridge. Full rationale in the design doc. -**** 2026-05-16 Sat @ 02:34:22 -0500 Added coverage for cj/tmr-select-sound-file with a pre-test refactor +*** 2026-05-26 Tue @ 20:06:58 -0500 Linked as secondary device; contact parser verified against live shape +Installed signal-cli 0.14.4.1 (AUR; imported AsamK's signing key FA10826A... to clear the makepkg verification). Linked the account via QR. Built and unit-tested the pure helper layer in =modules/signal-config.el= (contact-list parsing, notify-when-not-viewing predicate) with =tests/test-signal-config.el=. Confirmed the live =listContacts= shape: givenName/familyName are top-level in 0.14, not under profile as first assumed; corrected the parser and verified it produces a picker entry for all 94 real contacts. Sent a request to archsetup to add signal-cli to the standard install. -The prefix-arg branch now delegates to =cj/tmr-reset-sound-to-default= -directly (single source for the reset path). Extracted a pure helper -=cj/tmr--available-sound-files= so the directory scan is testable -without driving =completing-read=. =tests/test-chrono-tools-tmr-sound.el= -covers Normal / Boundary / Error: available-sounds against a populated -dir, empty dir, missing dir; reset path; select with prefix-arg -(delegates to reset, no prompt); select normal (picks a file); select -boundary paths for empty dir, missing dir, cancel (empty completion). -9 tests, all green. +*** 2026-05-27 Wed @ 22:08:40 -0500 Shipped initiate-message workflow: picker + Note-to-Self + keymap +=cj/signel-message= (=C-; M m=) names contacts via =completing-read= over the cj-owned =cj/signel--contact-cache=, with "Note to Self" pinned first. =cj/signel-message-self= (=C-; M s=) sends straight to =signel-account=. Daemon guard =cj/signel--ensure-started= auto-starts the daemon when =signel-account= is set and =user-error='s with the remedy when it isn't; on start it pre-warms the cache. =cj/signel--fetch-contacts= rides the new RPC callback contract (=signel--send-rpc= with success-callback), the result feeds =cj/signal--parse-contacts=, and =cj/signel-refresh-contacts= (=C-; M no leaf=) clears + refetches. Cold-cache invocations =accept-process-output= up to =cj/signel-fetch-timeout= seconds (3s default) and =user-error= on timeout so a wedged daemon can't hang Emacs. Prefix keymap =cj/signel-prefix-map= bound under =C-; M= via =keybindings.el='s =cj/custom-keymap=: m / s / d / q / SPC. 15 new ERT tests in =tests/test-signal-config.el= cover ensure-started branches, fetch contract, cache empty-vs-failure, refresh, picker happy-path + cold-cache resolves + cold-cache timeout, message-self, and the prefix map bindings. -*** DOING [#B] Harden custom editing utility modules :harden: +*** 2026-05-27 Wed @ 21:55:57 -0500 Added JSON-RPC success-result dispatch in the signel fork +Fork commit 4740d97 added =signel--request-handler-map= (id → success callback), extended =signel--send-rpc= with an optional =success-callback= that registers under the new request id, and gave =signel--dispatch= a result branch that invokes the callback and removes the handler. Error responses also remhash the handler entry, and =signel-start= / =signel-stop= both =clrhash= the map so reconnect is reliably empty. Backward-compatible: existing callers that don't pass a callback hit the same code path as before. Five ERT tests in this project (=tests/test-signel-rpc-dispatch.el=, dotemacs commit bfec0eab) lock the contract: Normal (result invokes callback + cleanup, send-rpc registers), Boundary (unknown id is a no-op), Error (error response cleans up handler), reconnect (=signel-stop= empties the map). Refactor audit surfaced a separate pre-existing leak in =signel--handle-error= (request-buffer-map entries aren't removed on error); filed as the [#C] follow-up below. -Scope: -- =custom-buffer-file.el= -- =custom-case.el= -- =custom-comments.el= -- =custom-datetime.el= -- =custom-line-paragraph.el= -- =custom-misc.el= -- =custom-ordering.el= -- =custom-text-enclose.el= -- =custom-whitespace.el= -- =external-open.el= -- =media-utils.el= +*** 2026-05-27 Wed @ 22:08:40 -0500 Shipped clobber fix for both insert paths +Fork commit 5ec56c0 added =signel--pending-input= (capture from input-marker to point-max) and =signel--restore-input= (re-insert after the redrawn prompt; nil-safe), and wired both into =signel--insert-msg= (the receive path) and =signel--insert-system-msg= (the error path). A mid-type send now survives both an incoming message and a system-error insertion. Four ERT tests in =tests/test-signel-input-preservation.el= cover the helpers (typed text, empty) and both insert paths via a temp =signel-chat-mode= buffer. -Review progress: -- Core =custom-*= text modules reviewed 2026-05-03. They have unusually strong - direct ERT coverage compared with the rest of the config. -- =external-open.el= and =media-utils.el= reviewed 2026-05-03. See child tasks. -- =custom-buffer-file.el= reviewed 2026-05-03. See child tasks. +*** 2026-05-27 Wed @ 22:08:40 -0500 use-package wired with C-; M keymap and local account config +=use-package signel :load-path "~/code/signel" :ensure nil= already wired earlier with =signel-auto-open-buffer nil=. Account source is =signel-account= set from =cj/signal-private-config-file= (=signal-config.local.el=, gitignored) loaded in =:config=, decided in the workflow spec. Keymap prefix =C-; M= attached via =with-eval-after-load 'keybindings= so the binding survives load-order. -Completion review 2026-05-15: -- Re-checked the scoped custom editing utility modules and their test files. -- The pure editing modules remain well covered by focused ERT tests. -- Remaining actionable issues are already logged below: process-launch - hardening and coverage for =external-open.el= / =media-utils.el=, - destructive buffer/file keybinding policy, and explicit cross-module - autoload/require boundaries. +*** 2026-06-06 Sat @ 12:29:24 -0500 Fixed C-; M load-order bug via canonical register-prefix-map +Root cause: signal-config.el was the only feature module that violated the prefix-registration contract documented in =keybindings.el:41-45=. Every other prefix map uses =(require 'keybindings)= + a top-level =(cj/register-prefix-map "X" map)=; signal-config had neither, mutating =cj/custom-keymap= directly through a =(with-eval-after-load 'keybindings (when (boundp 'cj/custom-keymap) ...))= form. The =boundp= guard turned a load-order miss into a SILENT no-op — no error, the binding just never happened — which is why a live-reload (keybindings definitely loaded by then) papered over it. +Fix: added =(require 'keybindings)= at the top of signal-config.el and replaced the guarded form with =(cj/register-prefix-map "M" cj/signel-prefix-map "signal messages")=, matching the 25+ other prefix maps. +Verified: (1) new contract test =test-signal-config-prefix-map-registered-under-c-semi-m= asserts =C-; M= resolves to =cj/signel-prefix-map= (35/35 green); (2) full =emacs --batch= init.el launch — the exact failing scenario — now shows =C-; M= bound; (3) clean byte-compile; (4) live-reloaded into the daemon, binding confirmed. No unit-level red was possible: the =boundp= guard is robust under all standard test timings, which is the CLAUDE.md launch-only-failure class. -**** TODO [#B] Harden external process launching in =external-open.el= and =media-utils.el= :security:refactor: +*** 2026-05-28 Thu @ 03:09:18 -0500 Chat buffer docks bottom 30% and C-c C-k cancels +=display-buffer-alist= entry in =modules/signal-config.el= matches =^\*Signel: = chat buffers and routes them through =display-buffer-at-bottom= with =window-height . 0.3=, so the chat docks to the bottom 30% of the frame. The signel fork's =signel-chat= switched from =switch-to-buffer= to =pop-to-buffer= so the rule can apply (=switch-to-buffer= ignores =display-buffer-alist=). =C-c C-c= was already bound to =signel--send-input= in the mode; =C-c C-k= now binds =signel--cancel-input=, a new fork helper that clears the editable region between =signel--input-marker= and =point-max= and then calls =quit-window=. Buffer stays alive so chat history above the marker survives revisits; cleared input means the next visit lands on a fresh prompt. Five ERT tests in =tests/test-signel-cancel-input.el= (clears pending, empty-area no-op, quit-window called, buffer preserved, keymap binding) and two new tests in =tests/test-signal-config.el= (entry shape + regex match set). Dotemacs commit 998e9c7a, fork commit df02d79. -=external-open.el= and =media-utils.el= use shell command strings for launching -external applications: -- =cj/open-this-file-with= interpolates the user-supplied command into - =call-process-shell-command=. -- =cj/media-play-it= builds a shell command for players and optional =yt-dlp= - stream extraction. +** DOING [#B] Migrate All Terminals From Vterm to Ghostel :terminal:ghostel: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-04 +:END: +Replace vterm with ghostel (libghostty-vt) as the single terminal engine across every workflow, and rename ai-vterm → ai-term. References: [[file:docs/2026-05-25-emacs-terminal-comparison.org][docs/2026-05-25-emacs-terminal-comparison.org]] (vterm vs eat vs ghostel research); migration spec [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] (READY; external review incorporated 2026-06-04, D1-D7 agreed). Build in 5 phases (0-4); see the spec's Implementation tasks block. -This is mostly controlled local input, but it is still brittle: command paths -with spaces can fail, arguments are hard to reason about, and future URL/source -changes could create shell quoting bugs. +Decisions D1-D7 are settled in the spec's Agreed-decisions section. Build order below; each phase stays green (suite + byte-compile) at every step. -Expected outcome: -- Prefer =start-process= / =call-process= with argv lists where possible. -- If shell is required for command substitution, isolate and quote every - untrusted value. -- Add tests around command construction for: - - file paths with spaces and shell metacharacters, - - URL strings with shell metacharacters, - - configured player args, - - missing executable errors. +*** TODO [#B] Phase 2: rename ai-vterm→ai-term on ghostel :terminal:ghostel: +Swap the 6 vterm call sites; F9 family on global + ghostel-mode-map; drop refuse-in-terminal guard (D4); preserve the tmux-suppression invariant. Rename engine-agnostic tests after green; rework coupled tests; add D4 + F12-excludes-agent regression tests. -Pitfalls: -- =cj/open-this-file-with= may intentionally accept "program plus args". If so, - split the command deliberately or introduce separate program/args prompts. -- Some media players need different URL handling; preserve the existing - =:needs-stream-url= behavior. +*** TODO [#B] Follow-up: theme ghostel ANSI faces in dupre :terminal:ghostel:dupre: +D2 — set the 16 ghostel-color-* + ghostel-default faces in dupre-faces/palette. -**** 2026-05-23 Sat @ 03:41:00 -0500 Added media-utils coverage; external-open already covered -=external-open= already had three test files (=test-external-open-commands.el=, =test-external-open-lib-command.el=, =test-external-open-lib-launcher-p.el=). =media-utils.el= had none, so I added =test-media-utils.el= (8 cases): player availability from =cj/media-players=, the play command-builder (direct vs yt-dlp -g stream wrap), and the missing-tool error paths for the player, =yt-dlp=, and =tsp=. All process/exec boundaries mocked. Added in the test-media-utils commit. +*** TODO [#B] Follow-up: evaluate ghostel-eshell + ghostel-compile :terminal:ghostel:eval: +D3 — ghostel-eshell as eshell visual backend; ghostel-compile against F4 dev-fkeys. -**** TODO [#B] Audit destructive buffer/file keybindings for confirmation policy :ux: +*** TODO [#B] Investigate ghostel selection/highlight color :terminal:ghostel: +Look at how selected text is highlighted in a ghostel buffer — the region face in =ghostel-copy-mode= and any live selection — surfaced during the copy-mode debugging. Check whether the highlight is legible against the dupre background and consistent with the rest of the config; if it needs theming, fold it in with D2 (theming the ghostel faces in dupre). -=cj/buffer-and-file-map= includes destructive operations under =C-; b=, -including delete file, erase buffer, clear top, clear bottom, and revert. Some -are intentionally fast, but this module is high blast radius. +*** 2026-06-04 Thu @ 23:57:09 -0500 Phase 0 done: characterization baseline green +=make test= green except the 5 documented pre-existing failures (4 test-dupre-theme, 1 test-init-module-headers), none terminal-related. Characterization coverage already present + green for all six must-survive behaviors: vterm-toggle--dispatch/display/buffer-filter, vterm-tmux-history, ai-vterm--show-or-create/launch-command/f9-in-vterm, ui-config--buffer-cursor-state + vterm-copy-mode-cursor, dashboard-config-launchers. Add a characterization test before any behavior change in later phases if a gap appears. -Expected outcome: -- Decide which operations need confirmation when the buffer is modified or - visiting a file. -- At minimum, document the intended policy in =custom-buffer-file.el=. -- Consider safer wrappers for =erase-buffer= and =revert-buffer= under the - personal keymap. +*** 2026-06-05 Fri @ 00:38:34 -0500 Phase 1 done: ghostel + term-config.el +=modules/term-config.el= written (full port of vterm-config: tmux history/copy-mode-dwim preserved via process-tty-name + ghostel-send-string; F12 toggle + display rule + geometry; cj/term-map C-; x menu → ghostel commands; which-key "terminal menu"; ghostel-max-scrollback 10MB; C-; added to ghostel-keymap-exceptions; F12 + C-; in ghostel-mode-map; use-package ghostel guarded per D6). Dropped: mouse-wheel SGR forwarding, vterm-timer-delay hacks, copy-mode cursor hook, goto-address hook. ghostel installed into elpa (MELPA + auto-downloaded native module). Tests: test-term-toggle--{dispatch,display,buffer-filter} + test-term-tmux-history (16) ported with a ghostel stub in testutil-ghostel-buffers; all green. -**** 2026-05-24 Sun @ 14:43:13 -0500 Declared cross-module commands bound in custom keymaps +*** 2026-06-05 Fri @ 00:38:34 -0500 Phase 2 done: ai-vterm→ai-term on ghostel +=modules/ai-vterm.el= → =modules/ai-term.el=: 6 vterm call sites swapped to ghostel (buffer named via let-bound ghostel-buffer-name + pinned ghostel-buffer-name-function so OSC titles don't rename agent buffers); F9/C-F9/M-F9 on global + ghostel-mode-map; refuse-in-terminal guard removed (D4 — F9 launches in TTY frames); tmux-suppression invariant preserved (cj/--ai-term-suppress-tmux). 23 ai-vterm tests renamed → test-ai-term--* (terminal-guard test deleted, obsolete); show-or-create + f9-in-term rewritten for ghostel; all green. ui-config cursor-state ported (ghostel-mode + ghostel--input-mode; copy/emacs = read-only, else writeable) + its test. init.el now requires term-config + ai-term; vterm-config.el + ai-vterm.el deleted. Full suite green except the 5 documented pre-existing failures (4 dupre-theme, 1 init-module-headers/popper-config-missing — both unrelated). validate-modules ✓; full early-init+init smoke clean (no ghostel/term/ai-term errors). vterm package still installed (Phase 4) — dashboard "Launch VTerm" + dormant auto-dim still reference it until Phase 3/4. Restart Emacs to pick up ghostel (load-order + use-package :config change). -Byte-compiling =custom-ordering.el= and =custom-text-enclose.el= standalone warned "not known to be defined" for =cj/org-sort-by-todo-and-priority= (owned by org-config) and =change-inner=/=change-outer= (the change-inner package). Both work at runtime — org-config loads eagerly, and text-config autoloads change-inner via =use-package :commands= — so only the compiler needed telling; added =declare-function= for each (no autoload needed since the runtime autoload/eager-load already exists). =custom-buffer-file.el= byte-compiles clean already, so it needed no change. Commit =ad173a77=. +*** 2026-06-05 Fri @ 00:50:58 -0500 Phase 3 done: satellites ported to ghostel +Deleted auto-dim's vterm color-advice + redraw integration (~165 lines; D1 — terminals don't dim, ghostel bakes its palette per-terminal so there's no per-window color hook); dashboard launcher → =(ghostel)= + "Launch Terminal" label; cj-window-geometry/toggle-lib doc comments; module-inventory + init-load-graph doc refs. (ui-config cursor-state + init.el requires landed in Phase 2.) Trimmed test-auto-dim-config (dropped the 6 vterm tests) + updated the dashboard-launcher test stub. Incidental: removed the stale =popper-config= entry from the test-init-module-headers allowlist (the file doesn't exist + isn't required) — fixes the long-standing pre-existing test failure. -**** 2026-05-24 Sun @ 07:26:31 -0500 Extracted shared region-or-buffer bounds helper +*** 2026-06-05 Fri @ 00:50:58 -0500 Phase 4 done: vterm + vterm-toggle removed +=package-delete='d vterm + vterm-toggle from elpa. No vterm refs remain in modules/init except intentional historical comments. Suite green except the 4 pre-existing dupre-theme failures (the popper-config one is now fixed). validate-modules ✓; full early-init+init batch smoke = INIT-SMOKE-OK. The migration parent stays DOING until Craig restarts Emacs and walks the ghostel manual-verify matrix under "Emacs Manual Testing and Validation". -The described docstring mismatch was already resolved: =custom-ordering.el='s =cj/--arrayify=/=cj/--unarrayify= now document an explicit =(start end)= contract accurately and are region-required by design. The remaining work was the enclose side, where append/prepend/indent/dedent each inlined the same region-or-buffer bounds block (four copies). Extracted =cj/--region-or-buffer-bounds= as the single source of that contract and routed all four through it (behavior unchanged; public-wrapper tests still pass). Each pair now has one clear, consistent, documented contract. New tests cover the helper (region / no-region / empty buffer). Commit =a7cc8948=. +*** 2026-06-05 Fri @ 14:24:02 -0500 Auto-dim revisit cancelled — current no-dim behavior is fine +Craig confirmed the shipped auto-dim setup works fine as-is: terminal buffers don't participate in unfocused-window dimming (D1), and the rest of auto-dim behaves. That is the measured decision the original task asked for — option (a), keep no-dim — so no rework (the focus-loss palette-blend in option (b) or an upstream per-window hook in option (c)) is needed. Closing without further investigation. Context: [[file:docs/design/vterm-to-ghostel-migration-spec.org][migration spec]] D1. -**** 2026-05-16 Sat @ 02:47:15 -0500 Preserved trailing newlines in custom-ordering output +*** 2026-05-26 Tue @ 15:15:43 -0500 Direction confirmed; Claude Code in eat needs a caveat +Craig confirmed the consolidation: one terminal engine everywhere — eat for standalone terminal buffers (replacing vterm) plus =eat-eshell-mode= as eshell's visual backend, keeping eshell as the shell. Not dropping eshell for eat + zsh. -Both =cj/--arrayify= and =cj/--unarrayify= now detect a trailing -newline on the input region (via =string-suffix-p=) and re-append it -to the result. Matches the pattern =custom-text-enclose.el= already -uses. Docstrings updated to document the contract. +Researched whether Claude Code runs cleanly in eat (Craig runs it in his Emacs terminal). Verdict: mostly, with caveats. eat is the default backend for claude-code.el and renders the TUI with color and full key handling, but there is an eat-specific bug where Claude Code's input handling makes the buffer scroll-pop to the top on window-buffer changes and the input box can get stuck mid-buffer (recoverable, but it does not happen in vterm or ghostel), and eat runs about 1.5x slower than vterm on heavy streaming output. claude-code.el's own docs name ghostel as the most faithful Claude TUI renderer. -**** 2026-05-16 Sat @ 02:47:15 -0500 Guarded cj/duplicate-line-or-region against modes without comment syntax +Recommendation: consolidate everyday terminals onto eat, but keep ghostel (or vterm) for the Claude Code workflow specifically — the scroll-pop / stuck-input bug and the slower heavy-stream handling are exactly what bites a long Claude session. Sources: [[https://github.com/cpoile/claudemacs][claudemacs]], [[https://github.com/stevemolitor/claude-code.el][claude-code.el]], [[https://codeberg.org/akib/emacs-eat][emacs-eat]]. -=cj/duplicate-line-or-region= now signals a clear =user-error= when -=COMMENT= is non-nil but the current mode has no =comment-start= -(=fundamental-mode= and similar). Docstring updated to document the -error. Picks the "error out clearly" branch from the task body -- -restricting the binding per-mode would be a larger refactor that -isn't justified for the silent-malformed-output blast radius. +Eval plan (from the research doc): install EAT alongside vterm, run the same workloads through both, decide. Test matrix: Claude Code TUI, lazygit, htop/btop, yazi, a heavy-output build, ssh to a remote, and eshell with =eat-eshell-mode=. Assess rendering fidelity, stability under heavy output, and Emacs-native line editing. Switch only if it covers every workflow without regression. -**** 2026-05-16 Sat @ 02:47:15 -0500 Made external-open advice install explicit via cj/external-open-install-advice +*** 2026-06-02 Tue @ 14:12:48 -0500 Audit: eval plan not yet run; back to TODO +Task audit found no eval work recorded since the 2026-05-26 direction-confirmed note. The test matrix above is unrun, so the task isn't actively in progress — moved DOING back to TODO until the eval starts. -Factored the =advice-remove= / =advice-add= pair into -=cj/external-open-install-advice= and called it once at the bottom -of the module. Same idempotent shape (remove-then-add) but now the -intent is named. Re-running the module updates the advice rather -than stacking it; if a future caller wants to opt out, they can -=advice-remove= the helper or skip calling it altogether. +*** 2026-06-04 Thu @ 22:40:27 -0500 Pivot: ghostel as the single engine (not eat) +Direction changed from eat-everyday + ghostel-for-Claude to ghostel-for-everything, and the task is now a migration rather than an eval. Rationale: ghostel is claude-code.el's most-faithful Claude TUI renderer and the fastest engine (81 vs vterm 34 vs eat 4.9 MB/s), and an audit confirmed it exposes an analog for every vterm primitive this config uses (=ghostel-send-string=, =ghostel-keymap-exceptions=, =ghostel-copy-mode=, =ghostel-clear-scrollback=, =ghostel-send-next-key=, =ghostel-next-prompt= / =ghostel-previous-prompt=, =ghostel-max-scrollback=, =ghostel-kill-buffer-on-exit=). eat's washed colors, the scroll-pop / stuck-input bug under Claude Code, and slowest throughput made it the weaker single-engine pick; one engine beats running two. Surface audited: 2 main modules (=vterm-config.el=, =ai-vterm.el=) + 4 satellites (=auto-dim-config.el= is the heavy one) + ~35 test files + init.el. Next: spike ghostel read-only to answer the open migration questions (auto-dim rework — ARCHITECTURE.md forbids the around-redraw color advice vterm uses; tmux pane-id via =process-tty-name= on a ghostel process; buffer naming; TTY-frame behavior; copy-mode keybinding parity), then write the migration spec under =docs/design/= and review it. -**** 2026-05-16 Sat @ 02:47:15 -0500 Added cj/--validate-decoration-char across all six divider/border helpers +*** 2026-06-04 Thu @ 23:17:54 -0500 Spec review: not ready until decisions and handoff shape are closed +Ran the spec-review workflow against [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] and wrote a companion review file (incorporated and deleted 2026-06-04). Verdict: =Not ready=. Direction is sound, but the draft still has open D1-D5 decisions, lacks the workflow-required =Implementation phases= section and acceptance criteria, and needs explicit ghostel package/native-module failure behavior before implementation tasks can be emitted. -New top-level validator =cj/--validate-decoration-char= rejects -anything that isn't a printable single-character string and signals -=user-error=. Wired into all six internal helpers: -=cj/--comment-inline-border=, =cj/--comment-simple-divider=, -=cj/--comment-padded-divider=, =cj/--comment-box=, -=cj/--comment-heavy-box=, =cj/--comment-block-banner=. The five -nil-decoration ERT tests updated from =:type 'wrong-type-argument= -(the old crash signal from =string-to-char= on nil) to -=:type 'user-error=, since the guard now produces a clear message -instead of a deep crash. +*** 2026-06-04 Thu @ 23:24:28 -0500 Spec-response: review incorporated, raised to READY +Folded the external review via spec-response. Craig accepted D1-D5; baked them plus D6 (module-failure = degrade-with-warning, modifying the reviewer's fail-loud) and D7 (=ghostel-max-scrollback= 10 MB) into a new Agreed-decisions section. Added Implementation phases (0-4), Acceptance criteria, Dependency/module-failure behavior, Test strategy, per-phase key/menu ownership, the tmux-suppression contract, and an Implementation-tasks drop-in block. Status DRAFT → READY; review file deleted. Build is now unblocked. -**** 2026-05-23 Sat @ 03:38:30 -0500 Filled the remaining title-case edge gaps -=test-custom-case-title-case-region.el= already had 29 cases (empty region, unicode words, numbers, separators, colon resets, partial region). The named gaps that were missing — leading-quote and leading-paren handling, plus a caseless RTL first word — are now covered by three boundary tests (32 total). Added in 3841c59e. +*** 2026-06-04 Thu @ 23:30:18 -0500 External re-review: ready +Re-reviewed [[file:docs/design/vterm-to-ghostel-migration-spec.org][docs/design/vterm-to-ghostel-migration-spec.org]] after incorporation. Verdict: =Ready=. No further blocking review notes; implementation can start from the phase plan and acceptance criteria in the spec. -**** 2026-05-16 Sat @ 02:47:15 -0500 Extracted cj/--require-spell-checker +** DOING [#B] Module-by-module hardening :harden:nosync: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: -Both =cj/flyspell-toggle= and =cj/flyspell-then-abbrev= now call -=cj/--require-spell-checker= instead of carrying their own copy of -the executable-find check. The checker list lives in the new -defconst =cj/--spell-checker-executables=, so adding nuspell (or any -other checker) is a one-line edit. Top-level =(require 'cl-lib)= -added since the new helper uses =cl-some=. +Review every file in =modules/= and capture concrete bugs, tests, refactors, +and design improvements as child tasks. This is intentionally separate from the +top-level architecture review: the architecture project tracks cross-cutting +load/startup/test structure, while this project tracks module-specific work. -**** 2026-05-23 Sat @ 03:44:50 -0500 Covered flyspell-and-abbrev testable seams -Added =test-flyspell-and-abbrev.el= (8 cases): =cj/--require-spell-checker= (PATH gate, mocked), =cj/find-previous-flyspell-overlay= against synthetic overlays (closest-previous match, non-flyspell skipped, nil when none), and =cj/flyspell-on-for-buffer-type= (prog-mode -> flyspell-prog-mode, text-mode -> flyspell-mode). Left =cj/flyspell-then-abbrev= to manual testing — pinning its flyspell-UI orchestration would mean mocking flyspell internals rather than our logic. Added in the test-flyspell-abbrev commit. +Audit reconciliation 2026-05-27: four sessions between 2026-05-23 and +2026-05-26 drained the umbrella significantly. Roughly 24 of the original +~89 sub-task findings remain open (TODO/DOING/VERIFY) across all six tracks. +Notable shipped work since the 2026-05-22 review: user-constants +filesystem-init split, system-defaults smoke tests, env-desktop-p doc fix, +popper-config removal, UI/navigation runtime smoke coverage, mu4e +org-contacts coverage, prog-lisp smoke coverage, Org export tool guards. +The six =***= track tasks are all still DOING (track status unchanged); +the change is mass of completed sub-work, not track status. -*** DOING [#B] Harden UI and navigation modules :harden: +Re-review pass 2026-05-15: +- Each of the six existing review tracks (foundation, custom editing, UI / + navigation, Org workflow, programming workflow, integrations and + applications) was re-walked as if it had not been reviewed before. +- 32 new sub-task findings filed across the tracks above (foundation 5, + custom editing 6, UI / navigation 9, Org workflow 3, programming 6, + integrations 2). Findings already covered by an existing sub-task were + dropped during consolidation. +- A separate =Review newly added modules= task lists the 24 modules that + were either added after the parent task was written (post-2026-04) or + fell outside the original scope lists. Each is routed to its target + track; module-specific findings are filed under the relevant track. -Scope: -- =ui-config.el= -- =ui-navigation.el= -- =ui-theme.el= -- =font-config.el= -- =modeline-config.el= -- =selection-framework.el= -- =mousetrap-mode.el= -- =popper-config.el= +Review protocol for each module: +- Read the module directly, not just the test names. +- Check runtime dependencies, top-level side effects, keybindings, timers, + external executable assumptions, secrets, host-specific paths, and user-data + writes. +- Check existing test coverage and whether tests protect the highest-risk + behavior. +- Promote larger findings into child =PROJECT= tasks with phases. Keep small + fixes as plain =TODO= tasks. -Review progress: -- Reviewed 2026-05-03. -- =mousetrap-mode.el= has strong focused and integration tests. -- =modeline-config.el= has pure string-helper coverage, but not VC/runtime - segment behavior. -- =font-config.el=, =ui-theme.el=, =selection-framework.el=, =ui-navigation.el=, - and =popper-config.el= have little direct test coverage. +Priority scheme: use the top-level =Priority Scheme= section in this file. -Completion review 2026-05-15: -- Re-checked the scoped UI/navigation modules and current tests. -- =mousetrap-mode.el=, =ui-navigation.el=, =ui-theme.el=, - =selection-framework.el=, and selected modeline/UI helpers now have focused - tests, but the font/modeline/popper runtime policy remains under-tested. -- Existing cleanup below covers the disabled =popper-config.el= load-graph - issue; added a separate test-gap task for the remaining UI smoke coverage. +Suggested review order: +1. Foundation: =system-lib=, =user-constants=, =host-environment=, + =system-defaults=, =keybindings=, =config-utilities=, =early-init=, + =init=. +2. Custom editing utilities: =custom-*=, =external-open=, =media-utils=. +3. UI and navigation: =ui-*=, =font-config=, =modeline-config=, + =selection-framework=, =mousetrap-mode=, =popper-config=. +4. Org workflow: =org-*=, =calendar-sync=, =hugo-config=, =gloss-config=. +5. Programming workflow: =prog-*=, =dev-fkeys=, =test-runner=, + =coverage-*=, =vc-config=. +6. Integrations and applications: mail, Slack, ERC, Elfeed, EWW, Dirvish, + PDF, Calibre, music, recording/transcription, AI/rest tooling. -**** 2026-05-25 Mon @ 17:05:00 -0500 Added UI/navigation runtime smoke coverage +*** DOING [#B] Harden foundation modules :harden: -Added =tests/test-font-config.el= (4 tests): cj/font-installed-p returns t/nil -off find-font, and cj/apply-font-settings-to-frame is a no-op on a non-GUI -frame and applies the preset exactly once per frame (idempotent). find-font, -env-gui-p, and fontaine-set-preset are stubbed so the run stays headless, and -a skip-unless on the demanded packages keeps a bare checkout green. -font-config had zero direct coverage; this fills the gap the task named. +Scope: +- =system-lib.el= +- =user-constants.el= +- =host-environment.el= +- =system-defaults.el= +- =keybindings.el= +- =config-utilities.el= +- =early-init.el= +- =init.el= -modeline-config was already well covered (string-cut-middle, string-truncate-p, -vc-cache, vc-cache-key, the flycheck segment, the recording indicator), so it -needed no net-new smoke tests. popper-config's no-op smoke test is gated on the -"Decide whether popper-config.el should exist while disabled" task and was -deferred there, since whether to write it depends on that keep/remove call. +Expected output: +- Add one child task for each actionable finding. +- Note "no action" only when the module has been reviewed and no task is + needed. +- Cross-reference existing architecture tasks instead of duplicating them. -Original scope: -- =font-config.el=: font fallback/daemon frame setup does not error when - optional fonts or emoji packages are absent. -- =modeline-config.el=: runtime segment assembly handles missing VC/project - data and does not signal in non-file buffers. -- =popper-config.el=: if the module remains in =init.el= while disabled, a - smoke test should prove requiring it is an intentional no-op. +Review progress: +- =system-lib.el=: reviewed 2026-05-03. No immediate action beyond the existing + [#B] system-lib extraction task. +- =host-environment.el=: reviewed 2026-05-03. See child tasks below. +- =user-constants.el=: reviewed 2026-05-03. See child tasks below. +- =system-defaults.el=: reviewed 2026-05-03. See child tasks below. +- =keybindings.el=: reviewed during architecture pass. No new module-specific + action beyond the load-order/keymap architecture tasks. +- =config-utilities.el=: reviewed 2026-05-03. No new module-specific action; + profiling extraction is already tracked by [#B] "Build debug-profiling.el + module". +- =early-init.el=: reviewed 2026-05-10. See child tasks below and the existing + [#B] "Split early startup from package bootstrap" task. +- =init.el=: reviewed 2026-05-10. See child tasks below and the existing + eager load-graph architecture tasks. -**** 2026-05-26 Tue @ 17:33:28 -0500 Removed popper-config.el (disabled no-op) -Deleted =modules/popper-config.el= and its =(require 'popper-config)= in =init.el= (commit 1cca84c5). It was =use-package :disabled t=, so use-package elided the whole form and it ran nothing while still sitting in the load graph. No test existed and none was needed. validate-modules passes and init loads clean. The config stays in git history if popper is ever wanted. +Completion review 2026-05-15: +- Re-read the parent =Module-by-module review and hardening= context and the + adjacent architecture follow-up so this review stays module-specific. +- Re-checked all scoped files against the review protocol. Existing child + tasks below still cover the actionable module findings for + =user-constants.el=, =host-environment.el=, =system-defaults.el=, and + =early-init.el=. +- =system-lib.el=, =keybindings.el=, =config-utilities.el=, and =init.el= do + not need additional module-specific child tasks from this pass; remaining + concerns are already tracked by the utility-consolidation, keymap + registration, debug-profiling, and eager-load-graph architecture tasks. -***** 2026-05-26 Tue @ 15:15:43 -0500 Decided: remove popper-config.el -Craig's call: remove it (quick, solo). It has been a disabled no-op in the load graph. Remaining action: drop =(require 'popper-config)= from =init.el= and delete =modules/popper-config.el= (and any test), then close this task. +**** 2026-05-25 Mon @ 19:12:02 -0500 Split path constants from filesystem init in user-constants.el -**** 2026-05-16 Sat @ 02:55:14 -0500 Moved popper-mode activation from :init to :config +=(require 'user-constants)= used to create ~8 directories and ~10 org/calendar +files at load — the source of the stray =sync/org/= tree that appeared in the +repo during test runs. Both load-time forms are gone now; the path defconsts +stay pure, and init.el calls =cj/initialize-user-directories-and-files= on real +startup (guarded by =(unless noninteractive)=) so a bare require is +side-effect-free. Verified end-to-end: a require creates nothing, and the +interactive guard creates the backbone dirs and files. Landed in two commits on +the =refactor/user-constants-defer-fs-init= branch. -=popper-mode +1= and =popper-echo-mode +1= now live in the -=:config= block of =modules/popper-config.el='s use-package form. -=:disabled t= now actually disables the mode (=:config= is skipped -when disabled; =:init= still runs but it only sets the reference- -buffer list and the display-buffer-alist entry, both of which are -harmless no-ops when popper itself never loads). Comment in the -module explains the split. +***** 2026-05-25 Mon @ 19:12:02 -0500 Extracted pure path definitions from startup writes -**** 2026-05-16 Sat @ 02:55:14 -0500 Made cj/modeline-vc-fetch fall back when vc-git--symbolic-ref is missing +Removed the top-level calendar =dolist= and the top-level initializer call, and +folded gcal/pcal/dcal into =cj/initialize-user-directories-and-files=. init.el +now calls it right after the require, guarded by =(unless noninteractive)=. +Added =tests/test-user-constants.el= (loading creates nothing; the initializer +creates the configured paths) and updated the module header — top-level side +effects are now none and it's safe to load in tests. -The =require 'vc-git= now uses =nil 'noerror=, and the call to -=vc-git--symbolic-ref= is gated on =(fboundp ...)= so an Emacs -version that renames or removes the internal accessor just leaves -=branch= at =vc-working-revision='s output instead of crashing the -modeline render. Added =ignore-errors= around the call too in case -the internal accessor signals on unusual inputs. +***** 2026-05-25 Mon @ 19:12:02 -0500 Made initialization failures actionable -**** 2026-05-25 Mon @ 18:18:29 -0500 Theme-aware font label face in cj/display-available-fonts +=cj/verify-or-create-dir=/=-file= took an optional =required= flag routed +through =cj/--report-path-failure=: required failures raise a prominent +=display-warning=, optional ones are logged. The initializer groups paths by +that split — required: the sync/org/roam dirs and the gcal/pcal/dcal stubs; +optional: the secondary dirs and content files. Chose a warning over a +=user-error= so a directory hiccup surfaces loudly without aborting init. Added +error-path tests for the optional-logs and required-warns behavior. -Replaced the hardcoded =((:foreground "Light Blue" :weight bold))= label -face in =modules/font-config.el= with =(font-lock-keyword-face (:weight -bold))= so the family header follows theme contrast instead of being -unreadable on light themes. The Regular/Bold/Italic sample lines stay as-is -(they render in each font family on purpose). +**** 2026-05-23 Sat @ 03:33:30 -0500 Fixed env-desktop-p doc and normalized the X predicates +Corrected =env-desktop-p='s docstring (it described a laptop; the function returns t for the desktop/no-battery case). Switched =env-x-p= from =(string= (window-system) "x")= to =(eq (window-system) 'x)= to match =env-x11-p='s style, and documented the difference: =env-x-p= is any X display incl. XWayland, =env-x11-p= is a real X11 session with no WAYLAND_DISPLAY. Behavior unchanged, existing display-predicate tests stay green. Fixed in 14ec32b2. -=modules/font-config.el:266= hardcodes ="Light Blue"= and gray -foreground for font labels. Switching themes (especially light -themes) makes the labels nearly unreadable. Replace the literal -color with a face reference (=font-lock-keyword-face= or a face this -config owns) so the labels follow theme contrast. +Left =cj/match-localtime-to-zoneinfo= caching alone — it was a "consider if this runs during startup" note, not an acceptance item, and it doesn't run at startup. File a separate task if it ever shows up in a profile. -**** 2026-05-25 Mon @ 18:18:29 -0500 Routed emoji fontset through per-frame hook in daemon mode +**** 2026-05-25 Mon @ 16:59:37 -0500 Added system-defaults settings smoke tests -The emoji-fontset =(when (env-gui-p) (cond ...))= block in -=modules/font-config.el= ran once at load. In daemon mode =env-gui-p= is -nil at load (no GUI frame yet), so a later =emacsclient -c= frame inherited -no emoji fontset. Wrapped it in =cj/setup-emoji-fontset= (idempotent, GUI- -guarded) and, mirroring the fontaine pattern, added it to -=server-after-make-frame-hook= in daemon mode / ran it directly otherwise. -The all-the-icons install path already used the per-frame hook, so it was -left alone. Manual daemon TTY-then-GUI test added under "Manual testing and -validation" (batch can't drive it). +Added =tests/test-system-defaults.el= with three settings assertions the +existing files didn't cover: custom-file is redirected to a temp trashbin +(not the repo), backups land under =user-emacs-directory/backups=, and the +minibuffer GC hooks are wired onto the minibuffer hooks. The module's +functions were already covered by =test-system-defaults-functions.el= and the +=vc-follow-symlinks= default by its own file, so this stayed narrow to the +settings gap. Extracted the shared sandbox loader into +=tests/testutil-system-defaults.el= so both the new file and the +vc-follow-symlinks test use one copy. The backups test clears +=cj/backup-directory= first because it's a defvar that only recomputes when +unbound. -**** 2026-05-25 Mon @ 18:05:56 -0500 Cached mousetrap keymaps per profile +**** TODO [#B] Move package bootstrap policy out of =early-init.el= :startup:refactor: -=mouse-trap--build-keymap= rebuilt the whole keymap on every major-mode hook. -Moved the build into =mouse-trap--build-keymap-1= and cached its result in -=mouse-trap--keymap-cache=, keyed on =(profile-name . allowed-categories)=, so -the same profile reuses the cached map and editing a profile's categories -changes the key and rebuilds. Sharing one keymap object across buffers is safe -since the map only binds disallowed events to =ignore= and is never mutated. -Added =mouse-trap--clear-keymap-cache=. Behavior is unchanged; 5 cache tests -plus the existing 66 mousetrap tests pass. Done by subagent, reviewed. +=early-init.el= currently handles performance/debug setup, package archive +construction, archive refresh policy, =use-package= installation, package +signature policy, and Unicode defaults. That makes early startup do network- and +package-manager-adjacent work before the regular module system exists. -**** 2026-05-24 Sun @ 07:26:31 -0500 Keyed VC modeline cache on resolved truename +This overlaps with the existing [#B] "Split early startup from package +bootstrap" task; keep the implementation there if that task is already active. +This foundation review finding is the module-level acceptance detail. -=cj/modeline-vc-cache-key= keyed on =(list file cj/modeline-vc-show-remote)=, so a symlink whose target moved (shared drives, CI workspaces) kept serving the old VC backend. Added =(file-truename file)= to the key — one stat per refresh, cheap next to the VC calls the cache avoids — so a re-pointed symlink produces a different key and refreshes. Tests cover truename inclusion, stability for an unchanged file, and a symlink whose target moves. Commit =9135298c=. +Expected outcome: +- =early-init.el= keeps only settings that must happen before normal init: + startup GC/file-handler tuning, debug flag setup, native-comp workaround, + =load-prefer-newer=, site-start suppression, and package startup suppression. +- Package archive setup, refresh/install policy, and =use-package= bootstrap + live in a normal module or bootstrap helper that can be tested directly. +- Offline and missing-package states produce actionable errors without doing an + unexpected package refresh during early startup. +- Existing local repo and ELPA mirror behavior is preserved. -**** 2026-05-24 Sun @ 04:01:02 -0500 Verified C-s already advances isearch — non-bug, no change +Pitfalls: +- Do not break first-run bootstrap on a clean machine. +- Keep local repositories higher priority than online archives. +- Avoid prompting or refreshing archives during batch tests. -The premise didn't hold on Emacs 30.2. Investigated in the live daemon: while isearch is active, =overriding-terminal-local-map= is =isearch-mode-map= and the effective =C-s= resolves to =isearch-repeat-forward=, not =cj/consult-line-or-repeat=. isearch installs its own map as an overriding map, so the global =C-s= binding can't shadow it during a search. =isearch-mode-map= already binds =C-s= to =isearch-repeat-forward= by default. Adding an explicit binding to the consult =:bind= block would only duplicate that default, so I left =selection-framework.el= unchanged. +**** TODO [#B] Decide and test package signature policy :security:startup: -**** 2026-05-16 Sat @ 02:55:14 -0500 Guarded cursor-color hook behind display-graphic-p (with daemon-mode catch) +=early-init.el= sets =package-check-signature= to =nil= after package setup, with +an earlier commented emergency toggle for expired signatures. That may be +intentional for local mirrors, but it is security-sensitive enough to make the +policy explicit. -Both the install (=add-hook= on =post-command-hook=) and the function -body now gate on =(display-graphic-p)=. Batch and TTY runs short- -circuit cleanly: no per-command overhead, no =set-cursor-color= calls -on frames that don't have a cursor color. A =server-after-make-frame-hook= -catches the daemon case where the first GUI frame is created after -=ui-config= loads -- it installs the hook lazily the first time a -GUI frame appears. +Expected outcome: +- Document when signatures should be disabled, if ever. +- Prefer signatures on for online archives unless a local-mirror workflow + requires otherwise. +- If signatures stay disabled, add a clear comment explaining the trust model. +- Add a small test or validation helper around the computed package policy if + package bootstrap is extracted. -The two cursor-color test files -(=test-ui-config--buffer-cursor-state.el=, -=test-ui-cursor-color-integration.el=) stub =display-graphic-p= to -return t so the work body still runs in batch. +**** 2026-05-16 Sat @ 02:34:22 -0500 Consolidated user-home-dir into early-init as canonical -**** 2026-05-16 Sat @ 02:55:14 -0500 Deferred nerd-icons by dropping :demand t plus an after-load safety net +Canonical defconst in =early-init.el= kept (the package-archive paths +need it during package bootstrap, before normal modules load). +=modules/user-constants.el= switched to a `defvar` with the identical +=(getenv "HOME")= expression and a comment explaining the pattern: +defvar is a no-op at runtime (early-init's defconst wins, defvar +doesn't reassign a bound symbol), but it lets the module load / +byte-compile standalone when early-init hasn't run. Drift risk is +mitigated by both expressions being =(getenv "HOME")= literally; the +comment flags the requirement to keep them identical. -=(use-package nerd-icons :demand t ...)= flipped to =:defer t=. The -=:config= block already wraps the advice + tint in lazy-on-load -semantics, so the advice now installs the first time nerd-icons -loads (typically when a feature module like =dashboard-icon-type= -or =dirvish-attributes= triggers a load). An additional -=(with-eval-after-load 'nerd-icons ...)= block at module bottom -catches the "already-loaded when this module re-evaluates" case -- -it checks =advice-member-p= so it doesn't stack the advice on every -re-eval. +**** 2026-05-16 Sat @ 02:34:22 -0500 Dropped redundant autoload alongside compile-time require in system-defaults.el -*** DOING [#B] Harden Org workflow modules :harden: +Kept the =eval-when-compile= requires for =host-environment= and +=user-constants= (they silence free-variable / free-function warnings +during byte-compile in isolation) and dropped the +=(autoload 'env-bsd-p ...)= line — both modules are loaded earlier in +init.el at runtime, and the eval-when-compile already exposes +=env-bsd-p= to the byte-compiler. Added a comment documenting the +chosen boundary. -Scope: -- =org-config.el= -- =org-agenda-config.el= -- =org-babel-config.el= -- =org-capture-config.el= -- =org-contacts-config.el= -- =org-drill-config.el= -- =org-export-config.el= -- =org-noter-config.el= -- =org-refile-config.el= -- =org-reveal-config.el= -- =org-roam-config.el= -- =org-webclipper.el= -- =calendar-sync.el= -- =hugo-config.el= -- =gloss-config.el= +**** 2026-05-16 Sat @ 02:34:22 -0500 Converted cj/debug-modules and cj/use-online-repos to defcustom -Review progress: -- Reviewed 2026-05-03 at high level. -- =calendar-sync.el= has substantial focused coverage for parsing, recurrence, - timezone conversion, event conversion, and regressions. The largest remaining - risks are configuration/secrets, startup side effects, and process/network - boundaries. -- =org-agenda-config.el= and =org-refile-config.el= now have useful cache tests, - but the cache lifecycle and startup idle timers still deserve a design pass. -- =org-noter-config.el= already has an older [#B] workflow VERIFY task. Do not - duplicate that work here. -- =hugo-config.el= and =org-reveal-config.el= have focused helper coverage. -- =gloss-config.el= is a thin package wrapper; no local unit-test target unless - custom glue is added. -- Deeper pass 2026-05-10 added follow-up tasks for org-roam done hooks, drill - file selection/package loading, Org export defaults, Babel templates, and - contact/Mu4e boundaries. +Both toggles now live as =defcustom= with explicit =:type= and +=:group 'cj=. =cj/debug-modules='s type is the natural choice form: +either =t= (all modules) or a list of module symbols. +=cj/use-online-repos='s type is boolean. Added a top-level +=(defgroup cj ...)= in early-init.el so the group exists for both, +plus the package-priority constants below it. -Completion review 2026-05-15: -- Re-checked the scoped Org workflow modules and their test coverage. -- The broad parser/cache/helper areas now have useful focused tests, especially - =calendar-sync.el=, agenda/refile helpers, org-roam helpers, org-noter, Hugo, - reveal, and webclipper processing. -- Remaining issues are already logged below, including security-sensitive - calendar config and Babel evaluation policy, cache lifecycle/timer behavior, - org-roam destructive workflow guardrails, executable checks, capture-template - smoke tests, and Org workflow ownership documentation. +**** 2026-05-25 Mon @ 18:29:40 -0500 Made the Customize-save discard non-silent -**** 2026-05-23 Sat @ 04:18:44 -0500 Split personal calendar config out of calendar-sync.el -=calendar-sync.el= now defaults =calendar-sync-calendars= to nil and loads the real plists from =calendar-sync-private-config-file= (an ignored file), so the engine carries no private feed tokens in source. =calendar-sync-status= / =calendar-sync-start= report missing config without erroring, and agenda startup is unaffected (tests/test-calendar-sync-no-config-startup.el). Rotating the previously-committed feed URLs remains a manual credential action — tracked under the L2557 calendar-sync hardening finding. +Took the display-warning option. =cj/--warn-customize-discarded= advises +=custom-save-all= (the chokepoint both =customize-save-variable= and the +Customize "Save for Future Sessions" button funnel through) with a one-shot +=:before= warning that explains the edit won't persist and points at the Elisp +init files. The advice removes itself after firing, so it warns once per +session, and the body never runs at load, so startup stays quiet. Kept the +throwaway =custom-file= as-is. Test added in =tests/test-system-defaults.el=. -**** PROJECT [#B] Normalize Org agenda/refile cache lifecycle :perf:refactor: +**** 2026-05-16 Sat @ 02:34:22 -0500 Named the package archive priorities in early-init.el -Two of three children are done (shared cache helper extracted, idle timers gated). Still open: the directory-scan-failure visibility child below. +Nine =defconst= entries replace the magic numbers: +=cj/package-priority-localrepo= (200) for the project-pinned repo, +four =cj/package-priority-mirror-*= entries for the local ELPA +mirrors (125 / 120 / 115 / 100), four =cj/package-priority-online-*= +entries for the online archives (25 / 20 / 15 / 5). A header comment +above the block explains the local-first ordering and the +gnu > nongnu > melpa > melpa-stable trust ranking within each tier. -***** 2026-05-23 Sat @ 04:18:44 -0500 Extracted a shared cache helper -=cj-cache-lib.el= now provides =cj/cache-valid-p=, =cj/cache-building-p=, and =cj/cache-value-or-rebuild=, consumed by both =org-agenda-config.el= and =org-refile-config.el=; the contract is documented in =docs/design/cache-helper-design.org=. The agenda and refile public commands are unchanged. +**** 2026-05-16 Sat @ 02:34:22 -0500 Deleted dead world-clock block in chrono-tools.el -***** 2026-05-24 Sun @ 07:26:31 -0500 Surfaced directory-scan failures instead of hiding/crashing +The 19-line commented-out =use-package time= block is gone. The +=time-zones= use-package directly above it is the active replacement; +git history preserves the old config if anyone needs to dig it back up. -The refile scan caught =permission-denied= and silently dropped the dir, and crashed outright on a missing root (only permission-denied was caught, so a missing =code-dir=/=projects-dir= raised =file-missing= and aborted the build); the agenda build had the same missing-dir crash via =directory-files=. Extracted =cj/--org-refile-scan-dir= (warns + returns nil for missing/unreadable/permission-denied so the scan continues) and guarded the agenda scan the same way. Also fixed a latent bug found here: =org-refile-targets= was never declared special, so under =make compile= =cj/org-refile-in-file= let-bound it lexically and the scoped targets never reached =org-refile= — added =(defvar org-refile-targets)=. Tests cover the helper + the agenda missing-dir guard. Commit =12fb0108=. +**** 2026-05-16 Sat @ 02:34:22 -0500 Added coverage for cj/tmr-select-sound-file with a pre-test refactor -***** 2026-05-23 Sat @ 04:18:44 -0500 Gated cache idle timers out of batch -Both cache builders' =run-with-idle-timer= calls are wrapped in =(unless noninteractive)= (=org-refile-config.el:105=, =org-agenda-config.el:203=), so requiring the modules in batch schedules nothing. =tests/test-architecture-startup-contracts.el= scans every module and asserts there are no unguarded top-level timer forms. +The prefix-arg branch now delegates to =cj/tmr-reset-sound-to-default= +directly (single source for the reset path). Extracted a pure helper +=cj/tmr--available-sound-files= so the directory scan is testable +without driving =completing-read=. =tests/test-chrono-tools-tmr-sound.el= +covers Normal / Boundary / Error: available-sounds against a populated +dir, empty dir, missing dir; reset path; select with prefix-arg +(delegates to reset, no prompt); select normal (picks a file); select +boundary paths for empty dir, missing dir, cancel (empty completion). +9 tests, all green. -**** 2026-05-23 Sat @ 19:48:00 -0500 Made org-confirm-babel-evaluate default to t with a toggle +*** DOING [#B] Harden custom editing utility modules :harden: -=org-babel-config.el= set =org-confirm-babel-evaluate= to nil globally, so every source block in every Org file (cloned repos, downloaded notes, web clips) ran without confirmation. Changed the default to =t= (confirm before running). Replaced the old =babel-confirm= command (which reported, and toggled only with a prefix arg) with =cj/org-babel-toggle-confirm=, a plain toggle bound to =C-; k= for flipping confirmation off in trusted files and back on. 3 ERT tests cover the toggle both directions plus the binding. +Scope: +- =custom-buffer-file.el= +- =custom-case.el= +- =custom-comments.el= +- =custom-datetime.el= +- =custom-line-paragraph.el= +- =custom-misc.el= +- =custom-ordering.el= +- =custom-text-enclose.el= +- =custom-whitespace.el= +- =external-open.el= +- =media-utils.el= -**** TODO [#B] Rebind babel-confirm toggle off =C-; k= :keybinding:solo:discuss: +Review progress: +- Core =custom-*= text modules reviewed 2026-05-03. They have unusually strong + direct ERT coverage compared with the rest of the config. +- =external-open.el= and =media-utils.el= reviewed 2026-05-03. See child tasks. +- =custom-buffer-file.el= reviewed 2026-05-03. See child tasks. -=cj/org-babel-toggle-confirm= landed on =C-; k= as a placeholder. Pick a permanent home — likely under an Org-specific prefix rather than the global =C-;= map. +Completion review 2026-05-15: +- Re-checked the scoped custom editing utility modules and their test files. +- The pure editing modules remain well covered by focused ERT tests. +- Remaining actionable issues are already logged below: process-launch + hardening and coverage for =external-open.el= / =media-utils.el=, + destructive buffer/file keybinding policy, and explicit cross-module + autoload/require boundaries. -Triggered by: 2026-05-23 org-confirm-babel-evaluate hardening. +**** TODO [#B] Harden external process launching in =external-open.el= and =media-utils.el= :security:refactor: -**** 2026-05-24 Sun @ 14:43:13 -0500 Guarded move-branch-to-roam against data loss +=external-open.el= and =media-utils.el= use shell command strings for launching +external applications: +- =cj/open-this-file-with= interpolates the user-supplied command into + =call-process-shell-command=. +- =cj/media-play-it= builds a shell command for players and optional =yt-dlp= + stream extraction. -The command cut the subtree from the source before writing the new roam file, so any failure in demote/format/write/db-sync lost the subtree with no rollback. Reordered to write and verify the file on disk before =org-cut-subtree=, so a failed write aborts with the source intact. Added a no-clobber guard (refuse an existing target file) and a confirmation prompt for large subtrees (>= =cj/move-org-branch-confirm-lines=, 30) or buffers with unsaved changes. Decided: leave the source buffer modified and undoable rather than auto-saving, so the move stays reversible. New test drives the write-failure-preserves-source invariant via an unwritable roam dir. Commit =5c0fa15d=. +This is mostly controlled local input, but it is still brittle: command paths +with spaces can fail, arguments are hard to reason about, and future URL/source +changes could create shell quoting bugs. -**** 2026-05-25 Mon @ 18:29:40 -0500 Already done — clip URL/title scoped to dynamic bindings +Expected outcome: +- Prefer =start-process= / =call-process= with argv lists where possible. +- If shell is required for command substitution, isolate and quote every + untrusted value. +- Add tests around command construction for: + - file paths with spaces and shell metacharacters, + - URL strings with shell metacharacters, + - configured player args, + - missing executable errors. -Found this already shipped in =6dfc41af= ("refactor(webclipper): scope clip -URL/title to dynamic bindings", 2026-05-24). The temp vars =cj/--webclip-url= / -=cj/--webclip-title= are now =let=-bound around the org-capture call instead of -=setq='d and manually cleared, so they unwind on every exit path including a -=C-g= abort — which covers the "aborted captures clear temp state" outcome more -completely than a finalize hook would. The bookmarklet/org-protocol workflow is -unchanged. =tests/test-org-webclipper-commands.el= already covers the -leaves-no-stale-state and aborted-capture-clears-state cases. No new work needed. +Pitfalls: +- =cj/open-this-file-with= may intentionally accept "program plus args". If so, + split the command deliberately or introduce separate program/args prompts. +- Some media players need different URL handling; preserve the existing + =:needs-stream-url= behavior. -**** 2026-05-25 Mon @ 17:51:17 -0500 Guarded external-tool assumptions in Org export/publishing +**** 2026-05-23 Sat @ 03:41:00 -0500 Added media-utils coverage; external-open already covered +=external-open= already had three test files (=test-external-open-commands.el=, =test-external-open-lib-command.el=, =test-external-open-lib-launcher-p.el=). =media-utils.el= had none, so I added =test-media-utils.el= (8 cases): player availability from =cj/media-players=, the play command-builder (direct vs yt-dlp -g stream wrap), and the missing-tool error paths for the player, =yt-dlp=, and =tsp=. All process/exec boundaries mocked. Added in the test-media-utils commit. -Added command-time guards to four export/publishing commands so a missing tool -fails with a user-error that names it, instead of an opaque process error (or, -for reveal.js, a silently broken presentation): -- =org-export-config.el=: zathura check in my/org-pandoc-export-to-pdf-and-open. -- =hugo-config.el=: hugo binary check in cj/hugo-preview, and the platform - file-manager opener check in cj/hugo-open-blog-dir-external. -- =org-reveal-config.el=: extracted =cj/--reveal-ensure-root= (checks the local - reveal.js clone, points at scripts/setup-reveal.sh), called from - cj/reveal-export and cj/reveal-preview-start. -- =org-webclipper.el=: pandoc check in cj/org-protocol-webclip-handler, the - single path that shells out to pandoc via org-web-tools. +**** TODO [#B] Audit destructive buffer/file keybindings for confirmation policy :ux: -All checks run at command time, not load, so startup stays quiet. Each guard -has a user-error test; existing happy-path tests now stub the lookups. Things -deliberately not guarded: hugo-publish (magit, internal), the preview filter -(browse-url, internal), hugo-export-post (ox-hugo, Elisp). Done with four -parallel implementation agents, reviewed individually; full suite green. +=cj/buffer-and-file-map= includes destructive operations under =C-; b=, +including delete file, erase buffer, clear top, clear bottom, and revert. Some +are intentionally fast, but this module is high blast radius. -**** 2026-05-16 Sat @ 03:44:45 -0500 Guarded org-roam completed-task hook with cj/--org-roam-should-copy-completed-task-p +Expected outcome: +- Decide which operations need confirmation when the buffer is modified or + visiting a file. +- At minimum, document the intended policy in =custom-buffer-file.el=. +- Consider safer wrappers for =erase-buffer= and =revert-buffer= under the + personal keymap. -=org-roam-config.el= adds a global =org-after-todo-state-change-hook= that -copies newly completed tasks to today's org-roam journal. The hook assumes the -current Org buffer is visiting a file: +**** 2026-05-24 Sun @ 14:43:13 -0500 Declared cross-module commands bound in custom keymaps -- It calls =(buffer-file-name)= and passes the result to =string=. -- =cj/org-roam-copy-todo-to-today= later compares =file-truename= of the daily - file and the current buffer file. +Byte-compiling =custom-ordering.el= and =custom-text-enclose.el= standalone warned "not known to be defined" for =cj/org-sort-by-todo-and-priority= (owned by org-config) and =change-inner=/=change-outer= (the change-inner package). Both work at runtime — org-config loads eagerly, and text-config autoloads change-inner via =use-package :commands= — so only the compiler needed telling; added =declare-function= for each (no autoload needed since the runtime autoload/eager-load already exists). =custom-buffer-file.el= byte-compiles clean already, so it needed no change. Commit =ad173a77=. -That can error in capture buffers, indirect buffers, temporary Org buffers, or -other fileless Org workflows. +**** 2026-05-24 Sun @ 07:26:31 -0500 Extracted shared region-or-buffer bounds helper -Expected outcome: -- Extract a predicate for "should copy this completed task to today's journal". -- Skip fileless buffers, calendar sync files, aborted capture buffers, and tasks - already in the target daily file. -- Keep the normal completed-task journal workflow unchanged. -- Add tests for fileless buffers, =gcal-file=, already-daily buffers, and a - normal project/todo buffer. +The described docstring mismatch was already resolved: =custom-ordering.el='s =cj/--arrayify=/=cj/--unarrayify= now document an explicit =(start end)= contract accurately and are region-required by design. The remaining work was the enclose side, where append/prepend/indent/dedent each inlined the same region-or-buffer bounds block (four copies). Extracted =cj/--region-or-buffer-bounds= as the single source of that contract and routed all four through it (behavior unchanged; public-wrapper tests still pass). Each pair now has one clear, consistent, documented contract. New tests cover the helper (region / no-region / empty buffer). Commit =a7cc8948=. -**** 2026-05-24 Sun @ 04:30:14 -0500 Shared one validated drill-file selector +**** 2026-05-16 Sat @ 02:47:15 -0500 Preserved trailing newlines in custom-ordering output -org-capture-config.el and org-drill-config.el each scanned =drill-dir= with an inline =directory-files= call, so a missing/empty/unreadable dir surfaced as a low-level error or an empty =completing-read= depending on which command ran. Added =cj/--drill-files-or-error=, the single validated entry point: clear =user-error= when the dir is missing, unreadable, or has no drill files; otherwise the list. =cj/--drill-pick-file= and both drill capture templates route through it; the pure =cj/--drill-files-in= primitive and its tests are unchanged. Tests cover missing/empty/non-org/normal. Commit =49038c41=. +Both =cj/--arrayify= and =cj/--unarrayify= now detect a trailing +newline on the input region (via =string-suffix-p=) and re-append it +to the result. Matches the pattern =custom-text-enclose.el= already +uses. Docstrings updated to document the contract. -**** 2026-05-24 Sun @ 14:43:13 -0500 Removed contradictory org-export-with-tasks default +**** 2026-05-16 Sat @ 02:47:15 -0500 Guarded cj/duplicate-line-or-region against modes without comment syntax -=org-export-config.el= set =org-export-with-tasks= twice (=("TODO")= then =nil=); the final =nil= won but the stale first line + comment contradicted it. Removed the leftover. =nil= (export no tasks) is the deliberate default — it was already winning, its comment matches, and it sits with the adjacent "without tags / section numbers by default" settings. Added a smoke test that fires the deferred =ox= :config and pins the value to =nil=. Commit =94ef5242=. +=cj/duplicate-line-or-region= now signals a clear =user-error= when +=COMMENT= is non-nil but the current mode has no =comment-start= +(=fundamental-mode= and similar). Docstring updated to document the +error. Picks the "error out clearly" branch from the task body -- +restricting the binding per-mode would be a larger refactor that +isn't justified for the silent-malformed-output blast radius. -**** 2026-05-23 Sat @ 03:48:50 -0500 Fixed java structure-template typo and pinned the aliases -=("java" . "src javas")= expanded to a bogus =#+begin_src javas=; corrected it to =src java=. Added =test-org-babel-config-structure-templates.el=, which requires the module then org-tempo (firing the deferred :config) and asserts =bash=, =zsh=, =el=, =py=, =json=, =yaml=, =java= each map to the intended src language. Fixed in the org-babel commit. +**** 2026-05-16 Sat @ 02:47:15 -0500 Made external-open advice install explicit via cj/external-open-install-advice -**** TODO [#B] Make org-contacts/Mu4e boundaries explicit :cleanup:refactor: +Factored the =advice-remove= / =advice-add= pair into +=cj/external-open-install-advice= and called it once at the bottom +of the module. Same idempotent shape (remove-then-add) but now the +intent is named. Re-running the module updates the advice rather +than stacking it; if a future caller wants to opt out, they can +=advice-remove= the helper or skip calling it altogether. -=org-contacts-config.el= defines helpers that call Mu4e functions when the -current major mode is a Mu4e mode, and the =use-package org-contacts= block is -=:after (org mu4e)= while also requiring =mu4e= inside =:config=. This works in -the current eager setup, but the ownership boundary is unclear now that -=mu4e-org-contacts-integration.el= exists. +**** 2026-05-16 Sat @ 02:47:15 -0500 Added cj/--validate-decoration-char across all six divider/border helpers -Expected outcome: -- Decide whether contact capture-from-email behavior belongs in - =org-contacts-config.el= or the Mu4e integration modules. -- Add =declare-function= / autoloads or move Mu4e-specific code behind - =with-eval-after-load 'mu4e=. -- Keep plain Org contact commands usable on systems without Mu4e loaded. -- Add a smoke test for loading =org-contacts-config.el= without Mu4e stubs if - practical. +New top-level validator =cj/--validate-decoration-char= rejects +anything that isn't a printable single-character string and signals +=user-error=. Wired into all six internal helpers: +=cj/--comment-inline-border=, =cj/--comment-simple-divider=, +=cj/--comment-padded-divider=, =cj/--comment-box=, +=cj/--comment-heavy-box=, =cj/--comment-block-banner=. The five +nil-decoration ERT tests updated from =:type 'wrong-type-argument= +(the old crash signal from =string-to-char= on nil) to +=:type 'user-error=, since the guard now produces a clear message +instead of a deep crash. -**** TODO [#B] Add an Org workflow health check command :feature:ux:solo:discuss: +**** 2026-05-23 Sat @ 03:38:30 -0500 Filled the remaining title-case edge gaps +=test-custom-case-title-case-region.el= already had 29 cases (empty region, unicode words, numbers, separators, colon resets, partial region). The named gaps that were missing — leading-quote and leading-paren handling, plus a caseless RTL first word — are now covered by three boundary tests (32 total). Added in 3841c59e. -Several Org workflow modules depend on personal paths, optional external tools, -and local package checkouts. Failures currently show up at command time in -different ways, depending on which module hits the missing dependency first. +**** 2026-05-16 Sat @ 02:47:15 -0500 Extracted cj/--require-spell-checker -Recommended improvement: -- Add a lightweight =cj/org-workflow-doctor= command that checks the main Org - workflow prerequisites without mutating user data. -- Report status for core files/directories: =org-dir=, =roam-dir=, =drill-dir=, - =contacts-file=, =webclipped-file=, =cj/hugo-content-org-dir=, and - =cj/reveal-root=. -- Report optional executable/package availability for Pandoc/org-web-tools, - Hugo, reveal.js, org-drill, org-roam, and org-noter. -- Keep startup quiet; run this only on demand. -- Make the checker return structured data so it can be unit-tested and displayed - either in Messages or a buffer. +Both =cj/flyspell-toggle= and =cj/flyspell-then-abbrev= now call +=cj/--require-spell-checker= instead of carrying their own copy of +the executable-find check. The checker list lives in the new +defconst =cj/--spell-checker-executables=, so adding nuspell (or any +other checker) is a one-line edit. Top-level =(require 'cl-lib)= +added since the new helper uses =cl-some=. -**** 2026-05-24 Sun @ 14:43:13 -0500 Added capture-template key + target smoke tests +**** 2026-05-23 Sat @ 03:44:50 -0500 Covered flyspell-and-abbrev testable seams +Added =test-flyspell-and-abbrev.el= (8 cases): =cj/--require-spell-checker= (PATH gate, mocked), =cj/find-previous-flyspell-overlay= against synthetic overlays (closest-previous match, non-flyspell skipped, nil when none), and =cj/flyspell-on-for-buffer-type= (prog-mode -> flyspell-prog-mode, text-mode -> flyspell-mode). Left =cj/flyspell-then-abbrev= to manual testing — pinning its flyspell-UI orchestration would mean mocking flyspell internals rather than our logic. Added in the test-flyspell-abbrev commit. -New =test-org-capture-templates-integrity.el= loads the cleanly-loadable capture modules (=org-capture-config=, =quick-video-capture=, =org-contacts-config=), applies their lazy additions, and asserts no two templates share a dispatch key and that every symbol-valued file target resolves to a non-empty path string. Literal-string targets (the video template's no-save =(file "")=) and lambda targets (drill file pickers) are excluded. Webclipper templates need org-web-tools at registration time, so they stay covered by their own test rather than this batch smoke test. Mutation-checked that the uniqueness assertion flags a duplicate key. Commit =2e3905c7=. +*** DOING [#B] Harden UI and navigation modules :harden: -**** TODO [#B] Document Org workflow module ownership and load boundaries :docs:refactor:solo:discuss: +Scope: +- =ui-config.el= +- =ui-navigation.el= +- =ui-theme.el= +- =font-config.el= +- =modeline-config.el= +- =selection-framework.el= +- =mousetrap-mode.el= +- =popper-config.el= -The Org workflow is spread across many modules with overlapping responsibilities: -capture templates, keymaps, org-protocol handlers, refile/agenda target -construction, roam notes, publishing, and document annotation. The code is -usable, but future load-order work will be easier with explicit ownership notes. +Review progress: +- Reviewed 2026-05-03. +- =mousetrap-mode.el= has strong focused and integration tests. +- =modeline-config.el= has pure string-helper coverage, but not VC/runtime + segment behavior. +- =font-config.el=, =ui-theme.el=, =selection-framework.el=, =ui-navigation.el=, + and =popper-config.el= have little direct test coverage. -Recommended improvement: -- Add a short design note under =docs/design/= that maps each Org module to the - behavior it owns. -- Call out which modules may mutate global Org variables, capture templates, - keymaps, and protocol handlers. -- Define which modules should be safe to load in batch mode and which are - allowed to start timers or require interactive packages. -- Link this note from the Org workflow review task and the broader load-graph - refactor. +Completion review 2026-05-15: +- Re-checked the scoped UI/navigation modules and current tests. +- =mousetrap-mode.el=, =ui-navigation.el=, =ui-theme.el=, + =selection-framework.el=, and selected modeline/UI helpers now have focused + tests, but the font/modeline/popper runtime policy remains under-tested. +- Existing cleanup below covers the disabled =popper-config.el= load-graph + issue; added a separate test-gap task for the remaining UI smoke coverage. -**** 2026-05-16 Sat @ 03:44:45 -0500 Removed duplicate org-protocol-protocol-alist registration in cj/webclipper-ensure-initialized +**** 2026-05-25 Mon @ 17:05:00 -0500 Added UI/navigation runtime smoke coverage -The =webclip= protocol handler is registered twice: -=modules/org-webclipper.el:72-76= inside =cj/webclipper-ensure-initialized= -(unconditional =add-to-list=) and =:207-214= inside a -=with-eval-after-load 'org-protocol= block (=unless (assoc ...)= guard). -=add-to-list= uses =equal= membership so the two are effectively -idempotent, but maintaining two registration paths invites drift if -the alist entry shape ever changes. Pick one site -- the -=with-eval-after-load= block is the more robust location -- and -remove the other. +Added =tests/test-font-config.el= (4 tests): cj/font-installed-p returns t/nil +off find-font, and cj/apply-font-settings-to-frame is a no-op on a non-GUI +frame and applies the preset exactly once per frame (idempotent). find-font, +env-gui-p, and fontaine-set-preset are stubbed so the run stays headless, and +a skip-unless on the demanded packages keeps a bare checkout green. +font-config had zero direct coverage; this fills the gap the task named. -**** 2026-05-16 Sat @ 03:44:45 -0500 Validated :url and :title in cj/org-protocol-webclip before stashing +modeline-config was already well covered (string-cut-middle, string-truncate-p, +vc-cache, vc-cache-key, the flycheck segment, the recording indicator), so it +needed no net-new smoke tests. popper-config's no-op smoke test is gated on the +"Decide whether popper-config.el should exist while disabled" task and was +deferred there, since whether to write it depends on that keep/remove call. -=modules/org-webclipper.el:124-125= extracts =:url= and =:title= from -the incoming protocol plist with no type or nil check. An unexpected -plist shape silently sets the globals to nil, and downstream code -fails inside the capture handler with confusing messages. Guard with -=(unless (and (stringp url) (not (string-empty-p url))) (user-error ...))= -before stashing. +Original scope: +- =font-config.el=: font fallback/daemon frame setup does not error when + optional fonts or emoji packages are absent. +- =modeline-config.el=: runtime segment assembly handles missing VC/project + data and does not signal in non-file buffers. +- =popper-config.el=: if the module remains in =init.el= while disabled, a + smoke test should prove requiring it is an intentional no-op. -**** 2026-05-24 Sun @ 07:26:31 -0500 Scoped webclip URL/title to dynamic bindings +**** 2026-05-26 Tue @ 17:33:28 -0500 Removed popper-config.el (disabled no-op) +Deleted =modules/popper-config.el= and its =(require 'popper-config)= in =init.el= (commit 1cca84c5). It was =use-package :disabled t=, so use-package elided the whole form and it ran nothing while still sitting in the load graph. No test existed and none was needed. validate-modules passes and init loads clean. The config stays in git history if popper is ever wanted. -The protocol handler =setq= globals =cj/webclip-current-url= / =cj/webclip-current-title= that the "W" template and handler read (and cleared), so an aborted/erroring capture left stale state for the next clip. Renamed to =cj/--webclip-url= / =cj/--webclip-title= and =let=-bind them around the =org-capture= call: the template =%(identity ...)= forms and the handler run within that dynamic extent, and an abort/error unwinds the binding automatically — no stale state, no manual clear. Mirrors the quick-video-capture fix. Tests updated to the new contract (visible-during-capture, nothing-left-after, aborted-leaves-nothing). Commit =6dfc41af=. +***** 2026-05-26 Tue @ 15:15:43 -0500 Decided: remove popper-config.el +Craig's call: remove it (quick, solo). It has been a disabled no-op in the load graph. Remaining action: drop =(require 'popper-config)= from =init.el= and delete =modules/popper-config.el= (and any test), then close this task. -**** 2026-05-16 Sat @ 03:44:45 -0500 Declared cross-module free vars in mu4e-org-contacts-integration.el +**** 2026-05-16 Sat @ 02:55:14 -0500 Moved popper-mode activation from :init to :config -The module reads =contacts-file= (defined in =user-constants.el=) and -calls =cj/get-all-contact-emails= (defined in =org-contacts-config.el=) -without any forward declaration at the top of the file. Byte-compile -in isolation warns about both as free variables / unknown functions. -Add =(eval-when-compile (defvar contacts-file))= and -=(declare-function cj/get-all-contact-emails "org-contacts-config")= -near the existing requires so the compile is clean and the -cross-module dependency is explicit at the top of the file. +=popper-mode +1= and =popper-echo-mode +1= now live in the +=:config= block of =modules/popper-config.el='s use-package form. +=:disabled t= now actually disables the mode (=:config= is skipped +when disabled; =:init= still runs but it only sets the reference- +buffer list and the display-buffer-alist entry, both of which are +harmless no-ops when popper itself never loads). Comment in the +module explains the split. -**** 2026-05-25 Mon @ 17:10:47 -0500 Added mu4e org-contacts completion coverage +**** 2026-05-16 Sat @ 02:55:14 -0500 Made cj/modeline-vc-fetch fall back when vc-git--symbolic-ref is missing -Added =tests/test-mu4e-org-contacts-integration.el= (10 tests). The capf -(cj/org-contacts-completion-at-point) is checked for the header-field and -compose-mode gating both ways, the bounds/table it returns when contacts -exist, and the empty-contacts case. TAB (cj/mu4e-org-contacts-tab-complete) -is checked across all three branches: completion-at-point in a header, -org-cycle in the org-msg body, indent elsewhere. Comma completion and the -direct-insert no-op-outside-header path round it out. mail-abbrev-in-expansion-header-p, -the mode actions, and cj/get-all-contact-emails are stubbed, so the run is -headless with no mu4e/org-contacts dependency. +The =require 'vc-git= now uses =nil 'noerror=, and the call to +=vc-git--symbolic-ref= is gated on =(fboundp ...)= so an Emacs +version that renames or removes the internal accessor just leaves +=branch= at =vc-working-revision='s output instead of crashing the +modeline render. Added =ignore-errors= around the call too in case +the internal accessor signals on unusual inputs. -*** DOING [#B] Harden programming workflow modules :harden: +**** 2026-05-25 Mon @ 18:18:29 -0500 Theme-aware font label face in cj/display-available-fonts -Scope: -- =prog-c.el= -- =prog-general.el= -- =prog-go.el= -- =prog-json.el= -- =prog-lisp.el= -- =prog-lsp.el= -- =prog-python.el= -- =prog-shell.el= -- =prog-training.el= -- =prog-webdev.el= -- =prog-yaml.el= -- =coverage-core.el= -- =coverage-elisp.el= -- =test-runner.el= -- =vc-config.el= -- =keyboard-compat.el= -- =dev-fkeys.el= +Replaced the hardcoded =((:foreground "Light Blue" :weight bold))= label +face in =modules/font-config.el= with =(font-lock-keyword-face (:weight +bold))= so the family header follows theme contrast instead of being +unreadable on light themes. The Regular/Bold/Italic sample lines stay as-is +(they render in each font family on purpose). -Review progress: -- Reviewed 2026-05-03 at high level. -- =dev-fkeys.el= reviewed 2026-05-03 after local edits settled. The focused - dev-fkeys test set passed: 22 test files, 163 ERT tests. -- =coverage-core.el= / =coverage-elisp.el= have strong pure-helper tests. -- Language formatter wiring is covered for Python, Go, shell, webdev, JSON, and - YAML. -- =test-runner.el= has direct tests, but project-scoping is still a design gap. +=modules/font-config.el:266= hardcodes ="Light Blue"= and gray +foreground for font labels. Switching themes (especially light +themes) makes the labels nearly unreadable. Replace the literal +color with a face reference (=font-lock-keyword-face= or a face this +config owns) so the labels follow theme contrast. -Completion review 2026-05-15: -- Re-checked the scoped programming workflow modules and current tests. -- =dev-fkeys.el=, coverage modules, formatter wiring, keyboard compatibility, - and test-runner helpers have meaningful focused coverage. -- Remaining issues are logged below: F4 project capability classification, - LSP ownership and smoke coverage, tree-sitter auto-install policy, Git clone - process handling, shell-script executable policy, and formatter process - boundaries. +**** 2026-05-25 Mon @ 18:18:29 -0500 Routed emoji fontset through per-frame hook in daemon mode -**** 2026-05-25 Mon @ 17:35:02 -0500 Added prog-lisp smoke coverage; assessed the other two +The emoji-fontset =(when (env-gui-p) (cond ...))= block in +=modules/font-config.el= ran once at load. In daemon mode =env-gui-p= is +nil at load (no GUI frame yet), so a later =emacsclient -c= frame inherited +no emoji fontset. Wrapped it in =cj/setup-emoji-fontset= (idempotent, GUI- +guarded) and, mirroring the fontaine pattern, added it to +=server-after-make-frame-hook= in daemon mode / ran it directly otherwise. +The all-the-icons install path already used the per-frame hook, so it was +left alone. Manual daemon TTY-then-GUI test added under "Manual testing and +validation" (batch can't drive it). -Added =tests/test-prog-lisp.el= (4 tests) covering the config prog-lisp owns -directly: cj/elisp-setup and cj/common-lisp-setup are each registered on their -mode hook and apply the right buffer locals (4-space/no-tabs/fill-120 for -elisp, 2-space/fill-100 for Common Lisp). The module loads with use-package -stubbed to a no-op, so nothing installs or downloads in batch. +**** 2026-05-25 Mon @ 18:05:56 -0500 Cached mousetrap keymaps per profile -=prog-training.el= got no test: it's entirely deferred use-package config with -no top-level surface, and its only owned settings (leetcode language/dir) live -in a deferred =:config= that would make the test package-dependent for no real -value. Forcing a test there would be coverage theater. +=mouse-trap--build-keymap= rebuilt the whole keymap on every major-mode hook. +Moved the build into =mouse-trap--build-keymap-1= and cached its result in +=mouse-trap--keymap-cache=, keyed on =(profile-name . allowed-categories)=, so +the same profile reuses the cached map and editing a profile's categories +changes the key and rebuilds. Sharing one keymap object across buffers is safe +since the map only binds disallowed events to =ignore= and is never mutated. +Added =mouse-trap--clear-keymap-cache=. Behavior is unchanged; 5 cache tests +plus the existing 66 mousetrap tests pass. Done by subagent, reviewed. -=prog-general.el= is deferred: it's the one of the three that touches LSP and -tree-sitter, and the task itself says to wait for the LSP/tree-sitter policy -tasks to land before fixing its assertions. Its smoke coverage rides with those. +**** 2026-05-24 Sun @ 07:26:31 -0500 Keyed VC modeline cache on resolved truename -**** TODO [#B] Revisit F4 project classification vs actual project capabilities :ux: +=cj/modeline-vc-cache-key= keyed on =(list file cj/modeline-vc-show-remote)=, so a symlink whose target moved (shared drives, CI workspaces) kept serving the old VC backend. Added =(file-truename file)= to the key — one stat per refresh, cheap next to the VC calls the cache avoids — so a re-pointed symlink produces a different key and refreshes. Tests cover truename inclusion, stability for an unchanged file, and a symlink whose target moves. Commit =9135298c=. -=dev-fkeys.el= classifies a project as =interpreted= if it has -=pyproject.toml=, =requirements.txt=, =Pipfile=, or =package.json=, even when it -also has a =Makefile=. That intentionally keeps Python/Node projects on a -Run-only F4 menu, but it also hides useful Compile/Clean options for projects -where =Makefile=, =package.json= scripts, or Projectile cached commands provide -real build/test tasks. +**** 2026-05-24 Sun @ 04:01:02 -0500 Verified C-s already advances isearch — non-bug, no change -Expected outcome: -- Decide whether F4 should classify by language family or by available - capabilities. -- Consider deriving candidates from Projectile's known compile/run/test commands - first, then falling back to markers. -- Keep the current "interpreted markers win" behavior only if that remains the - intentional UX after trying it in mixed Python/Node projects. +The premise didn't hold on Emacs 30.2. Investigated in the live daemon: while isearch is active, =overriding-terminal-local-map= is =isearch-mode-map= and the effective =C-s= resolves to =isearch-repeat-forward=, not =cj/consult-line-or-repeat=. isearch installs its own map as an overriding map, so the global =C-s= binding can't shadow it during a search. =isearch-mode-map= already binds =C-s= to =isearch-repeat-forward= by default. Adding an explicit binding to the consult =:bind= block would only duplicate that default, so I left =selection-framework.el= unchanged. -**** PROJECT [#B] Consolidate LSP ownership across programming modules :architecture:refactor: +**** 2026-05-16 Sat @ 02:55:14 -0500 Guarded cursor-color hook behind display-graphic-p (with daemon-mode catch) -LSP setup is currently split across =prog-general.el=, =prog-lsp.el=, and each -language module. There are multiple =use-package lsp-mode= forms and some -conflicting defaults: -- =prog-general.el= enables snippets/UI doc/sideline behavior. -- =prog-lsp.el= disables snippets/UI doc/sideline-heavy behavior. -- Python, Go, shell, C, and webdev modules both call =lsp-deferred= from local - setup functions and add package hooks that call =lsp-deferred= again. +Both the install (=add-hook= on =post-command-hook=) and the function +body now gate on =(display-graphic-p)=. Batch and TTY runs short- +circuit cleanly: no per-command overhead, no =set-cursor-color= calls +on frames that don't have a cursor color. A =server-after-make-frame-hook= +catches the daemon case where the first GUI frame is created after +=ui-config= loads -- it installs the hook lazily the first time a +GUI frame appears. -This probably works because lsp-mode is defensive, but it makes the final -runtime policy hard to predict. +The two cursor-color test files +(=test-ui-config--buffer-cursor-state.el=, +=test-ui-cursor-color-integration.el=) stub =display-graphic-p= to +return t so the work body still runs in batch. -***** TODO [#B] Make =prog-lsp.el= the single owner of generic LSP policy :refactor: +**** 2026-05-16 Sat @ 02:55:14 -0500 Deferred nerd-icons by dropping :demand t plus an after-load safety net -Expected outcome: -- Move generic =lsp-mode= and =lsp-ui= defaults out of =prog-general.el=. -- Keep language-specific server variables in language modules. -- Keep one hook path per language for starting LSP. -- Preserve the remote-file guard. +=(use-package nerd-icons :demand t ...)= flipped to =:defer t=. The +=:config= block already wraps the advice + tint in lazy-on-load +semantics, so the advice now installs the first time nerd-icons +loads (typically when a feature module like =dashboard-icon-type= +or =dirvish-attributes= triggers a load). An additional +=(with-eval-after-load 'nerd-icons ...)= block at module bottom +catches the "already-loaded when this module re-evaluates" case -- +it checks =advice-member-p= so it doesn't stack the advice on every +re-eval. -Pitfalls: -- =lsp-pyright= may still need a language-specific hook to load before LSP - starts. -- Do not accidentally re-enable UI/doc/sideline behavior that was explicitly - disabled for performance. +*** DOING [#B] Harden Org workflow modules :harden: -***** TODO [#B] Add a startup smoke test for LSP config resolution :solo: +Scope: +- =org-config.el= +- =org-agenda-config.el= +- =org-babel-config.el= +- =org-capture-config.el= +- =org-contacts-config.el= +- =org-drill-config.el= +- =org-export-config.el= +- =org-noter-config.el= +- =org-refile-config.el= +- =org-reveal-config.el= +- =org-roam-config.el= +- =org-webclipper.el= +- =calendar-sync.el= +- =hugo-config.el= +- =gloss-config.el= -Keep this narrow. A useful test can require the LSP-related modules with mocked -=use-package= side effects and assert that: -- generic defaults are set in one place, -- no duplicate hook entries are installed for the same mode, -- =lsp-enable-remote= remains nil. +Review progress: +- Reviewed 2026-05-03 at high level. +- =calendar-sync.el= has substantial focused coverage for parsing, recurrence, + timezone conversion, event conversion, and regressions. The largest remaining + risks are configuration/secrets, startup side effects, and process/network + boundaries. +- =org-agenda-config.el= and =org-refile-config.el= now have useful cache tests, + but the cache lifecycle and startup idle timers still deserve a design pass. +- =org-noter-config.el= already has an older [#B] workflow VERIFY task. Do not + duplicate that work here. +- =hugo-config.el= and =org-reveal-config.el= have focused helper coverage. +- =gloss-config.el= is a thin package wrapper; no local unit-test target unless + custom glue is added. +- Deeper pass 2026-05-10 added follow-up tasks for org-roam done hooks, drill + file selection/package loading, Org export defaults, Babel templates, and + contact/Mu4e boundaries. -**** TODO [#B] Gate tree-sitter grammar auto-install behind an explicit policy :startup: +Completion review 2026-05-15: +- Re-checked the scoped Org workflow modules and their test coverage. +- The broad parser/cache/helper areas now have useful focused tests, especially + =calendar-sync.el=, agenda/refile helpers, org-roam helpers, org-noter, Hugo, + reveal, and webclipper processing. +- Remaining issues are already logged below, including security-sensitive + calendar config and Babel evaluation policy, cache lifecycle/timer behavior, + org-roam destructive workflow guardrails, executable checks, capture-template + smoke tests, and Org workflow ownership documentation. -=prog-general.el= sets =treesit-auto-install= to =t=. That means opening a file -can trigger grammar download/build/install behavior. This is convenient on a -fresh machine, but it is a startup/network/build side effect in normal editing -and batch contexts. +**** 2026-05-23 Sat @ 04:18:44 -0500 Split personal calendar config out of calendar-sync.el +=calendar-sync.el= now defaults =calendar-sync-calendars= to nil and loads the real plists from =calendar-sync-private-config-file= (an ignored file), so the engine carries no private feed tokens in source. =calendar-sync-status= / =calendar-sync-start= report missing config without erroring, and agenda startup is unaffected (tests/test-calendar-sync-no-config-startup.el). Rotating the previously-committed feed URLs remains a manual credential action — tracked under the L2557 calendar-sync hardening finding. -Expected outcome: -- Prefer ='prompt= or a custom command such as =cj/install-treesit-grammars=. -- Batch/test startup should never auto-install grammars. -- Document the intentional bootstrap path for a new machine. +**** PROJECT [#B] Normalize Org agenda/refile cache lifecycle :perf:refactor: -Originally meant to coordinate with the [#A] Python tree-sitter predicate -syntax issue. That one resolved upstream on 2026-05-14 (see =docs/python- -treesit-predicate-mismatch.txt= RESOLVED footer), so this task no longer -depends on it. +Two of three children are done (shared cache helper extracted, idle timers gated). Still open: the directory-scan-failure visibility child below. -**** 2026-05-24 Sun @ 04:30:14 -0500 Hardened clipboard git-clone process and path handling +***** 2026-05-23 Sat @ 04:18:44 -0500 Extracted a shared cache helper +=cj-cache-lib.el= now provides =cj/cache-valid-p=, =cj/cache-building-p=, and =cj/cache-value-or-rebuild=, consumed by both =org-agenda-config.el= and =org-refile-config.el=; the contract is documented in =docs/design/cache-helper-design.org=. The agenda and refile public commands are unchanged. -=cj/git-clone-clipboard-url= shelled out via =shell-command= and derived the dir with =file-name-nondirectory=, which mishandled scp-style SSH with no slash (=git@host:repo.git= → =git@host:repo=) and silently did nothing on a failed clone. Now clones as a direct =git= process (=call-process=, no shell) with =clone -- url dir= (so a =-=-leading URL can't be read as a flag); the destination comes from =cj/--git-clone-dir-name= (last component split on =/= and =:=, handling HTTPS, scp/ssh:// SSH, local paths); validates non-empty clipboard + writable target dir + non-existing destination; surfaces a non-zero git exit as a =user-error= with the =*git-clone*= output. Tests cover the deriver across schemes + empty-clipboard + clone-failure. Commit =35e4d701=. +***** 2026-05-24 Sun @ 07:26:31 -0500 Surfaced directory-scan failures instead of hiding/crashing -**** TODO [#B] Decide whether auto-executable shell scripts should be opt-in :ux: +The refile scan caught =permission-denied= and silently dropped the dir, and crashed outright on a missing root (only permission-denied was caught, so a missing =code-dir=/=projects-dir= raised =file-missing= and aborted the build); the agenda build had the same missing-dir crash via =directory-files=. Extracted =cj/--org-refile-scan-dir= (warns + returns nil for missing/unreadable/permission-denied so the scan continues) and guarded the agenda scan the same way. Also fixed a latent bug found here: =org-refile-targets= was never declared special, so under =make compile= =cj/org-refile-in-file= let-bound it lexically and the scoped targets never reached =org-refile= — added =(defvar org-refile-targets)=. Tests cover the helper + the agenda missing-dir guard. Commit =12fb0108=. -=prog-shell.el= adds a global =after-save-hook= that sets executable bits on any -saved file with a shebang. This is convenient, but it silently changes file -modes for every buffer in the session. +***** 2026-05-23 Sat @ 04:18:44 -0500 Gated cache idle timers out of batch +Both cache builders' =run-with-idle-timer= calls are wrapped in =(unless noninteractive)= (=org-refile-config.el:105=, =org-agenda-config.el:203=), so requiring the modules in batch schedules nothing. =tests/test-architecture-startup-contracts.el= scans every module and asserts there are no unguarded top-level timer forms. -Expected outcome: -- Decide whether this should remain global, be limited to shell/script modes, or - prompt the first time per file. -- Preserve the fast path for real scripts. -- Keep the existing =cj/make-script-executable= tests updated for the chosen - policy. +**** 2026-05-23 Sat @ 19:48:00 -0500 Made org-confirm-babel-evaluate default to t with a toggle -**** 2026-05-25 Mon @ 18:05:56 -0500 Moved JSON/YAML/webdev formatters to argv process calls +=org-babel-config.el= set =org-confirm-babel-evaluate= to nil globally, so every source block in every Org file (cloned repos, downloaded notes, web clips) ran without confirmation. Changed the default to =t= (confirm before running). Replaced the old =babel-confirm= command (which reported, and toggled only with a prefix arg) with =cj/org-babel-toggle-confirm=, a plain toggle bound to =C-; k= for flipping confirmation off in trusted files and back on. 3 ERT tests cover the toggle both directions plus the binding. -Replaced =shell-command-on-region= with =call-process-region= (explicit program -+ argv, no shell) in cj/json-format-buffer (jq), cj/yaml-format-buffer -(prettier), and cj/webdev-format-buffer (prettier). The webdev path dropped its -=shell-quote-argument= once the filename became a plain argv element. Point -preservation is unchanged. One deliberate, tested improvement: the old code -clobbered the buffer with the formatter's error text on a non-zero exit; the new -per-module =cj/--<lang>-format-region= helper captures output, checks the exit -code, replaces only on success, and otherwise raises a user-error with stderr. -Kept a small helper in each of the three modules rather than one shared one, -since they share no module short of system-lib. Added argv-invocation and -no-clobber tests per formatter; existing wiring tests stay green. Done by -subagent, reviewed. +**** TODO [#B] Rebind babel-confirm toggle off =C-; k= :keybinding:solo:discuss: -**** 2026-05-16 Sat @ 03:54:56 -0500 Added cj/executable-find-or-warn checks for prettier and pyright at load time +=cj/org-babel-toggle-confirm= landed on =C-; k= as a placeholder. Pick a permanent home — likely under an Org-specific prefix rather than the global =C-;= map. -=modules/prog-webdev.el:34-40= declares =prettier-path= and -=modules/prog-python.el:33-40= declares =pyright-path= as string -literals. No validation at module load means a missing executable -surfaces only at first use -- format-on-save fires, then errors -mid-edit, then the user has to discover why. Wrap with -=cj/executable-find-or-warn= (already in =system-lib.el=) at module -load time so the missing dependency is reported up front. +Triggered by: 2026-05-23 org-confirm-babel-evaluate hardening. -**** 2026-05-16 Sat @ 03:54:56 -0500 Documented keyboard-compat hook idempotence (already correct) +**** 2026-05-24 Sun @ 14:43:13 -0500 Guarded move-branch-to-roam against data loss -=modules/keyboard-compat.el:169-174= adds the frame-setup hook -unconditionally. If the module is required twice (e.g. via two -=eval-after-load= chains in different load orders), the hook runs -twice per new frame and installs duplicate =key-translation-map= -entries. Wrap the =add-hook= in a guard, or use a named function -and rely on =add-hook='s own duplicate-check. +The command cut the subtree from the source before writing the new roam file, so any failure in demote/format/write/db-sync lost the subtree with no rollback. Reordered to write and verify the file on disk before =org-cut-subtree=, so a failed write aborts with the source intact. Added a no-clobber guard (refuse an existing target file) and a confirmation prompt for large subtrees (>= =cj/move-org-branch-confirm-lines=, 30) or buffers with unsaved changes. Decided: leave the source buffer modified and undoable rather than auto-saving, so the move stays reversible. New test drives the write-failure-preserves-source invariant via an unwritable roam dir. Commit =5c0fa15d=. -**** 2026-05-16 Sat @ 03:54:56 -0500 Wired F6 TypeScript clause to npx vitest|jest +**** 2026-05-25 Mon @ 18:29:40 -0500 Already done — clip URL/title scoped to dynamic bindings -=modules/dev-fkeys.el:261-269= maps =tsx= to =typescript= in the -language detection table. =modules/dev-fkeys.el:347-349= -(=cj/--f6-test-runner-cmd-for=) has no clause for =typescript= -- -the catch-all =(_)= returns nil, so F6 errors instead of routing to -a real runner. Either add a =typescript= → =jest=/=vitest= clause -or remove the =tsx= mapping until the runner side is implemented. +Found this already shipped in =6dfc41af= ("refactor(webclipper): scope clip +URL/title to dynamic bindings", 2026-05-24). The temp vars =cj/--webclip-url= / +=cj/--webclip-title= are now =let=-bound around the org-capture call instead of +=setq='d and manually cleared, so they unwind on every exit path including a +=C-g= abort — which covers the "aborted captures clear temp state" outcome more +completely than a finalize hook would. The bookmarklet/org-protocol workflow is +unchanged. =tests/test-org-webclipper-commands.el= already covers the +leaves-no-stale-state and aborted-capture-clears-state cases. No new work needed. -**** 2026-05-16 Sat @ 03:54:56 -0500 Fixed prog-lsp eldoc-provider removal to act on the global hook +**** 2026-05-25 Mon @ 17:51:17 -0500 Guarded external-tool assumptions in Org export/publishing -=modules/prog-lsp.el:51-54,76= attaches -=cj/lsp--remove-eldoc-provider= globally to =lsp-managed-mode-hook= -but the removal it performs uses =(remove-hook ... t)= -- a -buffer-local removal. The first LSP buffer activates the hook, -which removes the provider for that buffer. Subsequent LSP buffers -still inherit the global default because the hook itself never -re-fires the buffer-local removal in their context. Either make -the hook itself buffer-local-friendly (add it inside -=lsp-managed-mode-hook= per-buffer) or remove from the global -provider list once instead of per-buffer. +Added command-time guards to four export/publishing commands so a missing tool +fails with a user-error that names it, instead of an opaque process error (or, +for reveal.js, a silently broken presentation): +- =org-export-config.el=: zathura check in my/org-pandoc-export-to-pdf-and-open. +- =hugo-config.el=: hugo binary check in cj/hugo-preview, and the platform + file-manager opener check in cj/hugo-open-blog-dir-external. +- =org-reveal-config.el=: extracted =cj/--reveal-ensure-root= (checks the local + reveal.js clone, points at scripts/setup-reveal.sh), called from + cj/reveal-export and cj/reveal-preview-start. +- =org-webclipper.el=: pandoc check in cj/org-protocol-webclip-handler, the + single path that shells out to pandoc via org-web-tools. -**** 2026-05-16 Sat @ 03:54:56 -0500 Externalized LanguageTool script path via user-emacs-directory +All checks run at command time, not load, so startup stays quiet. Each guard +has a user-error test; existing happy-path tests now stub the lookups. Things +deliberately not guarded: hugo-publish (magit, internal), the preview filter +(browse-url, internal), hugo-export-post (ox-hugo, Elisp). Done with four +parallel implementation agents, reviewed individually; full suite green. -=modules/flycheck-config.el:69= hardcodes -=~/.emacs.d/scripts/languagetool-flycheck= as the LanguageTool wrapper. -Users running from a non-standard =user-emacs-directory= (or anyone -auditing the module against a future package) get a broken checker. -Replace with =(expand-file-name "scripts/languagetool-flycheck" -user-emacs-directory)= or a defcustom. +**** 2026-05-16 Sat @ 03:44:45 -0500 Guarded org-roam completed-task hook with cj/--org-roam-should-copy-completed-task-p -**** 2026-05-16 Sat @ 03:54:56 -0500 Replaced hardcoded Zathura viewer with executable-find candidate list +=org-roam-config.el= adds a global =org-after-todo-state-change-hook= that +copies newly completed tasks to today's org-roam journal. The hook assumes the +current Org buffer is visiting a file: -=modules/latex-config.el:28= sets the LaTeX viewer to =zathura= -unconditionally. macOS / Windows users and anyone who prefers a -different PDF viewer lose document review without explanation. -Resolve via =executable-find= over a candidate list (=zathura=, -=evince=, =okular=, =Preview.app= via =open=, =SumatraPDF.exe=) and -fall back to =pdf-tools=. +- It calls =(buffer-file-name)= and passes the result to =string=. +- =cj/org-roam-copy-todo-to-today= later compares =file-truename= of the daily + file and the current buffer file. -**** 2026-05-15 Fri @ 18:49:24 -0500 Fixed abbrev-mode no-arg toggle in =cj/prose-helpers-on= +That can error in capture buffers, indirect buffers, temporary Org buffers, or +other fileless Org workflows. -Replaced the =(if (not (abbrev-mode)) (abbrev-mode))= shape with -=(unless (bound-and-true-p abbrev-mode) (abbrev-mode 1))= and the same -for =flycheck-mode= in =modules/flycheck-config.el:36-42=. Dropped -"flyspell" from the docstring (the commented-out -=cj/flyspell-on-for-buffer-type= line had been gone for a while; the -docstring was lying) and removed the stale comment marker. +Expected outcome: +- Extract a predicate for "should copy this completed task to today's journal". +- Skip fileless buffers, calendar sync files, aborted capture buffers, and tasks + already in the target daily file. +- Keep the normal completed-task journal workflow unchanged. +- Add tests for fileless buffers, =gcal-file=, already-daily buffers, and a + normal project/todo buffer. -Added =tests/test-flycheck-config-prose-helpers-on.el= -- 4 tests -covering Normal (both modes off -> each enabled once with a positive -arg) and Boundary (both on -> no-op; each mixed state -> only the off -one enabled). The "both on -> no-op" assertion is the regression -guard for the no-arg toggle shape: it would record a =(nil)= call list -under the bug and a =()= call list under the fix. +**** 2026-05-24 Sun @ 04:30:14 -0500 Shared one validated drill-file selector -Test infra needed an explicit =(defvar abbrev-mode)= / -=(defvar flycheck-mode)= at the top of the test file: with -=lexical-binding: t= and flycheck loaded =:defer t=, =let= on the -flycheck-mode symbol creates a lexical-only binding the production -code's =bound-and-true-p= can't see; declaring both as special makes -=let= dynamic and the test stable. +org-capture-config.el and org-drill-config.el each scanned =drill-dir= with an inline =directory-files= call, so a missing/empty/unreadable dir surfaced as a low-level error or an empty =completing-read= depending on which command ran. Added =cj/--drill-files-or-error=, the single validated entry point: clear =user-error= when the dir is missing, unreadable, or has no drill files; otherwise the list. =cj/--drill-pick-file= and both drill capture templates route through it; the pure =cj/--drill-files-in= primitive and its tests are unchanged. Tests cover missing/empty/non-org/normal. Commit =49038c41=. -Full suite: =make test= exits 0; 468 lines of output with =ALL UNIT -TESTS PASSED= banner; no regressions. +**** 2026-05-24 Sun @ 14:43:13 -0500 Removed contradictory org-export-with-tasks default -*** DOING [#B] Harden integrations and application modules :harden: +=org-export-config.el= set =org-export-with-tasks= twice (=("TODO")= then =nil=); the final =nil= won but the stale first line + comment contradicted it. Removed the leftover. =nil= (export no tasks) is the deliberate default — it was already winning, its comment matches, and it sits with the adjacent "without tags / section numbers by default" settings. Added a smoke test that fires the deferred =ox= :config and pins the value to =nil=. Commit =94ef5242=. -Scope: -- AI/rest: =ai-config.el=, =ai-conversations.el=, =restclient-config.el= -- Mail/chat/social: =mail-config.el=, =mu4e-*.el=, =slack-config.el=, - =erc-config.el=, =elfeed-config.el=, =eww-config.el= -- File/media/apps: =dirvish-config.el=, =dwim-shell-config.el=, =pdf-config.el=, - =calibredb-epub-config.el=, =music-config.el=, =quick-video-capture.el=, - =video-audio-recording.el=, =transcription-config.el= -- Utilities/apps: =auth-config.el=, =browser-config.el=, =dashboard-config.el=, - =help-config.el=, =help-utils.el=, =jumper.el=, =keyboard-macros.el=, - =local-repository.el=, =lorem-optimum.el=, =reconcile-open-repos.el=, - =show-kill-ring.el=, =system-commands.el=, =system-utils.el=, - =tramp-config.el=, =undead-buffers.el=, =weather-config.el=, =wrap-up.el= +**** 2026-05-23 Sat @ 03:48:50 -0500 Fixed java structure-template typo and pinned the aliases +=("java" . "src javas")= expanded to a bogus =#+begin_src javas=; corrected it to =src java=. Added =test-org-babel-config-structure-templates.el=, which requires the module then org-tempo (firing the deferred :config) and asserts =bash=, =zsh=, =el=, =py=, =json=, =yaml=, =java= each map to the intended src language. Fixed in the org-babel commit. -Review progress: -- Reviewed 2026-05-03 at high level by direct reads plus risky-pattern search. -- Recording/transcription and music modules have much stronger coverage than - most application wrappers. -- Existing coverage audit already tracks =ai-conversations=, =quick-video-capture=, - =dashboard-config=, =mail-config=, =show-kill-ring=, =system-commands=, and - =wrap-up= as high-value test targets. +**** TODO [#B] Make org-contacts/Mu4e boundaries explicit :cleanup:refactor: -Completion review 2026-05-15: -- Re-checked the scoped integration/application modules with risky-pattern and - test-coverage searches. -- Many integration modules now have focused tests, including AI config, - restclient, mail helpers, Slack commands, Dirvish helpers, music, - recording/transcription, system commands, browser/help/jumper/reconcile, and - undead buffer helpers. -- Remaining issues are already logged below, especially system command safety, - REST key persistence, mail privacy/lifecycle policy, quick-video timers and - temp state, shell-heavy dwim/recording command hardening, AI conversation - persistence coverage, calendar operational behavior, Dirvish dependency/path - hardening, EWW/Elfeed network helpers, and Slack which-key registration. +=org-contacts-config.el= defines helpers that call Mu4e functions when the +current major mode is a Mu4e mode, and the =use-package org-contacts= block is +=:after (org mu4e)= while also requiring =mu4e= inside =:config=. This works in +the current eager setup, but the ownership boundary is unclear now that +=mu4e-org-contacts-integration.el= exists. -**** 2026-05-24 Sun @ 04:15:36 -0500 Made Emacs restart and destructive confirms defensive +Expected outcome: +- Decide whether contact capture-from-email behavior belongs in + =org-contacts-config.el= or the Mu4e integration modules. +- Add =declare-function= / autoloads or move Mu4e-specific code behind + =with-eval-after-load 'mu4e=. +- Keep plain Org contact commands usable on systems without Mu4e loaded. +- Add a smoke test for loading =org-contacts-config.el= without Mu4e stubs if + practical. -Restart-Emacs scheduled an unconditional =kill-emacs= one second after firing the systemctl restart, so a missing or failed service killed the session with nothing to replace it. Restart now guards on =(daemonp)= and a present =emacs.service= (new =cj/system-cmd--emacs-service-available-p= via =systemctl --user cat=) before doing anything, and drops the separate =kill-emacs= — =systemctl restart= cycles the daemon itself, so a failed restart leaves the current Emacs alive. Shutdown and reboot moved to a strong =yes-or-no-p= confirm (a stray RET/space on the old quick prompt could power off the machine); logout and suspend keep the quick confirm since they are recoverable. Tests cover service detection, both restart guards, and the strong-confirm paths with system primitives stubbed. Commit =f1dbec16=. +**** TODO [#B] Add an Org workflow health check command :feature:ux:solo:discuss: -Not done: the detached restart+reconnect (=nohup sh -c '... && emacsclient -c'=) may still race systemd's cgroup teardown of =emacs.service= before =emacsclient -c= runs. Couldn't verify from here without cycling the live daemon — eyeball the reconnect on the next real restart. +Several Org workflow modules depend on personal paths, optional external tools, +and local package checkouts. Failures currently show up at command time in +different ways, depending on which module hits the missing dependency first. -**** 2026-05-23 Sat @ 19:01:53 -0500 Removed SkyFi key-injection feature from restclient-config +Recommended improvement: +- Add a lightweight =cj/org-workflow-doctor= command that checks the main Org + workflow prerequisites without mutating user data. +- Report status for core files/directories: =org-dir=, =roam-dir=, =drill-dir=, + =contacts-file=, =webclipped-file=, =cj/hugo-content-org-dir=, and + =cj/reveal-root=. +- Report optional executable/package availability for Pandoc/org-web-tools, + Hugo, reveal.js, org-drill, org-roam, and org-noter. +- Keep startup quiet; run this only on demand. +- Make the checker return structured data so it can be unit-tested and displayed + either in Messages or a buffer. -Resolved by removing the feature rather than hardening it. =cj/restclient-skyfi-buffer= opened =data/skyfi-api.rest= in a file-visiting buffer and rewrote the =:skyfi-key= line with the real key from authinfo, so an accidental save would persist the key to local disk (the file was gitignored and never tracked, so no repo/public-mirror exposure — local plaintext only). Deleted =cj/skyfi-api-key=, =cj/restclient--inject-skyfi-key=, =cj/restclient-skyfi-buffer=, the =C-; R s= binding, the two SkyFi test files, and the local =data/skyfi-api.rest= template. Generic restclient (=C-; R n=, =C-; R o=, restclient/restclient-jq) kept. +**** 2026-05-24 Sun @ 14:43:13 -0500 Added capture-template key + target smoke tests -**** TODO [#B] Reconcile mail image/privacy settings :privacy: +New =test-org-capture-templates-integrity.el= loads the cleanly-loadable capture modules (=org-capture-config=, =quick-video-capture=, =org-contacts-config=), applies their lazy additions, and asserts no two templates share a dispatch key and that every symbol-valued file target resolves to a non-empty path string. Literal-string targets (the video template's no-save =(file "")=) and lambda targets (drill file pickers) are excluded. Webclipper templates need org-web-tools at registration time, so they stay covered by their own test rather than this batch smoke test. Mutation-checked that the uniqueness assertion flags a duplicate key. Commit =2e3905c7=. -=mail-config.el= documents blocked remote images and sets -=gnus-blocked-images=, but later enables both =mu4e-show-images= and -=mu4e-view-show-images=. The interactive toggle changes =gnus-blocked-images= -buffer-locally, so the final privacy behavior is hard to reason about without -manual testing against real HTML messages. +**** TODO [#B] Document Org workflow module ownership and load boundaries :docs:refactor:solo:discuss: -Expected outcome: -- Decide the default policy for embedded images versus remote HTTP images. -- Make the toggle report the effective state in the current mu4e view buffer. -- Add a short manual checklist or mocked test for the variables that control - remote image display. +The Org workflow is spread across many modules with overlapping responsibilities: +capture templates, keymaps, org-protocol handlers, refile/agenda target +construction, roam notes, publishing, and document annotation. The code is +usable, but future load-order work will be easier with explicit ownership notes. -**** 2026-05-23 Sat @ 03:52:00 -0500 Set compose buffers to kill on exit, both composers -First clarified the ownership (dd671f8c): the org-msg comment "always kill buffers on exit" was backwards — org-msg set =nil= (keep), which won over mu4e's =t= because org-msg-mode runs in every compose buffer. Craig then chose to kill compose buffers on exit, so I set the org-msg value to =t= as well (82978c79). Both mu4e and org-msg now kill the buffer on send/exit, so HTML drafts don't linger. +Recommended improvement: +- Add a short design note under =docs/design/= that maps each Org module to the + behavior it owns. +- Call out which modules may mutate global Org variables, capture templates, + keymaps, and protocol handlers. +- Define which modules should be safe to load in batch mode and which are + allowed to start timers or require interactive packages. +- Link this note from the Org workflow review task and the broader load-graph + refactor. -**** 2026-05-24 Sun @ 07:26:31 -0500 Dropped startup timers for lazy protocol init +**** 2026-05-16 Sat @ 03:44:45 -0500 Removed duplicate org-protocol-protocol-alist registration in cj/webclipper-ensure-initialized -=quick-video-capture.el= scheduled an =after-init-hook= idle timer + a 2s fallback =run-with-timer= to call setup, which required org-protocol/capture and registered both the protocol handler and the capture template at every startup. Split the concerns like =org-webclipper.el=: the org-protocol handler registers in a =with-eval-after-load 'org-protocol= block (lightweight =add-to-list=, in place whenever org-protocol loads — org-config requires it at startup), and =cj/setup-video-download= now registers only the capture template lazily (first capture or first protocol call). Both timers gone. Tests pin that setup registers the template idempotently and no longer touches the protocol alist; verified in a live daemon that the protocol registers on load. Commit =bc965275=. +The =webclip= protocol handler is registered twice: +=modules/org-webclipper.el:72-76= inside =cj/webclipper-ensure-initialized= +(unconditional =add-to-list=) and =:207-214= inside a +=with-eval-after-load 'org-protocol= block (=unless (assoc ...)= guard). +=add-to-list= uses =equal= membership so the two are effectively +idempotent, but maintaining two registration paths invites drift if +the alist entry shape ever changes. Pick one site -- the +=with-eval-after-load= block is the more robust location -- and +remove the other. -**** 2026-05-24 Sun @ 04:30:14 -0500 Scoped video-capture URL to a dynamic binding +**** 2026-05-16 Sat @ 03:44:45 -0500 Validated :url and :title in cj/org-protocol-webclip before stashing -The protocol handler =setq= a global =cj/video-download-current-url= and the capture handler read/cleared it, so an aborted or erroring capture left the stale URL for the next manual capture. Renamed to =cj/--video-download-url= and =let=-bind it around the =org-capture= call instead of mutating a global: the binding lives only for the capture's dynamic extent, so the handler sees the URL while the capture runs and an abort/error unwinds it automatically — no stale state, no manual clear. Manual invocation still prompts. Tests cover bound-URL download, manual prompt, empty-URL error, URL-visible-during-capture, and aborted-capture-leaves-nothing. Commit =b26b74cb=. +=modules/org-webclipper.el:124-125= extracts =:url= and =:title= from +the incoming protocol plist with no type or nil check. An unexpected +plist shape silently sets the globals to nil, and downstream code +fails inside the capture handler with confusing messages. Guard with +=(unless (and (stringp url) (not (string-empty-p url))) (user-error ...))= +before stashing. -Note: the sibling =org-webclipper.el= still uses the same global-mutation pattern (=cj/webclip-current-url= / =title=); a separate =:solo:= task tracks that. +**** 2026-05-24 Sun @ 07:26:31 -0500 Scoped webclip URL/title to dynamic bindings -**** TODO [#B] Audit shell-command-heavy recording and dwim-shell workflows :security:refactor: +The protocol handler =setq= globals =cj/webclip-current-url= / =cj/webclip-current-title= that the "W" template and handler read (and cleared), so an aborted/erroring capture left stale state for the next clip. Renamed to =cj/--webclip-url= / =cj/--webclip-title= and =let=-bind them around the =org-capture= call: the template =%(identity ...)= forms and the handler run within that dynamic extent, and an abort/error unwinds the binding automatically — no stale state, no manual clear. Mirrors the quick-video-capture fix. Tests updated to the new contract (visible-during-capture, nothing-left-after, aborted-leaves-nothing). Commit =6dfc41af=. -=video-audio-recording.el= and =dwim-shell-config.el= are intentionally close to -the shell: pactl/ffmpeg/qpdf/7z/tesseract/media conversion commands are the -point. They also have the highest process and quoting surface in the config. +**** 2026-05-16 Sat @ 03:44:45 -0500 Declared cross-module free vars in mu4e-org-contacts-integration.el -Expected outcome: -- Keep the current workflows, but catalog which commands accept filenames, - URLs, passwords, or free-form user input. -- Prefer argv process APIs for commands that do not require a shell. -- For commands that must use shell templates, document which placeholders are - safely quoted by =dwim-shell-command= and add focused tests around password - temp-file cleanup. +The module reads =contacts-file= (defined in =user-constants.el=) and +calls =cj/get-all-contact-emails= (defined in =org-contacts-config.el=) +without any forward declaration at the top of the file. Byte-compile +in isolation warns about both as free variables / unknown functions. +Add =(eval-when-compile (defvar contacts-file))= and +=(declare-function cj/get-all-contact-emails "org-contacts-config")= +near the existing requires so the compile is clean and the +cross-module dependency is explicit at the top of the file. -***** 2026-05-23 Sat @ 19:11:30 -0500 Fixed async password temp-file lifetime in dwim-shell +**** 2026-05-25 Mon @ 17:10:47 -0500 Added mu4e org-contacts completion coverage -The four password commands (PDF protect/unprotect, remove-zip-encryption, create-encrypted-zip) deleted the password temp file in =unwind-protect= the instant the async command launched, so =qpdf=/=7z= could start after the file was gone. Extracted =cj/dwim-shell--run-with-password-file= + =cj/dwim-shell--password-cleanup-callback=: the temp file (mode 600) is now deleted from an =:on-completion= callback that fires after the process exits (success or failure), with the synchronous =unwind-protect= kept only as a pre-launch-failure backstop. Rewrote all four commands onto the helper. 5 ERT tests cover the cleanup callback (success/error/missing-file) and the runner (writes 600 file + defers cleanup; cleans up on launch failure). qpdf already passes the password via =--password-file= (out of argv); the 7z argv exposure is split into its own follow-up below. +Added =tests/test-mu4e-org-contacts-integration.el= (10 tests). The capf +(cj/org-contacts-completion-at-point) is checked for the header-field and +compose-mode gating both ways, the bounds/table it returns when contacts +exist, and the empty-contacts case. TAB (cj/mu4e-org-contacts-tab-complete) +is checked across all three branches: completion-at-point in a header, +org-cycle in the org-msg body, indent elsewhere. Comma completion and the +direct-insert no-op-outside-header path round it out. mail-abbrev-in-expansion-header-p, +the mode actions, and cj/get-all-contact-emails are stubbed, so the run is +headless with no mu4e/org-contacts dependency. -***** 2026-05-24 Sun @ 04:20:31 -0500 Accepted the brief 7z password-on-argv exposure, documented it +*** DOING [#B] Harden programming workflow modules :harden: -Investigated whether 7z could take the password off argv. It can't: 7-Zip 26.01 reads the password only from its controlling TTY, not stdin or a file. Verified empirically — =printf pw | 7z a -p ...= silently created an archive with an *empty* password (the piped value never reaches it), and a round-trip with the same password failed. So the password must go on argv via =$(cat tempfile)= and is briefly visible in the process list while 7z runs. +Scope: +- =prog-c.el= +- =prog-general.el= +- =prog-go.el= +- =prog-json.el= +- =prog-lisp.el= +- =prog-lsp.el= +- =prog-python.el= +- =prog-shell.el= +- =prog-training.el= +- =prog-webdev.el= +- =prog-yaml.el= +- =coverage-core.el= +- =coverage-elisp.el= +- =test-runner.el= +- =vc-config.el= +- =keyboard-compat.el= +- =dev-fkeys.el= -Craig's call (2026-05-24): accept the exposure rather than switch off the .7z format. On a single-user workstation, for a short-lived process, with the password already kept out of shell history by the mode-600 temp file, the residual exposure is acceptable. The gpg-wrapped-tar alternative would close it but change the archive format and decrypt workflow. Recorded the tradeoff in both function docstrings in =dwim-shell-config.el= so the decision is visible at the call site, not just here. +Review progress: +- Reviewed 2026-05-03 at high level. +- =dev-fkeys.el= reviewed 2026-05-03 after local edits settled. The focused + dev-fkeys test set passed: 22 test files, 163 ERT tests. +- =coverage-core.el= / =coverage-elisp.el= have strong pure-helper tests. +- Language formatter wiring is covered for Python, Go, shell, webdev, JSON, and + YAML. +- =test-runner.el= has direct tests, but project-scoping is still a design gap. -***** 2026-05-23 Sat @ 19:18:00 -0500 Quoted/validated user-controlled dwim-shell inputs +Completion review 2026-05-15: +- Re-checked the scoped programming workflow modules and current tests. +- =dev-fkeys.el=, coverage modules, formatter wiring, keyboard compatibility, + and test-runner helpers have meaningful focused coverage. +- Remaining issues are logged below: F4 project capability classification, + LSP ownership and smoke coverage, tree-sitter auto-install policy, Git clone + process handling, shell-script executable policy, and formatter process + boundaries. -Closed the four injection-quoting cases. git-clone-clipboard-url now validates the clipboard with =cj/dwim-shell--valid-git-url-p= and passes the URL via =shell-quote-argument= instead of the raw =<<cb>>= substitution. GPG recipient and the 7z archive name go through =shell-quote-argument= instead of hand-written single quotes. The ffmpeg thumbnail timestamp is validated with =cj/dwim-shell--valid-ffmpeg-timestamp-p= (digits/colons/dot only) before it reaches =-ss=. The sequential-rename prefix is validated filename-safe with =cj/dwim-shell--safe-rename-prefix-p=. 7 ERT tests cover the three validators (Normal/Boundary/Error); the two =shell-quote-argument= swaps trust the builtin. The fifth case — video concatenation's echo/tr/sed filelist — is a redesign rather than a quoting fix and is split out below. +**** 2026-05-25 Mon @ 17:35:02 -0500 Added prog-lisp smoke coverage; assessed the other two -***** 2026-05-23 Sat @ 19:58:00 -0500 Rebuilt video-concat filelist in Elisp +Added =tests/test-prog-lisp.el= (4 tests) covering the config prog-lisp owns +directly: cj/elisp-setup and cj/common-lisp-setup are each registered on their +mode hook and apply the right buffer locals (4-space/no-tabs/fill-120 for +elisp, 2-space/fill-100 for Common Lisp). The module loads with use-package +stubbed to a no-op, so nothing installs or downloads in batch. -=cj/dwim-shell-commands-concatenate-videos= built the ffmpeg concat list with =echo '<<*>>' | tr ' ' '\n' | sed 's/^/file /'=, which split on spaces and broke on quotes. Extracted =cj/dwim-shell--build-concat-filelist=, which renders each path as an escaped =file '...'= line (single quotes escaped as ='\''=), writes it to a temp file in Elisp, and runs =ffmpeg -f concat -i <quoted-listfile>= with a trailing =; rm -f= to clean up after the process exits. =<<*>>= stays only as an inert trailing shell comment so dwim-shell still runs one command over all marked files. 3 ERT tests cover plain paths, spaces, and an embedded quote. +=prog-training.el= got no test: it's entirely deferred use-package config with +no top-level surface, and its only owned settings (leetcode language/dir) live +in a deferred =:config= that would make the test package-dependent for no real +value. Forcing a test there would be coverage theater. -***** 2026-05-23 Sat @ 20:17:00 -0500 Clarified broad/misleading file-operation commands +=prog-general.el= is deferred: it's the one of the three that touches LSP and +tree-sitter, and the task itself says to wait for the LSP/tree-sitter policy +tasks to land before fixing its assertions. Its smoke coverage rides with those. -=remove-empty-directories= ran =find . -type d -empty -delete= from the ambient current directory. Now it prompts for an explicit root (via =read-directory-name=), names that root in the confirmation, and runs =find <quoted-root> ...= built by =cj/dwim-shell--empty-dirs-command= (2 ERT tests cover the command shape + space quoting). =secure-delete= called =shred= without =-u=, overwriting file contents but leaving the file in place despite the name and the "permanently destroy" prompt; added =-u= (=shred -vfzu=) so it actually unlinks. Both use the inert =<<*>>= comment trick for single-execution. +**** TODO [#B] Revisit F4 project classification vs actual project capabilities :ux: -***** 2026-05-24 Sun @ 04:10:20 -0500 Shell-quoted X11 and audio recording command paths +=dev-fkeys.el= classifies a project as =interpreted= if it has +=pyproject.toml=, =requirements.txt=, =Pipfile=, or =package.json=, even when it +also has a =Makefile=. That intentionally keeps Python/Node projects on a +Run-only F4 menu, but it also hides useful Compile/Clean options for projects +where =Makefile=, =package.json= scripts, or Projectile cached commands provide +real build/test tasks. -The Wayland =wf-recorder= path already quoted its args, but the X11 =ffmpeg= path and the audio-only =ffmpeg= path interpolated mic device, system device, and output filename raw — breaking on directories with spaces or unusual device names. Wrapped all three in =shell-quote-argument= on both paths. Extracted =cj/recording--build-audio-command= (mirroring =cj/recording--build-video-command=) so the audio command is unit-testable, then quoted there. Tests cover device names and filenames with spaces on both builders. Commit =39795e85=. +Expected outcome: +- Decide whether F4 should classify by language family or by available + capabilities. +- Consider deriving candidates from Projectile's known compile/run/test commands + first, then falling back to markers. +- Keep the current "interpreted markers win" behavior only if that remains the + intentional UX after trying it in mixed Python/Node projects. -***** 2026-05-24 Sun @ 04:10:20 -0500 Scoped wf-recorder stop signal to our own process +**** PROJECT [#B] Consolidate LSP ownership across programming modules :architecture:refactor: -Stop ran =pkill -INT wf-recorder=, signalling every wf-recorder on the system including an unrelated screen capture. Added =cj/recording--interrupt-child-wf-recorder=, which scopes the producer-first interrupt to the wf-recorder child of our own recording shell via =pkill -P <shell-pid>=. Producer-first ordering preserved (ffmpeg still sees a clean pipe EOF). The orphan-cleanup at recording start stays a broad by-name kill on purpose — those leftovers come from crashed sessions whose shells are already dead, so there is no live PID to scope to. Tests cover the scoped call, the nil-PID no-op, and that the bare system-wide form is never used. Commit =556f48a2=. +LSP setup is currently split across =prog-general.el=, =prog-lsp.el=, and each +language module. There are multiple =use-package lsp-mode= forms and some +conflicting defaults: +- =prog-general.el= enables snippets/UI doc/sideline behavior. +- =prog-lsp.el= disables snippets/UI doc/sideline-heavy behavior. +- Python, Go, shell, C, and webdev modules both call =lsp-deferred= from local + setup functions and add package hooks that call =lsp-deferred= again. -***** 2026-05-24 Sun @ 04:10:20 -0500 Created the selected recording directory, not its parent +This probably works because lsp-mode is defensive, but it makes the final +runtime policy hard to predict. -The toggles ran =(file-name-directory location)= before =make-directory=, which returns the *parent* for a path without a trailing slash — so the selected directory went uncreated and ffmpeg failed to write into it. Both toggles now route the destination through =cj/recording--normalize-recording-dir= (expand + =file-name-as-directory=) and =make-directory= that, creating the selected directory itself (including names with spaces). Tests cover trailing-slash normalization, idempotence, spaces, and relative-to-absolute expansion. Commit =dc033c75=. +***** TODO [#B] Make =prog-lsp.el= the single owner of generic LSP policy :refactor: -**** TODO [#B] Make AI conversation persistence path-safe and project-aware :cleanup:refactor: +Expected outcome: +- Move generic =lsp-mode= and =lsp-ui= defaults out of =prog-general.el=. +- Keep language-specific server variables in language modules. +- Keep one hook path per language for starting LSP. +- Preserve the remote-file guard. -=ai-conversations.el= has good pure helper seams but is currently untested in -this repo. The path slugging is simple and the save/load/delete commands operate -directly in a single global directory. +Pitfalls: +- =lsp-pyright= may still need a language-specific hook to load before LSP + starts. +- Do not accidentally re-enable UI/doc/sideline behavior that was explicitly + disabled for performance. -Expected outcome: -- Add tests for candidate sorting, topic slug collisions, autosave path setup, - and delete confirmation behavior. -- Consider whether conversations should remain global or support project-scoped - subdirectories. -- Confirm autosave never writes partial prompt/response state to an unexpected - file after loading a different conversation. +***** TODO [#B] Add a startup smoke test for LSP config resolution :solo: -**** TODO [#B] Harden calendar sync operational behavior around the parser :data:refactor: +Keep this narrow. A useful test can require the LSP-related modules with mocked +=use-package= side effects and assert that: +- generic defaults are set in one place, +- no duplicate hook entries are installed for the same mode, +- =lsp-enable-remote= remains nil. -=calendar-sync.el= has broad parser/recurrence coverage, but the operational -path around it still has startup, persistence, and fetch risks. +**** TODO [#B] Gate tree-sitter grammar auto-install behind an explicit policy :startup: + +=prog-general.el= sets =treesit-auto-install= to =t=. That means opening a file +can trigger grammar download/build/install behavior. This is convenient on a +fresh machine, but it is a startup/network/build side effect in normal editing +and batch contexts. Expected outcome: -- Move private calendar URLs out of source and rotate the exposed feed URLs - before doing further cleanup. -- Avoid immediate network fetches at module load unless explicitly enabled for - interactive sessions. -- Add a per-calendar in-flight guard so a timer tick cannot launch overlapping - syncs for the same calendar. -- Use =curl --fail= or equivalent status handling so HTTP error pages are not - treated as successful ICS downloads. -- Write generated Org files atomically via a temp file and rename. -- Read the local state file with =read-eval= disabled. - -**** 2026-05-23 Sat @ 04:18:44 -0500 AI conversation persistence coverage already in place -Premise was stale. =tests/test-ai-conversations.el= (47 cases) already covers slug generation, timestamp parsing, candidate sorting (newest/oldest), latest-file selection, save/load header stripping against a temp dir, autosave path/timer, and delete confirmation — with GPTel stubbed throughout. Acceptance list satisfied; no new file needed. - -**** 2026-05-23 Sat @ 03:31:12 -0500 Dirvish helper coverage already in place -The task premise was stale: =dirvish-config.el= now has 14 focused test files (=test-dirvish-config-*.el=, ~100 cases) covering duplicate-naming, resolve-display-path (project/home/absolute/org-link), ediff-pair, html/printable predicates, playlist filtering/sanitizing, wallpaper-program mapping, and the public wrappers. The remaining gaps (playlist name-safety, set-wallpaper nil-file) were filled by the L2668 hardening commit 8fc6432d. No new file needed. +- Prefer ='prompt= or a custom command such as =cj/install-treesit-grammars=. +- Batch/test startup should never auto-install grammars. +- Document the intentional bootstrap path for a new machine. -**** 2026-05-23 Sat @ 03:21:12 -0500 Declared dirvish-config runtime deps with plain require -Switched =user-constants= and =system-utils= from =eval-when-compile= to plain =require= in =dirvish-config.el=, matching the three sibling requires below. The module builds =dirvish-quick-access-entries= from =code-dir=/=music-dir=/=pix-dir= at load and binds keys to =cj/xdg-open=/=cj/open-file-with-command=, so the deps are genuine runtime inputs. Added =tests/test-dirvish-config-runtime-requires.el= as a dependency-contract smoke test. Fixed in b63c4f83. +Originally meant to coordinate with the [#A] Python tree-sitter predicate +syntax issue. That one resolved upstream on 2026-05-14 (see =docs/python- +treesit-predicate-mismatch.txt= RESOLVED footer), so this task no longer +depends on it. -**** 2026-05-23 Sat @ 03:31:12 -0500 Hardened dirvish wallpaper + playlist path helpers -=cj/set-wallpaper= passed =(dired-file-name-at-point)= straight into =expand-file-name=, so no-file-at-point raised a bare wrong-type-argument; added a nil guard that signals a clear user-error. =cj/dired-create-playlist-from-marked= expanded a raw name under =music-dir= with no check; added =cj/--playlist-name-safe-p= to reject any name carrying a directory separator (=../=, absolute, nested) before the path is built. Regression tests went into =test-dirvish-config-wrappers.el= and =test-dirvish-config-playlist.el=. The duplicate/copy-path helpers already guarded nil, so they were left alone. Fixed in 8fc6432d. +**** 2026-05-24 Sun @ 04:30:14 -0500 Hardened clipboard git-clone process and path handling -**** 2026-05-23 Sat @ 03:38:30 -0500 Coverage already in place for mail + system-commands -The task premise was stale. =mail-config.el= has =test-mail-config-helpers.el= (4), =test-mail-config-transport.el= (7), and =test-mail-config.el= (1) covering executable discovery and transport command assignment. =system-commands.el= has =test-system-commands-keymap.el= (2, keymap shape + candidates) and =test-system-commands-resolve-and-run.el= (13, confirmation routing + command-string construction with shell-command stubbed). Both acceptance lists are satisfied; no new tests needed. +=cj/git-clone-clipboard-url= shelled out via =shell-command= and derived the dir with =file-name-nondirectory=, which mishandled scp-style SSH with no slash (=git@host:repo.git= → =git@host:repo=) and silently did nothing on a failed clone. Now clones as a direct =git= process (=call-process=, no shell) with =clone -- url dir= (so a =-=-leading URL can't be read as a flag); the destination comes from =cj/--git-clone-dir-name= (last component split on =/= and =:=, handling HTTPS, scp/ssh:// SSH, local paths); validates non-empty clipboard + writable target dir + non-existing destination; surfaces a non-zero git exit as a =user-error= with the =*git-clone*= output. Tests cover the deriver across schemes + empty-clipboard + clone-failure. Commit =35e4d701=. -**** 2026-05-24 Sun @ 14:43:13 -0500 Bounded the elfeed YouTube fetch + locked EWW UA scoping +**** TODO [#B] Decide whether auto-executable shell scripts should be opt-in :ux: -=cj/youtube-to-elfeed-feed-format= called =url-retrieve-synchronously= with no timeout (a hung request blocks Emacs) and only killed the temp URL buffer when an ID was extracted, leaking it on the parse-failure path. Passed =cj/elfeed-url-fetch-timeout= (10s) and moved fetch+parse into an =unwind-protect= that always kills the buffer. The EWW user-agent advice (=eww-config.el=) was already correctly scoped — it injects the UA only from eww-mode buffers, so package.el and other non-EWW url callers pass through untouched — so no code change there, just tests pinning that scoping and the replace-not-duplicate header behavior. Commit =c097b5b4=. +=prog-shell.el= adds a global =after-save-hook= that sets executable bits on any +saved file with a shebang. This is convenient, but it silently changes file +modes for every buffer in the session. -**** 2026-05-16 Sat @ 04:00:00 -0500 Moved Slack which-key registration behind with-eval-after-load +Expected outcome: +- Decide whether this should remain global, be limited to shell/script modes, or + prompt the first time per file. +- Preserve the fast path for real scripts. +- Keep the existing =cj/make-script-executable= tests updated for the chosen + policy. -=slack-config.el= calls =which-key-add-keymap-based-replacements= at top level, -while most modules defer which-key registration. If which-key is not loaded or -autoloaded as expected, Slack config can fail during require. +**** 2026-05-25 Mon @ 18:05:56 -0500 Moved JSON/YAML/webdev formatters to argv process calls -Expected outcome: -- Wrap the registration in =with-eval-after-load 'which-key=. -- Add a module-load smoke test or byte-compile check if easy. +Replaced =shell-command-on-region= with =call-process-region= (explicit program ++ argv, no shell) in cj/json-format-buffer (jq), cj/yaml-format-buffer +(prettier), and cj/webdev-format-buffer (prettier). The webdev path dropped its +=shell-quote-argument= once the filename became a plain argv element. Point +preservation is unchanged. One deliberate, tested improvement: the old code +clobbered the buffer with the formatter's error text on a non-zero exit; the new +per-module =cj/--<lang>-format-region= helper captures output, checks the exit +code, replaces only on success, and otherwise raises a user-error with stderr. +Kept a small helper in each of the three modules rather than one shared one, +since they share no module short of system-lib. Added argv-invocation and +no-clobber tests per formatter; existing wiring tests stay green. Done by +subagent, reviewed. -**** 2026-05-16 Sat @ 04:00:00 -0500 Removed httpd-start side effect from markdown-preview +**** 2026-05-16 Sat @ 03:54:56 -0500 Added cj/executable-find-or-warn checks for prettier and pyright at load time -=modules/markdown-config.el:37-51= starts =simple-httpd= inside an -interactive command, then opens a browser at -=http://localhost:8080/imp=. Starting a network listener as a side -effect of a "preview" command surprises users; once started, the -server keeps running until Emacs exits. Either gate the start -behind an explicit confirmation, document the listener clearly, or -move the server start into a separate =cj/markdown-preview-server-start= -command so =markdown-preview= just opens the URL once the server is -known to be running. +=modules/prog-webdev.el:34-40= declares =prettier-path= and +=modules/prog-python.el:33-40= declares =pyright-path= as string +literals. No validation at module load means a missing executable +surfaces only at first use -- format-on-save fires, then errors +mid-edit, then the user has to discover why. Wrap with +=cj/executable-find-or-warn= (already in =system-lib.el=) at module +load time so the missing dependency is reported up front. -**** 2026-05-25 Mon @ 18:29:40 -0500 Moved eshell SSH hosts into a defcustom +**** 2026-05-16 Sat @ 03:54:56 -0500 Documented keyboard-compat hook idempotence (already correct) -Replaced the three inline =eshell/alias= SSH-jump lines with a -=cj/eshell-ssh-hosts= defcustom (an alias→remote-path alist defaulting to the -current gocj/gosb/gowolf entries) that a per-machine config can override or set -to nil. The aliases are now built by iterating it via -=cj/--eshell-define-ssh-aliases=; the pure =cj/--eshell-ssh-alias-commands= -helper makes the construction testable without a live eshell. Tests added in -=tests/test-eshell-config-ssh-aliases.el=. +=modules/keyboard-compat.el:169-174= adds the frame-setup hook +unconditionally. If the module is required twice (e.g. via two +=eval-after-load= chains in different load orders), the hook runs +twice per new frame and installs duplicate =key-translation-map= +entries. Wrap the =add-hook= in a guard, or use a named function +and rely on =add-hook='s own duplicate-check. -**** 2026-05-16 Sat @ 04:00:00 -0500 Fixed https→http in markdown-preview + extracted server start +**** 2026-05-16 Sat @ 03:54:56 -0500 Wired F6 TypeScript clause to npx vitest|jest -=modules/markdown-config.el:45= opens -=https://localhost:8080/imp= via =browse-url-generic=, but the -=simple-httpd= listener bound in =httpd-config.el= serves plain -HTTP on port 8080. The =https= scheme causes the browser to -attempt a TLS handshake against a plaintext listener -- the request -fails before any preview content reaches the page, so the entire -feature is broken end-to-end. Change the URL to -=http://localhost:8080/imp= (and consider switching the launch to -=browse-url= so the user's default protocol handler is respected). +=modules/dev-fkeys.el:261-269= maps =tsx= to =typescript= in the +language detection table. =modules/dev-fkeys.el:347-349= +(=cj/--f6-test-runner-cmd-for=) has no clause for =typescript= -- +the catch-all =(_)= returns nil, so F6 errors instead of routing to +a real runner. Either add a =typescript= → =jest=/=vitest= clause +or remove the =tsx= mapping until the runner side is implemented. -**** TODO [#B] Document or vendor strapdown.js CDN dependency in =markdown-preview= :cleanup:solo:discuss: +**** 2026-05-16 Sat @ 03:54:56 -0500 Fixed prog-lsp eldoc-provider removal to act on the global hook -=cj/markdown-html= (=modules/markdown-config.el:48-51=) embeds a -=<script src="http://ndossougbe.github.io/strapdown/dist/strapdown.js">= -in every rendered page. The preview silently fails when offline, -when the GitHub Pages host is unreachable, or if the upstream project -disappears. Document the dependency in the module commentary at -minimum; better, vendor a copy of =strapdown.js= under -=assets/= and serve it from the local =simple-httpd= root. +=modules/prog-lsp.el:51-54,76= attaches +=cj/lsp--remove-eldoc-provider= globally to =lsp-managed-mode-hook= +but the removal it performs uses =(remove-hook ... t)= -- a +buffer-local removal. The first LSP buffer activates the hook, +which removes the provider for that buffer. Subsequent LSP buffers +still inherit the global default because the hook itself never +re-fires the buffer-local removal in their context. Either make +the hook itself buffer-local-friendly (add it inside +=lsp-managed-mode-hook= per-buffer) or remove from the global +provider list once instead of per-buffer. -**** 2026-05-16 Sat @ 04:00:00 -0500 Scoped TERM=xterm-256color to eshell buffers via process-environment +**** 2026-05-16 Sat @ 03:54:56 -0500 Externalized LanguageTool script path via user-emacs-directory -=modules/eshell-config.el:131= calls =(setenv "TERM" "xterm-256color")= -at config time inside the =xterm-color= use-package block. That -changes =TERM= for the entire Emacs process, so every subsequent -=start-process= / =call-process= inherits =xterm-256color= rather -than the terminal's actual emulator. Most subprocesses treat it as -truthful and emit ANSI escapes, which surface as raw =\e[31m= bytes -in shells that aren't interpreting them. Move the setenv into the -eshell entry hook (=eshell-mode-hook= or =eshell-before-prompt-hook=) -so it scopes to eshell processes only. +=modules/flycheck-config.el:69= hardcodes +=~/.emacs.d/scripts/languagetool-flycheck= as the LanguageTool wrapper. +Users running from a non-standard =user-emacs-directory= (or anyone +auditing the module against a future package) get a broken checker. +Replace with =(expand-file-name "scripts/languagetool-flycheck" +user-emacs-directory)= or a defcustom. -**** 2026-05-16 Sat @ 04:00:00 -0500 Quoted agent command in cj/--ai-vterm-launch-command via shell-quote-argument +**** 2026-05-16 Sat @ 03:54:56 -0500 Replaced hardcoded Zathura viewer with executable-find candidate list -=modules/ai-vterm.el:236-240= builds the tmux launch command by -wrapping =(concat cj/ai-vterm-agent-command "; exec bash")= in -literal single quotes. The default value carries embedded double -quotes (=claude "Read .ai/protocols.org and follow all -instructions."=) which survives that wrap, but a user-customized -=cj/ai-vterm-agent-command= containing a single quote breaks the -shell parse silently. Run the inner command through -=shell-quote-argument= (or pass the command as a separate tmux -=new-session= positional argument) so any user-customized agent -command launches safely. +=modules/latex-config.el:28= sets the LaTeX viewer to =zathura= +unconditionally. macOS / Windows users and anyone who prefers a +different PDF viewer lose document review without explanation. +Resolve via =executable-find= over a candidate list (=zathura=, +=evince=, =okular=, =Preview.app= via =open=, =SumatraPDF.exe=) and +fall back to =pdf-tools=. -*** 2026-05-15 Fri @ 18:14:26 -0500 Reviewed newly added modules +**** 2026-05-15 Fri @ 18:49:24 -0500 Fixed abbrev-mode no-arg toggle in =cj/prose-helpers-on= -Fresh end-to-end re-read of the 24 modules listed for this review, -applying the parent's protocol (runtime deps, top-level side effects, -keybindings, timers, external-executable assumptions, secrets, -host-specific paths, user-data writes, and test coverage). +Replaced the =(if (not (abbrev-mode)) (abbrev-mode))= shape with +=(unless (bound-and-true-p abbrev-mode) (abbrev-mode 1))= and the same +for =flycheck-mode= in =modules/flycheck-config.el:36-42=. Dropped +"flyspell" from the docstring (the commented-out +=cj/flyspell-on-for-buffer-type= line had been gone for a while; the +docstring was lying) and removed the stale comment marker. -The 24 modules in scope: +Added =tests/test-flycheck-config-prose-helpers-on.el= -- 4 tests +covering Normal (both modes off -> each enabled once with a positive +arg) and Boundary (both on -> no-op; each mixed state -> only the off +one enabled). The "both on -> no-op" assertion is the regression +guard for the no-arg toggle shape: it would record a =(nil)= call list +under the bug and a =()= call list under the fix. -- Post-2026-04 additions (11): =telega-config.el=, - =mu4e-attachments.el=, =vterm-config.el=, =external-open-lib.el=, - =eshell-config.el=, =cj-window-toggle-lib.el=, - =cj-window-geometry-lib.el=, =cj-org-text-lib.el=, - =cj-cache-lib.el=, =nerd-icons-config.el=, =ai-vterm.el=. -- Pre-existing modules outside the original scope (13): - =text-config.el=, =markdown-config.el=, =latex-config.el=, - =flycheck-config.el=, =flyspell-and-abbrev.el=, =ledger-config.el=, - =httpd-config.el=, =chrono-tools.el=, =diff-config.el=, - =games-config.el=, =mu4e-org-contacts-setup.el=, - =mu4e-org-contacts-integration.el=, =org-agenda-config-debug.el=. +Test infra needed an explicit =(defvar abbrev-mode)= / +=(defvar flycheck-mode)= at the top of the test file: with +=lexical-binding: t= and flycheck loaded =:defer t=, =let= on the +flycheck-mode symbol creates a lexical-only binding the production +code's =bound-and-true-p= can't see; declaring both as special makes +=let= dynamic and the test stable. -Confirmed the 5 findings from the 2026-05-15 re-review pass are -filed and visible under their target Harden tracks: -=markdown-config= httpd start (UI/integrations track), =flycheck-config= -LanguageTool path (programming track), =latex-config= Zathura -(programming), =eshell-config= SSH hostnames (integrations), and -=nerd-icons-config= advice-timing / =:demand t= (UI/navigation). +Full suite: =make test= exits 0; 468 lines of output with =ALL UNIT +TESTS PASSED= banner; no regressions. -Filed 11 new sub-tasks across the Harden tracks this pass: +*** DOING [#B] Harden integrations and application modules :harden: -- Foundation: dead world-clock block in =chrono-tools.el=, and - coverage for the TMR sound-selection helpers (with a refactor to - collapse the prefix-arg duplication). -- Custom editing: de-duplicate the spell-checker availability guard - in =flyspell-and-abbrev.el=, and add coverage for - =cj/flyspell-then-abbrev= + helpers. -- Org workflow: declare cross-module free variables in - =mu4e-org-contacts-integration.el=, and add coverage for the - completion-at-point / TAB / comma logic there. -- Programming workflow: fix the =cj/prose-helpers-on= toggle bug in - =flycheck-config.el= (=(if (not (abbrev-mode)) (abbrev-mode))= - flips the mode twice; needs =bound-and-true-p= + explicit enable). -- Integrations: fix the =https= vs =http= scheme mismatch in - =markdown-preview=, document/vendor its strapdown.js CDN - dependency, narrow the global =TERM=xterm-256color= setenv in - =eshell-config= so it doesn't leak into every subprocess, and - shell-quote the user-customized agent command in - =cj/--ai-vterm-launch-command=. +Scope: +- AI/rest: =ai-config.el=, =ai-conversations.el=, =restclient-config.el= +- Mail/chat/social: =mail-config.el=, =mu4e-*.el=, =slack-config.el=, + =erc-config.el=, =elfeed-config.el=, =eww-config.el= +- File/media/apps: =dirvish-config.el=, =dwim-shell-config.el=, =pdf-config.el=, + =calibredb-epub-config.el=, =music-config.el=, =quick-video-capture.el=, + =video-audio-recording.el=, =transcription-config.el= +- Utilities/apps: =auth-config.el=, =browser-config.el=, =dashboard-config.el=, + =help-config.el=, =help-utils.el=, =jumper.el=, =keyboard-macros.el=, + =local-repository.el=, =lorem-optimum.el=, =reconcile-open-repos.el=, + =show-kill-ring.el=, =system-commands.el=, =system-utils.el=, + =tramp-config.el=, =undead-buffers.el=, =weather-config.el=, =wrap-up.el= -The remaining 13 of the 24 modules had no concrete findings worth -filing -- they are either pure libraries with strong test coverage -(=cj-window-toggle-lib=, =cj-window-geometry-lib=, =cj-org-text-lib=, -=cj-cache-lib=, =external-open-lib=) or thin declarative -configuration (=text-config=, =diff-config=, =ledger-config=, -=games-config=, =mu4e-org-contacts-setup=, =telega-config=, -=httpd-config=, =org-agenda-config-debug=). +Review progress: +- Reviewed 2026-05-03 at high level by direct reads plus risky-pattern search. +- Recording/transcription and music modules have much stronger coverage than + most application wrappers. +- Existing coverage audit already tracks =ai-conversations=, =quick-video-capture=, + =dashboard-config=, =mail-config=, =show-kill-ring=, =system-commands=, and + =wrap-up= as high-value test targets. -** TODO [#B] Add Signal to the dashboard :quick: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: -** TODO [#C] Consider consolidating/harmonizing the UI in all Message Clients -:PROPERTIES: -:LAST_REVIEWED: 2026-06-06 -:END: -They should have the same UI paradigms and patters for consistency. -** TODO [#C] Slack message buffers in a reused popup window :slack:ux:quick: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-05 -:END: -Display slack.el message and thread buffers in a dedicated popup window (side or bottom) and reuse that one window instead of spawning a new window per buffer. Likely a =display-buffer-alist= rule (or popper integration) in =modules/slack-config.el=. +Completion review 2026-05-15: +- Re-checked the scoped integration/application modules with risky-pattern and + test-coverage searches. +- Many integration modules now have focused tests, including AI config, + restclient, mail helpers, Slack commands, Dirvish helpers, music, + recording/transcription, system commands, browser/help/jumper/reconcile, and + undead buffer helpers. +- Remaining issues are already logged below, especially system command safety, + REST key persistence, mail privacy/lifecycle policy, quick-video timers and + temp state, shell-heavy dwim/recording command hardening, AI conversation + persistence coverage, calendar operational behavior, Dirvish dependency/path + hardening, EWW/Elfeed network helpers, and Slack which-key registration. -** TODO [#C] Implement EMMS-free music-config architecture :refactor: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: -*** 2026-05-15 Fri @ 19:17:01 -0500 Specification -Implement the design in [[file:docs/design/music-config-without-emms.org][Design: music-config Without EMMS]]. +**** 2026-05-24 Sun @ 04:15:36 -0500 Made Emacs restart and destructive confirms defensive -The implementation should make =music-config.el= load without EMMS, introduce -package-owned playlist and track state, add a =cj/music-playlist-mode= view, -and route playback through a small backend protocol with an initial =mpv= -backend. Preserve the current F10 and =C-; m= user workflows where practical, -and keep M3U load/save/edit/reload plus radio station creation working. +Restart-Emacs scheduled an unconditional =kill-emacs= one second after firing the systemctl restart, so a missing or failed service killed the session with nothing to replace it. Restart now guards on =(daemonp)= and a present =emacs.service= (new =cj/system-cmd--emacs-service-available-p= via =systemctl --user cat=) before doing anything, and drops the separate =kill-emacs= — =systemctl restart= cycles the daemon itself, so a failed restart leaves the current Emacs alive. Shutdown and reboot moved to a strong =yes-or-no-p= confirm (a stray RET/space on the old quick prompt could power off the machine); logout and suspend keep the quick confirm since they are recoverable. Tests cover service detection, both restart guards, and the strong-confirm paths with system primitives stubbed. Commit =f1dbec16=. -Complexity estimate: high. This is a module rewrite with a new internal data -model, package-owned playlist mode, backend protocol, mpv process management, -and migration of existing EMMS-backed commands/tests. +Not done: the detached restart+reconnect (=nohup sh -c '... && emacsclient -c'=) may still race systemd's cgroup teardown of =emacs.service= before =emacsclient -c= runs. Couldn't verify from here without cycling the live daemon — eyeball the reconnect on the next real restart. -Time estimate: 2-4 focused days for an EMMS-free v1 with play/stop/next/previous, -M3U persistence, playlist UI, and focused tests. Add another 1-2 days if v1 -must include full mpv IPC support for pause, seek, and volume parity. +**** 2026-05-23 Sat @ 19:01:53 -0500 Removed SkyFi key-injection feature from restclient-config -Acceptance checks: -- =music-config.el= can be required in batch with no EMMS package installed. -- Existing focused music tests pass without EMMS preload or EMMS stubs except - where a compatibility adapter is explicitly under test. -- New tests cover playlist state, backend command dispatch, M3U persistence, - and the EMMS-free load smoke path. +Resolved by removing the feature rather than hardening it. =cj/restclient-skyfi-buffer= opened =data/skyfi-api.rest= in a file-visiting buffer and rewrote the =:skyfi-key= line with the real key from authinfo, so an accidental save would persist the key to local disk (the file was gitignored and never tracked, so no repo/public-mirror exposure — local plaintext only). Deleted =cj/skyfi-api-key=, =cj/restclient--inject-skyfi-key=, =cj/restclient-skyfi-buffer=, the =C-; R s= binding, the two SkyFi test files, and the local =data/skyfi-api.rest= template. Generic restclient (=C-; R n=, =C-; R o=, restclient/restclient-jq) kept. -*** TODO [#B] Pure helpers + state structs extraction :refactor: -Lift EMMS-free pure code into standalone form: file validation, recursive -collection, M3U parse/write, safe filenames, radio-station content, and -URL/file track typing. Introduce =cj/music-track= and =cj/music-playlist= -cl-structs plus state-mutation helpers (=cj/music-playlist-*= predicates and -setters). Files: =modules/music-config.el=, possibly a new -=modules/music-state.el= split. Existing pure-helper tests should pass -unchanged. +**** TODO [#B] Reconcile mail image/privacy settings :privacy: -Acceptance: structs defined, helpers callable in batch without EMMS loaded. +=mail-config.el= documents blocked remote images and sets +=gnus-blocked-images=, but later enables both =mu4e-show-images= and +=mu4e-view-show-images=. The interactive toggle changes =gnus-blocked-images= +buffer-locally, so the final privacy behavior is hard to reason about without +manual testing against real HTML messages. -Depends on: none (start here). +Expected outcome: +- Decide the default policy for embedded images versus remote HTTP images. +- Make the toggle report the effective state in the current mu4e view buffer. +- Add a short manual checklist or mocked test for the variables that control + remote image display. -*** TODO [#B] Backend protocol + fake test backend :refactor:tests: -Define the backend plist contract (=:available-p :play :pause :resume :stop -:seek :volume :status :metadata=) and =cj/music-current-backend=. Add -=cj/music-state-change-functions= abnormal hook with the v1 event set -(=started=, =paused=, =resumed=, =stopped=, =finished=, =error=, -=playlist-changed=, =mode-changed=). Create =tests/testutil-music-backend.el= -exposing =cj/test-music-fake-backend= with an event ledger. +**** 2026-05-23 Sat @ 03:52:00 -0500 Set compose buffers to kill on exit, both composers +First clarified the ownership (dd671f8c): the org-msg comment "always kill buffers on exit" was backwards — org-msg set =nil= (keep), which won over mu4e's =t= because org-msg-mode runs in every compose buffer. Craig then chose to kill compose buffers on exit, so I set the org-msg value to =t= as well (82978c79). Both mu4e and org-msg now kill the buffer on send/exit, so HTML drafts don't linger. -Acceptance: fake backend installable in tests; ordered-event assertions work -against a no-op playback flow. +**** 2026-05-24 Sun @ 07:26:31 -0500 Dropped startup timers for lazy protocol init -Depends on: pure helpers + state structs. +=quick-video-capture.el= scheduled an =after-init-hook= idle timer + a 2s fallback =run-with-timer= to call setup, which required org-protocol/capture and registered both the protocol handler and the capture template at every startup. Split the concerns like =org-webclipper.el=: the org-protocol handler registers in a =with-eval-after-load 'org-protocol= block (lightweight =add-to-list=, in place whenever org-protocol loads — org-config requires it at startup), and =cj/setup-video-download= now registers only the capture template lazily (first capture or first protocol call). Both timers gone. Tests pin that setup registers the template idempotently and no longer touches the protocol alist; verified in a live daemon that the protocol registers on load. Commit =bc965275=. -*** TODO [#B] Read-side state API + characterization tests :tests:refactor: -Implement =cj/music-playing-p=, =cj/music-paused-p=, =cj/music-current-track=, -=cj/music-playlist-state=, =cj/music-track-description=. Before rewriting -command bodies, add characterization tests against current behavior for -=cj/music-next=, =cj/music-previous=, =cj/music-toggle-consume=, -=cj/music-playlist-toggle=, =cj/music-playlist-load=, =cj/music-playlist-clear= -so the migration has a safety net. +**** 2026-05-24 Sun @ 04:30:14 -0500 Scoped video-capture URL to a dynamic binding -Acceptance: read-side helpers covered; characterization tests green against -the current EMMS-backed implementation. +The protocol handler =setq= a global =cj/video-download-current-url= and the capture handler read/cleared it, so an aborted or erroring capture left the stale URL for the next manual capture. Renamed to =cj/--video-download-url= and =let=-bind it around the =org-capture= call instead of mutating a global: the binding lives only for the capture's dynamic extent, so the handler sees the URL while the capture runs and an abort/error unwinds it automatically — no stale state, no manual clear. Manual invocation still prompts. Tests cover bound-URL download, manual prompt, empty-URL error, URL-visible-during-capture, and aborted-capture-leaves-nothing. Commit =b26b74cb=. -Depends on: backend protocol + fake test backend. +Note: the sibling =org-webclipper.el= still uses the same global-mutation pattern (=cj/webclip-current-url= / =title=); a separate =:solo:= task tracks that. -*** TODO [#B] Playlist major mode + render-from-state :feature: -Add =cj/music-playlist-mode= rendering the buffer as a view over -=cj/music-current-playlist=. Selected-track overlay + face, header reads -package state, full keymap from design Section "Playlist Buffer" (RET/p, SPC, -s, >/<, f/b, +/=/-, a, A, c/C, L/S/E/g, r/t/z/x, Z, i, o, q, S-up/down). -Preserve the active-window background highlight. +**** TODO [#B] Audit shell-command-heavy recording and dwim-shell workflows :security:refactor: -Acceptance: opening the playlist renders package state; reorder/shuffle/clear -go through state mutations and re-render; tests cover header + overlay -positioning. +=video-audio-recording.el= and =dwim-shell-config.el= are intentionally close to +the shell: pactl/ffmpeg/qpdf/7z/tesseract/media conversion commands are the +point. They also have the highest process and quoting surface in the config. -Depends on: read-side state API. +Expected outcome: +- Keep the current workflows, but catalog which commands accept filenames, + URLs, passwords, or free-form user input. +- Prefer argv process APIs for commands that do not require a shell. +- For commands that must use shell templates, document which placeholders are + safely quoted by =dwim-shell-command= and add focused tests around password + temp-file cleanup. -*** TODO [#B] mpv backend implementation :feature: -Implement =cj/music-mpv-*= backend functions. Phase the work per migration -plan §5: (a) process spawn, UID/PID-stamped socket under -=temporary-file-directory=, stale-socket sweep, IPC connect via -=make-network-process :family 'local=, state-hook plumbing. (b) play/stop/ -next/previous + finished-track auto-advance with deliberate-stop tracking. -(c) pause/resume, seek, volume over JSON IPC. (d) metadata read on track -start. Add =cj/music-doctor= reporting platform capabilities; ship Windows -degraded mode (play/stop/next/previous only via stdin/=call-process=). +***** 2026-05-23 Sat @ 19:11:30 -0500 Fixed async password temp-file lifetime in dwim-shell -Acceptance: integration tests tagged =:slow= and skipped when =mpv= not on -PATH; on Linux/macOS pause/seek/volume parity works; clean socket lifecycle -across Emacs restart and exit. +The four password commands (PDF protect/unprotect, remove-zip-encryption, create-encrypted-zip) deleted the password temp file in =unwind-protect= the instant the async command launched, so =qpdf=/=7z= could start after the file was gone. Extracted =cj/dwim-shell--run-with-password-file= + =cj/dwim-shell--password-cleanup-callback=: the temp file (mode 600) is now deleted from an =:on-completion= callback that fires after the process exits (success or failure), with the synchronous =unwind-protect= kept only as a pre-launch-failure backstop. Rewrote all four commands onto the helper. 5 ERT tests cover the cleanup callback (success/error/missing-file) and the runner (writes 600 file + defers cleanup; cleans up on launch failure). qpdf already passes the password via =--password-file= (out of argv); the 7z argv exposure is split into its own follow-up below. -Depends on: backend protocol + fake test backend. +***** 2026-05-24 Sun @ 04:20:31 -0500 Accepted the brief 7z password-on-argv exposure, documented it -*** TODO [#B] Command + Dired/Dirvish rewire :refactor: -Migrate user-facing commands (=cj/music-play=, =cj/music-pause=, -=cj/music-stop=, =cj/music-next=, =cj/music-previous=, seek/volume, -random/repeat/consume/shuffle toggles) to operate on package state and call -=cj/music-current-backend=. Update Dired/Dirvish =+= add routing, -M3U load/save/edit/reload, radio-station creation, F10 toggle, and =C-; m= -keymap entries to drop EMMS symbols. Migrate command-flow tests to the fake -backend. +Investigated whether 7z could take the password off argv. It can't: 7-Zip 26.01 reads the password only from its controlling TTY, not stdin or a file. Verified empirically — =printf pw | 7z a -p ...= silently created an archive with an *empty* password (the piped value never reaches it), and a round-trip with the same password failed. So the password must go on argv via =$(cat tempfile)= and is briefly visible in the process list while 7z runs. -Acceptance: full keymap functional end-to-end against the fake backend; -characterization tests still green; Dirvish =+= add path covered. +Craig's call (2026-05-24): accept the exposure rather than switch off the .7z format. On a single-user workstation, for a short-lived process, with the password already kept out of shell history by the mode-600 temp file, the residual exposure is acceptable. The gpg-wrapped-tar alternative would close it but change the archive format and decrypt workflow. Recorded the tradeoff in both function docstrings in =dwim-shell-config.el= so the decision is visible at the call site, not just here. -Depends on: playlist major mode + mpv backend. +***** 2026-05-23 Sat @ 19:18:00 -0500 Quoted/validated user-controlled dwim-shell inputs -*** TODO [#B] EMMS removal + parity walk :cleanup:tests: -Remove =cj/emms--setup=, the on-demand EMMS loader, and the =use-package emms= -block. Add the EMMS-free batch-load smoke test (=music-config.el= requires -clean without EMMS installed). Run the 22-step parity walk from design -§"Parity Walk" against the new implementation; record measurements against -the performance budget (1000-track load <500ms, reorder <50ms, IPC dispatch -<100ms, header refresh <16ms) and note any deviations. +Closed the four injection-quoting cases. git-clone-clipboard-url now validates the clipboard with =cj/dwim-shell--valid-git-url-p= and passes the URL via =shell-quote-argument= instead of the raw =<<cb>>= substitution. GPG recipient and the 7z archive name go through =shell-quote-argument= instead of hand-written single quotes. The ffmpeg thumbnail timestamp is validated with =cj/dwim-shell--valid-ffmpeg-timestamp-p= (digits/colons/dot only) before it reaches =-ss=. The sequential-rename prefix is validated filename-safe with =cj/dwim-shell--safe-rename-prefix-p=. 7 ERT tests cover the three validators (Normal/Boundary/Error); the two =shell-quote-argument= swaps trust the builtin. The fifth case — video concatenation's echo/tr/sed filelist — is a redesign rather than a quoting fix and is split out below. -Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity -walk recorded as a completion log entry under the parent task. +***** 2026-05-23 Sat @ 19:58:00 -0500 Rebuilt video-concat filelist in Elisp -Depends on: command + Dired/Dirvish rewire. +=cj/dwim-shell-commands-concatenate-videos= built the ffmpeg concat list with =echo '<<*>>' | tr ' ' '\n' | sed 's/^/file /'=, which split on spaces and broke on quotes. Extracted =cj/dwim-shell--build-concat-filelist=, which renders each path as an escaped =file '...'= line (single quotes escaped as ='\''=), writes it to a temp file in Elisp, and runs =ffmpeg -f concat -i <quoted-listfile>= with a trailing =; rm -f= to clean up after the process exits. =<<*>>= stays only as an inert trailing shell comment so dwim-shell still runs one command over all marked files. 3 ERT tests cover plain paths, spaces, and an embedded quote. -** TODO [#C] music-config option-combination audit + tests :tests:harden:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-06 -:END: +***** 2026-05-23 Sat @ 20:17:00 -0500 Clarified broad/misleading file-operation commands -Two-part task surfaced 2026-05-28 during the Signel verify walk — generalized from the "are there combinations of options that we'd want to disallow together" question. +=remove-empty-directories= ran =find . -type d -empty -delete= from the ambient current directory. Now it prompts for an explicit root (via =read-directory-name=), names that root in the confirmation, and runs =find <quoted-root> ...= built by =cj/dwim-shell--empty-dirs-command= (2 ERT tests cover the command shape + space quoting). =secure-delete= called =shred= without =-u=, overwriting file contents but leaving the file in place despite the name and the "permanently destroy" prompt; added =-u= (=shred -vfzu=) so it actually unlinks. Both use the inert =<<*>>= comment trick for single-execution. -Part 1 — enumerate the configurable option surface of =modules/music-config.el=: every =defcustom=, every behavior toggle, every backend-selection variable, every cross-cutting flag (auto-play, repeat, shuffle, follow-cursor, side-window-height-fraction, etc.). Audit each option for valid value ranges. Capture the matrix in =docs/design/music-config-options.org= (or inline in the test file's header — judgment call when the matrix lands). +***** 2026-05-24 Sun @ 04:10:20 -0500 Shell-quoted X11 and audio recording command paths -Part 2 — combinatorial test coverage. Use the =/pairwise-tests= skill: identify parameters, value partitions, and inter-parameter constraints, build a PICT model, generate the minimal test matrix that hits every 2-way combination. For each problematic combination the matrix surfaces, decide: (a) validate at config-load time with a =user-error= that names the conflict, (b) runtime guard in the affected command, or (c) doc-only warning in the option's docstring. Disallow only the genuinely-broken pairs; doc-warn the merely-confusing ones. +The Wayland =wf-recorder= path already quoted its args, but the X11 =ffmpeg= path and the audio-only =ffmpeg= path interpolated mic device, system device, and output filename raw — breaking on directories with spaces or unusual device names. Wrapped all three in =shell-quote-argument= on both paths. Extracted =cj/recording--build-audio-command= (mirroring =cj/recording--build-video-command=) so the audio command is unit-testable, then quoted there. Tests cover device names and filenames with spaces on both builders. Commit =39795e85=. -The recent F10 side-window-height-fraction work and the EMMS-free refactor candidate ("Implement EMMS-free music-config architecture" above) are both natural near-term touchpoints — best to land this audit before the EMMS swap so the new architecture inherits a clean option spec. +***** 2026-05-24 Sun @ 04:10:20 -0500 Scoped wf-recorder stop signal to our own process -** TODO [#C] gptel-magit activation fails on velox :bug:ai:quick: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: -Surfaced 2026-05-25 while diagnosing an unrelated load failure over SSH. velox-specific — the workstation has a current gptel and does not show it. +Stop ran =pkill -INT wf-recorder=, signalling every wf-recorder on the system including an unrelated screen capture. Added =cj/recording--interrupt-child-wf-recorder=, which scopes the producer-first interrupt to the wf-recorder child of our own recording shell via =pkill -P <shell-pid>=. Producer-first ordering preserved (ffmpeg still sees a clean pipe EOF). The orphan-cleanup at recording start stays a broad by-name kill on purpose — those leftovers come from crashed sessions whose shells are already dead, so there is no live PID to scope to. Tests cover the scoped call, the nil-PID no-op, and that the bare system-wide form is never used. Commit =556f48a2=. -At startup (and reproducibly in batch) velox logs: "Unable to activate package `gptel-magit'. Required package `gptel-0.9.8' is unavailable." gptel-magit depends on gptel >= 0.9.8 and velox's installed gptel is older or missing, so it can't activate. A startup warning, not a blocker. +***** 2026-05-24 Sun @ 04:10:20 -0500 Created the selected recording directory, not its parent -Reproduce: -: emacs --batch --no-site-file -L . -L modules --eval "(package-initialize)" --eval "(message \"done\")" 2>&1 | grep -i gptel +The toggles ran =(file-name-directory location)= before =make-directory=, which returns the *parent* for a path without a trailing slash — so the selected directory went uncreated and ffmpeg failed to write into it. Both toggles now route the destination through =cj/recording--normalize-recording-dir= (expand + =file-name-as-directory=) and =make-directory= that, creating the selected directory itself (including names with spaces). Tests cover trailing-slash normalization, idempotence, spaces, and relative-to-absolute expansion. Commit =dc033c75=. -Next step: check the installed gptel version (=(assq 'gptel package-alist)= or =M-x package-list-packages=), update gptel to >= 0.9.8, then re-evaluate gptel-magit activation. If gptel was pinned/held on velox, reconcile the pin against the gptel-magit dependency. +**** TODO [#B] Make AI conversation persistence path-safe and project-aware :cleanup:refactor: -** TODO [#C] GPTel Work :feature:ai: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: +=ai-conversations.el= has good pure helper seams but is currently untested in +this repo. The path slugging is simple and the save/load/delete commands operate +directly in a single global directory. -Categories below thematize the agent affordances the design doc -[[file:docs/design/gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] -points at -- Git, Org, messaging, file / buffer / workspace state, -media, and the dev loop. The shortlist's first-batch ADOPT tools -(git_status / git_log / git_diff / web_fetch) already shipped; the -themes below are next-tier work where the agent treats Emacs as a -structured workspace, not a text terminal. Per-theme spec lives in -the task body once written; implementation tasks land as siblings -of the spec heading once the spec is approved. The magit-backend -reimplementation of the shipped git tools is tracked separately in -[[file:docs/design/gptel-git-tools-magit-backend.org][gptel-git-tools-magit-backend.org]]. +Expected outcome: +- Add tests for candidate sorting, topic slug collisions, autosave path setup, + and delete confirmation behavior. +- Consider whether conversations should remain global or support project-scoped + subdirectories. +- Confirm autosave never writes partial prompt/response state to an unexpected + file after loading a different conversation. -*** TODO [#C] Wire Up MCP.el so That GPTel Has Access to MCP Servers via GPTel Tools +**** TODO [#B] Harden calendar sync operational behavior around the parser :data:refactor: -**** 2026-05-16 Sat @ 15:44:36 -0500 Spec +=calendar-sync.el= has broad parser/recurrence coverage, but the operational +path around it still has startup, persistence, and fetch risks. -Design doc: [[file:docs/design/mcp-el-gptel-integration.org][docs/design/mcp-el-gptel-integration.org]] +Expected outcome: +- Move private calendar URLs out of source and rotate the exposed feed URLs + before doing further cleanup. +- Avoid immediate network fetches at module load unless explicitly enabled for + interactive sessions. +- Add a per-calendar in-flight guard so a timer tick cannot launch overlapping + syncs for the same calendar. +- Use =curl --fail= or equivalent status handling so HTTP error pages are not + treated as successful ICS downloads. +- Write generated Org files atomically via a temp file and rename. +- Read the local state file with =read-eval= disabled. -**** 2026-05-17 Sun @ 14:14:34 -0500 Landed ai-mcp.el pure-helper foundation +**** 2026-05-23 Sat @ 04:18:44 -0500 AI conversation persistence coverage already in place +Premise was stale. =tests/test-ai-conversations.el= (47 cases) already covers slug generation, timestamp parsing, candidate sorting (newest/oldest), latest-file selection, save/load header stripping against a temp dir, autosave path/timer, and delete confirmation — with GPTel stubbed throughout. Acceptance list satisfied; no new file needed. -Commit =54d231be=. Sections 1 (constants + defcustoms) and 3 (pure helpers) of the seven-section outline. 41 ERT tests, all green. Refactor audit caught two duplications during Phase 4 and folded them into the same commit (=cj/mcp--get-server-entry= and =cj/mcp--name-matches-p=). Phase 1.5 (confirmation contract) is next. +**** 2026-05-23 Sat @ 03:31:12 -0500 Dirvish helper coverage already in place +The task premise was stale: =dirvish-config.el= now has 14 focused test files (=test-dirvish-config-*.el=, ~100 cases) covering duplicate-naming, resolve-display-path (project/home/absolute/org-link), ediff-pair, html/printable predicates, playlist filtering/sanitizing, wallpaper-program mapping, and the public wrappers. The remaining gaps (playlist name-safety, set-wallpaper nil-file) were filled by the L2668 hardening commit 8fc6432d. No new file needed. -**** TODO [#C] Phase 1.5 -- GPTel confirmation contract :mcp: +**** 2026-05-23 Sat @ 03:21:12 -0500 Declared dirvish-config runtime deps with plain require +Switched =user-constants= and =system-utils= from =eval-when-compile= to plain =require= in =dirvish-config.el=, matching the three sibling requires below. The module builds =dirvish-quick-access-entries= from =code-dir=/=music-dir=/=pix-dir= at load and binds keys to =cj/xdg-open=/=cj/open-file-with-command=, so the deps are genuine runtime inputs. Added =tests/test-dirvish-config-runtime-requires.el= as a dependency-contract smoke test. Fixed in b63c4f83. -*Goal:* flip =gptel-confirm-tool-calls= to ='auto= and gate the existing local tools that need it. +**** 2026-05-23 Sat @ 03:31:12 -0500 Hardened dirvish wallpaper + playlist path helpers +=cj/set-wallpaper= passed =(dired-file-name-at-point)= straight into =expand-file-name=, so no-file-at-point raised a bare wrong-type-argument; added a nil guard that signals a clear user-error. =cj/dired-create-playlist-from-marked= expanded a raw name under =music-dir= with no check; added =cj/--playlist-name-safe-p= to reject any name carrying a directory separator (=../=, absolute, nested) before the path is built. Regression tests went into =test-dirvish-config-wrappers.el= and =test-dirvish-config-playlist.el=. The duplicate/copy-path helpers already guarded nil, so they were left alone. Fixed in 8fc6432d. -*Entry:* Phase 1 module exists and helpers tested. +**** 2026-05-23 Sat @ 03:38:30 -0500 Coverage already in place for mail + system-commands +The task premise was stale. =mail-config.el= has =test-mail-config-helpers.el= (4), =test-mail-config-transport.el= (7), and =test-mail-config.el= (1) covering executable discovery and transport command assignment. =system-commands.el= has =test-system-commands-keymap.el= (2, keymap shape + candidates) and =test-system-commands-resolve-and-run.el= (13, confirmation routing + command-string construction with shell-command stubbed). Both acceptance lists are satisfied; no new tests needed. -*DECISION (cj):* which of the existing local tools register with =:confirm t= once ='auto= is in effect? Reads (=read_buffer=, =read_text_file=, =list_directory_files=, =git_status=, =git_log=, =git_diff=) clearly stay =:confirm nil=. Judgment calls: -- =web_fetch= -- fetches arbitrary URLs the agent supplies. Spec recommends gating. -- =write_text_file= -- writes any path under =$HOME= with agent-supplied content. -- =update_text_file= -- modifies an existing file with an agent-supplied transform. -- =move_to_trash= -- moves a path to trash (reversible but disruptive). +**** 2026-05-24 Sun @ 14:43:13 -0500 Bounded the elfeed YouTube fetch + locked EWW UA scoping -*Deliverables:* -- =ai-mcp.el= setup section runs =(setq gptel-confirm-tool-calls 'auto)=. -- Remove =(setq gptel-confirm-tool-calls nil)= from =modules/ai-config.el:386= with a comment pointing at =ai-mcp.el=. -- For each tool the decision marks "gate," add =:confirm t= to its =gptel-make-tool= form. -- Tests in =tests/test-ai-mcp-confirm-contract.el= asserting: =gptel-confirm-tool-calls= is ='auto= after load; write-classified stub MCP tool with =:confirm t= triggers the confirm branch in =gptel-send='s dispatch (stub the prompt); read-classified MCP tool with =:confirm nil= does not; =git_log= (=:confirm nil=) still runs without prompting; each newly-gated local tool does prompt. - -*Exit:* tests green. Manual smoke: open GPTel, call a gated tool, confirm prompt appears. Call =git_log=, no prompt. +=cj/youtube-to-elfeed-feed-format= called =url-retrieve-synchronously= with no timeout (a hung request blocks Emacs) and only killed the temp URL buffer when an ID was extracted, leaking it on the parse-failure path. Passed =cj/elfeed-url-fetch-timeout= (10s) and moved fetch+parse into an =unwind-protect= that always kills the buffer. The EWW user-agent advice (=eww-config.el=) was already correctly scoped — it injects the UA only from eww-mode buffers, so package.el and other non-EWW url callers pass through untouched — so no code change there, just tests pinning that scoping and the replace-not-duplicate header behavior. Commit =c097b5b4=. -**** TODO [#B] Phase 2 -- Compat layer + registration pipeline (fake inventory) :mcp: +**** 2026-05-16 Sat @ 04:00:00 -0500 Moved Slack which-key registration behind with-eval-after-load -*Goal:* implement the mcp.el compat wrappers and the tool-registration pipeline against stubbed =mcp-server-connections=. +=slack-config.el= calls =which-key-add-keymap-based-replacements= at top level, +while most modules defer which-key registration. If which-key is not loaded or +autoloaded as expected, Slack config can fail during require. -*Entry:* Phase 1.5 proves gptel respects per-tool =:confirm= slot. +Expected outcome: +- Wrap the registration in =with-eval-after-load 'which-key=. +- Add a module-load smoke test or byte-compile check if easy. -*Deliverables:* -- Section 4 of =ai-mcp.el= (compat layer): =cj/mcp--server-status=, =cj/mcp--server-tools=, =cj/mcp--server-name=, =cj/mcp--assert-capabilities=. Each helper documents the upstream commit / file location it targets. -- Section 5 of =ai-mcp.el= (registration pipeline): =cj/mcp--register-tool=, =cj/mcp--register-server-tools=, =cj/mcp--deregister-server-tools=, =cj/mcp--rewrite-plist=, =cj/mcp--registered-tools= hash. -- All MCP tools register with =:async t=. -- Tests in =tests/test-ai-mcp-registration.el=. +**** 2026-05-16 Sat @ 04:00:00 -0500 Removed httpd-start side effect from markdown-preview -*Exit:* with a stubbed =mcp-server-connections=, registration produces correctly prefixed =mcp__SERVER__TOOL= entries in =gptel-tools=; closures call =mcp-call-tool SERVER REMOTE-NAME= (verified by stubbing =mcp-async-call-tool=); deregistration removes only MCP-owned tools and leaves a pre-populated local =git_log= entry intact; re-registration replaces function pointer without duplicating menu entries; confirm overrides win over patterns. +=modules/markdown-config.el:37-51= starts =simple-httpd= inside an +interactive command, then opens a browser at +=http://localhost:8080/imp=. Starting a network listener as a side +effect of a "preview" command surprises users; once started, the +server keeps running until Emacs exits. Either gate the start +behind an explicit confirmation, document the listener clearly, or +move the server start into a separate =cj/markdown-preview-server-start= +command so =markdown-preview= just opens the URL once the server is +known to be running. -**** TODO [#B] Phase 3 -- Async state machine + timer-race timeout wrapper :mcp: +**** 2026-05-25 Mon @ 18:29:40 -0500 Moved eshell SSH hosts into a defcustom -*Goal:* implement the lifecycle state machine and the per-call timer-race timeout. +Replaced the three inline =eshell/alias= SSH-jump lines with a +=cj/eshell-ssh-hosts= defcustom (an alias→remote-path alist defaulting to the +current gocj/gosb/gowolf entries) that a per-machine config can override or set +to nil. The aliases are now built by iterating it via +=cj/--eshell-define-ssh-aliases=; the pure =cj/--eshell-ssh-alias-commands= +helper makes the construction testable without a live eshell. Tests added in +=tests/test-eshell-config-ssh-aliases.el=. -*Entry:* Phase 2 registration works against stubs. +**** 2026-05-16 Sat @ 04:00:00 -0500 Fixed https→http in markdown-preview + extracted server start -*Deliverables:* -- Section 6 of =ai-mcp.el= (async state machine): =cj/mcp--state=, =cj/mcp--server-status= alist, =cj/mcp--stall-timer=, =cj/mcp-ensure-started=, =cj/mcp--on-hub-callback=, =cj/mcp--poll-status=, =cj/mcp--start-stall-timer=, =cj/mcp--build-status-from-specs=. -- =cj/mcp--wrap-async-with-timeout= (timer/callback race; both branches set =done= before invoking gptel callback so late responses are ignored). -- Tests in =tests/test-ai-mcp-async.el=. +=modules/markdown-config.el:45= opens +=https://localhost:8080/imp= via =browse-url-generic=, but the +=simple-httpd= listener bound in =httpd-config.el= serves plain +HTTP on port 8080. The =https= scheme causes the browser to +attempt a TLS handshake against a plaintext listener -- the request +fails before any preview content reaches the page, so the entire +feature is broken end-to-end. Change the URL to +=http://localhost:8080/imp= (and consider switching the launch to +=browse-url= so the user's default protocol handler is respected). -*Exit:* =cj/mcp-ensure-started= returns in <100 ms with delayed-callback stubs; stall timer fires for stuck servers; timer-race wrapper handles all three orderings (MCP-first, timer-first, late-MCP-after-timer); async error path (=:error-callback= without inited callback) reaches =failed= state via polling. +**** TODO [#B] Document or vendor strapdown.js CDN dependency in =markdown-preview= :cleanup:solo:discuss: -**** TODO [#B] Phase 4 -- First real connection (drawio or slack-deepsat) :mcp: +=cj/markdown-html= (=modules/markdown-config.el:48-51=) embeds a +=<script src="http://ndossougbe.github.io/strapdown/dist/strapdown.js">= +in every rendered page. The preview silently fails when offline, +when the GitHub Pages host is unreachable, or if the upstream project +disappears. Document the dependency in the module commentary at +minimum; better, vendor a copy of =strapdown.js= under +=assets/= and serve it from the local =simple-httpd= root. -*Goal:* wire one real no-auth server end-to-end against actual mcp.el and prove the stubbed Phase 3 behavior matches reality. +**** 2026-05-16 Sat @ 04:00:00 -0500 Scoped TERM=xterm-256color to eshell buffers via process-environment -*Entry:* Phase 3 async works against stubs. +=modules/eshell-config.el:131= calls =(setenv "TERM" "xterm-256color")= +at config time inside the =xterm-color= use-package block. That +changes =TERM= for the entire Emacs process, so every subsequent +=start-process= / =call-process= inherits =xterm-256color= rather +than the terminal's actual emulator. Most subprocesses treat it as +truthful and emit ANSI escapes, which surface as raw =\e[31m= bytes +in shells that aren't interpreting them. Move the setenv into the +eshell entry hook (=eshell-mode-hook= or =eshell-before-prompt-hook=) +so it scopes to eshell processes only. -*Deliverables:* -- Add =use-package mcp= to =ai-mcp.el= (MELPA active, =:load-path= for local checkout commented). -- =cj/mcp--assert-capabilities= called at load time; signals clearly if mcp.el is too old. -- Set =cj/mcp-enabled-servers= temporarily to =("drawio")= (or =("slack-deepsat")= if the local proxy is running). -- First real =cj/mcp-ensure-started= invocation from =cj/toggle-gptel=. +**** 2026-05-16 Sat @ 04:00:00 -0500 Quoted agent command in cj/--ai-vterm-launch-command via shell-quote-argument -*Exit:* manual smoke -- =C-; a t= opens GPTel without blocking; within 30 s, drawio (or slack-deepsat) tools appear in =gptel-menu= grouped by category; calling a tool returns expected output; killing the subprocess externally surfaces as =failed= in =cj/mcp--server-status=. +=modules/ai-vterm.el:236-240= builds the tmux launch command by +wrapping =(concat cj/ai-vterm-agent-command "; exec bash")= in +literal single quotes. The default value carries embedded double +quotes (=claude "Read .ai/protocols.org and follow all +instructions."=) which survives that wrap, but a user-customized +=cj/ai-vterm-agent-command= containing a single quote breaks the +shell parse silently. Run the inner command through +=shell-quote-argument= (or pass the command as a separate tmux +=new-session= positional argument) so any user-customized agent +command launches safely. -**** TODO [#B] Phase 5 -- Status UX + commands + doctor (static) :mcp: +*** 2026-05-15 Fri @ 18:14:26 -0500 Reviewed newly added modules -*Goal:* ship the full server-management UX so partial-availability and failures are visible. +Fresh end-to-end re-read of the 24 modules listed for this review, +applying the parent's protocol (runtime deps, top-level side effects, +keybindings, timers, external-executable assumptions, secrets, +host-specific paths, user-data writes, and test coverage). -*Entry:* Phase 4 proves a real connection works. +The 24 modules in scope: -*Deliverables:* -- Section 7 of =ai-mcp.el= (UI). -- Commands: =cj/mcp-status= (echo-area summary keyed off =cj/mcp--state=), =cj/mcp-list-tools= (tabulated buffer with failed servers at top in red face; keys =g r c RET q=), =cj/mcp-doctor= (static mode only -- capability, =npx=/=uvx=, Claude config, per-server env, local endpoints; output buffer keys =c r q=), =cj/mcp-wait-until-ready=, =cj/mcp-hub= (thin wrapper that ensures startup first), =cj/mcp-restart-failed=, =cj/mcp-restart-server=, =cj/mcp-stop-all=. -- Keymap: =C-; a C= subprefix bound in =ai-config.el='s autoload section. Keys =h s l r R S d w=. -- which-key labels for every binding. -- =kill-emacs-hook= registration for =cj/mcp-stop-all=. -- Investigation: does =gptel-menu= refresh after mid-call tool registration? Document the answer in =ai-mcp.el= commentary; if it requires close+reopen, add to known UX caveats. +- Post-2026-04 additions (11): =telega-config.el=, + =mu4e-attachments.el=, =vterm-config.el=, =external-open-lib.el=, + =eshell-config.el=, =cj-window-toggle-lib.el=, + =cj-window-geometry-lib.el=, =cj-org-text-lib.el=, + =cj-cache-lib.el=, =nerd-icons-config.el=, =ai-vterm.el=. +- Pre-existing modules outside the original scope (13): + =text-config.el=, =markdown-config.el=, =latex-config.el=, + =flycheck-config.el=, =flyspell-and-abbrev.el=, =ledger-config.el=, + =httpd-config.el=, =chrono-tools.el=, =diff-config.el=, + =games-config.el=, =mu4e-org-contacts-setup.el=, + =mu4e-org-contacts-integration.el=, =org-agenda-config-debug.el=. -*Exit:* all keymap bindings work; audit buffer surfaces failed servers prominently; doctor identifies each scenario in the manual test matrix; status command shows the right state for each phase transition. +Confirmed the 5 findings from the 2026-05-15 re-review pass are +filed and visible under their target Harden tracks: +=markdown-config= httpd start (UI/integrations track), =flycheck-config= +LanguageTool path (programming track), =latex-config= Zathura +(programming), =eshell-config= SSH hostnames (integrations), and +=nerd-icons-config= advice-timing / =:demand t= (UI/navigation). -**** TODO [#B] Phase 6 -- HTTP servers (linear, notion) :mcp: +Filed 11 new sub-tasks across the Harden tracks this pass: -*Goal:* add the two HTTP-transport servers with in-protocol OAuth. +- Foundation: dead world-clock block in =chrono-tools.el=, and + coverage for the TMR sound-selection helpers (with a refactor to + collapse the prefix-arg duplication). +- Custom editing: de-duplicate the spell-checker availability guard + in =flyspell-and-abbrev.el=, and add coverage for + =cj/flyspell-then-abbrev= + helpers. +- Org workflow: declare cross-module free variables in + =mu4e-org-contacts-integration.el=, and add coverage for the + completion-at-point / TAB / comma logic there. +- Programming workflow: fix the =cj/prose-helpers-on= toggle bug in + =flycheck-config.el= (=(if (not (abbrev-mode)) (abbrev-mode))= + flips the mode twice; needs =bound-and-true-p= + explicit enable). +- Integrations: fix the =https= vs =http= scheme mismatch in + =markdown-preview=, document/vendor its strapdown.js CDN + dependency, narrow the global =TERM=xterm-256color= setenv in + =eshell-config= so it doesn't leak into every subprocess, and + shell-quote the user-customized agent command in + =cj/--ai-vterm-launch-command=. -*Entry:* Phase 5 UX shipped. +The remaining 13 of the 24 modules had no concrete findings worth +filing -- they are either pure libraries with strong test coverage +(=cj-window-toggle-lib=, =cj-window-geometry-lib=, =cj-org-text-lib=, +=cj-cache-lib=, =external-open-lib=) or thin declarative +configuration (=text-config=, =diff-config=, =ledger-config=, +=games-config=, =mu4e-org-contacts-setup=, =telega-config=, +=httpd-config=, =org-agenda-config-debug=). -*Deliverables:* -- Add =linear= and =notion= back to =cj/mcp-enabled-servers=. -- Doctor gains live-auth-check mode (=C-u C-; a C d=): invokes a single safe read per auth class to verify OAuth tokens haven't silently expired. Static checks first; live probe only fires after static passes. -- OAuth recovery pattern matcher surfaces auth URLs in =cj/mcp-status= on first connect. +** TODO [#C] theme-studio picker panel blends into the page :bug:theme-studio:ux:quick:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-11 +:END: +Craig, 2026-06-11 manual-test walk: the color picker's background is hard to distinguish from the page background. Give the picker panel a visibly distinct background or a highlighted border so it stands out. Pin with a gate asserting the picker element carries the distinct style. -*Exit:* first connect surfaces the OAuth URL through the recovery pattern; after browser handshake completes, subsequent connects succeed without prompt; live-auth-check correctly identifies a deliberately revoked token; both servers appear ready in the audit buffer. +** TODO [#C] theme-studio Rust + Zig language previews :feature:theme-studio:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-11 +:END: +Requested by Craig 2026-06-11: add Rust and Zig code samples to the language previews (samples.py currently carries Elisp, Go, Python, TypeScript, Java, C, C++, Shell). Each sample should exercise the treesit token categories distinctive to its language (Rust: lifetimes, macros, attributes, traits; Zig: comptime, builtins, error unions), then regenerate theme-studio.html and extend the test surface. -**** TODO [#B] Phase 7 -- Env-dependent stdio servers (figma, google-*) :mcp: +** TODO [#C] theme-studio face-consistency check :feature:theme-studio: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-10 +:END: +Rule taxonomy captured in [[file:docs/design/theme-studio-face-rules.org][docs/design/theme-studio-face-rules.org]] (Design Rules vs Fidelity Rules). The two checks below map to those two rule kinds. Both surface structural-attribute (weight/slant/underline/box/overline/height) issues; color is the theme's design and out of scope. -*Goal:* add the remaining five env-dependent servers. +1. Theme cross-cutting consistency (primary, per Craig 2026-06-09): the theme has deliberate cross-cutting rules — e.g. headings/titles are bold, links are underlined, errors/warnings/success are bold. Flag where the theme BREAKS ITS OWN rule (a heading that isn't bold, a link that isn't underlined). The designer declares the rules; the check finds the violators. This is the "tell me where I broke the rule" guardrail. -*Entry:* Phase 6 HTTP servers connect cleanly. +2. defface-baseline divergence (secondary): flag where a face's structural attrs differ from its package =defface= so each divergence is deliberate, not an accidental drop. Would have caught the dropped underline/bold defaults and the contradictions (shr-h3 bold-vs-italic, erc-action italic-vs-bold) from the package-face audit as they were introduced. -*Deliverables:* -- Add =figma=, =google-calendar=, =google-docs-personal=, =google-docs-work=, =google-keep= to =cj/mcp-enabled-servers=. -- Verify env-merge from =~/.claude.json= for each (the mtime-cached reader from Phase 1). -- Verify figma's =:secret-args= splicing places the API key correctly without echoing it. -- Manual smoke: simulate token expiry on one Google server; recovery message points at "re-auth via Claude Code, then C-; a C r SERVER". +Bake into the tool (a lint surfaced in the UI) or run as a build-time check (seeds vs live deffaces via emacsclient). -*Exit:* all 9 servers reach =ready= state on a clean machine. Sentinel-grep check across status / audit / hub / errors / audit-log shows zero secret leakage. Doctor's live-auth covers each auth class (oauth, token, args-token, in-protocol, local, none). +** TODO [#C] Color-family per-hex hint override :feature:theme-studio: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-11 +:END: +For the ~1 color per palette that sits on a ramp-collision point (e.g. yellow+2 on the distinguished palette, which by every hex signal belongs to the olive ramp though its name says gold), automatic grouping cannot recover the designer's intent. Add a per-hex family override: drag a swatch to a different column, store the override keyed by hex (never the name, so renaming is still free), consult it after the LCCL clustering, and drop/mark-stale it when the hex changes substantially. Export stays mostly flat; only overrides are extra metadata. Both reviews recommend this exact shape; details in =~/color-sorting-fable.org= (§ "The irreducible case") and =~/color-sorting-codex.org= (§ "What to store"). -**** TODO [#B] Phase 8 -- Privacy + audit polish :mcp: +** TODO [#C] Internet radio now-playing song :feature:music:emms:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-11 +:END: +Show the currently-playing song while streaming an internet radio station. Lives in =modules/music-config.el= (EMMS + MPV backend, M3U radio stations). The track title comes from the stream's ICY metadata — EMMS exposes it via =emms-track-description= / =emms-playing-time= and updates it on the metadata-change hook; MPV reports the ICY title too. Add an option to show the song in the minibuffer (e.g. echo on track change, or an on-demand command). Consider also a mode-line indicator as a second surface. -*Goal:* land the final UX polish and documentation. +** TODO [#C] Evaluate jamescherti essential-emacs-packages list :packages:research:quick:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-11 +:END: +Review [[https://www.jamescherti.com/essential-emacs-packages/][James Cherti's essential Emacs packages]] for anything worth installing. Cross-check each candidate against what is already in the config (=modules/= + =init.el=), skip the ones already present, and shortlist the genuinely new ones with a one-line rationale. Future-installation research, not a commitment to install. -*Entry:* all 9 servers working. +** TODO [#C] dupre-clear theme — contrast-first AAA sibling :feature:theme:dupre: +Build a new theme (working name "dupre-clear", final name TBD) that takes dupre's color identity and rebuilds it Prot's way: contrast-first, targeting WCAG AAA (~7:1 on the ground), where the in-progress dupre revision is mood/depth-first and lands at AA. Same hues (dupre blue, emerald, gold, terracotta, regal violet, mint) brightened to clear the AAA floor; same modus-style role mapping (blue keywords bold, gold functions, violet types, emerald strings, terracotta constants, silver default, warm-grey comments, metallic greys, navy + regal fills). Build the dupre revision first; this reuses its hue choices as the starting point. -*Deliverables:* -- Audit buffer privacy header: "Tool results land in =gptel-tools= responses; saved conversations persist them. Use =cj/gptel-autosave-toggle= per buffer to opt out." -- =cj/mcp-tool-audit-log-enabled= defcustom + log writer (=~/.emacs.d/data/mcp-tool-log/YYYY-MM-DD.log= -- metadata only, one line per call, daily rotation). -- =ai-mcp.el= commentary updated with the code-organization outline as a table of contents. -- Final pass on tests covering saved-conversation behavior (autosave persists MCP tool results; toggling off prevents persistence). +Full design + methodology + starting palette + open questions in the spec: [[file:docs/design/dupre-clear-theme.org][docs/design/dupre-clear-theme.org]]. Key prerequisite/context: the dupre-redesign entry in =.ai/session-context.org= (the AA palette this brightens). Hardest slot: blue keywords (a deep dupre blue can't be AAA on near-black — decide brighten vs keep-AA-exception vs lift-the-ground). +** TODO [#C] theme-studio terminal/ANSI colors :feature:theme-studio: +theme-studio represents GUI faces only; terminal colors aren't surfaced at all. Scope decided 2026-06-09: GUI-first faces, NOT full per-face display-class fallback. Two pieces: -*Exit:* all 10 acceptance criteria from the spec pass. Manual matrix run end-to-end on a fresh Emacs. Working tree clean. +1. ANSI-16 panel. Map the 16 ANSI slots (black/red/green/yellow/blue/magenta/cyan/white + bright variants) to palette colors, with a preview, and export them so =build-theme.el= emits the =ansi-color-*= / =term-color-*= faces. This matters even in pure-GUI Emacs: colored shell output, compilation buffers, eshell, and vterm/eat all draw from these. Signals must line up with their ANSI slot (error red→ansi red, success→green, warning→yellow, info/link→blue) so a signal reads the same in a terminal. -*** TODO [#C] Wrap the gh CLI as a GPTel tool +2. Core-face 16-color fallback. Only the ~10 faces that decide console legibility get a =(((class color) (min-colors 16)) ...)= clause plus a =(t ...)= floor: default/fg, bg, keyword, string, comment, constant, error, warning, region, mode-line, line-number. Tune these for contrast — push it UP, legibility over fidelity, because the only 16-color target is the bare Linux virtual console (an occasional emergency context). The long tail stays GUI-first and auto-approximates. -**** 2026-05-16 Sat @ 16:20:00 -0500 Spec +Why this scope: the GUI and the normal terminal (foot + tmux, truecolor / ≥256-color) both render the GUI hexes fine; GUI-first is correct there. Only the Linux VT is 16-color, and a low-contrast palette approximates badly down to 16 — so a few core faces get a deliberately higher-contrast 16-color fallback rather than every face carrying a multi-spec. Tool work: the ANSI-16 panel + a flag on the core faces to also capture a 16-color value; =build-theme.el= emits multi-spec only for those. Full per-face fallback is revisited only if console work becomes regular. +** TODO [#C] Consider consolidating/harmonizing the UI in all Message Clients +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: +They should have the same UI paradigms and patters for consistency. +** TODO [#C] Slack message buffers in a reused popup window :slack:ux:quick: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: +Display slack.el message and thread buffers in a dedicated popup window (side or bottom) and reuse that one window instead of spawning a new window per buffer. Likely a =display-buffer-alist= rule (or popper integration) in =modules/slack-config.el=. -Design doc: [[file:docs/design/gptel-gh-tool.org][docs/design/gptel-gh-tool.org]] +** TODO [#C] Implement EMMS-free music-config architecture :refactor: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +*** 2026-05-15 Fri @ 19:17:01 -0500 Specification +Implement the design in [[file:docs/design/music-config-without-emms.org][Design: music-config Without EMMS]]. -*** TODO [#C] GPTel should autosave regularly after a conversation is saved -*** TODO [#B] Org Workflow Related Tools +The implementation should make =music-config.el= load without EMMS, introduce +package-owned playlist and track state, add a =cj/music-playlist-mode= view, +and route playback through a small backend protocol with an initial =mpv= +backend. Preserve the current F10 and =C-; m= user workflows where practical, +and keep M3U load/save/edit/reload plus radio station creation working. -Affordances that expose the Org workspace -- agenda state, capture -targets, org-roam nodes and backlinks, dailies, drill review state -- -to the agent as structured context, not raw .org buffer text. +Complexity estimate: high. This is a module rewrite with a new internal data +model, package-owned playlist mode, backend protocol, mpv process management, +and migration of existing EMMS-backed commands/tests. -**** TODO [#B] Agenda state tools :feature: +Time estimate: 2-4 focused days for an EMMS-free v1 with play/stop/next/previous, +M3U persistence, playlist UI, and focused tests. Add another 1-2 days if v1 +must include full mpv IPC support for pause, seek, and volume parity. -Read scheduled / deadline / waiting tasks for a date range; query by -tag, priority, or TODO keyword; list what's blocking today. Lets the -agent answer "what's on the critical path this week" without me -pasting agenda output, and feeds the daily-prep / wrap-up workflows. +Acceptance checks: +- =music-config.el= can be required in batch with no EMMS package installed. +- Existing focused music tests pass without EMMS preload or EMMS stubs except + where a compatibility adapter is explicitly under test. +- New tests cover playlist state, backend command dispatch, M3U persistence, + and the EMMS-free load smoke path. -**** TODO [#B] Org-roam node tools :feature: +*** TODO [#B] Pure helpers + state structs extraction :refactor: +Lift EMMS-free pure code into standalone form: file validation, recursive +collection, M3U parse/write, safe filenames, radio-station content, and +URL/file track typing. Introduce =cj/music-track= and =cj/music-playlist= +cl-structs plus state-mutation helpers (=cj/music-playlist-*= predicates and +setters). Files: =modules/music-config.el=, possibly a new +=modules/music-state.el= split. Existing pure-helper tests should pass +unchanged. -Resolve a topic to its node; return body + backlinks; list nodes by -tag; surface dailies for a date range. Lets the agent reason over -the personal knowledge graph and write back into it via the capture -tools below. +Acceptance: structs defined, helpers callable in batch without EMMS loaded. -**** TODO [#B] Capture creation tools :feature: +Depends on: none (start here). -Drive =org-capture= from a template key + body string. Lets the -agent file inbox items, reading notes, journal entries, or roam -nodes without me leaving the chat. Tight pairing with the -=cj/org-capture= optimization task in todo.org. +*** TODO [#B] Backend protocol + fake test backend :refactor:tests: +Define the backend plist contract (=:available-p :play :pause :resume :stop +:seek :volume :status :metadata=) and =cj/music-current-backend=. Add +=cj/music-state-change-functions= abnormal hook with the v1 event set +(=started=, =paused=, =resumed=, =stopped=, =finished=, =error=, +=playlist-changed=, =mode-changed=). Create =tests/testutil-music-backend.el= +exposing =cj/test-music-fake-backend= with an event ledger. -**** TODO [#B] Org-drill review tools :feature: +Acceptance: fake backend installable in tests; ordered-event assertions work +against a no-op playback flow. -Surface next-due drill cards in =drill-dir=; let the agent quiz on a -topic and report performance. Useful for prompted recall sessions -("ask me five medical-Spanish cards") and for "did this card stick" -analysis. +Depends on: pure helpers + state structs. -*** TODO [#B] Git Related Tools +*** TODO [#B] Read-side state API + characterization tests :tests:refactor: +Implement =cj/music-playing-p=, =cj/music-paused-p=, =cj/music-current-track=, +=cj/music-playlist-state=, =cj/music-track-description=. Before rewriting +command bodies, add characterization tests against current behavior for +=cj/music-next=, =cj/music-previous=, =cj/music-toggle-consume=, +=cj/music-playlist-toggle=, =cj/music-playlist-load=, =cj/music-playlist-clear= +so the migration has a safety net. -Affordances that expose magit's structured view of a repo -- sections, -staged-vs-unstaged, commit metadata, rebase / conflict state -- as -first-class tools rather than asking the model to reason over raw -diff text. +Acceptance: read-side helpers covered; characterization tests green against +the current EMMS-backed implementation. -**** TODO [#B] Section-aware git tools :feature: +Depends on: backend protocol + fake test backend. -Expose Magit sections as first-class GPTel tools: current section type, -heading, file, hunk range, and content; sibling sections under the same -file; staged / unstaged / untracked status; commit metadata around the -selected commit or branch; the exact staged patch that would be -committed. Lets prompts say "review the file section at point" or -"explain this hunk in the context of adjacent hunks" without manual -context-copying. +*** TODO [#B] Playlist major mode + render-from-state :feature: +Add =cj/music-playlist-mode= rendering the buffer as a view over +=cj/music-current-playlist=. Selected-track overlay + face, header reads +package state, full keymap from design Section "Playlist Buffer" (RET/p, SPC, +s, >/<, f/b, +/=/-, a, A, c/C, L/S/E/g, r/t/z/x, Z, i, o, q, S-up/down). +Preserve the active-window background highlight. -**** TODO [#B] Commit intent workbench :feature: +Acceptance: opening the playlist renders package state; reorder/shuffle/clear +go through state mutations and re-render; tests cover header + overlay +positioning. -Transient that builds a commit intentionally: -1. Agent reads unstaged + staged changes. -2. Agent proposes coherent commit groups. -3. User selects groups in a Magit-style buffer. -4. Agent stages those paths or hunks only after confirmation. -5. Agent generates a message reflecting the selected intent. +Depends on: read-side state API. -Addresses the common case of two or three unrelated edits in one -working tree -- a single commit-message generator can't handle that -cleanly. +*** TODO [#B] mpv backend implementation :feature: +Implement =cj/music-mpv-*= backend functions. Phase the work per migration +plan §5: (a) process spawn, UID/PID-stamped socket under +=temporary-file-directory=, stale-socket sweep, IPC connect via +=make-network-process :family 'local=, state-hook plumbing. (b) play/stop/ +next/previous + finished-track auto-advance with deliberate-stop tracking. +(c) pause/resume, seek, volume over JSON IPC. (d) metadata read on track +start. Add =cj/music-doctor= reporting platform capabilities; ship Windows +degraded mode (play/stop/next/previous only via stdin/=call-process=). -**** TODO [#B] Patch narrative buffer :feature: +Acceptance: integration tests tagged =:slow= and skipped when =mpv= not on +PATH; on Linux/macOS pause/seek/volume parity works; clean socket lifecycle +across Emacs restart and exit. -Generate an Org buffer that explains a change set as a reviewable -narrative: -- "What changed" by subsystem. -- "Why it appears to have changed" inferred from names, tests, and docs. -- "Risk areas" with links back to Magit file sections. -- "Suggested verification" using local Makefile targets when present. +Depends on: backend protocol + fake test backend. -Reusable artifact: paste into a PR description, save with an AI -session, or file into org-roam. +*** TODO [#B] Command + Dired/Dirvish rewire :refactor: +Migrate user-facing commands (=cj/music-play=, =cj/music-pause=, +=cj/music-stop=, =cj/music-next=, =cj/music-previous=, seek/volume, +random/repeat/consume/shuffle toggles) to operate on package state and call +=cj/music-current-backend=. Update Dired/Dirvish =+= add routing, +M3U load/save/edit/reload, radio-station creation, F10 toggle, and =C-; m= +keymap entries to drop EMMS symbols. Migrate command-flow tests to the fake +backend. -**** TODO [#B] Review-thread simulator :feature: +Acceptance: full keymap functional end-to-end against the fake backend; +characterization tests still green; Dirvish =+= add path covered. -Before opening a PR, create a local review buffer with inline comments -attached to Magit diff positions. The agent writes comments as if -reviewing someone else's patch: -- Comments grouped by severity. -- Each comment links to file and line. -- Resolved comments check off in Org. -- Accepted suggestions apply through the existing text-update tools. +Depends on: playlist major mode + mpv backend. -Makes "review my diff" less ephemeral and avoids losing useful findings -inside a chat transcript. +*** TODO [#B] EMMS removal + parity walk :cleanup:tests: +Remove =cj/emms--setup=, the on-demand EMMS loader, and the =use-package emms= +block. Add the EMMS-free batch-load smoke test (=music-config.el= requires +clean without EMMS installed). Run the 22-step parity walk from design +§"Parity Walk" against the new implementation; record measurements against +the performance budget (1000-track load <500ms, reorder <50ms, IPC dispatch +<100ms, header refresh <16ms) and note any deviations. -**** TODO [#B] Rebase and conflict coach :feature: +Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity +walk recorded as a completion log entry under the parent task. -When Magit enters a rebase, cherry-pick, merge, or conflict state, -expose an agent command that reads: -- Git operation state from =.git/=. -- Conflict markers in the worktree. -- Relevant commits from =git log --merge= or the rebase todo. -- The current Magit status sections. +Depends on: command + Dired/Dirvish rewire. -The agent explains the conflict in domain terms and proposes a -resolution patch; the actual edit and =git add= stay under explicit -user control. +** TODO [#C] music-config option-combination audit + tests :tests:harden:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: -**** TODO [#B] Regression archaeology :feature: +Two-part task surfaced 2026-05-28 during the Signel verify walk — generalized from the "are there combinations of options that we'd want to disallow together" question. -Magit transient that runs a bisect-like reasoning workflow: -- Ask for a symptom and a known-good / known-bad range. -- Summarize candidate commits in small batches. -- Use tests or user-provided repro commands when available. -- Maintain a bisect journal in an Org buffer. +Part 1 — enumerate the configurable option surface of =modules/music-config.el=: every =defcustom=, every behavior toggle, every backend-selection variable, every cross-cutting flag (auto-play, repeat, shuffle, follow-cursor, side-window-height-fraction, etc.). Audit each option for valid value ranges. Capture the matrix in =docs/design/music-config-options.org= (or inline in the test file's header — judgment call when the matrix lands). -Even when the agent can't run the whole bisect, it keeps the -investigation structured and preserves why each commit was judged -good or bad. +Part 2 — combinatorial test coverage. Use the =/pairwise-tests= skill: identify parameters, value partitions, and inter-parameter constraints, build a PICT model, generate the minimal test matrix that hits every 2-way combination. For each problematic combination the matrix surfaces, decide: (a) validate at config-load time with a =user-error= that names the conflict, (b) runtime guard in the affected command, or (c) doc-only warning in the option's docstring. Disallow only the genuinely-broken pairs; doc-warn the merely-confusing ones. -*** TODO [#B] Messaging Related Tools +The recent F10 side-window-height-fraction work and the EMMS-free refactor candidate ("Implement EMMS-free music-config architecture" above) are both natural near-term touchpoints — best to land this audit before the EMMS swap so the new architecture inherits a clean option spec. -Affordances over mu4e, Slack, Telegram, and ERC. Same shape across -protocols: read recent threads, search by sender / topic, compose a -draft from a prompt + thread context, leave the send under explicit -user control. +** TODO [#C] gptel-magit activation fails on velox :bug:ai:quick: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +Surfaced 2026-05-25 while diagnosing an unrelated load failure over SSH. velox-specific — the workstation has a current gptel and does not show it. -**** TODO [#B] Mu4e thread and compose tools :feature: +At startup (and reproducibly in batch) velox logs: "Unable to activate package `gptel-magit'. Required package `gptel-0.9.8' is unavailable." gptel-magit depends on gptel >= 0.9.8 and velox's installed gptel is older or missing, so it can't activate. A startup warning, not a blocker. -Read the message at point and surrounding thread (with attachments -summarized); query the inbox by =from:= / =subject:= / date range; -compose a draft from a prompt + thread context using =org-msg=. -Pairs with the existing =mu4e-org-contacts-integration.el=. +Reproduce: +: emacs --batch --no-site-file -L . -L modules --eval "(package-initialize)" --eval "(message \"done\")" 2>&1 | grep -i gptel -**** TODO [#B] Slack thread and compose tools :feature: +Next step: check the installed gptel version (=(assq 'gptel package-alist)= or =M-x package-list-packages=), update gptel to >= 0.9.8, then re-evaluate gptel-magit activation. If gptel was pinned/held on velox, reconcile the pin against the gptel-magit dependency. -Read channel / DM / thread history through =emacs-slack=; search by -user or channel; compose a draft message but leave sending to me. -Mirrors the mu4e shape so the agent's interface is uniform across -messaging protocols. +** TODO [#C] GPTel Work :feature:ai: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: -**** TODO [#B] Telegram and IRC read tools :feature: +Categories below thematize the agent affordances the design doc +[[file:docs/design/gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] +points at -- Git, Org, messaging, file / buffer / workspace state, +media, and the dev loop. The shortlist's first-batch ADOPT tools +(git_status / git_log / git_diff / web_fetch) already shipped; the +themes below are next-tier work where the agent treats Emacs as a +structured workspace, not a text terminal. Per-theme spec lives in +the task body once written; implementation tasks land as siblings +of the spec heading once the spec is approved. The magit-backend +reimplementation of the shipped git tools is tracked separately in +[[file:docs/design/gptel-git-tools-magit-backend.org][gptel-git-tools-magit-backend.org]]. -Same shape as Slack for =telega= (Telegram) and =erc= (IRC): -recent-message reads, search, and draft compose. Bundled because -the API shape is identical even if the underlying clients differ. +*** TODO [#C] Wire Up MCP.el so That GPTel Has Access to MCP Servers via GPTel Tools -**** TODO [#B] Contact resolution tools :feature: +**** 2026-05-16 Sat @ 15:44:36 -0500 Spec -Resolve a name to email / Slack ID / Telegram handle via -=org-contacts= and the configured address books. Removes the -"who's this person again" friction from the compose flows above. +Design doc: [[file:docs/design/mcp-el-gptel-integration.org][docs/design/mcp-el-gptel-integration.org]] -*** TODO [#B] File and Buffer Related Tools +**** 2026-05-17 Sun @ 14:14:34 -0500 Landed ai-mcp.el pure-helper foundation -Affordances that expose the user's actual workspace -- open buffers, -narrowed regions, marked files, vterm / eshell sessions -- as -structured context. Stops the model from asking "what file are you -looking at" or "what region is selected." +Commit =54d231be=. Sections 1 (constants + defcustoms) and 3 (pure helpers) of the seven-section outline. 41 ERT tests, all green. Refactor audit caught two duplications during Phase 4 and folded them into the same commit (=cj/mcp--get-server-entry= and =cj/mcp--name-matches-p=). Phase 1.5 (confirmation contract) is next. -**** TODO [#B] Buffer state tools :feature: +**** TODO [#C] Phase 1.5 -- GPTel confirmation contract :mcp: -List visible buffers with major-mode + file (when any); read the -narrowed region instead of the whole buffer; report point + mark -positions and the active region's text. The single most-asked -question between turns becomes a tool call. +*Goal:* flip =gptel-confirm-tool-calls= to ='auto= and gate the existing local tools that need it. -**** TODO [#B] Dirvish / Dired tools :feature: +*Entry:* Phase 1 module exists and helpers tested. -Read marked files, sort state, and filter state from a Dired or -Dirvish buffer. Lets the agent operate on "the files I just marked" -rather than "files in this directory" -- a real distinction in any -review or refactor workflow. +*DECISION (cj):* which of the existing local tools register with =:confirm t= once ='auto= is in effect? Reads (=read_buffer=, =read_text_file=, =list_directory_files=, =git_status=, =git_log=, =git_diff=) clearly stay =:confirm nil=. Judgment calls: +- =web_fetch= -- fetches arbitrary URLs the agent supplies. Spec recommends gating. +- =write_text_file= -- writes any path under =$HOME= with agent-supplied content. +- =update_text_file= -- modifies an existing file with an agent-supplied transform. +- =move_to_trash= -- moves a path to trash (reversible but disruptive). -**** TODO [#B] Vterm session tools :feature: +*Deliverables:* +- =ai-mcp.el= setup section runs =(setq gptel-confirm-tool-calls 'auto)=. +- Remove =(setq gptel-confirm-tool-calls nil)= from =modules/ai-config.el:386= with a comment pointing at =ai-mcp.el=. +- For each tool the decision marks "gate," add =:confirm t= to its =gptel-make-tool= form. +- Tests in =tests/test-ai-mcp-confirm-contract.el= asserting: =gptel-confirm-tool-calls= is ='auto= after load; write-classified stub MCP tool with =:confirm t= triggers the confirm branch in =gptel-send='s dispatch (stub the prompt); read-classified MCP tool with =:confirm nil= does not; =git_log= (=:confirm nil=) still runs without prompting; each newly-gated local tool does prompt. -Recent command output from a named vterm session; scroll-history -search. Pairs naturally with the =ai-vterm= design: the agent -running in one project's vterm can read another project's vterm -without leaving the chat. +*Exit:* tests green. Manual smoke: open GPTel, call a gated tool, confirm prompt appears. Call =git_log=, no prompt. -**** TODO [#B] Eshell session tools :feature: +**** TODO [#B] Phase 2 -- Compat layer + registration pipeline (fake inventory) :mcp: -Same shape as the vterm tools for =eshell= sessions -- last-command -output, history search, current directory. Most useful for -agent-driven inspection of long-running pipelines. +*Goal:* implement the mcp.el compat wrappers and the tool-registration pipeline against stubbed =mcp-server-connections=. -*** TODO [#B] Filesystem Related Tools +*Entry:* Phase 1.5 proves gptel respects per-tool =:confirm= slot. -Affordances that let the agent operate on actual files on disk and -run common CLI utilities -- pandoc, ffmpeg, imagemagick, ripgrep, -fd, jq -- rather than relying on me to paste content or run -commands by hand. +*Deliverables:* +- Section 4 of =ai-mcp.el= (compat layer): =cj/mcp--server-status=, =cj/mcp--server-tools=, =cj/mcp--server-name=, =cj/mcp--assert-capabilities=. Each helper documents the upstream commit / file location it targets. +- Section 5 of =ai-mcp.el= (registration pipeline): =cj/mcp--register-tool=, =cj/mcp--register-server-tools=, =cj/mcp--deregister-server-tools=, =cj/mcp--rewrite-plist=, =cj/mcp--registered-tools= hash. +- All MCP tools register with =:async t=. +- Tests in =tests/test-ai-mcp-registration.el=. -*Design tension to resolve before any of these ship: one tool per -utility, or one generic =run_shell_command=?* +*Exit:* with a stubbed =mcp-server-connections=, registration produces correctly prefixed =mcp__SERVER__TOOL= entries in =gptel-tools=; closures call =mcp-call-tool SERVER REMOTE-NAME= (verified by stubbing =mcp-async-call-tool=); deregistration removes only MCP-owned tools and leaves a pre-populated local =git_log= entry intact; re-registration replaces function pointer without duplicating menu entries; confirm overrides win over patterns. -The shortlist's first pass DEFERRED a generic =run_shell_command=: -sandboxing to HOME + /tmp with a denylist for destructive ops is -straightforward, but the denylist can never be exhaustive, and -"confirmation for everything else" becomes click-fatigue. +**** TODO [#B] Phase 3 -- Async state machine + timer-race timeout wrapper :mcp: -The children below take the other path -- *one gptel tool per -binary*, with a strictly-typed argv shape (e.g. -=pandoc_convert(input_path, output_format)=, not -=pandoc_convert(args_string)=). Each tool: +*Goal:* implement the lifecycle state machine and the per-call timer-race timeout. -- Validates its own paths (must be under HOME, outputs in a - sandboxed dir). -- Rejects dangerous flags explicitly (pandoc =--filter=, ffmpeg's - =-protocol_whitelist= chicanery, imagemagick's policy bypasses). -- Runs via =call-process= with an argv list -- no shell parsing, - no string-interpolation injection. -- Caps output and reports truncation inline. +*Entry:* Phase 2 registration works against stubs. -The trade-off is breadth: every new CLI tool means a new gptel tool -file. Acceptable because (a) the list of utilities I actually need -agent access to is small (~8 below covers most of it), and (b) each -wrapper gets type-checked argv and a focused description the model -can reason over, which is genuinely better than a free-form -=run_shell_command(string)=. +*Deliverables:* +- Section 6 of =ai-mcp.el= (async state machine): =cj/mcp--state=, =cj/mcp--server-status= alist, =cj/mcp--stall-timer=, =cj/mcp-ensure-started=, =cj/mcp--on-hub-callback=, =cj/mcp--poll-status=, =cj/mcp--start-stall-timer=, =cj/mcp--build-status-from-specs=. +- =cj/mcp--wrap-async-with-timeout= (timer/callback race; both branches set =done= before invoking gptel callback so late responses are ignored). +- Tests in =tests/test-ai-mcp-async.el=. -The =eshell_submit= entry at the end is the escape hatch for one- -off needs the wrappers don't cover -- =:confirm t= always. +*Exit:* =cj/mcp-ensure-started= returns in <100 ms with delayed-callback stubs; stall timer fires for stuck servers; timer-race wrapper handles all three orderings (MCP-first, timer-first, late-MCP-after-timer); async error path (=:error-callback= without inited callback) reaches =failed= state via polling. -Adjacent categories: the existing =gptel-tools/= file CRUD -(=read_text_file=, =write_text_file=, =update_text_file=, -=list_directory_files=, =move_to_trash=) is the foundation this -category extends. =web_fetch= is the network-fetch counterpart. +**** TODO [#B] Phase 4 -- First real connection (drawio or slack-deepsat) :mcp: -**** TODO [#B] Document conversion (pandoc) :feature: +*Goal:* wire one real no-auth server end-to-end against actual mcp.el and prove the stubbed Phase 3 behavior matches reality. -Convert between markdown, org, html, pdf, docx, latex, epub, plain -text. Most common use: "extract this docx to markdown so I can -read it inline." Strict argv: input path, output format, optional -output path. Reject =--filter= and =--lua-filter= (arbitrary code -execution). Output written to a sandbox dir unless explicit -override. +*Entry:* Phase 3 async works against stubs. -**** TODO [#B] Image manipulation (imagemagick) :feature: +*Deliverables:* +- Add =use-package mcp= to =ai-mcp.el= (MELPA active, =:load-path= for local checkout commented). +- =cj/mcp--assert-capabilities= called at load time; signals clearly if mcp.el is too old. +- Set =cj/mcp-enabled-servers= temporarily to =("drawio")= (or =("slack-deepsat")= if the local proxy is running). +- First real =cj/mcp-ensure-started= invocation from =cj/toggle-gptel=. -Resize, format-convert, get-metadata (=identify=), optionally crop / -rotate / annotate. Common use: "resize this PNG to a thumbnail" or -"convert these HEICs to JPEGs." Strict argv per operation. -Reject pre-validated dangerous formats (the historical EXR / SVG / -MVG CVE surface) unless explicitly enabled. ImageMagick's -=policy.xml= is the underlying defense; the wrapper enforces it at -the tool boundary too. +*Exit:* manual smoke -- =C-; a t= opens GPTel without blocking; within 30 s, drawio (or slack-deepsat) tools appear in =gptel-menu= grouped by category; calling a tool returns expected output; killing the subprocess externally surfaces as =failed= in =cj/mcp--server-status=. -**** TODO [#B] Audio / video processing (ffmpeg) :feature: +**** TODO [#B] Phase 5 -- Status UX + commands + doctor (static) :mcp: -Trim, transcode, extract audio, get-metadata (=ffprobe=). Paths -under HOME only; reject network-protocol inputs (=http:= / =rtmp:= -/ =rtsp:=) so the model can't pull from arbitrary sources. Pairs -with the existing transcription module -- the same "extract audio -from video" path =cj/transcribe-media= uses internally. +*Goal:* ship the full server-management UX so partial-availability and failures are visible. -**** TODO [#B] Content search (ripgrep) :feature: +*Entry:* Phase 4 proves a real connection works. -=rg= wrapper with path / glob filtering, result-count cap, optional -literal-vs-regex mode. Pure read. Was in the shortlist's ADOPT -bucket as =search_in_files=. Highest-leverage filesystem tool by -expected call frequency -- "where in this repo is X" is the -question I paste agent output for most often. +*Deliverables:* +- Section 7 of =ai-mcp.el= (UI). +- Commands: =cj/mcp-status= (echo-area summary keyed off =cj/mcp--state=), =cj/mcp-list-tools= (tabulated buffer with failed servers at top in red face; keys =g r c RET q=), =cj/mcp-doctor= (static mode only -- capability, =npx=/=uvx=, Claude config, per-server env, local endpoints; output buffer keys =c r q=), =cj/mcp-wait-until-ready=, =cj/mcp-hub= (thin wrapper that ensures startup first), =cj/mcp-restart-failed=, =cj/mcp-restart-server=, =cj/mcp-stop-all=. +- Keymap: =C-; a C= subprefix bound in =ai-config.el='s autoload section. Keys =h s l r R S d w=. +- which-key labels for every binding. +- =kill-emacs-hook= registration for =cj/mcp-stop-all=. +- Investigation: does =gptel-menu= refresh after mid-call tool registration? Document the answer in =ai-mcp.el= commentary; if it requires close+reopen, add to known UX caveats. -**** TODO [#B] File discovery (fd) :feature: +*Exit:* all keymap bindings work; audit buffer surfaces failed servers prominently; doctor identifies each scenario in the manual test matrix; status command shows the right state for each phase transition. -=fd= (or =find= fallback) wrapper, capped result count. Pure -read, lower stakes than =search_in_files= (filenames only, no -content). Common pairing: =find_file_by_name= then -=read_text_file=. +**** TODO [#B] Phase 6 -- HTTP servers (linear, notion) :mcp: -**** TODO [#B] Metadata extraction (file / exiftool) :feature: +*Goal:* add the two HTTP-transport servers with in-protocol OAuth. -=file= for MIME-type detection; =exiftool= for image / video / -audio metadata. Lets the agent answer "what is this file" or -"when was this photo taken" without me opening external tools. -Pure read. +*Entry:* Phase 5 UX shipped. -**** TODO [#B] Structured data processing (jq / yq) :feature: +*Deliverables:* +- Add =linear= and =notion= back to =cj/mcp-enabled-servers=. +- Doctor gains live-auth-check mode (=C-u C-; a C d=): invokes a single safe read per auth class to verify OAuth tokens haven't silently expired. Static checks first; live probe only fires after static passes. +- OAuth recovery pattern matcher surfaces auth URLs in =cj/mcp-status= on first connect. -=jq= for JSON, =yq= for YAML / TOML. Filter / project / transform -structured data into a smaller, more focused view before reading. -Strictly read-only -- output goes to the chat, not to disk. The -agent often wants "the third element of .results" from a JSON file -and this is much cheaper than pasting the whole thing. +*Exit:* first connect surfaces the OAuth URL through the recovery pattern; after browser handshake completes, subsequent connects succeed without prompt; live-auth-check correctly identifies a deliberately revoked token; both servers appear ready in the audit buffer. -**** TODO [#B] Eshell command submission :feature: +**** TODO [#B] Phase 7 -- Env-dependent stdio servers (figma, google-*) :mcp: -Submit a single eshell command line, return output (capped). -=:confirm t= always -- this is the escape hatch where the -strictly-typed wrappers above don't fit, so each invocation needs -my eyeball. Eshell parses in-process (no /bin/sh fork) so the -security surface is narrower than a shell command runner, but it's -still effectively arbitrary execution -- treat it as such. +*Goal:* add the remaining five env-dependent servers. -*** TODO [#B] Media and Reading Related Tools +*Entry:* Phase 6 HTTP servers connect cleanly. -Affordances over non-code content: feeds, PDFs, EPUBs, music. The -agent's job here is summarize / extract / queue, not produce. +*Deliverables:* +- Add =figma=, =google-calendar=, =google-docs-personal=, =google-docs-work=, =google-keep= to =cj/mcp-enabled-servers=. +- Verify env-merge from =~/.claude.json= for each (the mtime-cached reader from Phase 1). +- Verify figma's =:secret-args= splicing places the API key correctly without echoing it. +- Manual smoke: simulate token expiry on one Google server; recovery message points at "re-auth via Claude Code, then C-; a C r SERVER". -**** TODO [#B] Elfeed entry tools :feature: +*Exit:* all 9 servers reach =ready= state on a clean machine. Sentinel-grep check across status / audit / hub / errors / audit-log shows zero secret leakage. Doctor's live-auth covers each auth class (oauth, token, args-token, in-protocol, local, none). -Read entry body; list unread by feed or tag; mark read after a -summary lands in a roam node or inbox. Enables "give me the -non-noise headlines from this week's feeds" flows. +**** TODO [#B] Phase 8 -- Privacy + audit polish :mcp: -**** TODO [#B] PDF and EPUB text tools :feature: +*Goal:* land the final UX polish and documentation. -Extract plain text from a PDF page or page range (via =pdftotext=) -and from an EPUB (via the existing nov-mode pipeline). Lets the -agent summarize / quote a research paper or book chapter without -me pasting passages. +*Entry:* all 9 servers working. -**** TODO [#B] EMMS playback and queue tools :feature: +*Deliverables:* +- Audit buffer privacy header: "Tool results land in =gptel-tools= responses; saved conversations persist them. Use =cj/gptel-autosave-toggle= per buffer to opt out." +- =cj/mcp-tool-audit-log-enabled= defcustom + log writer (=~/.emacs.d/data/mcp-tool-log/YYYY-MM-DD.log= -- metadata only, one line per call, daily rotation). +- =ai-mcp.el= commentary updated with the code-organization outline as a table of contents. +- Final pass on tests covering saved-conversation behavior (autosave persists MCP tool results; toggling off prevents persistence). -Current track, queue contents, playback state; queue or play a -path; compose a playlist from a prompt ("play something focusing -that's not Nick Cave"). Light tools, but a frequent friction -point. +*Exit:* all 10 acceptance criteria from the spec pass. Manual matrix run end-to-end on a fresh Emacs. Working tree clean. -*** TODO [#B] Development Workflow Related Tools +*** TODO [#C] Wrap the gh CLI as a GPTel tool -Affordances over the dev loop: compilation output, test invocation, -coverage / profile data, flycheck / flymake diagnostics. +**** 2026-05-16 Sat @ 16:20:00 -0500 Spec -**** TODO [#B] Compilation buffer tools :feature: +Design doc: [[file:docs/design/gptel-gh-tool.org][docs/design/gptel-gh-tool.org]] -Read the most recent =compile= buffer output; parse error locations -to =file:line=; summarize what broke. Pairs with the F6 test-runner -flow -- "tell me what's failing" becomes a single agent turn -instead of paste + parse. +*** TODO [#C] GPTel should autosave regularly after a conversation is saved +*** TODO [#B] Org Workflow Related Tools -**** TODO [#B] Project test invocation tools :feature: +Affordances that expose the Org workspace -- agenda state, capture +targets, org-roam nodes and backlinks, dailies, drill review state -- +to the agent as structured context, not raw .org buffer text. -Run =make test-file FILE=X= / =make test-name TEST=Y= / -project-equivalent and return results. Currently each agent guesses -the project convention; expose the canonical invocation explicitly -per project so the agent can run focused tests itself. +**** TODO [#B] Agenda state tools :feature: -**** TODO [#B] Coverage and profile tools :feature: +Read scheduled / deadline / waiting tasks for a date range; query by +tag, priority, or TODO keyword; list what's blocking today. Lets the +agent answer "what's on the critical path this week" without me +pasting agenda output, and feeds the daily-prep / wrap-up workflows. -Read the most recent SimpleCov JSON or profile dump. Lets the -agent answer "what's still uncovered after this push" or "what -function dominates startup time" against real measured data. +**** TODO [#B] Org-roam node tools :feature: -**** TODO [#B] Diagnostic tools (flycheck / flymake) :feature: +Resolve a topic to its node; return body + backlinks; list nodes by +tag; surface dailies for a date range. Lets the agent reason over +the personal knowledge graph and write back into it via the capture +tools below. -Surface current-buffer or project-wide errors and warnings. Useful -both as a "what's broken right now" check and as input to the -patch-narrative buffer / commit-intent workbench above. +**** TODO [#B] Capture creation tools :feature: -** TODO [#C] Review and rebind M-S- keybindings :refactor: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: +Drive =org-capture= from a template key + body string. Lets the +agent file inbox items, reading notes, journal entries, or roam +nodes without me leaving the chat. Tight pairing with the +=cj/org-capture= optimization task in todo.org. -Changed from M-uppercase to M-S-lowercase for terminal compatibility. -These may override useful defaults - review and pick better bindings: -- M-S-b calibredb (was overriding backward-word) -- M-S-c time-zones (was overriding capitalize-word) -- M-S-d dwim-shell-menu (was overriding kill-word) -- M-S-e eww (was overriding forward-sentence) -- M-S-f fontaine (was overriding forward-word) -- M-S-h split-below -- M-S-i edit-indirect -- M-S-k show-kill-ring (was overriding kill-sentence) -- M-S-l switch-themes (was overriding downcase-word) -- M-S-m kill-all-buffers -- M-S-o kill-other-window -- M-S-r elfeed -- M-S-s window-swap -- M-S-t toggle-split (was overriding transpose-words) -- M-S-u winner-undo (was overriding upcase-word) -- M-S-v split-right (was overriding scroll-down) -- M-S-w wttrin (was overriding kill-ring-save) -- M-S-y yank-media (was overriding yank-pop) -- M-S-z undo-kill-buffer (was overriding zap-to-char) +**** TODO [#B] Org-drill review tools :feature: -** TODO [#C] Build cj/dev-setup-project helper (per docs/design/dev-setup-project.org) :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: -*** 2026-05-15 Fri @ 19:17:37 -0500 Specification +Surface next-due drill cards in =drill-dir=; let the agent quiz on a +topic and report performance. Useful for prompted recall sessions +("ask me five medical-Spanish cards") and for "did this card stick" +analysis. -Interactive command that opens a review buffer with proposed per-subdirectory .dir-locals.el contents (projectile compile/run/test + cj/coverage-backend), optional starter Makefile when none exists, and gitignore updates. User edits inline, C-c C-c writes all files. +*** TODO [#B] Git Related Tools -Design: [[file:docs/design/dev-setup-project.org][docs/design/dev-setup-project.org]] +Affordances that expose magit's structured view of a repo -- sections, +staged-vs-unstaged, commit metadata, rebase / conflict state -- as +first-class tools rather than asking the model to reason over raw +diff text. -Scope of v1: -- modules/dev-setup-config.el (command + review-buffer major mode) -- Three-tier detection: existing Makefile, existing package.json/pyproject.toml scripts, fall-back starter Makefile generation. -- Project shapes supported: pure Elisp, pure Go, pure Python, pure Node/TS, Docker Compose polyglot. -- Re-run semantics: status banners (UNCHANGED / WILL UPDATE / WILL CREATE), idempotent gitignore append, never modifies an existing Makefile. -- ERT tests for the pure helpers (Makefile parser, package.json parser, shape detection, target-to-role mapping, review-buffer parser). - -Deferred: -- Rust (Cargo.toml), Java (pom.xml), other language shapes. -- Project-wide override config file. -- Auto-detecting external run scripts in conventional locations. +**** TODO [#B] Section-aware git tools :feature: -Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. +Expose Magit sections as first-class GPTel tools: current section type, +heading, file, hunk range, and content; sibling sections under the same +file; staged / unstaged / untracked status; commit metadata around the +selected commit or branch; the exact staged patch that would be +committed. Lets prompts say "review the file section at point" or +"explain this hunk in the context of adjacent hunks" without manual +context-copying. -*** TODO [#B] Pure detection + parsing helpers :feature: -Implement the four pure helpers the rest of the command composes on: -- =cj/--dev-setup-parse-makefile-targets FILE= (.PHONY + bare target lines, skip pattern rules) -- =cj/--dev-setup-parse-package-json-scripts FILE= (scripts block, JSON) -- =cj/--dev-setup-detect-project-shape ROOT= (Elisp / Go / Python / Node-TS / Docker-Compose polyglot / unknown) -- =cj/--dev-setup-map-targets-to-roles TARGETS= (best-guess compile/run/test mapping per design § Detection) +**** TODO [#B] Commit intent workbench :feature: -Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O -beyond reading the named file. +Transient that builds a commit intentionally: +1. Agent reads unstaged + staged changes. +2. Agent proposes coherent commit groups. +3. User selects groups in a Magit-style buffer. +4. Agent stages those paths or hunks only after confirmation. +5. Agent generates a message reflecting the selected intent. -Acceptance: each helper callable in isolation with handcrafted fixtures; -no command yet. +Addresses the common case of two or three unrelated edits in one +working tree -- a single commit-message generator can't handle that +cleanly. -Depends on: none -- start here. +**** TODO [#B] Patch narrative buffer :feature: -*** TODO [#B] ERT coverage for the pure helpers :feature:tests: -Normal/Boundary/Error tests for every helper from the prior sub-task, -matching the design's testing section. +Generate an Org buffer that explains a change set as a reviewable +narrative: +- "What changed" by subsystem. +- "Why it appears to have changed" inferred from names, tests, and docs. +- "Risk areas" with links back to Magit file sections. +- "Suggested verification" using local Makefile targets when present. -Files: =tests/test-dev-setup-config.el=, plus -=tests/testutil-dev-setup-config.el= for the temp-project fixture builder -(writes Makefile / package.json / compose stub into =make-temp-file ... 'dir=). +Reusable artifact: paste into a PR description, save with an AI +session, or file into org-roam. -Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; -every helper has at least one Normal, one Boundary, one Error case. +**** TODO [#B] Review-thread simulator :feature: -Depends on: pure detection + parsing helpers. +Before opening a PR, create a local review buffer with inline comments +attached to Magit diff positions. The agent writes comments as if +reviewing someone else's patch: +- Comments grouped by severity. +- Each comment links to file and line. +- Resolved comments check off in Org. +- Accepted suggestions apply through the existing text-update tools. -*** TODO [#B] Starter-Makefile + .dir-locals.el proposal generator :feature: -Pure function =cj/--dev-setup-build-proposal SHAPE ROOT= returning a -structured plist of proposed blocks: one per subproject =.dir-locals.el= -(projectile compile/run/test + =cj/coverage-backend=), the optional starter -Makefile (only when none exists, adapted per shape per design § Tier 3), -and the gitignore append lines. +Makes "review my diff" less ephemeral and avoids losing useful findings +inside a chat transcript. -Files: =modules/dev-setup-config.el=. +**** TODO [#B] Rebase and conflict coach :feature: -Acceptance: given a shape plist, returns deterministic block list ready for -the review buffer; ERT cases cover each shape (Elisp / Go / Python / Node-TS -/ polyglot) plus the Tier-1 "Makefile already exists, suppress Makefile -block" branch. +When Magit enters a rebase, cherry-pick, merge, or conflict state, +expose an agent command that reads: +- Git operation state from =.git/=. +- Conflict markers in the worktree. +- Relevant commits from =git log --merge= or the rebase todo. +- The current Magit status sections. -Depends on: pure detection + parsing helpers. +The agent explains the conflict in domain terms and proposes a +resolution patch; the actual edit and =git add= stay under explicit +user control. -*** TODO [#B] Review-buffer major mode + parser :feature: -Define =cj/dev-setup-review-mode= (derived from =emacs-lisp-mode=) with =C-c -C-c= / =C-c C-k= bindings, plus the pure parser -=cj/--dev-setup-review-buffer-parse CONTENTS= that turns buffer text back -into a block list. Banner syntax per design § Review Buffer (=;; ==== <path> -====[ <status>]==, gitignore special, Makefile special). +**** TODO [#B] Regression archaeology :feature: -Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el= -(parser cases: well-formed multi-block, single block, empty body, missing -banner, malformed elisp inside a dir-locals block). +Magit transient that runs a bisect-like reasoning workflow: +- Ask for a symptom and a known-good / known-bad range. +- Summarize candidate commits in small batches. +- Use tests or user-provided repro commands when available. +- Maintain a bisect journal in an Org buffer. -Acceptance: round-trip -- render proposal -> parse buffer -> equal block -list. Mode keybindings smoke-tested. +Even when the agent can't run the whole bisect, it keeps the +investigation structured and preserves why each commit was judged +good or bad. -Depends on: starter-Makefile + .dir-locals.el proposal generator. +*** TODO [#B] Messaging Related Tools -*** TODO [#B] Writer + status diff + projectile cache reset :feature: -Implement the =C-c C-c= writer: diff each parsed block against the on-disk -file to assign =UNCHANGED= / =WILL UPDATE= / =WILL CREATE=, write only the -non-UNCHANGED ones, append gitignore idempotently, never touch an existing -Makefile, honor the =;;; cj/dev-setup-project: ignore= escape hatch, clear -projectile's per-project command cache, print the summary line. +Affordances over mu4e, Slack, Telegram, and ERC. Same shape across +protocols: read recent threads, search by sender / topic, compose a +draft from a prompt + thread context, leave the send under explicit +user control. -Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + -idempotent-append logic against temp dirs. +**** TODO [#B] Mu4e thread and compose tools :feature: -Acceptance: re-run on an unchanged project writes nothing; renaming a -Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay -untouched. +Read the message at point and surrounding thread (with attachments +summarized); query the inbox by =from:= / =subject:= / date range; +compose a draft from a prompt + thread context using =org-msg=. +Pairs with the existing =mu4e-org-contacts-integration.el=. -Depends on: review-buffer major mode + parser. +**** TODO [#B] Slack thread and compose tools :feature: -*** TODO [#B] Interactive command + smoke test :feature:tests: -Thin =cj/dev-setup-project= interactive wrapper: resolve project root via -projectile, run detection, build proposal, render the review buffer, pop to -it. One smoke test against a prepared temp project asserting the expected -files exist after a simulated =C-c C-c=. +Read channel / DM / thread history through =emacs-slack=; search by +user or channel; compose a draft message but leave sending to me. +Mirrors the mu4e shape so the agent's interface is uniform across +messaging protocols. -Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add -=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). +**** TODO [#B] Telegram and IRC read tools :feature: -Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review -buffer; =C-c C-c= writes the expected files. +Same shape as Slack for =telega= (Telegram) and =erc= (IRC): +recent-message reads, search, and draft compose. Bundled because +the API shape is identical even if the underlying clients differ. -Depends on: writer + status diff + projectile cache reset. +**** TODO [#B] Contact resolution tools :feature: -*** TODO [#B] Resolve open questions + design follow-ups :cleanup: -Three design questions to close before / during implementation: (a) include -=make coverage= target in starter Makefile? (b) project-wide override file -=.cj-dev-setup.el=? (c) Cargo/pom detection. +Resolve a name to email / Slack ID / Telegram handle via +=org-contacts= and the configured address books. Removes the +"who's this person again" friction from the compose flows above. -Body: park decisions inline in the design doc or run =arch-decide= if they -turn out load-bearing. +*** TODO [#B] File and Buffer Related Tools -Depends on: none, but easiest after the writer sub-task surfaces real -friction. +Affordances that expose the user's actual workspace -- open buffers, +narrowed regions, marked files, vterm / eshell sessions -- as +structured context. Stops the model from asking "what file are you +looking at" or "what region is selected." -** TODO [#C] Pick and wire a debug backend for F5 :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-01 -:END: +**** TODO [#B] Buffer state tools :feature: -#+begin_src emacs-lisp - Give me an idea of the amount of work and complexity and what allows for a consistent UX across languages. -#+end_src +List visible buffers with major-mode + file (when any); read the +narrowed region instead of the whole buffer; report point + mark +positions and the active region's text. The single most-asked +question between turns becomes a tool call. -*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals -Bind F5 globally to a debug entry point. Backend choice is the hard part: +**** TODO [#B] Dirvish / Dired tools :feature: -- dape (Debug Adapter Protocol for Emacs) — modern, multi-language via DAP. Single UX across Python, Go, TS, Rust, etc. Less mature than DAP clients in other editors. -- realgud — wraps multiple debuggers (pdb, gdb, node --inspect, etc.). More mature; UX varies by backend. -- Language-specific stacks — dap-mode (python-mode + dap), delve for go, ts-node --inspect, etc. Best per-language UX; most config work. +Read marked files, sort state, and filter state from a Dired or +Dirvish buffer. Lets the agent operate on "the files I just marked" +rather than "files in this directory" -- a real distinction in any +review or refactor workflow. -F5 itself will be simple (start/resume debug). Likely modifier variants once the backend is picked: -- C-F5 toggle breakpoint at point -- M-F5 eval expression in debug context (or step-over shortcut) +**** TODO [#B] Vterm session tools :feature: -Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. +Recent command output from a named vterm session; scroll-history +search. Pairs naturally with the =ai-vterm= design: the agent +running in one project's vterm can read another project's vterm +without leaving the chat. -Do this after the F-key rework ticket ships so F5 is the only hole left. +**** TODO [#B] Eshell session tools :feature: -** TODO [#C] Build debug-profiling.el module :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +Same shape as the vterm tools for =eshell= sessions -- last-command +output, history search, current directory. Most useful for +agent-driven inspection of long-running pipelines. -Reusable profiling infrastructure for targeted slow-command investigation. Consolidates scattered profiler bindings (currently in =modules/config-utilities.el=) and adds two pure-helper-backed entry points: "profile next command" and "time region or sexp." Designed via =/brainstorm= 2026-04-26. +*** TODO [#B] Filesystem Related Tools -Design: [[file:docs/design/debug-profiling.org][docs/design/debug-profiling.org]] +Affordances that let the agent operate on actual files on disk and +run common CLI utilities -- pandoc, ffmpeg, imagemagick, ripgrep, +fd, jq -- rather than relying on me to paste content or run +commands by hand. -Implement via =/start-work= against the design — branch =feat/debug-profiling=, commits decomposed along the test-first split-for-testability boundary. Once shipped, use it as the v1 exercise on the queued [#B] org-capture target-building investigation. +*Design tension to resolve before any of these ship: one tool per +utility, or one generic =run_shell_command=?* -** TODO [#C] Org-noter custom workflow — fix and finish :feature:bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +The shortlist's first pass DEFERRED a generic =run_shell_command=: +sandboxing to HOME + /tmp with a denylist for destructive ops is +straightforward, but the denylist can never be exhaustive, and +"confirmation for everything else" becomes click-fatigue. -Continue debugging and testing the custom org-noter workflow from 2025-11-21 session. -This is partially implemented but has known issues that need fixing before it's usable. +The children below take the other path -- *one gptel tool per +binary*, with a strictly-typed argv shape (e.g. +=pandoc_convert(input_path, output_format)=, not +=pandoc_convert(args_string)=). Each tool: -*Last worked on:* 2025-11-21 -*Current status:* Implementation complete but has bugs, needs testing +- Validates its own paths (must be under HOME, outputs in a + sandboxed dir). +- Rejects dangerous flags explicitly (pandoc =--filter=, ffmpeg's + =-protocol_whitelist= chicanery, imagemagick's policy bypasses). +- Runs via =call-process= with an argv list -- no shell parsing, + no string-interpolation injection. +- Caps output and reports truncation inline. -*Known issues to fix:* +The trade-off is breadth: every new CLI tool means a new gptel tool +file. Acceptable because (a) the list of utilities I actually need +agent access to is small (~8 below covers most of it), and (b) each +wrapper gets type-checked argv and a focused description the model +can reason over, which is genuinely better than a free-form +=run_shell_command(string)=. -1. /Double notes buffer appearing when pressing 'i' to insert note/ - - When user presses 'i' in document to insert a note, two notes buffers appear - - Expected: single notes buffer appears - - Need to debug why the insert-note function is creating duplicate buffers +The =eshell_submit= entry at the end is the escape hatch for one- +off needs the wrappers don't cover -- =:confirm t= always. -2. /Toggle behavior refinement needed/ - - The toggle between document and notes needs refinement - - May have edge cases with window management - - Need to test various scenarios +Adjacent categories: the existing =gptel-tools/= file CRUD +(=read_text_file=, =write_text_file=, =update_text_file=, +=list_directory_files=, =move_to_trash=) is the foundation this +category extends. =web_fetch= is the network-fetch counterpart. -*Testing needed:* +**** TODO [#B] Document conversion (pandoc) :feature: -1. /EPUB files/ - Test with EPUB documents (primary use case) -2. /Reopening existing notes/ - Verify it works when notes file already exists -3. /Starting from notes file/ - Test opening document from an existing notes file -4. /PDF files/ - Verify compatibility with PDF workflow -5. /Edge cases:/ - - Multiple windows open - - Splitting behavior - - Window focus after operations +Convert between markdown, org, html, pdf, docx, latex, epub, plain +text. Most common use: "extract this docx to markdown so I can +read it inline." Strict argv: input path, output format, optional +output path. Reject =--filter= and =--lua-filter= (arbitrary code +execution). Output written to a sandbox dir unless explicit +override. -*Implementation files:* -- =modules/org-noter-config.el= - Custom workflow implementation -- Contains custom functions for document/notes toggling and insertion +**** TODO [#B] Image manipulation (imagemagick) :feature: -*Context:* -This custom workflow is designed to make org-noter more ergonomic for Craig's reading/annotation -workflow. It simplifies the toggle between document and notes, and streamlines note insertion. -The core functionality is implemented but needs debugging before it's production-ready. +Resize, format-convert, get-metadata (=identify=), optionally crop / +rotate / annotate. Common use: "resize this PNG to a thumbnail" or +"convert these HEICs to JPEGs." Strict argv per operation. +Reject pre-validated dangerous formats (the historical EXR / SVG / +MVG CVE surface) unless explicitly enabled. ImageMagick's +=policy.xml= is the underlying defense; the wrapper enforces it at +the tool boundary too. -**Next Steps:** -1. Debug the double buffer issue when pressing 'i' -2. Test all scenarios listed above -3. Refine toggle behavior based on testing -4. Document the final keybindings and workflow +**** TODO [#B] Audio / video processing (ffmpeg) :feature: -** TODO [#C] Build an Org-native API workspace :feature:tests: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +Trim, transcode, extract audio, get-metadata (=ffprobe=). Paths +under HOME only; reject network-protocol inputs (=http:= / =rtmp:= +/ =rtsp:=) so the model can't pull from arbitrary sources. Pairs +with the existing transcription module -- the same "extract audio +from video" path =cj/transcribe-media= uses internally. -Build an Emacs-native API workspace layer that keeps =restclient.el= useful for -lightweight request execution while adding OpenAPI import, Org notebooks, -response capture, inline images, and =gptel=-assisted API documentation. +**** TODO [#B] Content search (ripgrep) :feature: -*** Spec +=rg= wrapper with path / glob filtering, result-count cap, optional +literal-vs-regex mode. Pure read. Was in the shortlist's ADOPT +bucket as =search_in_files=. Highest-leverage filesystem tool by +expected call frequency -- "where in this repo is X" is the +question I paste agent output for most often. -**** Summary -Build a small Emacs API-workspace layer that keeps =restclient.el= as the -plain-text request executor, while adding higher-level discovery, generation, -Org notebook, response handling, and =gptel=-assisted documentation workflows. +**** TODO [#B] File discovery (fd) :feature: -The intended result is not a Postman clone. It should feel like an -Emacs-native API lab: -- generate request collections from OpenAPI/Swagger specs -- browse and execute requests from =.rest= files or Org notebooks -- save useful responses back into Org -- display image responses inline -- use =gptel= to explain APIs, endpoints, request bodies, and responses -- leave room for =verb.el= or Hurl where they are a better fit +=fd= (or =find= fallback) wrapper, capped result count. Pure +read, lower stakes than =search_in_files= (filenames only, no +content). Common pairing: =find_file_by_name= then +=read_text_file=. -**** Goals -- Preserve the current lightweight =restclient.el= workflow for ad-hoc calls. -- Add an OpenAPI importer that can generate useful first-draft request files. -- Add an Org workspace format for API notes, executable request blocks, results, - response links, and generated summaries. -- Add response post-processing helpers for JSON, binary/image data, and model - summaries. -- Make common auth flows easy to scaffold without storing secrets in generated - files. -- Keep generated artifacts readable and editable by hand. -- Keep implementation modular enough that =verb.el= can be evaluated as a richer - Org-native frontend. +**** TODO [#B] Metadata extraction (file / exiftool) :feature: -**** Non-Goals -- Do not build a full graphical API client. -- Do not store secrets directly in Org or =.rest= files. -- Do not attempt complete OpenAPI 3.1 schema synthesis in the first pass. -- Do not require =gptel= for ordinary request execution. -- Do not make Hurl a runtime dependency for the restclient workflow. +=file= for MIME-type detection; =exiftool= for image / video / +audio metadata. Lets the agent answer "what is this file" or +"when was this photo taken" without me opening external tools. +Pure read. -**** Primary User Flows -***** Import An API -1. User runs =cj/restclient-import-openapi=. -2. Command prompts for a URL or local OpenAPI/Swagger file. -3. Command parses the spec into normalized endpoint records. -4. Command prompts for output format: - - =restclient= request collection - - Org API workspace - - both -5. Command writes generated files under a project/API workspace directory. -6. Generated file includes host variables, auth placeholders, request examples, - and a short summary of how to start using the collection. +**** TODO [#B] Structured data processing (jq / yq) :feature: -***** Describe An API -1. User runs =cj/restclient-describe-api= from a generated workspace or spec file. -2. Command extracts API metadata, paths, operations, schemas, auth, and tags. -3. Command sends a bounded summary payload to =gptel=. -4. Result is inserted under an Org =Overview= subtree. +=jq= for JSON, =yq= for YAML / TOML. Filter / project / transform +structured data into a smaller, more focused view before reading. +Strictly read-only -- output goes to the chat, not to disk. The +agent often wants "the third element of .results" from a JSON file +and this is much cheaper than pasting the whole thing. -***** Execute And Capture A Request -1. User executes a request via =restclient.el= or =ob-restclient=. -2. Command captures response status, headers, content type, body, and timestamp - when available. -3. JSON/XML responses can be inserted as source blocks or summarized. -4. Image responses are saved to an assets directory and linked inline in Org. -5. Binary responses that are not image-like are saved as file links. +**** TODO [#B] Eshell command submission :feature: -***** Iterate On A Response -1. User runs helper commands against the last response: - - pretty-print JSON/XML - - run =jq= - - summarize with =gptel= - - extract a value into a restclient variable - - save body to a file -2. The result is inserted near the endpoint subtree or shown in a temporary - buffer depending on command prefix/options. +Submit a single eshell command line, return output (capped). +=:confirm t= always -- this is the escape hatch where the +strictly-typed wrappers above don't fit, so each invocation needs +my eyeball. Eshell parses in-process (no /bin/sh fork) so the +security surface is narrower than a shell command runner, but it's +still effectively arbitrary execution -- treat it as such. -**** Proposed Modules -***** =modules/restclient-workspace.el= -Main configuration and user-facing commands. Owns keybindings, workspace -creation, dispatch commands, and integration with existing restclient config. +*** TODO [#B] Media and Reading Related Tools -***** =modules/restclient-openapi.el= -OpenAPI/Swagger loading and normalization: -- fetch URL or read file -- parse JSON/YAML where available -- normalize servers, paths, methods, parameters, request bodies, auth schemes, - tags, operation IDs, and examples -- expose pure helper functions suitable for unit tests +Affordances over non-code content: feeds, PDFs, EPUBs, music. The +agent's job here is summarize / extract / queue, not produce. -***** =modules/restclient-generate.el= -Generation layer: -- render =.rest= / =.http= request collections -- render Org workspaces -- synthesize simple JSON request bodies from schemas/examples -- generate variables and auth placeholders +**** TODO [#B] Elfeed entry tools :feature: -***** =modules/restclient-response.el= -Response helpers: -- identify content type -- save binary/image bodies -- insert Org links -- display inline images -- route JSON/XML/text handling -- track last response metadata +Read entry body; list unread by feed or tag; mark read after a +summary lands in a roam node or inbox. Enables "give me the +non-noise headlines from this week's feeds" flows. -***** =modules/restclient-ai.el= -=gptel= integration: -- summarize API specs -- explain endpoint behavior -- generate example payload notes -- summarize responses -- keep prompts bounded and avoid sending secrets +**** TODO [#B] PDF and EPUB text tools :feature: -**** File And Workspace Layout -Default generated workspace: +Extract plain text from a PDF page or page range (via =pdftotext=) +and from an EPUB (via the existing nov-mode pipeline). Lets the +agent summarize / quote a research paper or book chapter without +me pasting passages. -#+begin_src text -data/apis/<api-slug>/ - <api-slug>.rest - <api-slug>.org - openapi.json - assets/ - responses/ -#+end_src +**** TODO [#B] EMMS playback and queue tools :feature: -The exact root should be configurable, defaulting to the existing REST data -directory if one is already present in the config. +Current track, queue contents, playback state; queue or play a +path; compose a playlist from a prompt ("play something focusing +that's not Nick Cave"). Light tools, but a frequent friction +point. -**** Org Workspace Shape -#+begin_example -,* API Name -:PROPERTIES: -:OPENAPI_SOURCE: https://example.com/openapi.json -:BASE_URL: https://api.example.com -:END: +*** TODO [#B] Development Workflow Related Tools -,** Overview -Generated or user-written API notes. +Affordances over the dev loop: compilation output, test invocation, +coverage / profile data, flycheck / flymake diagnostics. -,** Auth -Token acquisition notes and placeholders. No secrets stored here. +**** TODO [#B] Compilation buffer tools :feature: -,** Endpoints -,*** GET /users -:PROPERTIES: -:OPERATION_ID: listUsers -:METHOD: GET -:PATH: /users -:END: +Read the most recent =compile= buffer output; parse error locations +to =file:line=; summarize what broke. Pairs with the F6 test-runner +flow -- "tell me what's failing" becomes a single agent turn +instead of paste + parse. -#+begin_src restclient :results raw -GET :host/users -Authorization: Bearer :token -Accept: application/json -#+end_src +**** TODO [#B] Project test invocation tools :feature: -,**** Notes -,**** Responses -#+end_example +Run =make test-file FILE=X= / =make test-name TEST=Y= / +project-equivalent and return results. Currently each agent guesses +the project convention; expose the canonical invocation explicitly +per project so the agent can run focused tests itself. -**** Commands -- =cj/restclient-new-scratch= :: open a scratch =restclient-mode= buffer. -- =cj/restclient-open-file= :: open a REST file from the configured API data dir. -- =cj/restclient-import-openapi= :: generate a workspace from OpenAPI/Swagger. -- =cj/restclient-describe-api= :: insert a =gptel=-generated API overview. -- =cj/restclient-describe-endpoint= :: explain the endpoint at point. -- =cj/restclient-generate-example-body= :: generate or refresh sample JSON body. -- =cj/restclient-save-last-response= :: save response body and metadata. -- =cj/restclient-insert-last-response-org= :: insert response under Org subtree. -- =cj/restclient-display-image-response= :: save and display image response. -- =cj/restclient-response-jq= :: run =jq= against the last JSON response. -- =cj/restclient-copy-curl= :: copy the request at point as curl if supported. - -**** Keybindings -Keep the existing prefix shape under =C-; R=: -- =C-; R n= :: new scratch request buffer -- =C-; R o= :: open REST file -- =C-; R i= :: import OpenAPI/Swagger -- =C-; R d= :: describe API or endpoint -- =C-; R s= :: save/capture last response -- =C-; R j= :: run =jq= on last response -- =C-; R m= :: transient menu for workspace commands +**** TODO [#B] Coverage and profile tools :feature: -**** OpenAPI Import Details -Minimum first-pass support: -- OpenAPI 3.x JSON -- Swagger 2.0 JSON if easy to normalize -- YAML via available Emacs YAML library or external converter if already present -- =servers= / =host= + =basePath= -- path-level and operation-level parameters -- query/path/header parameters -- JSON request bodies -- examples and default schema values -- security schemes: - - HTTP bearer - - basic - - API key header - - API key query +Read the most recent SimpleCov JSON or profile dump. Lets the +agent answer "what's still uncovered after this push" or "what +function dominates startup time" against real measured data. -First pass can skip or mark as unsupported: -- polymorphic schemas beyond simple =oneOf= / =anyOf= note generation -- multipart body generation -- full OAuth flows -- callbacks/webhooks -- complete response schema rendering +**** TODO [#B] Diagnostic tools (flycheck / flymake) :feature: -**** Secret Handling -- Generated files must use placeholders like =:token=, =:api-key=, or - =:basic-auth=. -- Do not write tokens into generated files. -- Prefer variables loaded from auth-source, environment variables, or manually - entered restclient variables. -- =gptel= prompts must strip obvious auth headers and secret-like values from - request/response payloads before sending context. +Surface current-buffer or project-wide errors and warnings. Useful +both as a "what's broken right now" check and as input to the +patch-narrative buffer / commit-intent workbench above. -**** Response Handling -- Text JSON/XML/HTML/plain responses may be inserted into Org as source blocks. -- JSON responses should support optional =jq= filters. -- Image responses should be saved under =assets/responses/= and inserted as Org - file links. -- After inserting image links, call =org-display-inline-images= when in Org. -- Large responses should be saved as files and linked rather than inserted. -- Binary non-image responses should be saved and linked with content type notes. +** TODO [#C] Review and rebind M-S- keybindings :refactor: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: -**** Integration Choices To Evaluate -- =restclient.el= remains the default executor for =.rest= files. -- =ob-restclient= powers executable Org source blocks. -- =verb.el= should be evaluated as an alternate frontend for Org-native API - workspaces because it already has tree inheritance, embedded Elisp, and image - response display. -- Hurl should be evaluated as an export/test target, especially for chained - request tests and CI assertions. +Changed from M-uppercase to M-S-lowercase for terminal compatibility. +These may override useful defaults - review and pick better bindings: +- M-S-b calibredb (was overriding backward-word) +- M-S-c time-zones (was overriding capitalize-word) +- M-S-d dwim-shell-menu (was overriding kill-word) +- M-S-e eww (was overriding forward-sentence) +- M-S-f fontaine (was overriding forward-word) +- M-S-h split-below +- M-S-i edit-indirect +- M-S-k show-kill-ring (was overriding kill-sentence) +- M-S-l switch-themes (was overriding downcase-word) +- M-S-m kill-all-buffers +- M-S-o kill-other-window +- M-S-r elfeed +- M-S-s window-swap +- M-S-t toggle-split (was overriding transpose-words) +- M-S-u winner-undo (was overriding upcase-word) +- M-S-v split-right (was overriding scroll-down) +- M-S-w wttrin (was overriding kill-ring-save) +- M-S-y yank-media (was overriding yank-pop) +- M-S-z undo-kill-buffer (was overriding zap-to-char) -**** Testing Strategy -- Unit-test OpenAPI normalization with small fixture specs. -- Unit-test request generation for GET, POST, auth, query params, path params, - and request-body examples. -- Unit-test secret redaction before =gptel= calls. -- Unit-test response classification and Org insertion helpers. -- Integration-test generated =.rest= files for representative APIs. -- Integration-test generated Org workspaces with =ob-restclient= where feasible. -- Avoid live network tests by default; use fixtures/stubs unless explicitly - tagged =:network=. +** TODO [#C] Build cj/dev-setup-project helper (per docs/design/dev-setup-project.org) :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +*** 2026-05-15 Fri @ 19:17:37 -0500 Specification -**** First Milestone -1. Keep/verify existing restclient scratch/open commands. -2. Add a tiny OpenAPI JSON parser/normalizer for a fixture spec. -3. Generate a readable =.rest= collection with variables and examples. -4. Generate a matching Org workspace. -5. Add response save/link helpers for JSON and images. -6. Add a =gptel= API-summary command with secret redaction. -7. Add focused unit tests and one sample fixture. +Interactive command that opens a review buffer with proposed per-subdirectory .dir-locals.el contents (projectile compile/run/test + cj/coverage-backend), optional starter Makefile when none exists, and gitignore updates. User edits inline, C-c C-c writes all files. -**** Open Questions -- Should the canonical workspace be =.rest= first, Org first, or generated in - both formats by default? -- Is =verb.el= a better primary target than =ob-restclient= for the Org notebook - experience? -- Which YAML parser should be used if no YAML package is already configured? -- Where should API workspaces live by default: =data/=, =docs/=, or project root? -- Should response capture hook into restclient internals, or should capture be a - separate explicit command operating on response buffers? -- How much schema synthesis is useful before it becomes noisy? +Design: [[file:docs/design/dev-setup-project.org][docs/design/dev-setup-project.org]] -*** Ideas -- Treat =restclient.el= as the lightweight request scratchpad, and layer richer workflow commands around it instead of trying to turn it into Postman. -- Add an OpenAPI/Swagger importer: - - prompt for a spec URL or local file - - parse paths, methods, auth schemes, request bodies, and examples - - generate a =.http= / =.rest= request collection - - optionally generate an Org notebook with one subtree per endpoint -- Add an API description command using =gptel=: - - summarize the API from an OpenAPI spec - - explain each endpoint, auth requirement, parameters, and response shape - - write the summary into the generated Org workspace -- Generate example requests automatically: - - =GET= examples with query params - - =POST= / =PUT= / =PATCH= examples with sample JSON bodies - - =DELETE= examples with safe placeholder IDs - - shared variables like =:host=, =:token=, =:api-version=, =:tenant= -- Add auth helpers: - - bearer token insertion - - basic auth - - API key header/query param - - OAuth token fetch request template -- Improve Org integration: - - use =ob-restclient= for executable API notebooks - - support =:jq= filters for clean JSON results - - save response bodies under endpoint subtrees - - capture request/response metadata as Org properties -- Handle images and binary responses: - - detect image =Content-Type= - - save response data into an assets directory - - insert =[[file:...]]= links into Org - - call =org-display-inline-images= after execution -- Add response-processing commands: - - pretty-print JSON/XML - - run =jq= against the last response - - summarize response with =gptel= - - extract fields into restclient variables for follow-up calls -- Add request collection ergonomics: - - imenu/consult navigation by endpoint - - transient menu for send/copy curl/jq/save response - - templates for common headers - - per-project API workspace discovery -- Investigate =verb.el= as the richer Org-native frontend: - - Org tree inheritance for host/header/auth defaults - - embedded Elisp in request specs - - built-in display of image/PDF/SVG responses - - likely better base for a notebook-style API client -- Investigate Hurl for repeatable API tests: - - request chaining - - captures - - assertions - - CI-friendly execution - - possible export target from generated API workspaces +Scope of v1: +- modules/dev-setup-config.el (command + review-buffer major mode) +- Three-tier detection: existing Makefile, existing package.json/pyproject.toml scripts, fall-back starter Makefile generation. +- Project shapes supported: pure Elisp, pure Go, pure Python, pure Node/TS, Docker Compose polyglot. +- Re-run semantics: status banners (UNCHANGED / WILL UPDATE / WILL CREATE), idempotent gitignore append, never modifies an existing Makefile. +- ERT tests for the pure helpers (Makefile parser, package.json parser, shape detection, target-to-role mapping, review-buffer parser). -*** Original Goals -**** Keybindings to test -- C-; R n — new scratch *restclient* buffer (should open in restclient-mode) -- C-; R o — open .rest file (should default to data/ directory) +Deferred: +- Rust (Cargo.toml), Java (pom.xml), other language shapes. +- Project-wide override config file. +- Auto-detecting external run scripts in conventional locations. -**** Functional tests -1. Open tutorial-api.rest, run JSONPlaceholder GET (C-c C-c) — verify response inline -2. Run POST example — verify 201 response with fake ID -3. Run httpbin header echo — verify custom headers echoed back -4. Navigate between requests with C-c C-n / C-c C-p -5. Test jq filtering (requires jq installed): restclient-jq loaded? -6. Open scratch buffer (C-; R n), type a request manually, execute -7. which-key shows "REST client" menu under C-; R - -** TODO [#C] Migrate from Company to Corfu (with prescient integration) :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. -Spec: [[file:docs/design/company-to-corfu-migration.org][docs/design/company-to-corfu-migration.org]] +*** TODO [#B] Pure detection + parsing helpers :feature: +Implement the four pure helpers the rest of the command composes on: +- =cj/--dev-setup-parse-makefile-targets FILE= (.PHONY + bare target lines, skip pattern rules) +- =cj/--dev-setup-parse-package-json-scripts FILE= (scripts block, JSON) +- =cj/--dev-setup-detect-project-shape ROOT= (Elisp / Go / Python / Node-TS / Docker-Compose polyglot / unknown) +- =cj/--dev-setup-map-targets-to-roles TARGETS= (best-guess compile/run/test mapping per design § Detection) -*** TODO [#C] Install corfu-side packages -Add corfu, cape, kind-icon, corfu-prescient to the package list. corfu-popupinfo ships inside corfu. Spec step 1. +Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O +beyond reading the named file. -*** TODO [#C] Rewrite selection-framework.el company block as corfu/cape stack -Replace the three company-* use-package blocks (lines 192-226) and company-prescient (240-243) with corfu / cape / corfu-popupinfo / kind-icon / corfu-prescient. Rename the section header Company → Corfu in the same change. Spec steps 2 + 8. +Acceptance: each helper callable in isolation with handcrafted fixtures; +no command yet. -*** TODO [#C] Swap mail-compose completion disable to corfu -Rewrite cj/disable-company-in-mu4e-compose to (corfu-mode -1) across mu4e-compose, org-msg-edit, and message modes (mail-config.el:319-333). Spec step 3. +Depends on: none -- start here. -*** TODO [#C] Drop company-ledger for ledger's built-in capf -ledger-config.el: remove company-ledger; verify ledger-complete-at-point registers on completion-at-point-functions, add a ledger-mode-hook capf push only if it doesn't. Spec step 4. +*** TODO [#B] ERT coverage for the pure helpers :feature:tests: +Normal/Boundary/Error tests for every helper from the prior sub-task, +matching the design's testing section. -*** TODO [#C] Drop company-auctex for AUCTeX capf + cape-tex -latex-config.el: remove company-auctex and (company-auctex-init); add cape-tex on TeX-mode-hook. Spec step 5. +Files: =tests/test-dev-setup-config.el=, plus +=tests/testutil-dev-setup-config.el= for the temp-project fixture builder +(writes Makefile / package.json / compose stub into =make-temp-file ... 'dir=). -*** TODO [#C] Rewire eshell completion to pcomplete capf -eshell-config.el:163-171: drop company-shell and the company-mode activation; add cape-capf-buster around pcomplete-completions-at-point + corfu-mode. Spec step 6. +Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; +every helper has at least one Normal, one Boundary, one Error case. -*** TODO [#C] Remove company-mode calls from prog-go/python/webdev -Delete (declare-function company-mode ...) and (company-mode) from the three mode hooks; global-corfu-mode covers them. Spec step 7. +Depends on: pure detection + parsing helpers. -*** TODO [#C] Uninstall company packages + recompile -After the rewrite is green: package-delete company, -quickhelp, -box, -prescient, -ledger, -auctex, -shell; make clean && make compile. Spec step 9. +*** TODO [#B] Starter-Makefile + .dir-locals.el proposal generator :feature: +Pure function =cj/--dev-setup-build-proposal SHAPE ROOT= returning a +structured plist of proposed blocks: one per subproject =.dir-locals.el= +(projectile compile/run/test + =cj/coverage-backend=), the optional starter +Makefile (only when none exists, adapted per shape per design § Tier 3), +and the gitignore append lines. -*** TODO [#C] Tests: corfu activation, mail-disable, capf registration -New tests/test-selection-framework-corfu.el and tests/test-mail-config-corfu-disable.el; update ledger/latex tests to assert their capf registers. Spec Testing section. +Files: =modules/dev-setup-config.el=. -*** 2026-05-16 Sat @ 11:07:24 -0500 Goals -Drop-in replacement for the in-buffer completion stack: =company= → -=corfu=, =company-quickhelp= → =corfu-popupinfo=, =company-box= → -=kind-icon=, =company-prescient= → =corfu-prescient=, plus =cape= for -the file/keyword/dabbrev capfs that =company-files= / =company-keywords= -used to handle. Per-module fixups for ledger, AUCTeX, eshell, mu4e -compose, and the three =prog-*= modules. See the design doc for the -full translation table, migration steps, tests, and risks. - -** TODO [#C] Extend F2 "preview" convention across modes :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: - -F2 is the universal preview key. Currently bound only in markdown-mode (markdown-preview, in =modules/markdown-config.el=). Org-reveal lives on =C-; o R= via =cj/org-map=, not F2. Extend F2 to other modes where a "preview" action is natural: - -- Hugo blog (hugo-config.el) — preview the post in browser -- HTML / web-mode — open in browser -- Reveal presentations - preview in browser -- Any other mode with a natural "preview this" action +Acceptance: given a shape plist, returns deterministic block list ready for +the review buffer; ERT cases cover each shape (Elisp / Go / Python / Node-TS +/ polyglot) plus the Tier-1 "Makefile already exists, suppress Makefile +block" branch. -Keep the binding mode-local so F2 stays available as a global candidate where no preview makes sense. +Depends on: pure detection + parsing helpers. -** TODO [#C] Localrepo Documentation :feature:docs:localrepo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-05 -:END: +*** TODO [#B] Review-buffer major mode + parser :feature: +Define =cj/dev-setup-review-mode= (derived from =emacs-lisp-mode=) with =C-c +C-c= / =C-c C-k= bindings, plus the pure parser +=cj/--dev-setup-review-buffer-parse CONTENTS= that turns buffer text back +into a block list. Banner syntax per design § Review Buffer (=;; ==== <path> +====[ <status>]==, gitignore special, Makefile special). -Audit on 2026-05-27 found the localrepo build half is shipped (=.localrepo/= holds 185 entries; =early-init.el= L135–165 wires the priority-200 pin above the local ELPA-mirror tier at 120–125 and the online fallback). The remaining "document limitations" half splits into one docs-set plus four gap-fix follow-ups that the docs cross-reference. +Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el= +(parser cases: well-formed multi-block, single block, empty body, missing +banner, malformed elisp inside a dir-locals block). -Docs land in three artifacts. =docs/design/localrepo.org= carries the full architecture (tier model, install path, refresh story, all four limitations with pointers to the follow-up tasks). =.localrepo/README.org= sits next to the artifact as the user-facing entry — a short summary that survives even if =early-init.el= moves. =early-init.el= grows a commentary header that points at the README, not at the design doc — the README is what future-Craig hits first. +Acceptance: round-trip -- render proposal -> parse buffer -> equal block +list. Mode keybindings smoke-tested. -The four limitations the docs cover (each spun out below as its own task): -- Treesitter grammars (downloaded by =treesit-auto= on first use; not in the localrepo) -- Native-comp =.eln= cache (Emacs-version-specific; invalidated by version bumps) -- System-tool deps (=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, etc.; flagged at load by =cj/executable-find-or-warn=, not packageable via =package.el=) -- Refresh / update story (no dedicated script today; ad-hoc =cp= from the elpa mirrors) +Depends on: starter-Makefile + .dir-locals.el proposal generator. -*** TODO [#C] Design doc — docs/design/localrepo.org :docs: -Write the design doc: tier model, priorities, install path, refresh story, all four limitations with cross-links to the follow-up tasks below. +*** TODO [#B] Writer + status diff + projectile cache reset :feature: +Implement the =C-c C-c= writer: diff each parsed block against the on-disk +file to assign =UNCHANGED= / =WILL UPDATE= / =WILL CREATE=, write only the +non-UNCHANGED ones, append gitignore idempotently, never touch an existing +Makefile, honor the =;;; cj/dev-setup-project: ignore= escape hatch, clear +projectile's per-project command cache, print the summary line. -*** TODO [#C] README — .localrepo/README.org :docs: -Write the README at the artifact: short prose entry point summarizing the tier model, pointing at =docs/design/localrepo.org= for full detail. This is what =early-init.el='s commentary header links to. +Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + +idempotent-append logic against temp dirs. -*** TODO [#C] Commentary header in early-init.el :docs: -Add a Commentary-section header in =early-init.el= pointing at =.localrepo/README.org= for usage and =docs/design/localrepo.org= for architecture. Sits at the top of the localrepo block (around L130). +Acceptance: re-run on an unchanged project writes nothing; renaming a +Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay +untouched. -** TODO [#C] TRAMP/dirvish "?" for remote dates — verify the fix per host :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +Depends on: review-buffer major mode + parser. -Root cause is traced (see the dated investigation entry below). What's left needs a live remote: open each remote host in dirvish and run the three diagnostic evals to find which gate is closed, then close it. +*** TODO [#B] Interactive command + smoke test :feature:tests: +Thin =cj/dev-setup-project= interactive wrapper: resolve project root via +projectile, run detection, build proposal, render the review buffer, pop to +it. One smoke test against a prepared temp project asserting the expected +files exist after a simulated =C-c C-c=. -Diagnostics (run with point in a remote dirvish buffer): -- =M-: (dirvish-prop :remote-async)= — nil means =tramp-direct-async-process-p= is failing for this method/host, so dirvish's remote attribute fetch never runs. -- =M-: (dirvish-prop :gnuls)= — nil means the remote has no GNU =ls= (the =ls --version= probe failed), so the parser gate stays shut. Likely on truenas (FreeBSD). -- =M-: (tramp-direct-async-process-p)= — confirms whether direct-async is actually active for the connection. +Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add +=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). -Likely fixes, by which gate is closed: -- =:gnuls= nil → install GNU coreutils on the remote (FreeBSD: =pkg install coreutils=) and make =ls= resolve to GNU on the TRAMP path, or accept "?" on that host. +Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review +buffer; =C-c C-c= writes the expected files. - - Constraint: nothing gets installed on the remote host, so the =:gnuls= gate is resolved by accepting "?" on that host rather than installing coreutils. -- =:remote-async= nil → the scp/sshx method isn't advertising direct-async; switch to a method that supports it or check =tramp-direct-async-process= is taking effect for that protocol. +Depends on: writer + status diff + projectile cache reset. -Files involved: =modules/tramp-config.el=, =modules/dirvish-config.el=. +*** TODO [#B] Resolve open questions + design follow-ups :cleanup: +Three design questions to close before / during implementation: (a) include +=make coverage= target in starter Makefile? (b) project-wide override file +=.cj-dev-setup.el=? (c) Cargo/pom detection. -*** 2026-05-22 Fri @ 20:24:44 -0500 Traced the root cause through dirvish source -Remote dates/sizes don't come from the dired =ls= listing or =dired-listing-switches=. They come from =dirvish-data-for-dir= (=dirvish-tramp.el:95=), which runs =ls -1lahi= on the remote and parses the columns into the attribute cache. That method only fires when both =(dirvish-prop :remote-async)= is a number and =(dirvish-prop :gnuls)= is a string. When either gate is shut, dirvish falls back to its default, which deliberately skips =(file-attributes f-name)= for remote files (=dirvish.el:904=, a perf guard) — leaving attrs nil, so the file-size and file-time widgets render "?" (=dirvish-widgets.el:216,247=). +Body: park decisions inline in the design doc or run =arch-decide= if they +turn out load-bearing. -That explains why every prior fix missed: dired-listing-switches feed a different code path entirely, and disabling =tramp-direct-async-process= shuts the =:remote-async= gate, which is the one path that populates remote attributes — exactly backwards. The config already enables direct-async for ssh/sshx (=tramp-config.el:79-88=), so the remaining closed gate is per-host: =:gnuls= (no GNU ls on FreeBSD-based truenas) or direct-async not taking effect for the method. Could not verify on a live remote from the work session — handed the per-host diagnostics up into the task body. +Depends on: none, but easiest after the writer sub-task surfaces real +friction. -** TODO [#C] Terminal GPG pinentry Completion :feature: +** TODO [#C] Pick and wire a debug backend for F5 :feature: :PROPERTIES: -:LAST_REVIEWED: 2026-06-05 +:LAST_REVIEWED: 2026-06-01 :END: -Audit on 2026-05-27 found no trace of the =terminal-pinentry= branch on this machine: no local or remote ref, no reflog entry across 732 entries reaching back through January, no stash, no dangling commit, no sibling worktree. The 2026-01-24 session log says the branch was created that day, but the work either lived on another machine or was deleted before reaching here. The original task above (=Finish terminal GPG pinentry configuration=) is superseded by this one. - -Surviving footprint on this machine: one commented line at =modules/auth-config.el:83= (=;; (setq epa-pinentry-mode 'loopback)=). The hook point =env-terminal-p= exists in =modules/host-environment.el:97=. Everything else (terminal-vs-GUI branching in the epa =:config=, external pinentry wiring for GUI, =GPG_TTY= export, tests) is to be written fresh off main. - -Goal: in terminal Emacs, GPG passphrase prompts land in the minibuffer via loopback mode; in GUI Emacs, prompts go to the existing external pinentry. - -Open: confirm the GUI pinentry tool (2026-01-24 notes named =pinentry-dmenu=; current =auth-config.el= names no pinentry program, leaving it to =gpg-agent='s config). Also worth checking whether the =terminal-pinentry= branch survives on the laptop and should be pulled here rather than rewritten. - -*** TODO [#C] env-terminal-p branch in epa :config :feature: -Inside the epa =use-package= =:config= in =modules/auth-config.el=, set =epa-pinentry-mode= to ='loopback= when =(env-terminal-p)=, else leave the external pinentry path active. Replace the lone commented line at =auth-config.el:83=. - -*** TODO [#C] GPG_TTY export for terminal sessions :feature: -When =(env-terminal-p)=, =(setenv "GPG_TTY" (shell-command-to-string "tty"))= so gpg-agent can target the controlling tty. Guard against a non-tty stdin. +#+begin_src emacs-lisp + Give me an idea of the amount of work and complexity and what allows for a consistent UX across languages. +#+end_src -*** TODO [#C] gpg-agent updatestartuptty refresh in terminal :feature: -The current =call-process= to "gpg-connect-agent updatestartuptty /bye" runs unconditionally; keep it for GUI, and re-fire it on terminal entry so the agent re-binds to the current tty. +*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals +Bind F5 globally to a debug entry point. Backend choice is the hard part: -*** TODO [#C] ERT tests for terminal vs GUI pinentry branching :tests: -Test that with =env-terminal-p= stubbed t, =epa-pinentry-mode= resolves to ='loopback= after =auth-config= loads; with it stubbed nil, the loopback setting is not applied. Use =cl-letf= around =env-terminal-p=; cover normal, boundary (=epa= already loaded), error (=gpg-connect-agent= missing). +- dape (Debug Adapter Protocol for Emacs) — modern, multi-language via DAP. Single UX across Python, Go, TS, Rust, etc. Less mature than DAP clients in other editors. +- realgud — wraps multiple debuggers (pdb, gdb, node --inspect, etc.). More mature; UX varies by backend. +- Language-specific stacks — dap-mode (python-mode + dap), delve for go, ts-node --inspect, etc. Best per-language UX; most config work. -*** TODO [#C] Minibuffer prompt in real terminal Emacs :verify: -=emacs -nw=, open an encrypted file or trigger an auth-source decrypt, confirm the passphrase prompt lands in the minibuffer rather than failing on missing pinentry. +F5 itself will be simple (start/resume debug). Likely modifier variants once the backend is picked: +- C-F5 toggle breakpoint at point +- M-F5 eval expression in debug context (or step-over shortcut) -*** TODO [#C] External pinentry still fires in GUI Emacs :verify: -Restart the daemon, open a GUI frame, trigger an encrypted decrypt, confirm =pinentry-dmenu= (or whatever GUI pinentry is configured) still appears. +Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. -*** TODO [#C] Archive the original L3813 task :chore: -After this work lands, mark the original "Finish terminal GPG pinentry configuration" task DONE with a =CLOSED:= stamp and a one-line note pointing at this parent task. +Do this after the F-key rework ticket ships so F5 is the only hole left. -** TODO [#D] Treesitter grammar offline cache :feature:offline:localrepo: -Treesitter grammars are downloaded by =treesit-auto= on first use and live outside the localrepo. For true offline reproducibility, cache the grammars next to the localrepo (a =.localrepo/treesitter/= tier, or a separate mirror script). Cross-linked from =docs/design/localrepo.org=. +** TODO [#C] Build debug-profiling.el module :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -** TODO [#D] Native-comp .eln cache strategy :feature:offline:localrepo: -The native-comp =.eln= cache is Emacs-version-specific; an Emacs upgrade invalidates everything. Document the cache location, what an upgrade triggers, and whether a warm-the-cache script is worth shipping. Cross-linked from =docs/design/localrepo.org=. +Reusable profiling infrastructure for targeted slow-command investigation. Consolidates scattered profiler bindings (currently in =modules/config-utilities.el=) and adds two pure-helper-backed entry points: "profile next command" and "time region or sexp." Designed via =/brainstorm= 2026-04-26. -** TODO [#D] System-tool dependency install script :feature:offline:localrepo: -=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, and other binaries that =cj/executable-find-or-warn= flags at module load are not in =package.el='s reach. Document the required-tool set and ship a setup script (or =pacman=/=apt= invocation set). Cross-linked from =docs/design/localrepo.org=. +Design: [[file:docs/design/debug-profiling.org][docs/design/debug-profiling.org]] -** TODO [#D] Localrepo refresh / update script :feature:offline:localrepo: -No dedicated update path today — refreshing a pinned package means ad-hoc =cp= from the local elpa mirrors. Document the current shape and decide whether a =scripts/refresh-localrepo.sh= is worth writing. Cross-linked from =docs/design/localrepo.org=. +Implement via =/start-work= against the design — branch =feat/debug-profiling=, commits decomposed along the test-first split-for-testability boundary. Once shipped, use it as the v1 exercise on the queued [#B] org-capture target-building investigation. -** TODO [#D] Dashboard over-scroll: pin last line to window bottom :bug: +** TODO [#C] Org-noter custom workflow — fix and finish :feature:bug: :PROPERTIES: -:LAST_REVIEWED: 2026-05-22 +:LAST_REVIEWED: 2026-06-02 :END: -Triggered by: 2026-05-20 Dashboard buffer too long follow-up. -After the opens-at-top fix (=4ac1b81=), the dashboard can still be -scrolled past its content: the banner image makes the buffer just over -one screenful, so the wheel / =C-v= / =M->= pull the last line up and -leave empty space below it. Craig wants scrolling to stop once the -trailing line reaches the window bottom (no void) while still allowing -scroll-down to reach content below the window. - -Findings from the 2026-05-20 investigation: -- =pixel-scroll-precision-mode= is off, so this is standard line-based - scroll overshoot (the tall banner image inflates the rendered height). -- A =window-start= clamp does not work: =window-start= only lands on - line boundaries, so it can't express a position partway into the - banner image — it either blocks all scrolling or leaves the void. -- A =recenter -1= pin on =post-command-hook= does not work: it fires on - every command, so it fights item navigation (the cursor can't reach - the projects / bookmarks / recents). -- Right design: clamp only on actual scroll commands — advise - =mwheel-scroll= / =scroll-up-command= / =scroll-down-command= / - =end-of-buffer= to =recenter -1= when over-scrolled, never on - navigation commands. -- Live experiment scratch file: =~/dashboard-overscroll-experiment.el=. - -** TODO [#D] Polish reveal.js presentation setup :feature: +Continue debugging and testing the custom org-noter workflow from 2025-11-21 session. +This is partially implemented but has known issues that need fixing before it's usable. -Three small reveal.js improvements; collected into one task because each on its own is too small to track separately. +*Last worked on:* 2025-11-21 +*Current status:* Implementation complete but has bugs, needs testing -1. *Image insertion helper.* Function to insert images with proper org-reveal attributes (sizing, background images, etc.) without having to remember the syntax. -2. *Default font sizing for slide elements.* Configure reveal.js font sizes for headings, body text, code blocks, etc. — better defaults via =org-reveal-head-preamble= CSS or a custom theme. -3. *Custom dupre reveal.js theme.* CSS theme using the colors from =themes/dupre-palette.el=. Install into =reveal.js/css/theme/= for use with =#+REVEAL_THEME: dupre=. +*Known issues to fix:* -** DOING Project-aware bug capture via C-c c t :feature:capture: -Relocated from the global capture inbox 2026-06-06. When inside a projectile project, C-c c t (Task) files into that project's root todo.org under the "<Project> Open Work" header. If the project has no todo.org, fall back to the global inbox-file and warn naming the project. +1. /Double notes buffer appearing when pressing 'i' to insert note/ + - When user presses 'i' in document to insert a note, two notes buffers appear + - Expected: single notes buffer appears + - Need to debug why the insert-note function is creating duplicate buffers -Implemented 2026-06-06 in =modules/org-capture-config.el=: a shared project-aware =function= capture target (=cj/--org-capture-project-location=) used by =C-c c t= (Task, =* TODO=) and a new =C-c c b= (Bug, =* TODO [#C]=). Matches an existing top-level "... Open Work" heading (so ~/.emacs.d hits "Emacs Open Work") and creates "<Capitalized project> Open Work" only when absent. Outside a project / no todo.org -> global inbox under "Inbox" (with a warning in the no-todo.org case). 15 ERT tests in =tests/test-org-capture-config-project-target.el=; daemon e2e confirmed a real capture lands "** TODO [#C] ..." prepended under Open Work. Awaiting Craig's interactive manual verify (see the Manual Testing task) before close. NOTE: the matching "<Project> Resolved Work" header for the wrap-up workflow is a separate concern, not handled here. +2. /Toggle behavior refinement needed/ + - The toggle between document and notes needs refinement + - May have edge cases with window management + - Need to test various scenarios -** TODO "? = curated help menu" convention across modes :feature:ux:discoverability: -From the calibredb keybindings work 2026-06-06. The pattern that worked: in a modal/major-mode buffer (calibredb), bind =?= to a curated transient of the frequent workflows, and move the package's own full dispatch to =H=. It fixes the "I can't discover the keys" problem that which-key can't help with (which-key only pops up after a prefix, not for top-level single keys in a mode-map). +*Testing needed:* -Task: survey the modes/modules Craig works in and identify where a =?= -> curated-help-menu (transient) makes sense. Candidates: any major-mode buffer with single-key bindings and no good discovery affordance -- calibredb (done), nov, dirvish, mu4e, ghostel/term, signel, pearl/linear, ELFeed, etc. For each, note whether =?= is free or already a help dispatch, and whether a curated menu (vs the package's own) adds value. Establish it as a convention (and maybe a small helper/macro to define a curated =?= menu consistently). +1. /EPUB files/ - Test with EPUB documents (primary use case) +2. /Reopening existing notes/ - Verify it works when notes file already exists +3. /Starting from notes file/ - Test opening document from an existing notes file +4. /PDF files/ - Verify compatibility with PDF workflow +5. /Edge cases:/ + - Multiple windows open + - Splitting behavior + - Window focus after operations -** TODO the preview splits an already split window into 3 temporarily. -looks strange. potentially problematic for ai-terms. +*Implementation files:* +- =modules/org-noter-config.el= - Custom workflow implementation +- Contains custom functions for document/notes toggling and insertion -** TODO [#C] Google Contacts ↔ org-contacts sync investigation :feature:research: -From the 2026-06-11 brainstorm. Goal: keep [[file:~/sync/org/contacts.org][contacts.org]] (real org-contacts: PROPERTIES drawers, mu4e completion, org-roam links) in sync with Google Contacts. Google side is solid — official People API (OAuth2, incremental syncToken) or CardDAV; no ToS risk. The hard parts are local: (1) identity — entries have no UID, so two-way needs a GOOGLE_ID property per entry plus a one-time fuzzy reconciliation of the two populated datasets (name/email/phone matching); (2) field mapping — space-separated multi-email in one property, free-text body notes, inconsistent phone formats (normalization decision); (3) conflict policy. First decision gates the rest: one-way Google→org read model (simple) vs true two-way. Candidate architectures: vdirsyncer (proven two-way engine w/ Google support; build only the vCard↔org translation, evaluate org-vcard fidelity) vs a direct People API script with sync state in org properties. Output: recommendation doc in docs/design/ naming direction + the normalization/conflict decisions for Craig. Not :solo: — the one-way-vs-two-way call and normalization policy are Craig's. +*Context:* +This custom workflow is designed to make org-noter more ergonomic for Craig's reading/annotation +workflow. It simplifies the toggle between document and notes, and streamlines note insertion. +The core functionality is implemented but needs debugging before it's production-ready. -** TODO [#C] Google Voice in Emacs — SMS + dialer investigation :feature:research:solo: -From the 2026-06-11 messenger-unification brainstorm. Google Voice has no official API; the viable routes ride the Matrix bridge ecosystem's reverse engineering (mautrix-gvoice). Research pass to establish the 2026 state of play: (1) is mautrix-gvoice healthy and what does its auth flow look like now; (2) any better-maintained alternative (CLI/daemon) for the signel-pattern architecture (external daemon + JSON-RPC + thin Emacs chat client); (3) does call initiation (ring-linked-phone-then-connect, Emacs as dialer) survive in the current protocol — two-way audio in Emacs is out of scope (WebRTC); (4) ToS/account-flag risk assessment for Craig's account. Output: a recommendation doc in docs/design/ naming the architecture (signel-pattern daemon vs Matrix bridge + ement.el) or a no-go with reasons. If go, GV becomes a registered backend under the messenger-unification convention (see the [#B] task below). +**Next Steps:** +1. Debug the double buffer issue when pressing 'i' +2. Test all scenarios listed above +3. Refine toggle behavior based on testing +4. Document the final keybindings and workflow -** TODO [#B] Messenger window/key unification :feature:ux: -Spec: [[file:docs/design/messenger-unification-spec.org][messenger-unification-spec.org]] (Draft, 2026-06-11). One library (=cj-messenger-lib.el=) gives every messenger the same shape: chat windows rise from the bottom (the signel rule, generalized), C-c C-c confirms, C-c C-k cancels, C-c C-a attaches — dispatched per backend through a registry + minor mode. Signel already conforms (reference backend); telega and slack join in phases 2-3; ERC later. All eight decisions settled 2026-06-11 (cancel closes an idle window; telega's filter-cancel shadow accepted; slack rooms join the bottom rule). Spec held open — Craig has more ideas to fold in before it's marked Ready. +** TODO [#C] Build an Org-native API workspace :feature:tests: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -** TODO [#A] Lock screen silently fails — slock is X11-only :bug: -=modules/system-commands.el:105= binds the lockscreen command to =slock=, which can't grab a Wayland session; =cj/system-cmd= launches it detached with output silenced, so C-; ! l does nothing and the screen never locks. Security issue: Craig believes the screen locks when it doesn't. Fix: =hyprlock= (or =swaylock=), ideally resolved per session type via =env-wayland-p= so an X11 fallback survives for other machines. From the 2026-06 config audit. +Build an Emacs-native API workspace layer that keeps =restclient.el= useful for +lightweight request execution while adding OpenAPI import, Org notebooks, +response capture, inline images, and =gptel=-assisted API documentation. -** TODO [#B] cj/undo-kill-buffer off-by-one on plain invocation :bug:quick:solo: -=modules/ui-navigation.el:181= — =(interactive "p")= makes arg always ≥1, and the body does =(if arg (nth arg list) (car list))=, so the nth branch always runs and plain M-S-z reopens the SECOND-most-recently-killed file. The existing test passes 0 explicitly, masking it. Fix the indexing (=(interactive "P")= + =prefix-numeric-value=, or =nth (1- arg)=) and fix the test to cover the no-prefix path. From the 2026-06 config audit. +*** Spec -** TODO [#B] reconcile-open-repos skips any repo with a dot in its name :bug:solo: -=modules/reconcile-open-repos.el:174= — discovery regexp ="^[^.]+$"= matches only dot-free names, so =~/code/mcp.el=, =capture.el=, =google-contacts.el=, =auto-dim-other-buffers.el= etc. are never reconciled while M-P still reports "Complete." Replace with =directory-files-no-dot-files-regexp= + a hidden-dir check; add a regression test with a dotted repo name. From the 2026-06 config audit. +**** Summary +Build a small Emacs API-workspace layer that keeps =restclient.el= as the +plain-text request executor, while adding higher-level discovery, generation, +Org notebook, response handling, and =gptel=-assisted documentation workflows. -** TODO [#B] jumper: register collisions and dead-marker errors :bug:solo: -Two related defects from the 2026-06 config audit: -- =modules/jumper.el:155= — removal shifts the vector without renumbering registers, so a later store allocates a register still held by a surviving location and silently overwrites it. Allocate the first free register char in the live slice; =set-register nil= on removal so freed markers don't pin buffers. -- =modules/jumper.el:117,132= — guards check =(markerp marker)= but not =(buffer-live-p (marker-buffer marker))=; after killing a buffer holding a location, M-SPC SPC and M-SPC j signal wrong-type errors. Treat dead entries as skippable/removable. -Also =jumper.el:178= — the promised single-location toggle never toggles back ('already-there branch should =jump-to-register= z when set). - -** TODO [#B] C-s C-s vertico-repeat path never works :bug:quick:solo: -=modules/selection-framework.el:263= — =cj/consult-line-or-repeat= calls =vertico-repeat= on the second consecutive C-s, but nothing adds =vertico-repeat-save= to =minibuffer-setup-hook= (grep: zero hits config-wide), so it always signals "No Vertico session". Add the hook next to the vertico use-package block. From the 2026-06 config audit. +The intended result is not a Postman clone. It should feel like an +Emacs-native API lab: +- generate request collections from OpenAPI/Swagger specs +- browse and execute requests from =.rest= files or Org notebooks +- save useful responses back into Org +- display image responses inline +- use =gptel= to explain APIs, endpoints, request bodies, and responses +- leave room for =verb.el= or Hurl where they are a better fit -** TODO [#B] dashboard-config setq wipes recentf-exclude list :bug:quick:solo: -=modules/dashboard-config.el:199= =(setq recentf-exclude '("/emms/history"))= discards the five exclusions system-defaults.el:239-243 added earlier in init order (bookmarks, elpa, recentf, ElfeedDB, airootfs). Change to =add-to-list=. From the 2026-06 config audit. +**** Goals +- Preserve the current lightweight =restclient.el= workflow for ad-hoc calls. +- Add an OpenAPI importer that can generate useful first-draft request files. +- Add an Org workspace format for API notes, executable request blocks, results, + response links, and generated summaries. +- Add response post-processing helpers for JSON, binary/image data, and model + summaries. +- Make common auth flows easy to scaffold without storing secrets in generated + files. +- Keep generated artifacts readable and editable by hand. +- Keep implementation modular enough that =verb.el= can be evaluated as a richer + Org-native frontend. -** TODO [#B] auth-config: unguarded gpg-connect-agent call + compile-time require :bug:quick:solo: -From the 2026-06 config audit. =modules/auth-config.el:88= — bare =(call-process "gpg-connect-agent" ...)= in a =:demand t= :config signals file-missing and aborts init on machines without the binary; guard with =cj/executable-find-or-warn=. =auth-config.el:36= — =user-constants= is required only =eval-when-compile= but =authinfo-file= is read at load time; works from .el source, fails from standalone .elc. Use a runtime require (system-defaults.el:32-35 documents this exact trap). +**** Non-Goals +- Do not build a full graphical API client. +- Do not store secrets directly in Org or =.rest= files. +- Do not attempt complete OpenAPI 3.1 schema synthesis in the first pass. +- Do not require =gptel= for ordinary request execution. +- Do not make Hurl a runtime dependency for the restclient workflow. -** TODO [#B] system-defaults: top-level server-start unguarded in batch :bug:quick:solo: -=modules/system-defaults.el:140= — raw module load under =--batch= (make validate-modules on a machine with no daemon socket) starts a server from a batch process; the suite only passes because the testutil stubs it. Wrap in =(unless noninteractive ...)= — the repo's established guard for this defect class; same guard stops the =custom-file= =make-temp-file= at line 104 littering temp files per batch load. From the 2026-06 config audit. +**** Primary User Flows +***** Import An API +1. User runs =cj/restclient-import-openapi=. +2. Command prompts for a URL or local OpenAPI/Swagger file. +3. Command parses the spec into normalized endpoint records. +4. Command prompts for output format: + - =restclient= request collection + - Org API workspace + - both +5. Command writes generated files under a project/API workspace directory. +6. Generated file includes host variables, auth placeholders, request examples, + and a short summary of how to start using the collection. -** TODO [#B] markdown live preview clobbered by markdown-mode :bug:quick:solo: -=modules/markdown-config.el:54= defines bare =markdown-preview=, which markdown-mode redefines the moment the first .md loads — the impatient-mode live preview is dead and F2 silently runs the package command (agent verified in the live daemon). Also =:61= guards on =(boundp 'httpd-process)=, a variable that doesn't exist in simple-httpd — use =(httpd-running-p)=. And the =:config= =(setq imp-set-user-filter 'markdown-html)= at line 41 is doubly dead (function-not-variable, symbol names nothing) — delete. Rename to =cj/markdown-preview=, rebind F2. From the 2026-06 config audit. +***** Describe An API +1. User runs =cj/restclient-describe-api= from a generated workspace or spec file. +2. Command extracts API metadata, paths, operations, schemas, auth, and tags. +3. Command sends a bounded summary payload to =gptel=. +4. Result is inserted under an Org =Overview= subtree. -** TODO [#B] org-roam dailies template writes FILETAGS and TITLE on one line :bug:quick:solo: -=modules/org-roam-config.el:42= — the "d" dailies head is ="#+FILETAGS: Journal #+TITLE: %<%Y-%m-%d>"= with no newline, so every C-c n d daily is malformed: no parsed #+TITLE, FILETAGS value "Journal #+TITLE: ...". The journal-copy template (lines 213-216) has it right. Add the newline; consider a sweep of existing dailies for the malformed first line. From the 2026-06 config audit. +***** Execute And Capture A Request +1. User executes a request via =restclient.el= or =ob-restclient=. +2. Command captures response status, headers, content type, body, and timestamp + when available. +3. JSON/XML responses can be inserted as source blocks or summarized. +4. Image responses are saved to an assets directory and linked inline in Org. +5. Binary responses that are not image-like are saved as file links. -** TODO [#B] agenda sources: roam Projects missing, no existence filtering :bug:solo: -From the 2026-06 config audit, =modules/org-agenda-config.el=: -- =:182-191= — commentary and docstrings promise org-roam nodes tagged "Project" as agenda sources, but =cj/--org-agenda-scan-files= never scans them, and files added by the roam finalize-hook are wiped on the next =cj/build-org-agenda-list= cache rebuild (≤1h). Add a roam Project pass (mirror =org-refile-config.el:101-109=) or correct the docs. -- =:186,456= — agenda file list built unconditionally (inbox/calendars may not exist on a fresh machine) and =org-agenda-skip-unavailable-files= is unset — the exact interactive-prompt class that once hung the chime daemon. Filter with =file-exists-p= + set the var as backstop. +***** Iterate On A Response +1. User runs helper commands against the last response: + - pretty-print JSON/XML + - run =jq= + - summarize with =gptel= + - extract a value into a restclient variable + - save body to a file +2. The result is inserted near the endpoint subtree or shown in a temporary + buffer depending on command prefix/options. -** TODO [#B] org-roam :config triggers the 15-20s refile scan synchronously at first idle :bug:solo: -=modules/org-roam-config.el:78-79= — org-roam is =:defer 1=, so its :config calls =cj/build-org-refile-targets= at 1s idle, BEFORE the 5s background timer (=org-refile-config.el:144-151=); on a cold cache the 30k-file scan runs inline and freezes Emacs at first idle. Drop the call — org-roam is loaded long before the 5s timer fires. Likely a player in the filed org-capture 15-20s perf task (=[#B] Optimize org-capture target building performance=) — check both together. From the 2026-06 config audit. +**** Proposed Modules +***** =modules/restclient-workspace.el= +Main configuration and user-facing commands. Owns keybindings, workspace +creation, dispatch commands, and integration with existing restclient config. -** TODO [#B] heavy-box comment inserts non-comment lines :bug:solo: -=modules/custom-comments.el:427= — =cj/--comment-heavy-box= interior/empty lines carry no comment prefix, so in line-comment languages (elisp, Python) C-; C h injects syntax-breaking bare =*...= lines. The existing test characterizes the broken output (asserts =^\*.*\*$=). Prefix interiors like =cj/--comment-box= does; add the missing min-length validation (negative width hits make-string with a raw error); fix the test to assert corrected output. From the 2026-06 config audit. +***** =modules/restclient-openapi.el= +OpenAPI/Swagger loading and normalization: +- fetch URL or read file +- parse JSON/YAML where available +- normalize servers, paths, methods, parameters, request bodies, auth schemes, + tags, operation IDs, and examples +- expose pure helper functions suitable for unit tests -** TODO [#C] latexmk workflow never activates (two breaks) :bug:solo: -=modules/latex-config.el:66= — =:hook (TeX-mode-hook . ...)= gets use-package's =-hook= suffix appended (unbound symbol not ending in =-mode=), registering on nonexistent =TeX-mode-hook-hook=, so =TeX-command-default "latexmk"= is never set. Independently =:80= auctex-latexmk is =:defer t= with no trigger, so =auctex-latexmk-setup= never runs and "latexmk" isn't in TeX-command-list. Fix hook name to =TeX-mode=; change auctex-latexmk to =:after tex=. From the 2026-06 config audit. +***** =modules/restclient-generate.el= +Generation layer: +- render =.rest= / =.http= request collections +- render Org workspaces +- synthesize simple JSON request bodies from schemas/examples +- generate variables and auth placeholders -** TODO [#A] mu4e: cmail can't trash, no account can refile :bug: -=modules/mail-config.el:217-220= — the cmail context (primary account) sets only drafts/sent, so D falls back to default "/trash" which doesn't exist under ~/.mail (=/cmail/Trash= does); and NO context sets =mu4e-refile-folder=, so r targets nonexistent "/archive" everywhere. Accepting mu4e's offer to create the maildir strands mail in a directory mbsync never syncs — messages silently vanish from the server's view. Add =mu4e-trash-folder= to cmail + per-context =mu4e-refile-folder=. From the 2026-06 config audit. +***** =modules/restclient-response.el= +Response helpers: +- identify content type +- save binary/image bodies +- insert Org links +- display inline images +- route JSON/XML/text handling +- track last response metadata -** TODO [#A] calendar-sync drops final occurrences and resurrects cancelled meetings :bug:solo: -RFC 5545 conformance holes in =modules/calendar-sync.el=, all agenda-visible (from the 2026-06 config audit): -- =:973,1015,1024= — UNTIL treated as exclusive (strict =calendar-sync--before-date-p=); RFC and Google make it inclusive, so the LAST instance of every UNTIL-bounded series vanishes. Tests assert loose count ranges, so it's unpinned. Allow equality. -- =:578= — comma-separated EXDATE lists (Google emits them) never parse; the exclusion drops silently and cancelled occurrences reappear on the agenda. Split on "," before parsing; no comma-case test exists. -- =:902= — timed events without DTEND render as all-day (time lost); multi-day all-day spans collapse to one day (end date unused, exclusive-DTEND unhandled). Emit start-time-only stamps and org date ranges. +***** =modules/restclient-ai.el= +=gptel= integration: +- summarize API specs +- explain endpoint behavior +- generate example payload notes +- summarize responses +- keep prompts bounded and avoid sending secrets -** TODO [#B] calendar-sync robustness: atomic writes, curl --fail, zero-event false errors :bug:solo: -From the 2026-06 config audit, =modules/calendar-sync.el=: -- =:1309= — agenda file written via =with-temp-file= directly on the target (truncate-in-place); org-agenda/chime reading mid-write sees a partial calendar, hourly. Write temp + =rename-file= (atomic same-fs). Same for =--save-state= :258. -- =:1284= — curl runs without =--fail=: an HTTP 404/500 error page exits 0 and the HTML proceeds into conversion. -- =:1229-1233= — =--parse-ics= returns nil for both garbage and a valid calendar with zero in-window events, so healthy near-empty calendars report "parse failed" in =calendar-sync-status=. Distinguish the cases. +**** File And Workspace Layout +Default generated workspace: -** TODO [#B] drill-refile clobbers global org-refile-targets with an invalid spec :bug:quick:solo: -=modules/org-drill-config.el:95-98= — =setq org-refile-targets= replaces the session-wide value, so after one drill refile every org-refile everywhere offers only drill targets until restart; and the =(drill-dir :maxlevel . 1)= spec names a directory-path variable where org expects files, so the drill side yields nothing usable. Let-bind around the call with =((directory-files drill-dir t "\\.org$") :maxlevel . 1)=. From the 2026-06 config audit. +#+begin_src text +data/apis/<api-slug>/ + <api-slug>.rest + <api-slug>.org + openapi.json + assets/ + responses/ +#+end_src -** TODO [#B] ERC: double mention notifications + tautological server list :bug:quick:solo: -From the 2026-06 config audit, =modules/erc-config.el=: -- =:281= — =erc-modules= includes the built-in =notifications= module AND :config adds =cj/erc-notify-on-mention= to the same hook — every mention fires two desktop notifications. Pick one path (keep the custom one, slated for messenger unification). -- =:100= — =cj/erc-connected-servers=: inside =with-current-buffer=, the free =erc-server-process= is the buffer's own local value, so the eq test is tautologically true — returns ALL ERC buffers (channels, dead connections). Use =erc-server-buffer-p= + =erc-server-process-alive=. -- =:238= — =user-whole-name= read at load but =user-constants= only required at compile time (same trap as auth-config/keyboard-macros). +The exact root should be configurable, defaulting to the existing REST data +directory if one is already present in the config. -** TODO [#B] slack-config lifecycle gaps :bug:quick:solo: -From the 2026-06 config audit, =modules/slack-config.el=: -- =:265= — w / @ / # bound to commands neither autoloaded nor in :commands — void-function before slack loads. Add to :commands. -- =:246= — =cj/slack-close-all-buffers= reads =slack-current-buffer= (declared but unbound) without the boundp guard its sibling has — void-variable on C-; S Q before slack loads. -- =:259= — raw =global-set-key= for C-; S bypasses =cj/register-prefix-map= (signal/erc use it); invisible to the keybindings registry and the planned unification enumeration. +**** Org Workspace Shape +#+begin_example +,* API Name +:PROPERTIES: +:OPENAPI_SOURCE: https://example.com/openapi.json +:BASE_URL: https://api.example.com +:END: -** TODO [#B] erc-yank silently publishes >5-line pastes as public gists :bug: -=modules/erc-config.el:345= — C-y in any ERC buffer auto-creates a public gist for anything over 5 lines: clipboard content goes to a public URL with no confirmation, and no executable-find guard for =gist= (errors mid-send if absent). Privacy trap. Add a =yes-or-no-p= gate or drop the package for plain C-y. From the 2026-06 config audit. +,** Overview +Generated or user-written API notes. -** TODO [#B] F7 diff-aware coverage classifies every changed file "not tracked" :bug:solo: -=modules/coverage-core.el:252= — =cj/--coverage-intersect= joins covered×changed by exact string key, but simplecov.json keys are ABSOLUTE paths while the git-diff parser returns repo-RELATIVE ones — zero matches ever, so working-tree/staged/branch scopes report ":tracked nil" for everything and F7's main feature is inert (whole-project scope works, same-source keys). Unit tests hand-build matching keys so they pass; add one integration test feeding a real undercover report + real diff. Normalize both sides to repo-relative. From the 2026-06 config audit. +,** Auth +Token acquisition notes and placeholders. No secrets stored here. -** TODO [#B] eshell: visual-commands nested-list + xterm-color dead hook :bug:quick:solo: -=modules/eshell-config.el:104= — =add-to-list= pushes one LIST into the flat string list =eshell-visual-commands=, so lf/ranger/htop/top never get a visual terminal (and the r→ranger alias garbles). dolist the strings. =:166= — =:hook (eshell-before-prompt-hook . ...)= gets "-hook" appended → registers on nonexistent =eshell-before-prompt-hook-hook=; and =xterm-color-filter= is never added to =eshell-preoutput-filter-functions= anyway while TERM advertises xterm-256color. Wire xterm-color fully per its README or drop it + the TERM override. From the 2026-06 config audit. +,** Endpoints +,*** GET /users +:PROPERTIES: +:OPERATION_ID: listUsers +:METHOD: GET +:PATH: /users +:END: -** TODO [#B] dirvish M (mark all files) marks every other file :bug:quick:solo: -=modules/dirvish-config.el:218= — =dired-mark= advances point to the next line itself; the loop's extra =forward-line 1= then skips it, so consecutive files are marked alternately. Live mis-marking on a key that feeds batch operations (delete/copy on marked files) — data-loss adjacent. Drop the manual forward-line when a mark was made (or =dired-unmark-all-marks= + mark dirs + =dired-toggle-marks=). The trivial line-predicate helper is tested; the loop isn't — add the marked-count test. From the 2026-06 config audit. +#+begin_src restclient :results raw +GET :host/users +Authorization: Bearer :token +Accept: application/json +#+end_src -** TODO [#B] dwim-shell: zip overwrites its own name, backup timestamp never expands, dired menu key dead :bug:quick:solo: -From the 2026-06 config audit, =modules/dwim-shell-config.el=: -- =:338= — single-file zip is =zip -r '<<fne>>.<<e>>' '<<f>>'= — reconstructs the input filename as the archive ("Zip file structure invalid"; directories produce =foo.=). Should be ='<<fne>>.zip'= like the tar-gzip sibling. -- =:549= — backup destination single-quotes =$(date ...)= so the substitution is literal: =foo.txt.$(date +%Y%m%d_%H%M%S).bak=. Move it outside the quotes or format-time-string in Elisp. -- =:932= — dired-mode binding "M-S-d" is unreachable (Meta+Shift+d generates M-D); the dirvish binding two lines down is correctly "M-D". Fix + the stale commentary at dirvish-config.el:30. +,**** Notes +,**** Responses +#+end_example -** TODO [#B] Go: format key void-functions, go-mode :config never runs :bug:quick:solo: -=modules/prog-go.el:99,113-118= — .go maps to go-ts-mode so the go-mode package never loads, and =gofmt= isn't autoloaded in go-mode 1.6.0 — C-; f signals void-function, and the :config (exec-path += ~/go/bin, =gofmt-command "goimports"=) never executes. Wrapper that requires go-mode first (or autoload gofmt), move the setup to top level. From the 2026-06 config audit. +**** Commands +- =cj/restclient-new-scratch= :: open a scratch =restclient-mode= buffer. +- =cj/restclient-open-file= :: open a REST file from the configured API data dir. +- =cj/restclient-import-openapi= :: generate a workspace from OpenAPI/Swagger. +- =cj/restclient-describe-api= :: insert a =gptel=-generated API overview. +- =cj/restclient-describe-endpoint= :: explain the endpoint at point. +- =cj/restclient-generate-example-body= :: generate or refresh sample JSON body. +- =cj/restclient-save-last-response= :: save response body and metadata. +- =cj/restclient-insert-last-response-org= :: insert response under Org subtree. +- =cj/restclient-display-image-response= :: save and display image response. +- =cj/restclient-response-jq= :: run =jq= against the last JSON response. +- =cj/restclient-copy-curl= :: copy the request at point as curl if supported. -** TODO [#B] prog hooks mutate global state per buffer :bug:quick:solo: -From the 2026-06 config audit: =prog-go.el:64=, =prog-c.el:73=, =prog-shell.el:77= call global =(electric-pair-mode t)= from buffer setup hooks — one Go/C/shell buffer turns on pairing in org/text everywhere (python/webdev correctly use =electric-pair-local-mode=). =prog-general.el:79-80= — =display-line-numbers-type 'relative= setq/setq-default run from the hook AFTER the mode is enabled, so the first prog buffer of a session gets absolute numbers. Local-mode for the three; move the line-number setqs to top level. +**** Keybindings +Keep the existing prefix shape under =C-; R=: +- =C-; R n= :: new scratch request buffer +- =C-; R o= :: open REST file +- =C-; R i= :: import OpenAPI/Swagger +- =C-; R d= :: describe API or endpoint +- =C-; R s= :: save/capture last response +- =C-; R j= :: run =jq= on last response +- =C-; R m= :: transient menu for workspace commands -** TODO [#B] M-S- launcher keys dead: eww, elfeed, calibredb unreachable :bug:quick:solo: -=eww-config.el:70= (M-S-e), =elfeed-config.el:36= (M-S-r), =calibredb-epub-config.el:115= (M-S-b) — Meta+Shift+letter generates the uppercase event (M-E/M-R/M-B), which never matches an explicit S- spec on a lowercase letter; verified dead in the live daemon (chord falls through to M-r move-to-window-line etc.). Same class as the text-config M-S-i finding. Write them as "M-E"/"M-R"/"M-B". Weather's M-S-w works only via the keyboard-compat translation layer — audit that layer's coverage while here. From the 2026-06 config audit. +**** OpenAPI Import Details +Minimum first-pass support: +- OpenAPI 3.x JSON +- Swagger 2.0 JSON if easy to normalize +- YAML via available Emacs YAML library or external converter if already present +- =servers= / =host= + =basePath= +- path-level and operation-level parameters +- query/path/header parameters +- JSON request bodies +- examples and default schema values +- security schemes: + - HTTP bearer + - basic + - API key header + - API key query -** TODO [#B] ai-rewrite: chosen directive never reaches the request :bug:solo: -=modules/ai-rewrite.el:64= — the directive is let-bound around =(call-interactively #'gptel-rewrite)=, but gptel-rewrite is a transient prefix that returns when the menu shows; the send resolves the directive AFTER the binding unwound (verified against ~/code/gptel/gptel-rewrite.el:780-799). The picker's choice is silently dropped — the module's core feature is inert. Set =gptel--rewrite-directive= buffer-locally (restore via =gptel-post-rewrite-functions=) or use a self-removing global hook entry. From the 2026-06 config audit. +First pass can skip or mark as unsupported: +- polymorphic schemas beyond simple =oneOf= / =anyOf= note generation +- multipart body generation +- full OAuth flows +- callbacks/webhooks +- complete response schema rendering -** TODO [#B] ai-conversations: dead-buffer load, role flattening, non-atomic writes :bug:solo: -From the 2026-06 config audit, =modules/ai-conversations.el=: -- =:324= — load in a fresh session does =get-buffer-create "*AI-Assistant*"= (plain fundamental-mode buffer); =--ensure-ai-buffer= then sees it exists and never calls =(gptel)=. Sending doesn't work, autosave self-cancels (requires gptel-mode). Use =get-buffer= for the check; let ensure create. The browser RET/l path inherits this. -- =:240= — persistence drops gptel's =response= text properties, so a reloaded history replays to the model as ONE user message (model re-reads its own answers as Craig's words). Adopt gptel's native bounds persistence or re-mark on load from the "* Backend:" headings. -- =:248= — =write-region= straight at the target; crash mid-write truncates the only copy of the history (autosave hits this constantly). Temp + rename. -- =:140= — three overlapping autosave mechanisms (after-send advice that fires before the response exists, post-response hook, 60s timer). Keep the hook; drop the advice (and likely the timer). +**** Secret Handling +- Generated files must use placeholders like =:token=, =:api-key=, or + =:basic-auth=. +- Do not write tokens into generated files. +- Prefer variables loaded from auth-source, environment variables, or manually + entered restclient variables. +- =gptel= prompts must strip obvious auth headers and secret-like values from + request/response payloads before sending context. -** TODO [#B] cj/gptel-switch-backend reintroduces the string-model crash :bug:quick:solo: -=modules/ai-config.el:272= — =(setq gptel-model model)= with the raw completing-read STRING — the documented wrong-type-argument-symbolp modeline hang (CLAUDE.md gotcha), reachable from C-; a B today. =cj/gptel-change-model= (C-; a m) already does backend+model switching and interns correctly. Intern here, or delete switch-backend and keep one command. From the 2026-06 config audit. +**** Response Handling +- Text JSON/XML/HTML/plain responses may be inserted into Org as source blocks. +- JSON responses should support optional =jq= filters. +- Image responses should be saved under =assets/responses/= and inserted as Org + file links. +- After inserting image links, call =org-display-inline-images= when in Org. +- Large responses should be saved as files and linked rather than inserted. +- Binary non-image responses should be saved and linked with content type notes. -** TODO [#B] transcription: stderr never reaches the log, video transcripts stranded in /tmp :bug:solo: -From the 2026-06 config audit, =modules/transcription-config.el=: -- =:210= — =make-process :stderr= with a file PATH creates a BUFFER named like the path (verified by probe); the "Errored. Logs in <file>" notification points at a log without the error text, and the hidden stderr buffer leaks per transcription. Route stderr into the process buffer or write it out in the sentinel. -- =:370-374= — video path derives txt/log from the temp mp3's /tmp path; the transcript lands in /tmp and dies on reboot, contradicting the "alongside the source" docstring. Pass the video's path as the output base. +**** Integration Choices To Evaluate +- =restclient.el= remains the default executor for =.rest= files. +- =ob-restclient= powers executable Org source blocks. +- =verb.el= should be evaluated as an alternate frontend for Org-native API + workspaces because it already has tree inheritance, embedded Elisp, and image + response display. +- Hurl should be evaluated as an export/test target, especially for chained + request tests and CI assertions. -** TODO [#B] ledger-config is orphaned — ledger-mode never configured :bug:quick: -Nothing requires =modules/ledger-config.el= (verified by grep), so .dat/.ledger/.journal open without ledger-mode, reports, or flycheck-ledger. The module looks finished, not staged (unlike duet-config, which documents its pre-alpha orphaning). Decide: wire into init.el (+ =cj/executable-find-or-warn= for the ledger binary) or delete. From the 2026-06 config audit. +**** Testing Strategy +- Unit-test OpenAPI normalization with small fixture specs. +- Unit-test request generation for GET, POST, auth, query params, path params, + and request-body examples. +- Unit-test secret redaction before =gptel= calls. +- Unit-test response classification and Org insertion helpers. +- Integration-test generated =.rest= files for representative APIs. +- Integration-test generated Org workspaces with =ob-restclient= where feasible. +- Avoid live network tests by default; use fixtures/stubs unless explicitly + tagged =:network=. -** TODO [#B] eww quick-add bookmarks split the store and break the default file :bug:quick:solo: -=modules/eww-config.el:116-126= — quick-add let-binds =eww-bookmarks-directory= to ~/.emacs.d/eww-bookmarks/ (creating a DIRECTORY at the path where the daemon's default store expects a FILE ~/.emacs.d/eww-bookmarks). After one quick-add, B reads an unreadable path and quick-added bookmarks are invisible post-restart. Drop the let-binding or setq the directory once in :config so both commands share one store. From the 2026-06 config audit. +**** First Milestone +1. Keep/verify existing restclient scratch/open commands. +2. Add a tiny OpenAPI JSON parser/normalizer for a fixture spec. +3. Generate a readable =.rest= collection with variables and examples. +4. Generate a matching Org workspace. +5. Add response save/link helpers for JSON and images. +6. Add a =gptel= API-summary command with secret redaction. +7. Add focused unit tests and one sample fixture. -** TODO [#B] help-config: three defects in one small file :bug:quick:solo: -From the 2026-06 config audit, =modules/help-config.el=: -- =:67= — =cl-return-from= inside a plain =defun= (no cl-block): declining the save prompt signals "No catch for tag" instead of canceling. =cl-defun= or restructure. -- =:108= — =:hook (info-mode . info-persist-history-mode)= is dead twice: Info's hook is =Info-mode-hook= (capital I), and =info-persist-history-mode= doesn't exist anywhere. Implement the intent or delete. -- =:111= — auto-mode-alist maps .info to an interactive command that KILLS the buffer mid find-file — programmatic =find-file-noselect= of any .info destroys buffers and pops Info windows. Drop the entry; keep the explicit command. Zero test coverage on this module (the two broken paths are exactly the untested ones). +**** Open Questions +- Should the canonical workspace be =.rest= first, Org first, or generated in + both formats by default? +- Is =verb.el= a better primary target than =ob-restclient= for the Org notebook + experience? +- Which YAML parser should be used if no YAML package is already configured? +- Where should API workspaces live by default: =data/=, =docs/=, or project root? +- Should response capture hook into restclient internals, or should capture be a + separate explicit command operating on response buffers? +- How much schema synthesis is useful before it becomes noisy? -** TODO [#A] Native compilation disabled config-wide; GC at stock 800KB :bug: -From the 2026-06 config audit (verified against the live daemon). =early-init.el:69= =(setq native-comp-deferred-compilation nil)= — the obsolete alias of =native-comp-jit-compilation= — turns JIT native compilation OFF entirely, not "synchronous" as the comment claims: 19 .eln files exist for 184 packages, ~100 of 121 modules run interpreted for the daemon's lifetime, and system-defaults.el:42-44's speed-3/8-jobs/always-compile settings are dead. Plus =early-init.el:113-116= restores =gc-cons-threshold= to the captured STOCK default (800000, verified) post-startup — frequent small GC pauses forever. Together these plausibly feed the filed org-capture 15-20s task more than anything in the capture path itself. Actions: retest the old "Selecting deleted buffer" race on 30.2 and re-enable JIT (or AOT sweep); set a deliberate 16-64MB threshold (or gcmh). Check both before burning time on the capture-perf debug task. +*** Ideas +- Treat =restclient.el= as the lightweight request scratchpad, and layer richer workflow commands around it instead of trying to turn it into Postman. +- Add an OpenAPI/Swagger importer: + - prompt for a spec URL or local file + - parse paths, methods, auth schemes, request bodies, and examples + - generate a =.http= / =.rest= request collection + - optionally generate an Org notebook with one subtree per endpoint +- Add an API description command using =gptel=: + - summarize the API from an OpenAPI spec + - explain each endpoint, auth requirement, parameters, and response shape + - write the summary into the generated Org workspace +- Generate example requests automatically: + - =GET= examples with query params + - =POST= / =PUT= / =PATCH= examples with sample JSON bodies + - =DELETE= examples with safe placeholder IDs + - shared variables like =:host=, =:token=, =:api-version=, =:tenant= +- Add auth helpers: + - bearer token insertion + - basic auth + - API key header/query param + - OAuth token fetch request template +- Improve Org integration: + - use =ob-restclient= for executable API notebooks + - support =:jq= filters for clean JSON results + - save response bodies under endpoint subtrees + - capture request/response metadata as Org properties +- Handle images and binary responses: + - detect image =Content-Type= + - save response data into an assets directory + - insert =[[file:...]]= links into Org + - call =org-display-inline-images= after execution +- Add response-processing commands: + - pretty-print JSON/XML + - run =jq= against the last response + - summarize response with =gptel= + - extract fields into restclient variables for follow-up calls +- Add request collection ergonomics: + - imenu/consult navigation by endpoint + - transient menu for send/copy curl/jq/save response + - templates for common headers + - per-project API workspace discovery +- Investigate =verb.el= as the richer Org-native frontend: + - Org tree inheritance for host/header/auth defaults + - embedded Elisp in request specs + - built-in display of image/PDF/SVG responses + - likely better base for a notebook-style API client +- Investigate Hurl for repeatable API tests: + - request chaining + - captures + - assertions + - CI-friendly execution + - possible export target from generated API workspaces -** TODO [#B] modeline runs synchronous git on the redisplay path, unguarded :bug:solo: -=modules/modeline-config.el:173,154,145= — the mode-line :eval calls vc-backend/vc-state/vc-working-revision (synchronous git) on TTL expiry; a slow or unmounted filesystem stalls ALL redisplay. The cache key computes =file-truename= on every render (the "one stat per refresh" comment is wrong), and nothing is condition-case-wrapped, so a signal lands inside the mode-line eval. Defer the truename behind the TTL check; wrap the fetch in condition-case caching nil. From the 2026-06 config audit. +*** Original Goals +**** Keybindings to test +- C-; R n — new scratch *restclient* buffer (should open in restclient-mode) +- C-; R o — open .rest file (should default to data/ directory) -** TODO [#A] Global yes-or-no-p fset defeats every strong confirmation :bug:quick: -=modules/system-defaults.el:203= =(fset 'yes-or-no-p 'y-or-n-p)= — verified live. Several modules deliberately chose yes-or-no-p as the strong tier for irreversible actions: shutdown/reboot (=system-commands.el:74=, whose comment explicitly says "so a stray RET/space can't trigger them"), "permanently destroy files" (=dwim-shell-config.el:804=), file overwrites (=custom-buffer-file.el:159,199=, =music-config.el:374=). The fset makes all of them single-keystroke — the two-tier design is dead. Drop the fset, or provide a real =cj/confirm-strong= (typed "yes") for the irreversible set. From the 2026-06 config audit. +**** Functional tests +1. Open tutorial-api.rest, run JSONPlaceholder GET (C-c C-c) — verify response inline +2. Run POST example — verify 201 response with fake ID +3. Run httpbin header echo — verify custom headers echoed back +4. Navigate between requests with C-c C-n / C-c C-p +5. Test jq filtering (requires jq installed): restclient-jq loaded? +6. Open scratch buffer (C-; R n), type a request manually, execute +7. which-key shows "REST client" menu under C-; R + +** TODO [#C] Migrate from Company to Corfu (with prescient integration) :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -** TODO [#B] Stale elpa gptel shadows the local fork — likely the gptel-magit root :bug:quick:solo: -=elpa/gptel-0.9.8.5= is still installed alongside the =~/code/gptel= fork (=ai-config.el:383=); package activation puts the elpa dir + autoloads on load-path, so which copy wins depends on ordering, and a mixed load (fork .el + elpa .elc) produces "impossible" bugs. =gptel-magit= (elpa) declares gptel as a dependency, so IT may be pulling the stale copy — check this first when working the open "[#B] Investigate gptel-magit not working properly" task. Fix: =package-delete= the elpa gptel + remove from .localrepo so the fork is the only copy on disk. From the 2026-06 config audit. +Spec: [[file:docs/design/company-to-corfu-migration.org][docs/design/company-to-corfu-migration.org]] -** TODO [#B] vertico-prescient clobbers orderless filtering :bug:quick:solo: -=modules/selection-framework.el:250= — =vertico-prescient-mode= defaults =vertico-prescient-enable-filtering t=, overriding =completion-styles= to prescient inside vertico sessions; the orderless config at :151 is dead exactly where it matters. Set =vertico-prescient-enable-filtering nil= — orderless matches, prescient sorts (and this resolves the dead =vertico-sort-function= finding in the buffer/window-libs child the other way around). From the 2026-06 config audit. +*** TODO [#C] Install corfu-side packages +Add corfu, cape, kind-icon, corfu-prescient to the package list. corfu-popupinfo ships inside corfu. Spec step 1. -** TODO [#B] 2026-06 full config audit — findings backlog :refactor: -Module-by-module review of all 121 modules + init/early-init, holistic passes (startup/perf, stability, UX consistency, package strategy), and spin-offs into pearl, chime, emacs-wttrin. Method: parallel read-only review agents per module group; key claims spot-verified (incl. against the live daemon) before filing. Run 2026-06-11/12, COMPLETE. Tally: ~165 module findings + ~40 holistic + 30 spin-off ≈ 235 total; 40 high-impact bugs filed as standalone tasks above this parent; the rest live in the group children below. Spin-off findings delivered as inbox handoffs to pearl, chime, and emacs-wttrin (2026-06-12-0057). Start with the synthesis child below for the recommended attack order. +*** TODO [#C] Rewrite selection-framework.el company block as corfu/cape stack +Replace the three company-* use-package blocks (lines 192-226) and company-prescient (240-243) with corfu / cape / corfu-popupinfo / kind-icon / corfu-prescient. Rename the section header Company → Corfu in the same change. Spec steps 2 + 8. -*** Synthesis: the overall picture and attack order -Six cross-cutting themes, then the order I'd work them. +*** TODO [#C] Swap mail-compose completion disable to corfu +Rewrite cj/disable-company-in-mu4e-compose to (corfu-mode -1) across mu4e-compose, org-msg-edit, and message modes (mail-config.el:319-333). Spec step 3. -Themes: -1. Performance has one systemic lever, not many small ones: native-comp is accidentally OFF config-wide and GC sits at the stock 800KB ([#A] task). Daemon init itself is healthy (1.11s measured). Fix the lever before any micro-deferral work, and before burning time on the org-capture-perf debug. -2. A "dangerous defaults" safety cluster: yes-or-no-p fset (single-keystroke shutdown/file-destruction), the silently-failing Wayland lock screen, erc-yank's public gists, mu4e's broken trash/refile on the primary account. All four are [#A]/[#B] standalones; do these first — they're where the config can actually hurt you. -3. Calendar/agenda data correctness: calendar-sync's RFC trio (vanishing final occurrences, resurrected cancelled meetings, collapsed multi-day events) + agenda sources missing roam Projects. Meetings are missed over this. -4. Recurring mechanical defect classes worth sweeping as one commit each, config-wide: use-package :hook "-hook" suffix trap (org-babel, eshell, latex); eval-when-compile-only requires read at runtime (auth-config, keyboard-macros, erc-config); M-S-<letter> bindings vs uppercase events (4 dead keys + 1 asymmetry); raw C-; entries bypassing cj/register-prefix-map (8 modules); unreachable modules (prog-lsp, ledger-config, show-kill-ring, mu4e-org-contacts-setup); config for package versions long gone (mu4e 1.7 block, dashboard override, org timeline, checkdoc-arguments). -5. The test suite has a blind-spot class: characterization tests asserting BROKEN output (reverse-lines, heavy-box, undo-kill's explicit 0), unit tests hand-building data that hides integration mismatches (F7 coverage paths), and an integration gate that prints green over "Ran 0 tests" (chime). When fixing any standalone bug above, fix its test to assert correct behavior — and consider extending the architecture smoke test to mechanically pin the class-4 sweeps (hooks must be bound after load, no raw C-; binds, no M-S-<letter> specs, no eval-when-compile requires of runtime vars). -6. Consistency wants conventions, not patches: one notification facade (cj/notify — messenger spec addendum already covers the messenger half), one confirmation tier (the fset fix), one prefix-registration mechanism with labels, one buffer-naming shape. The messenger-unification registry mindset generalizes. +*** TODO [#C] Drop company-ledger for ledger's built-in capf +ledger-config.el: remove company-ledger; verify ledger-complete-at-point registers on completion-at-point-functions, add a ledger-mode-hook capf push only if it doesn't. Spec step 4. -Attack order: (a) the three [#A]s + gptel-shadow (it's blocking the filed gptel-magit investigation); (b) the daily-data pair — mail trash/refile + calendar RFC trio; (c) the :quick:solo: standalone sweep — roughly 20 one-to-five-line fixes, a satisfying solo batch; (d) the class-4 mechanical sweeps, one commit per class, each with its smoke-test guard; (e) the consistency conventions, opportunistically as those modules get touched. +*** TODO [#C] Drop company-auctex for AUCTeX capf + cape-tex +latex-config.el: remove company-auctex and (company-auctex-init); add cape-tex on TeX-mode-hook. Spec step 5. -*** TODO Findings: foundation/system group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [BUG] =keyboard-compat.el:121= — terminal arrow-key fix runs once on emacs-startup-hook; =input-decode-map= is terminal-local, so =emacsclient -t= frames under the daemon never get it. Register on =tty-setup-hook= (GUI half already uses =server-after-make-frame-hook=). -- [BUG] =config-utilities.el:142= — =cj/recompile-emacs-home=: =(boundp 'native-compile-async)= is always nil (it's a function — needs =fboundp=), so native compilation is never selected; and the helper deletes =<dir>/eln= when the real cache is =eln-cache/= (derive from =native-comp-eln-load-path=). Extend the existing test. -- [BUG] =system-utils.el:94= — success message args swapped: prints "Running notes.txt on mpv...". Trivial; wired into dirvish (O) and calibredb so it shows regularly. -- [REMOVE] =local-repository.el:51= — =localrepo-initialize=, its three defcustoms, and unprefixed =car-member= are dead; early-init owns archive setup with its own divergent path constant. Shrink to =cj/update-localrepo-repository= pointed at early-init's =localrepo-location=. -- [REMOVE] =keybindings.el:146-147= — C-x C-f unset/reset is a no-op (already find-file); comment wrong. Delete or retarget. -- [COVERAGE] =local-repository.el= — only module in the group with no test file. +*** TODO [#C] Rewire eshell completion to pcomplete capf +eshell-config.el:163-171: drop company-shell and the company-mode activation; add cape-capf-buster around pcomplete-completions-at-point + corfu-mode. Spec step 6. -*** TODO Findings: UI core group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [BUG] =font-config.el:262= — emojify =:defer 1= means :config runs before any daemon GUI frame exists; =env-gui-p= picks ='unicode= permanently, GUI frames never get image emojis. Compute per-frame (=server-after-make-frame-hook=) or test =(daemonp)=. -- [BUG] =font-config.el:283= — =cj/display-available-fonts= errors on second invocation: first call's =special-mode= sets read-only; next call's erase/insert signals. Wrap in =inhibit-read-only=. (Also [COVERAGE]: untested — a call-twice test catches it.) -- [UX] =undead-buffers.el:82= — =cj/kill-other-window= in a single-window frame kills the buffer you're looking at (other-window no-ops; only delete-window is guarded). Add the sibling's =(user-error "No other window")= guard. -- [UX] =undead-buffers.el:48= — C-u C-x k silently marks a buffer undead (then it refuses to die with no explanation later). Undocumented mode-switch inside a core-command remap; document or split into its own command. -- [ENHANCE] =ui-theme.el:87= — theme persistence silently fails on a fresh machine until =persist/= exists; =make-directory= before the writability check. -- [REMOVE] =dashboard-config.el:32-58= — =dashboard-insert-bookmarks= override is dead code: the :demand t require lets upstream dashboard-widgets.el redefine it; behavior survives only because upstream natively honors the settings now. Delete. -- [REMOVE] =font-config.el:199-220= — all-the-icons stack (2 =:demand t= packages + unprompted network font install on fresh machines) likely redundant with nerd-icons everywhere; verify keyboard-compat's reference then drop. -- [REMOVE] =ui-config.el:185= — duplicate =(use-package nerd-icons :defer t)= stanza; nerd-icons-config owns it. Delete stanza + stale Commentary bullet. +*** TODO [#C] Remove company-mode calls from prog-go/python/webdev +Delete (declare-function company-mode ...) and (company-mode) from the three mode hooks; global-corfu-mode covers them. Spec step 7. -*** TODO Findings: buffer/window libs group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [REMOVE] =show-kill-ring.el= — loaded by nothing (init require deliberately removed in b785a19d), so its M-S-k binding is dead; =keyboard-compat.el:177= still installs the M-K → M-S-k translation whose only purpose was this module. Re-add or delete module + stale translation/comment (consult-yank-pop largely supersedes it). -- [UX] =selection-framework.el:38= — =vertico-sort-function= custom is dead config: =vertico-prescient-mode= (line 250) replaces sorting when it activates. Pick one policy (drop the custom, or =vertico-prescient-enable-sorting nil=). -- [BUG] =custom-buffer-file.el:486= — =cj/view-email-in-buffer= leaks MIME handles when no displayable part: =user-error= fires before =mm-destroy-parts=. unwind-protect. -- [ENHANCE] =custom-buffer-file.el:49= — eager =(require 'mm-decode)= at startup only for macro expansion; runtime require already exists at line 481. Make it =eval-when-compile=. -- [UX] =custom-buffer-file.el:221= — =cj/copy-link-to-buffer-file= is a silent no-op in non-file buffers while siblings signal =user-error=. Match them. +*** TODO [#C] Uninstall company packages + recompile +After the rewrite is green: package-delete company, -quickhelp, -box, -prescient, -ledger, -auctex, -shell; make clean && make compile. Spec step 9. -*** TODO Findings: editing helpers group -From agents 2026-06-11; spot-verified sample (jump-paren, sortable-time confirmed). Beyond the standalone heavy-box task: -- [BUG] =custom-misc.el:48= — jump-to-matching-paren with point ON a closer lands at the last inner sexp, not the opener (batch-verified). =(forward-char)= before =(backward-sexp)= in the char-after-closer case; the test only covers the after-closer position. -- [BUG] =custom-datetime.el:71= — "sortable" time format is 12-hour ="%I:%M:%S %p %Z"= — "01:00:00 PM" sorts before "09:00:00 AM". Should be ="%H:%M:%S"=. -- [BUG] =custom-comments.el:82= — =cj/comment-reformat= prints "No region was selected" even on success (message outside the if-else), and the fill-column shrink/restore isn't unwind-protected — an error leaves fill-column permanently -3. Use let-binding + =user-error=; also =mark-active= vs the config's usual =use-region-p=. -- [BUG] =custom-line-paragraph.el:52= — join-line-or-region without region inserts a spurious blank line mid-buffer (verified); only insert the newline at eobp. -- [BUG] =custom-line-paragraph.el:77= — duplicate-line-or-region splits a mid-line-ending region via open-line and duplicates an extra empty line when the region ends at bol. Normalize bounds to whole lines. -- [BUG] =custom-ordering.el:158= — reverse-lines and number-lines mishandle the trailing newline ("a\nb\n" → "\nb\na"); the trailing-newline test asserts the broken output. =cj/--arrayify= (line 43) has the correct pattern — apply it; fix the characterization test. -- [BUG] =custom-comments.el:152= — inline-border lines come out 2 chars short for even-length or empty text (parity computed from text length instead of remaining width); stacked dividers misalign. -- [UX] =custom-text-enclose.el:216= — indent-lines =(interactive "p\nP")= couples COUNT and USE-TABS to one prefix arg — multi-column space indent is impossible interactively; docstrings claim "default 4" but "p" defaults to 1 (same in dedent :256). -- [REMOVE] =custom-ordering.el:90= — =cj/arrayify-python= is byte-identical to =cj/arrayify-json= (two bindings, same output). Delete one or differentiate (single quotes for Python). -- [UX] =custom-case.el:66= — title-case contradicts its docstring: "is" is in word-skip despite "linking verbs are major words"; no sentence-restart capitalization after periods; no capitalize-last-word rule. Align list + docstring. +*** TODO [#C] Tests: corfu activation, mail-disable, capf registration +New tests/test-selection-framework-corfu.el and tests/test-mail-config-corfu-disable.el; update ledger/latex tests to assert their capf registers. Spec Testing section. -*** TODO Findings: text/prose tools group -From agents 2026-06-11. Beyond the standalone markdown/latex tasks: -- [BUG] =text-config.el:72= — "M-S-i" for edit-indirect-region is unreachable: Meta+Shift+i generates the event M-I, not M-S-i, so the keypress falls back to M-i tab-to-tab-stop. Rebind as "M-I" (the "was M-I" comment thought the rename was a no-op; it wasn't). -- [BUG] =keyboard-macros.el:46= — user-constants required only =eval-when-compile= but =macros-file= is read at runtime; works only because init.el loads user-constants first. Plain require (same trap as auth-config). -- [BUG] =keyboard-macros.el:137= — kill-emacs-hook fires =y-or-n-p= + an interactive name prompt whenever any last-kbd-macro exists — hazardous for daemon/systemd shutdown (no one to answer) and noisy for throwaway macros. Guard =(and last-kbd-macro (not noninteractive))= minimum; consider dropping the prompt (M-F3 already persists named macros). -- [BUG] =lorem-optimum.el:221= — empty Markov chain (missing assets/liber-primus.txt) makes =cj/lipsum-insert= do =(insert nil)= — cryptic wrong-type error far from cause. Signal =user-error= naming the fix; also Commentary advertises "M-x cj/lipsum" but it has no interactive spec. -- [UX] =flyspell-and-abbrev.el:230= — every C-' press re-runs =flyspell-buffer= over the whole buffer while flyspell-mode is off (the documented word-by-word workflow = O(buffer) per keypress in large files). Call =cj/flyspell-on-for-buffer-type= so the mode sticks and the scan runs once. -- [ENHANCE] =text-config.el:121= — accent is wired to the company backend (=accent-company=); the filed Company→Corfu migration task doesn't list it, so C-` breaks silently post-migration. Add to the migration scope or switch to =accent-menu= now. +*** 2026-05-16 Sat @ 11:07:24 -0500 Goals +Drop-in replacement for the in-buffer completion stack: =company= → +=corfu=, =company-quickhelp= → =corfu-popupinfo=, =company-box= → +=kind-icon=, =company-prescient= → =corfu-prescient=, plus =cape= for +the file/keyword/dabbrev capfs that =company-files= / =company-keywords= +used to handle. Per-module fixups for ledger, AUCTeX, eshell, mu4e +compose, and the three =prog-*= modules. See the design doc for the +full translation table, migration steps, tests, and risks. -*** TODO Findings: org core group -From agents 2026-06-11; spot-verified sample (dailies head, babel hook, void bindings confirmed). Beyond the standalone tasks: -- [BUG] =org-babel-config.el:27= — =:hook (org-babel-after-execute-hook . org-redisplay-inline-images)= gets a second "-hook" appended (symbol unbound at expansion, doesn't end in -mode) → registers on nonexistent =org-babel-after-execute-hook-hook=; inline dot-graph images never refresh after C-c C-c. Write =(org-babel-after-execute . ...)= or add-hook in :config. -- [BUG] =org-roam-config.el:67,71= — C-c n p / C-c n w bound (and which-key-labeled) to =cj/org-roam-find-node-project= / =-webclip=, defined nowhere — keypress errors "autoloading failed to define function". Define via =cj/org-roam-find-node= (a project template exists) or drop bindings + labels. -- [BUG] =org-export-config.el:74-81= — ox-texinfo block can never run (=:defer t=, no trigger, excluded from line-47 dolist and =org-export-backends=); commentary still advertises Texinfo. Add to the dolist or delete; also commentary says "subtree default scope" vs actual ='buffer= (line 61). -- [UX] =org-roam-config.el:50-63= — two parallel template dirs drift: :custom templates read =~/.emacs.d/org-roam-templates/= while find-node-topic/recipe read =roam-dir/templates/= — overlapping recipe/topic/v2mom files, edits don't propagate. Pick one canonical dir. -- [REMOVE] =org-agenda-config.el:84= — dead =timeline= entry in org-agenda-prefix-format (removed in org 9.1). Also =org-config.el:47-48= — the TASK note claiming =org-indent-indentation-per-level= "doesn't exist" is wrong (real org-indent defcustom); restore the setq or fix the comment. -- [REMOVE] =org-babel-config.el:161= — =org-html-footnote-separator= is an ox-html setting parked in the babel module with a wrong comment; =org-roam-config.el:76= similarly hides =org-agenda-timegrid-use-ampm= in roam's :config (only takes effect after roam loads). Move both to their owning modules. -- [REMOVE] =org-roam-config.el:363-390= — 28-line commented consult-org-roam block on a TASK comment; its proposed C-c n l / C-c n r now collide with live bindings, so it can't ship as written. Decide + delete (git keeps the draft). -- [COVERAGE] =org-agenda-config.el:423= cj/add-timestamp-to-org-entry (defvar-inside-defun smell), =org-roam-config.el:115,185= node-insert-immediate + finalize-hook — untested. +** TODO [#C] Extend F2 "preview" convention across modes :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -*** TODO Findings: org apps + calendar-sync group -From agents 2026-06-11/12; spot-verified sample (UNTIL comparisons, EXDATE regex, drill setq confirmed). Beyond the standalone tasks: -- [BUG] =org-reveal-config.el:241= — seven raw =global-set-key= "C-; p ..." calls carry a hidden load-order dependency on keybindings.el (signals "non-prefix key" otherwise); every sibling uses =defvar-keymap= + =cj/register-prefix-map=. Convert. -- [BUG] =org-drill-config.el:131= — =:load-path "~/code/org-drill"= dev checkout breaks drill on machines without it (velox already diverges per the gptel-magit task). Guard with =file-directory-p= fallback to :vc. -- [UX] =org-contacts-config.el:146= — =cj/org-contacts-find= visits the file BEFORE prompting (C-g strands you at point-min) and plain =search-forward= can match body text in another entry. Collect heading positions in org-map-entries, goto after prompt. -- [REMOVE] =calendar-sync.el:1240= — =calendar-sync--fetch-ics= (buffer-string variant) is dead; the sync path uses the temp-file variant exclusively. 30 lines of duplicate curl/sentinel logic that will drift. -- [REMOVE] =org-webclipper.el:216-241= dead commented keymap blocks; =org-contacts-config.el:118-124= commented duplicate capture template flagged "TASK: duplicate?!?". Delete both (git keeps drafts). -- [COVERAGE] =calendar-sync.el:1274= — fetch sentinel branches (curl failure, temp-file cleanup, signal exit) untested; dispatch tests stub above this layer. +F2 is the universal preview key. Currently bound only in markdown-mode (markdown-preview, in =modules/markdown-config.el=). Org-reveal lives on =C-; o R= via =cj/org-map=, not F2. Extend F2 to other modes where a "preview" action is natural: -*** TODO Findings: mail group -From agents 2026-06-12; spot-verified sample (cmail trash gap, no refile folders, gmail-first contexts confirmed). Beyond the standalone [#A] task: -- [BUG] =mail-config.el:392-407= — C-; e account nav lambdas call =mu4e-search=, not autoloaded — void-function before first mu4e launch. Add to :commands or require first. -- [BUG] =mail-config.el:481-484= — unconditional =org-msg-edit-mode= :after advice on replies defeats the =(reply-to-text . (text))= alternative at :459 and re-runs a major mode org-msg already set up. Gate or remove. -- [BUG] =mu4e-attachments.el:222= — the *mu4e attachments* selection buffer saves through stale MIME handles if the view changed before s — errors or saves the wrong message's parts. Check =buffer-live-p= per handle at save. -- [BUG] =mail-config.el:329= — "save attachment" in =mu4e-headers-actions= can't work from headers (MIME vars are view-buffer-local, nil in headers-mode). Drop it there. -- [BUG] =mail-config.el:282-305= — HTML view block sets variables obsolete since mu4e 1.7 (installed 1.14.1): =mu4e-view-prefer-html=, =mu4e-html2text-command= (also set twice: 186, 285), =mu4e-view-show-images=, =mu4e-view-image-max-width=. The pandoc/w3m selection never runs; shr renders regardless. Delete the dead block (image/privacy reconciliation already filed separately). -- [BUG] =mail-config.el:45-49,80-89= — top-level =(defvar message-send-mail-function nil)= pre-empts message.el's defcustom default; with msmtp absent the fallback leaves it nil → "invalid function: nil" on first send. Explicit =smtpmail-send-it= fallback or descriptive user-error. -- [UX] =mail-config.el:171,196-199= — =pick-first= + gmail listed first makes gmail the startup context though cmail reads as primary everywhere else — quiet wrong-account hazard for the first compose. Reorder contexts. -- [REMOVE] =mu4e-org-contacts-setup.el= — unreachable (nothing requires it; mail-config calls activation directly) and its featurep gate would be nil at init anyway. Delete or fold its two setqs into mail-config. -- [REMOVE] =mail-config.el:208,232= — =mu4e-starred-folder= isn't a mu4e variable (invented, no effect); =:174= =mu4e-maildir= is the obsolete alias of root-maildir set on the previous line. Drop all three. -- [REMOVE] =mu4e-org-contacts-integration.el:158,171-172= — hook surgery on =mu4e--compose-setup-completion= is a no-op on mu4e 1.14 (called directly, not via hook; already gated by the var activation sets). Delete both hook calls. -- [COVERAGE] =mu4e-attachments.el:101-105= — mid-batch save-failure path and stale-handle scenario untested. +- Hugo blog (hugo-config.el) — preview the post in browser +- HTML / web-mode — open in browser +- Reveal presentations - preview in browser +- Any other mode with a natural "preview this" action -*** TODO Findings: messengers group -From agents 2026-06-12. Beyond the standalone tasks; several feed the messenger-unification spec: -- [BUG] =signal-config.el:201= — contact cache docstring claims "cleared on signel-stop/restart"; nothing clears it (grep: fork never references it). Stale list after relink/reconnect. Advise =signel-stop= or clear on start. -- [BUG] =signal-config.el:298= — fetched-and-empty contact list is indistinguishable from cold cache (nil), so a zero-contact account re-runs the blocking fetch (up to fetch-timeout) on every C-; M m. Cache a sentinel. -- [UX] =slack-config.el:208= — =cj/slack-notify= lacks signel's hardening: no truncation (giant toasts), no sound gating, no notifications-notify fallback when the script is absent. Unification-relevant: extract a shared =cj/messenger-notify= (title prefix, truncation, sound flag, script-with-fallback) — noted in the unification spec. -- [ENHANCE] =telega-config.el:52= — telega has NO notification path (=telega-notifications-mode= not enabled); incoming Telegram messages invisible unless the buffer is on screen. Enable, or route through the shared notifier. Unification-relevant. -- [COVERAGE] — =cj/erc-join-channel-with-completion= (erc:148, four-way reconnect branching), =cj/erc-connected-servers= (would have caught the tautology), =cj/slack-notify= predicates, =cj/signel--ensure-started= branches — all untested. +Keep the binding mode-local so F2 stays available as a global candidate where no preview makes sense. -*** TODO Findings: programming group -From agents 2026-06-12; spot-verified sample (prog-lsp unreachable confirmed by grep). Beyond the standalone tasks: -- [BUG→FOLD] =prog-lsp.el= — the module is UNREACHABLE: nothing requires it, so its entire LSP policy (TRAMP guard, file-watch ignores, read-process-output-max, idle-delay 0.5) is dead while prog-general.el:388-416's older conflicting block wins (idle 0.1, lsp-ui-doc on). Fold this fact into the filed "Make prog-lsp.el the single owner of generic LSP policy" task — it doesn't currently record that prog-lsp never loads. -- [BUG] =flycheck-config.el:68-70= — =checkdoc-arguments= isn't a real variable (invented name + invented format); the intended checkdoc suppression has never worked. Use =flycheck-emacs-lisp-checkdoc-variables= or drop. -- [BUG] =prog-json.el:87-90= — C-c C-q → jq-interactively binding defers to eval-after-load of jq-mode, which nothing loads — dead key. Bind in =cj/json-setup= via local-set-key (jq-interactively IS autoloaded). -- [BUG] =prog-python.el:129-132= — lsp-pyright's :hook lambda calls =lsp-deferred= unguarded on the same hook as the guarded =cj/python-setup= — pyright-absent machines still get the LSP attach prompt the guard exists to prevent. Move the require into the guarded branch; delete the hook. -- [BUG] =prog-lisp.el:122-125= — =:after (flycheck package-lint)= waits for a manual M-x to load package-lint, so =flycheck-package-setup= effectively never runs. Hook on flycheck load + require inside. -- [UX] =prog-python.el:111-115=, =prog-go.el:111-114=, =prog-webdev.el:128-147= — setup hooks attach to ts-modes only (C/shell hook both variants); grammar-unavailable fallback to classic modes silently loses indent/keys/formatter/LSP. Add classic-mode hooks. -- [UX] =prog-webdev.el:165-173= — web-mode gets the format key but none of the promised setup (no company/flyspell/LSP in HTML buffers). Add to the setup hook or fix the Commentary. -- [ENHANCE] gopls, clangd, bash-language-server, shfmt, shellcheck lack the =cj/executable-find-or-warn= load-time warnings pyright/prettier have; prog-shell's =:if (executable-find ...)= evaluates once at startup and silently disables shfmt/flycheck setup forever. -- [REMOVE] =prog-training.el:36-37= — =(url-debug t)= turns on GLOBAL url.el debug logging once leetcode loads. Debugging leftover; delete. -- [REMOVE] =prog-webdev.el:85=, =prog-json.el:44=, =prog-yaml.el:39= — three byte-identical format-region helpers. Extract one shared tested helper (system-lib). +** TODO [#C] Localrepo Documentation :feature:docs:localrepo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: -*** TODO Findings: dev tooling group -From agents 2026-06-12; spot-verified sample. Beyond the standalone F7 task: -- [BUG] =vc-config.el:138-144= — =cj/goto-git-gutter-diff-hunks= (C-; v d) never did what it claims: consult-line over "^[+\\-]" matches source text, not gutter hunks. Build candidates from =git-gutter:diffinfos= or drop the binding (C-; v n/p covers it). -- [BUG] =dev-fkeys.el:116-122= — F4 compile+run one-shot hook installs on GLOBAL =compilation-finish-functions= before the prompt; C-g leaves it armed and the next unrelated compile triggers projectile-run-project. Use the buffer-local pattern the module already uses for cache-revert (same in =--f4-clean-rebuild-impl=:143). -- [BUG] =test-runner.el:84,222= — documented ~/.emacs.d/tests fallback doesn't exist (=cj/test-global-directory= defvar'd nil, never set); outside a project =(file-directory-p nil)= crashes in three commands. Initialize the defvar or guard with user-error. (Adds specifics to the open "Fix up test runner" task — fold.) -- [BUG] =test-runner.el:288= — focus-add prefix check lacks the trailing slash so =tests-scratch/= passes the "inside tests/" check; the correct helper =cj/test--file-in-directory-p= exists at :168 — use it. -- [BUG] =vc-config.el:217-219= — difftastic blame map binds D and S to the same command (show); D should be diff per the transient four lines down. -- [UX] =diff-config.el:37= — =ediff-diff-options "-w"= ignores ALL whitespace in every ediff session — indentation-only Python changes compare as identical. Drop the default; toggle per-session. -- [UX] =restclient-config.el:64-65= — raw global-set-key "C-; R n" hides a load-order dependency (header claims "Runtime requires: none"); use defvar-keymap + =cj/register-prefix-map= like siblings (same class as org-reveal, slack). -- [UX] =vc-config.el:196= — clipboard clone via synchronous =call-process= freezes every emacsclient frame for the whole clone. make-process + sentinel. -- [REMOVE] =vc-config.el:80-82= — phantom autoload =git-timemachine-show-selected-revision= (no such function in the package) appears in M-x and errors. Drop from :commands. -- [REMOVE] =httpd-config.el:19-30= — pointless =:defer 1= (impatient-mode loads simple-httpd on demand) + unprefixed eager globals =wwwdir=/=check-or-create-wwwdir= creating www/ on every startup. =:defer t=, prefix, or fold into markdown-config. -- [COVERAGE] — intersect/parse unit tests hand-build matching keys (the F7 bug's escape route); =--coverage-elisp-run='s compilation-finish wiring, goto-git-gutter-diff-hunks, timemachine candidate round-trip untested. F-key sweep clean: no collisions; F5 free for the debug-backend task. +Audit on 2026-05-27 found the localrepo build half is shipped (=.localrepo/= holds 185 entries; =early-init.el= L135–165 wires the priority-200 pin above the local ELPA-mirror tier at 120–125 and the online fallback). The remaining "document limitations" half splits into one docs-set plus four gap-fix follow-ups that the docs cross-reference. -*** TODO Findings: shell/term/files group -From agents 2026-06-12; spot-verified sample (eshell nested list confirmed). Beyond the standalone tasks: -- [BUG] =dirvish-config.el:37= — =cj/xdg-open= attributed to system-utils in the require-comment but defined in external-open.el; neither dirvish-config nor dwim-shell-config (caller at :876) requires it — "Direct test load: yes" headers are false. Require external-open (or move the fn into external-open-lib) + fix comment. -- [UX] =tramp-config.el:73= — =revert-without-query '(".*")= kills revert confirmation for EVERY file in Emacs, buried in the TRAMP module. Scope to =tramp-file-name-regexp= or move deliberately to an editing module. -- [UX] =dirvish-config.el:403= — quick-access entries lx (~/archive/lectures), phl (~/projects/homelab), pn (~/projects/nextjob) point at directories that don't exist on this machine. Prune or create. -- [REMOVE] =dwim-shell-config.el:474,507= — open-externally (raw xdg-open) and open-file-manager (thunar/nautilus probe chain) duplicate cj/xdg-open (dirvish o) and cj/dirvish-open-file-manager-here (f); ascii-art references jp2a, the module's only absent binary. Delete the two duplicates; install jp2a or drop ascii-art. -- [REMOVE] =tramp-config.el:115= — custom =sshfast= method referenced nowhere (everything uses sshx); =tramp-own-remote-path= added twice (:39,:128); =dirtrack-list= and =magit-git-executable "/usr/bin/git"= are unrelated globals hiding here. Prune/relocate. -- [COVERAGE] — eshell visual-commands/xterm-color wiring and the dirvish mark-all loop had no load-and-assert tests (both standalone bugs above); TRAMP perf settings look sound for the DUET latency concern (attr caching, no remote VC, direct-async + controlmaster). +Docs land in three artifacts. =docs/design/localrepo.org= carries the full architecture (tier model, install path, refresh story, all four limitations with pointers to the follow-up tasks). =.localrepo/README.org= sits next to the artifact as the user-facing entry — a short summary that survives even if =early-init.el= moves. =early-init.el= grows a commentary header that points at the README, not at the design doc — the README is what future-Craig hits first. -*** TODO Findings: AI group -From agents 2026-06-12; spot-verified sample (string-model setq confirmed). Beyond the standalone tasks: -- [BUG] =ai-term.el:875= — close derives the tmux session name from =default-directory=, which ghostel retargets via OSC 7; after a cd the kill-session misses (orphaned agent session) or name-collides with a different aiv- session. Derive from the buffer name's immutable basename. -- [UX] =ai-term.el:827= — multi-window F9 toggle-off unconditionally delete-windows, never restoring the displaced edge-window buffer the Commentary (:24) and reuse-edge docstring (:521) promise. Restore when quit-restore still matches, or fix the docs to describe delete-window reality. -- [UX] =ai-conversations-browser.el:191= — browser load stubs =y-or-n-p= to nil, silently discarding an unsaved in-progress conversation (the direct C-; a l path offers to save). Give ai-conversations a file-arg internal instead of puppeting the interactive command via cl-letf; also the =(caar cands)= fallback loads the newest conversation on a filename mismatch — fail loudly. -- [ENHANCE] =ai-quick-ask.el:103= — dismiss mid-stream kills the buffer without =gptel-abort= — request keeps streaming to a dead buffer (wasted tokens). -- [NOTE] =ai-mcp.el= — unreachable from init, consistent with the paused Phase 1.5; add a one-line Commentary note ("not wired until Phase 2") so future audits don't re-flag, and revisit =cj/mcp-enabled-servers= defaulting to all nine servers before wiring. -- [COVERAGE] — load/autosave lifecycle untested (fresh-session load, timer self-cancel, close-buffer session-name derivation). +The four limitations the docs cover (each spun out below as its own task): +- Treesitter grammars (downloaded by =treesit-auto= on first use; not in the localrepo) +- Native-comp =.eln= cache (Emacs-version-specific; invalidated by version bumps) +- System-tool deps (=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, etc.; flagged at load by =cj/executable-find-or-warn=, not packageable via =package.el=) +- Refresh / update story (no dedicated script today; ad-hoc =cp= from the elpa mirrors) -*** TODO Findings: media/reading group -From agents 2026-06-12; spot-verified sample (M-S- bindings, eww store split confirmed). Beyond the standalone tasks: -- [BUG] =music-config.el:585= — =cj/music-add-dired-selection= gates =dired-get-marked-files= on =(use-region-p)= — but dired marks aren't a region; marked files are ignored, + adds only file-at-point. Drop the conditional (the function already falls back correctly). Note for the EMMS-free rewrite: dirvish + shadows =dired-create-directory= — deliberate decision needed before carrying it over. -- [UX] =media-utils.el:195-204= — =cj/yt-dl-it= watches tsp (which enqueues and exits), so "Finished downloading" fires immediately while yt-dlp may fail later, silently; also affects elfeed d. Message "queued" honestly or watch the real job (tsp -f). -- [UX] =browser-config.el:34-47,171= — first-run fallback picks EWW (first, "always available") over installed real browsers; fresh machines get org links in a text browser until cj/choose-browser runs. Prefer the first external match. -- [REMOVE] =video-audio-recording.el:442-488= — =cj/recording-group-devices-by-hardware= is dead code (nothing calls it) carrying a hardcoded "Jabra SPEAK 510 USB" branch. Delete + its test file. -- [REMOVE] =calibredb-epub-config.el:198-212= — =set-auto-mode= :around advice for .epub is redundant with nov's :mode registration (auto-mode-alist wins before magic-fallback); overhead + failure surface on every file visit. Remove and verify. -- [COVERAGE] — eww interactive commands (switch-search-engine, bookmark-quick-add, copy-url) and =cj/nov-center-images= untested. +*** TODO [#C] Design doc — docs/design/localrepo.org :docs: +Write the design doc: tier model, priorities, install path, refresh story, all four limitations with cross-links to the follow-up tasks below. -*** TODO Findings: apps/misc group -From agents 2026-06-12. Beyond the standalone tasks: -- [BUG] =hugo-config.el:49= — =cj/hugo-new-post= void-functions on =org-hugo-slug= in a fresh session (ox-hugo is :after ox, which loads on first export); =cj/hugo-export-post= already requires ox-hugo — do the same here. -- [BUG] =help-utils.el:73= — arch-wiki search signals raw file-missing when the docs dir is absent; the friendly install hint at :81 is unreachable. Guard with =file-directory-p= + user-error up front. -- [UX] =hugo-config.el:244= — eight raw global-set-key C-; h calls + hand-rolled which-key mutate cj/custom-keymap directly, against keybindings.el's own instruction. Convert to defvar-keymap + =cj/register-prefix-map= (same class as org-reveal, restclient, slack). -- [ENHANCE] =games-config.el:25= — =:defer 1= pulls malyon + 2048 into every session for nothing; use =:commands=. Also :config references =org-dir= without requiring user-constants (free-variable warning at byte-compile). -- [REMOVE] =wrap-up.el:29= — =elisp-compile-mode= doesn't exist (real mode emacs-lisp-compilation-mode derives from compilation-mode, already covered at :27); dead line. (The prior unguarded-timer fix is intact.) -- [REMOVE] =help-config.el:99-106= — stray empty :preface + dead commented Info-directory-list block. Delete. -- [NOTE] =duet-config.el= — orphaned BY DESIGN (Commentary documents pre-alpha staging; Stage 1 is the wire-in trigger). Audit record only. -- [COVERAGE] — help-config and help-utils have zero test files; the two broken paths above are exactly the untested branches. +*** TODO [#C] README — .localrepo/README.org :docs: +Write the README at the artifact: short prose entry point summarizing the tier model, pointing at =docs/design/localrepo.org= for full detail. This is what =early-init.el='s commentary header links to. -*** TODO Findings: holistic — startup & performance -From the 2026-06-12 holistic pass; daemon init measured at 1.11s (healthy). Beyond the standalone [#A] native-comp/GC task: -- [BUG→FOLD] the eager-org chain: =org-config.el:352= org-appear has no defer trigger (only :custom) → requires all of org at init; org-agenda (=:after org :demand t=) cascades; chime's =:demand t= pulls it anyway. org-config is the most expensive require (0.229s of 1.11s). Decide fully-eager vs fully-deferred — and =init.el:146='s "calendar-sync must come after org-agenda" contract exists only as a comment (three uncoordinated writers of =org-agenda-files=). Both facts belong in the filed defer-modules task before that refactor starts. -- [PERF] =dirvish-config.el:385-387= — =:defer 0.5= defeated by :init calling autoloaded =dirvish-override-dired-mode= → dirvish fully loads at init (0.072s, third most expensive; trace-confirmed). Own the eager load or defer the override to a dired-mode-hook shim. -- [PERF] timed =:defer N= loads unused packages into every start: simple-httpd (:1s + startup mkdir despite the defer), malyon, 2048-game, emojify (may hit network), ligature. Convert to :commands/mode hooks. -- [UX] =early-init.el:235-256= — synchronous =package-refresh-contents= on the startup path when any archive cache is >7 days old (MELPA ~6MB) — multi-second network-bound start, fires in batch too. Make async post-startup or push into the localrepo update script (distinct from the filed bootstrap-relocation task). -- [PERF] =early-init.el:228= — no =package-quickstart= with 184 packages; activation walks every package dir each start (~0.3s of early-init). Free win; regenerate after package ops. -- [PERF] =prog-general.el:298= — =yas-reload-all= immediately before =yas-global-mode= scans snippet dirs twice per start (doubled "[yas] Prepared..." message). Delete the line. -- [REMOVE] cross-ref: the all-the-icons stack (already in UI core findings) is 2 of the :demand t packages plus a per-frame install-check hook. +*** TODO [#C] Commentary header in early-init.el :docs: +Add a Commentary-section header in =early-init.el= pointing at =.localrepo/README.org= for usage and =docs/design/localrepo.org= for architecture. Sits at the top of the localrepo block (around L130). -*** TODO Findings: holistic — daemon stability -From the 2026-06-12 holistic pass. Architecture-level verdict good (timers cancelled/guarded, calendar-sync async well-contained, advice mostly named + guarded). Residual: -- [STABILITY] =transcription-config.el:293= — sentinel chain has no unwind-protect; =--append-to-log='s =insert-file-contents= signals if the log is missing → process buffer leaks, entry stuck 'running in the modeline forever, no notification. Extends the filed transcription standalone — fix together. -- [STABILITY] =calendar-sync.el:1646= — hourly timer body: fetch/parse guarded but the timezone check and =--require-calendars= run bare — any signal repeats hourly forever (the exact class fixed in four modules once). Condition-case the body; demote the hourly echo-area message to the silent log. -- [STABILITY] =music-config.el:865= — four anonymous-lambda advice in :config stack per live reload (verified: lambdas don't dedupe) and can't be advice-removed. Name the function. -- [STABILITY] =system-defaults.el:69= — =display-warning= advice appends to comp-warnings-log with no condition-case (unwritable path → every async comp warning signals from inside display-warning) and the log grows unbounded. Guard + cap. -- [STABILITY] =media-utils.el:164= — playback sentinel assumes the process buffer is alive (user killed *player:...* → sentinel error, diagnostics lost); sibling yt-dl sentinel shares the kill-buffer gap. buffer-live-p guards. -- [ENHANCE] =system-commands.el:86= — =#'ignore= sentinel + output to /dev/null makes failing lock/suspend indistinguishable from success — the user walks away from an unlocked machine. Message on nonzero exit. (Compounds the [#A] slock task: the broken lock currently fails through exactly this silent path.) -- [ENHANCE] =ui-config.el:153= — post-command cursor hook unguarded: any future signal self-removes it silently (cursor stops signaling modified/read-only until restart); frame-hook lambda also accumulates per reload. with-demoted-errors + name it. -- (kill-emacs-hook y-or-n-p prompt independently re-found here — already filed in the text/prose child; convergence noted.) +** TODO [#C] TRAMP/dirvish "?" for remote dates — verify the fix per host :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -*** TODO Findings: holistic — UX consistency -From the 2026-06-12 holistic pass. Verdict: more coherent than most 120-module configs (~85% prefix-helper adoption, M-S translation fully covers its 18 bindings, F-keys collision-free, DEF-arg prompts dominate). Beyond the standalone [#A] fset task: -- [BUG] notification env gate: =transcription-config.el:169-171= gates desktop notifications on =(getenv "DISPLAY")= — an X11 predicate that works only because XWayland exports it. Use =env-gui-p= (host-environment.el provides it). -- [UX] four notification stacks beyond the messenger split (notify script ± fallback, alert.el, raw notifications-notify, echo-only for calendar-sync/recording completions). Proposed: one cj/notify facade (transcription's =cj/--notify= is the right shape) — config-wide companion to the messenger-notify addendum in the unification spec. -- [UX] five more C-; entries bypass the register helpers or lack labels: =browser-config.el:182= (C-; B, no label), =org-babel-config.el:51= (C-; k, no label), =flycheck-config.el:62-64= (:bind into cj/custom-keymap), =pearl-config.el:43= (:bind-keymap C-; L, no label), =dev-fkeys.el:533= (helper but no label). Sweep onto cj/register-prefix-map with labels. -- [UX] user-error vs message inconsistent for "nothing to act on" config-wide (examples: =custom-whitespace.el:190=, =jumper.el:202=, =chrono-tools.el:99= message; =mu4e-attachments.el:112=, =ai-rewrite.el:79= user-error; =test-runner.el:392/394= mixes both 2 lines apart). Convention: user-error when the command can't proceed; message when it ran and found nothing. -- [ENHANCE] M-S translation layer: complete for GUI (18/18) but installs only on env-gui-p paths — terminal frames have no M-uppercase route; and =dwim-shell-config.el:932/934= binds M-S-d (dired) vs raw M-D (dirvish) asymmetrically. Feeds the filed M-S review task with the concrete map. -- [ENHANCE] which-key labels: register-helper's LABEL arg used by exactly 1 of 23 registrants (rest use separate with-eval-after-load blocks); label style drifts ("X menu" vs bare nouns). Adopt LABEL arg + one style. -- [ENHANCE] "?" curated-menu candidates (for the filed convention task): elfeed search/show, dirvish, signel chat/dashboard, music playlist, ai-conversations-browser, mu4e-attachments, transcription status, pearl. calibredb remains the model. -- [UX] ="(Cancel)"= pseudo-candidate in =music-config.el:253-256= vs C-g everywhere else (90+ prompts). Drop it. -- [UX] buffer-naming drifts across three conventions (*AI-Assistant* / *Kill Ring* / *dashboard*); pick Title Case + "*Name: param*", lowercase for process logs. -- [ENHANCE] C-; f formatter shadowing implemented 3 ways (:bind :map vs local-set-key in hooks); unify on :bind. Also =keybindings.el:21= commentary still says "C-c j" for the jump prefix the code binds at C-; j. -- [ENHANCE] initial-input anti-pattern at =dwim-shell-config.el:661,680= and =erc-config.el:176-177= against the config's DEF-arg norm. +Root cause is traced (see the dated investigation entry below). What's left needs a live remote: open each remote host in dirvish and run the three diagnostic evals to find which gate is closed, then close it. -*** TODO Findings: holistic — package strategy -From the 2026-06-12 holistic pass (184 elpa dirs). Core stack modern (vertico/consult/embark/orderless, treesit-auto, built-in which-key, current magit/forge/telega/slack). Beyond the standalone gptel/prescient tasks: -- [REMOVE] true orphans, nothing references them: js2-mode, tide, json-mode (pre-treesit JS stack). package-delete + drop from .localrepo. -- [REMOVE] emojify: 2021 snapshot, dormant upstream, crashes in lui (slack disabled it), Emacs 30 renders emoji natively. Drop the use-package + hooks (=font-config.el:253=, =erc-config.el:211=); it stays on disk only as slack's declared dep. -- [BUG] legacy-mode hooks miss the ts modes: =prog-general.el:91-92= hooks =yaml-mode-hook=/=toml-mode-hook= but the config runs yaml-ts/toml-ts — general prog settings silently don't apply in YAML/TOML buffers. Rehook; delete toml-mode + eldoc-toml + yaml-mode packages (superseded by treesit). -- [RISK→FOLD] localrepo priority 200 is absolute, so package-upgrade silently no-ops on everything mirrored — the engine that fossilized emojify@2021/toml-mode@2016/js2@2023. The filed refresh-script task at [#D] deserves [#B] + a quarterly cadence, else every orphan finding regrows. -- [RISK] fork fleet sync-back stories: org-drill flip back to :vc when done (filed dev-checkout finding); auto-dim-other-buffers local checkout with :vc commented — decide its home; org-msg pins =:rev :newest= (unpinned moving target) — pin a known rev. signel/duet/pearl/wttrin/gloss/chime self-owned remotes are fine. -- [UPGRADE] wiki-summary (2018, dead upstream, predates Wikipedia's REST API; sole caller help-utils) — the audit's one write-your-own: ~30-line url-retrieve against the REST summary endpoint. Delete the package, inline the helper. -- [UPGRADE] xterm-color droppable in eshell on Emacs 30's native ansi-color (its only use; also doubly-broken per the eshell standalone task — fixing by deletion is an option). -- [ENHANCE] Python tier: poetry.el (sluggish) + pyvenv (2021) keep only if Poetry projects are still real; blacken fine until ruff-format (reformatter.el already installed). lsp-pyright current. -- [DECIDED] projectile, lsp-mode, dirvish: keep (wired into 10/7/many modules, maintained, migration cost > benefit). On the record so future audits don't relitigate. +Diagnostics (run with point in a remote dirvish buffer): +- =M-: (dirvish-prop :remote-async)= — nil means =tramp-direct-async-process-p= is failing for this method/host, so dirvish's remote attribute fetch never runs. +- =M-: (dirvish-prop :gnuls)= — nil means the remote has no GNU =ls= (the =ls --version= probe failed), so the parser gate stays shut. Likely on truenas (FreeBSD). +- =M-: (tramp-direct-async-process-p)= — confirms whether direct-async is actually active for the connection. -*** TODO Findings: spin-off repos (pearl, chime, emacs-wttrin) -Full findings delivered as handoffs to each repo's inbox/ (2026-06-12-0057-from-.emacs.d-handoff-*.org); each repo's next session files them through its own value gate. Highlights: -- pearl (10 findings; suite green, 66 ERT files): auth-source negative-cache trap in pearl-clear-cache (the 2026-06-01 incident class, unfixed); sync wrapper ignores pearl-request-timeout + async has no timeout; mutation errors discard Linear's GraphQL reason; no RATELIMITED handling; dead legacy API layer (~150 lines). -- chime (10 findings; suite green; the 2026-06-11 watchdog handoff VERIFIED landed in full): lookahead vars never injected into the async child (documented feature silently capped at 8 days — one-line fix); days-until-event nil crash on mixed timed/all-day events; stale-callback race after watchdog interrupt (generation counter needed); default test run prints green integration banner over "Ran 0 tests". -- emacs-wttrin (10 findings; ~56 ERT files, CI; the face-flood reminder VERIFIED resolved — test 8f3c770 + fix c5e5e1d, reminder cleared from notes.org): no network timeouts (wttr.in stalls hang the loading buffer); error-path response-buffer leak; non-favorite cache never expires; 17 unreleased commits incl. two features — tag v0.4.0. +Likely fixes, by which gate is closed: +- =:gnuls= nil → install GNU coreutils on the remote (FreeBSD: =pkg install coreutils=) and make =ls= resolve to GNU on the TRAMP path, or accept "?" on that host. + + - Constraint: nothing gets installed on the remote host, so the =:gnuls= gate is resolved by accepting "?" on that host rather than installing coreutils. +- =:remote-async= nil → the scp/sshx method isn't advertising direct-async; switch to a method that supports it or check =tramp-direct-async-process= is taking effect for that protocol. + +Files involved: =modules/tramp-config.el=, =modules/dirvish-config.el=. + +*** 2026-05-22 Fri @ 20:24:44 -0500 Traced the root cause through dirvish source +Remote dates/sizes don't come from the dired =ls= listing or =dired-listing-switches=. They come from =dirvish-data-for-dir= (=dirvish-tramp.el:95=), which runs =ls -1lahi= on the remote and parses the columns into the attribute cache. That method only fires when both =(dirvish-prop :remote-async)= is a number and =(dirvish-prop :gnuls)= is a string. When either gate is shut, dirvish falls back to its default, which deliberately skips =(file-attributes f-name)= for remote files (=dirvish.el:904=, a perf guard) — leaving attrs nil, so the file-size and file-time widgets render "?" (=dirvish-widgets.el:216,247=). + +That explains why every prior fix missed: dired-listing-switches feed a different code path entirely, and disabling =tramp-direct-async-process= shuts the =:remote-async= gate, which is the one path that populates remote attributes — exactly backwards. The config already enables direct-async for ssh/sshx (=tramp-config.el:79-88=), so the remaining closed gate is per-host: =:gnuls= (no GNU ls on FreeBSD-based truenas) or direct-async not taking effect for the method. Could not verify on a live remote from the work session — handed the per-host diagnostics up into the task body. + +** TODO [#C] Terminal GPG pinentry Completion :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: + +Audit on 2026-05-27 found no trace of the =terminal-pinentry= branch on this machine: no local or remote ref, no reflog entry across 732 entries reaching back through January, no stash, no dangling commit, no sibling worktree. The 2026-01-24 session log says the branch was created that day, but the work either lived on another machine or was deleted before reaching here. The original task above (=Finish terminal GPG pinentry configuration=) is superseded by this one. + +Surviving footprint on this machine: one commented line at =modules/auth-config.el:83= (=;; (setq epa-pinentry-mode 'loopback)=). The hook point =env-terminal-p= exists in =modules/host-environment.el:97=. Everything else (terminal-vs-GUI branching in the epa =:config=, external pinentry wiring for GUI, =GPG_TTY= export, tests) is to be written fresh off main. + +Goal: in terminal Emacs, GPG passphrase prompts land in the minibuffer via loopback mode; in GUI Emacs, prompts go to the existing external pinentry. + +Open: confirm the GUI pinentry tool (2026-01-24 notes named =pinentry-dmenu=; current =auth-config.el= names no pinentry program, leaving it to =gpg-agent='s config). Also worth checking whether the =terminal-pinentry= branch survives on the laptop and should be pulled here rather than rewritten. + +*** TODO [#C] env-terminal-p branch in epa :config :feature: +Inside the epa =use-package= =:config= in =modules/auth-config.el=, set =epa-pinentry-mode= to ='loopback= when =(env-terminal-p)=, else leave the external pinentry path active. Replace the lone commented line at =auth-config.el:83=. + +*** TODO [#C] GPG_TTY export for terminal sessions :feature: +When =(env-terminal-p)=, =(setenv "GPG_TTY" (shell-command-to-string "tty"))= so gpg-agent can target the controlling tty. Guard against a non-tty stdin. + +*** TODO [#C] gpg-agent updatestartuptty refresh in terminal :feature: +The current =call-process= to "gpg-connect-agent updatestartuptty /bye" runs unconditionally; keep it for GUI, and re-fire it on terminal entry so the agent re-binds to the current tty. + +*** TODO [#C] ERT tests for terminal vs GUI pinentry branching :tests: +Test that with =env-terminal-p= stubbed t, =epa-pinentry-mode= resolves to ='loopback= after =auth-config= loads; with it stubbed nil, the loopback setting is not applied. Use =cl-letf= around =env-terminal-p=; cover normal, boundary (=epa= already loaded), error (=gpg-connect-agent= missing). + +*** TODO [#C] Minibuffer prompt in real terminal Emacs :verify: +=emacs -nw=, open an encrypted file or trigger an auth-source decrypt, confirm the passphrase prompt lands in the minibuffer rather than failing on missing pinentry. + +*** TODO [#C] External pinentry still fires in GUI Emacs :verify: +Restart the daemon, open a GUI frame, trigger an encrypted decrypt, confirm =pinentry-dmenu= (or whatever GUI pinentry is configured) still appears. + +*** TODO [#C] Archive the original L3813 task :chore: +After this work lands, mark the original "Finish terminal GPG pinentry configuration" task DONE with a =CLOSED:= stamp and a one-line note pointing at this parent task. + +** TODO [#C] Google Contacts ↔ org-contacts sync investigation :feature:research: +From the 2026-06-11 brainstorm. Goal: keep [[file:~/sync/org/contacts.org][contacts.org]] (real org-contacts: PROPERTIES drawers, mu4e completion, org-roam links) in sync with Google Contacts. Google side is solid — official People API (OAuth2, incremental syncToken) or CardDAV; no ToS risk. The hard parts are local: (1) identity — entries have no UID, so two-way needs a GOOGLE_ID property per entry plus a one-time fuzzy reconciliation of the two populated datasets (name/email/phone matching); (2) field mapping — space-separated multi-email in one property, free-text body notes, inconsistent phone formats (normalization decision); (3) conflict policy. First decision gates the rest: one-way Google→org read model (simple) vs true two-way. Candidate architectures: vdirsyncer (proven two-way engine w/ Google support; build only the vCard↔org translation, evaluate org-vcard fidelity) vs a direct People API script with sync state in org properties. Output: recommendation doc in docs/design/ naming direction + the normalization/conflict decisions for Craig. Not :solo: — the one-way-vs-two-way call and normalization policy are Craig's. + +** TODO [#C] Google Voice in Emacs — SMS + dialer investigation :feature:research:solo: +From the 2026-06-11 messenger-unification brainstorm. Google Voice has no official API; the viable routes ride the Matrix bridge ecosystem's reverse engineering (mautrix-gvoice). Research pass to establish the 2026 state of play: (1) is mautrix-gvoice healthy and what does its auth flow look like now; (2) any better-maintained alternative (CLI/daemon) for the signel-pattern architecture (external daemon + JSON-RPC + thin Emacs chat client); (3) does call initiation (ring-linked-phone-then-connect, Emacs as dialer) survive in the current protocol — two-way audio in Emacs is out of scope (WebRTC); (4) ToS/account-flag risk assessment for Craig's account. Output: a recommendation doc in docs/design/ naming the architecture (signel-pattern daemon vs Matrix bridge + ement.el) or a no-go with reasons. If go, GV becomes a registered backend under the messenger-unification convention (see the [#B] task below). + +** TODO [#C] latexmk workflow never activates (two breaks) :bug:solo: +=modules/latex-config.el:66= — =:hook (TeX-mode-hook . ...)= gets use-package's =-hook= suffix appended (unbound symbol not ending in =-mode=), registering on nonexistent =TeX-mode-hook-hook=, so =TeX-command-default "latexmk"= is never set. Independently =:80= auctex-latexmk is =:defer t= with no trigger, so =auctex-latexmk-setup= never runs and "latexmk" isn't in TeX-command-list. Fix hook name to =TeX-mode=; change auctex-latexmk to =:after tex=. From the 2026-06 config audit. + +** TODO Manual testing and validation :verify:theme-studio: +Exercised once the phases above land. +*** 2026-06-11 Thu @ 18:29:39 -0500 Verified UI-face preview and contrast survive a ground bg change +Craig walked the repro: mode-line with its own fg/bg kept its preview bg and ratio through a ground change; ground-dependent rows re-rated; package-faces contrast column updated. Pass. Closed the [#A] contrast-cell and [#B] preview-bg parents. +*** 2026-06-11 Thu @ 18:29:39 -0500 Verified seeded package-face defaults, with steel tuning +Craig read org/magit/elfeed against the ground. Pass with tuning: steel reads a bit dark — flipped to steel+1 on magit (better), but org wanted darker; these are updated selections, NOT final — he expects to adjust many more before the theme ships. His export saved to scripts/theme-studio/theme.json (replaced the 2026-06-09 state, prior version in git at 4f2d00eb). Side find: the org preview's heading-three ↔ headline-todo flash linkage is cross-wired — filed as its own bug task. +*** 2026-06-11 Thu @ 18:29:39 -0500 Verified large face tables stay usable +Craig scrolled the org table, filtered on "agenda", reassigned a face — grouping, narrowing, and live preview update all behaved. Pass. +*** 2026-06-11 Thu @ 18:29:39 -0500 Verified perceptual readouts in the picker +Craig validated the readouts against computed reference values (default fg #f0fef0 on ground #000000: APCA Lc -104.7 / WCAG 20.14; keyword blue #67809c: Lc -33.7 / WCAG 5.14 — negative polarity correct for light-on-dark). Legible, uncrowded. Pass. Side find filed separately: the picker panel itself blends into the page background ([#C] picker-visibility task). +*** 2026-06-11 Thu @ 18:29:39 -0500 Verified ΔE warnings read clearly +Craig built a near-duplicate pair and a well-spread palette: the close pair was named with its ΔE, sorted closest-first with the cap behaving; no warning on the spread palette. Pass. +*** TODO OKLCH editor feels right +What we're verifying: the OKLCH sliders / C×L plane edit cleanly and clamping is visible. +- Switch the picker to OKLCH mode and drag L, then C, then H +- Push chroma past the sRGB gamut, then toggle the AA/AAA mask +Expected: each axis moves independently; the C×L plane (once 4b lands) opens on the current color; "chroma clamped to sRGB" shows on clamp; toggling the mask does not reset OKLCH mode. +*** TODO Generated ramp harmonizes +What we're verifying: a ramp generated from a base color reads as one family, not a grab-bag (the aesthetic the math is meant to produce). +- Open =scripts/theme-studio/theme-studio.html= in Chrome +- Pick a mid-lightness base swatch (e.g. a blue) and generate its ramp at the defaults +- Read the row of steps left to right, then try a near-black and a near-white base +Expected: the steps share an obvious hue and step evenly in lightness; the chroma-ease keeps the extreme steps from going muddy or garish; nothing looks like it belongs to a different color. +*** TODO Safe-lightness guidance reads clearly +What we're verifying: the L_max marker and unsafe-band shade are legible and land in the right place when editing a covered face. +- Open the picker in OKLCH mode on region (or hl-line), with syntax colors assigned +- Read the L_max marker and the shaded unsafe band on the lightness slider +- Drag lightness up toward and past the marker +Expected: the marker is visible and correctly placed, the band above it reads as "unsafe," and crossing it is obvious; an out-of-scope face shows no marker. +*** TODO Safe tint actually reads in real Emacs +What we're verifying: a background tint the tool calls safe really keeps every token readable behind real syntax-colored text — the whole point of the worst-case floor. +- In the tool, set a covered face (e.g. region) to a tint at or just below its L_max with the worst-case readout showing PASS +- Build the theme and load it in Emacs, open a code buffer with varied syntax, and select a region spanning many token colors +- Read every token through the region highlight, paying attention to the limiting foreground the tool named +Expected: every token stays readable over the tint, including the limiting one; a tint pushed just past L_max (readout FAIL) shows a visibly strained or unreadable token, confirming the floor matches reality. +*** TODO Color families group the way the eye reads them +What we're verifying: the OKLCH hue clustering (25° gap) splits and merges families the way you'd expect, and renaming never moves a color. +- Open =scripts/theme-studio/theme-studio.html= in Chrome and load a real theme (e.g. sterling) +- Read the strips top to bottom: are "the blues" one strip, "the greens" another, neutrals and ground pinned at the top +- Find a pair you'd consider one family that landed in two strips (or two you'd consider separate that merged) +- Rename any swatch to something absurd and confirm it stays in the same strip +Expected: families match your mental grouping; the few that don't are the cue to revisit the 25° gap; renaming never regroups. +*** TODO Regenerate-replace reads as deliberate +What we're verifying: the count control clearly signals it rewrites the whole family, so replacing hand-added same-hue colors isn't a surprise. +- Add two unrelated colors at a similar hue so they share a strip +- Set that strip's count to 2 +- Watch what happens to the two colors +Expected: the strip becomes a clean base±2 ramp, the two loose colors are gone, and the control made it obvious that's what it would do before you committed. +*** TODO Removed-step references read clearly as "(gone)" +What we're verifying: lowering a family's count leaves a referencing face visibly stale, not silently re-pointed. +- Assign a UI or syntax element to an outer step of a family (e.g. region = a blue+3) +- Lower that family's count to 2 so blue+3 disappears +- Read the assignment's dropdown +Expected: the dropdown shows "(gone)" for the removed step, never a silent jump to a different color; re-pointing it is a deliberate choice. +** TODO [#D] theme-studio per-tier reseed controls :feature:theme-studio: +Deferred from the seeding-engine spec (vNext). V1 reseeds all three guide-owned tiers at once; later consider separate "reseed syntax", "reseed UI", and "reseed package/org" controls if all-at-once proves too blunt. Spec: [[file:docs/design/theme-studio-seeding-engine-spec.org][spec]] (vNext; review folded in 2026-06-08). +** TODO [#D] theme-studio low-contrast preset/mask mode :feature:theme-studio: +Deferred from the perceptual color metrics spec (vNext). After raw OKLCH/APCA/DeltaE readouts exist, decide whether to add a named low-contrast workflow: APCA Lc bands, a contrast ceiling/floor mask, or a "soft" sibling to the existing any/AA+/AAA picker mask. Spec: [[file:docs/design/theme-studio-perceptual-color-metrics-spec.org][spec]] (vNext candidates; review folded in 2026-06-08). +** TODO [#D] theme-studio CIEDE2000 DeltaE option :feature:theme-studio: +Deferred from the perceptual color metrics spec (vNext). v1 uses DeltaE-OK on its native scale with a 0.02 threshold (decided); revisit CIEDE2000 only if the native OKLab scale proves too unfamiliar or poorly calibrated for palette distinguishability. Spec: [[file:docs/design/theme-studio-perceptual-color-metrics-spec.org][spec]] (vNext candidates; review folded in 2026-06-08). +** TODO [#D] Treesitter grammar offline cache :feature:offline:localrepo: +Treesitter grammars are downloaded by =treesit-auto= on first use and live outside the localrepo. For true offline reproducibility, cache the grammars next to the localrepo (a =.localrepo/treesitter/= tier, or a separate mirror script). Cross-linked from =docs/design/localrepo.org=. + +** TODO [#D] Native-comp .eln cache strategy :feature:offline:localrepo: +The native-comp =.eln= cache is Emacs-version-specific; an Emacs upgrade invalidates everything. Document the cache location, what an upgrade triggers, and whether a warm-the-cache script is worth shipping. Cross-linked from =docs/design/localrepo.org=. + +** TODO [#D] System-tool dependency install script :feature:offline:localrepo: +=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, and other binaries that =cj/executable-find-or-warn= flags at module load are not in =package.el='s reach. Document the required-tool set and ship a setup script (or =pacman=/=apt= invocation set). Cross-linked from =docs/design/localrepo.org=. + +** TODO [#D] Localrepo refresh / update script :feature:offline:localrepo: +No dedicated update path today — refreshing a pinned package means ad-hoc =cp= from the local elpa mirrors. Document the current shape and decide whether a =scripts/refresh-localrepo.sh= is worth writing. Cross-linked from =docs/design/localrepo.org=. + +** TODO [#D] Dashboard over-scroll: pin last line to window bottom :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-05-22 +:END: +Triggered by: 2026-05-20 Dashboard buffer too long follow-up. + +After the opens-at-top fix (=4ac1b81=), the dashboard can still be +scrolled past its content: the banner image makes the buffer just over +one screenful, so the wheel / =C-v= / =M->= pull the last line up and +leave empty space below it. Craig wants scrolling to stop once the +trailing line reaches the window bottom (no void) while still allowing +scroll-down to reach content below the window. + +Findings from the 2026-05-20 investigation: +- =pixel-scroll-precision-mode= is off, so this is standard line-based + scroll overshoot (the tall banner image inflates the rendered height). +- A =window-start= clamp does not work: =window-start= only lands on + line boundaries, so it can't express a position partway into the + banner image — it either blocks all scrolling or leaves the void. +- A =recenter -1= pin on =post-command-hook= does not work: it fires on + every command, so it fights item navigation (the cursor can't reach + the projects / bookmarks / recents). +- Right design: clamp only on actual scroll commands — advise + =mwheel-scroll= / =scroll-up-command= / =scroll-down-command= / + =end-of-buffer= to =recenter -1= when over-scrolled, never on + navigation commands. +- Live experiment scratch file: =~/dashboard-overscroll-experiment.el=. + +** TODO [#D] Polish reveal.js presentation setup :feature: + +Three small reveal.js improvements; collected into one task because each on its own is too small to track separately. + +1. *Image insertion helper.* Function to insert images with proper org-reveal attributes (sizing, background images, etc.) without having to remember the syntax. +2. *Default font sizing for slide elements.* Configure reveal.js font sizes for headings, body text, code blocks, etc. — better defaults via =org-reveal-head-preamble= CSS or a custom theme. +3. *Custom dupre reveal.js theme.* CSS theme using the colors from =themes/dupre-palette.el=. Install into =reveal.js/css/theme/= for use with =#+REVEAL_THEME: dupre=. + +** TODO "? = curated help menu" convention across modes :feature:ux:discoverability: +From the calibredb keybindings work 2026-06-06. The pattern that worked: in a modal/major-mode buffer (calibredb), bind =?= to a curated transient of the frequent workflows, and move the package's own full dispatch to =H=. It fixes the "I can't discover the keys" problem that which-key can't help with (which-key only pops up after a prefix, not for top-level single keys in a mode-map). + +Task: survey the modes/modules Craig works in and identify where a =?= -> curated-help-menu (transient) makes sense. Candidates: any major-mode buffer with single-key bindings and no good discovery affordance -- calibredb (done), nov, dirvish, mu4e, ghostel/term, signel, pearl/linear, ELFeed, etc. For each, note whether =?= is free or already a help dispatch, and whether a curated menu (vs the package's own) adds value. Establish it as a convention (and maybe a small helper/macro to define a curated =?= menu consistently). + +** TODO the preview splits an already split window into 3 temporarily. +looks strange. potentially problematic for ai-terms. + +** DOING Project-aware bug capture via C-c c t :feature:capture: +Relocated from the global capture inbox 2026-06-06. When inside a projectile project, C-c c t (Task) files into that project's root todo.org under the "<Project> Open Work" header. If the project has no todo.org, fall back to the global inbox-file and warn naming the project. + +Implemented 2026-06-06 in =modules/org-capture-config.el=: a shared project-aware =function= capture target (=cj/--org-capture-project-location=) used by =C-c c t= (Task, =* TODO=) and a new =C-c c b= (Bug, =* TODO [#C]=). Matches an existing top-level "... Open Work" heading (so ~/.emacs.d hits "Emacs Open Work") and creates "<Capitalized project> Open Work" only when absent. Outside a project / no todo.org -> global inbox under "Inbox" (with a warning in the no-todo.org case). 15 ERT tests in =tests/test-org-capture-config-project-target.el=; daemon e2e confirmed a real capture lands "** TODO [#C] ..." prepended under Open Work. Awaiting Craig's interactive manual verify (see the Manual Testing task) before close. NOTE: the matching "<Project> Resolved Work" header for the wrap-up workflow is a separate concern, not handled here. + +** VERIFY Palette-columns spec review :theme-studio: +SCHEDULED: <2026-06-12 Fri> +Read [[file:docs/theme-studio-palette-columns-spec.org][docs/theme-studio-palette-columns-spec.org]] (Draft, from the 2026-06-10 design discussion) and bless or amend. Decisions 9 and 10 are the two session calls awaiting your word: strips flip to lightest→darkest top→bottom to match the dropdown, and each dropdown column run places the base at its natural lightness position (vs bg/fg bases leading before any steps). On "spec's good": mark Ready, file the phase breakdown, cancel the [#C] hint-override task, start Phase 1. * Emacs Resolved ** DONE [#B] Fix likely =elpa-mirror-location= path bug :bug:quick: -- cgit v1.2.3