diff options
Diffstat (limited to 'CLAUDE.md')
| -rw-r--r-- | CLAUDE.md | 10 |
1 files changed, 10 insertions, 0 deletions
@@ -85,3 +85,13 @@ Prefer Write over cumulative Edits for nontrivial new code. Small functions (und - **Warn at module load when an external tool path is configured but missing.** Calling `cj/executable-find-or-warn` (from `system-lib.el`) at `:config` time emits a `display-warning` if `prettier` / `pyright` / `pandoc` / etc. isn't on PATH, instead of letting the first format-on-save or LSP-attach fail with a confusing mid-edit error. Pattern in use: `modules/prog-webdev.el` (prettier), `modules/prog-python.el` (pyright). (`pattern` — 2026-05-16) - **ghostel F-key / prefix bindings need `ghostel-keymap-exceptions` + a rebuild, not just `ghostel-mode-map`.** In semi-char mode ghostel forwards every key not in `ghostel-keymap-exceptions` to the pty, and `ghostel-semi-char-mode-map` (rebuilt from that list, and outranking the major-mode map) wins. So binding F9 / F12 / C-; in `ghostel-mode-map` alone is silently dead inside agent/terminal buffers — the key reaches the shell, not Emacs. Fix: add the key to `ghostel-keymap-exceptions` AND call `ghostel--rebuild-semi-char-keymap` (`add-to-list` updates the list but not the already-built map). `term-config.el` (C-;, F12) and `ai-term.el` (F9 family) do this in their `with-eval-after-load 'ghostel`. This is the opposite of vterm, where binding in `vterm-mode-map` sufficed. (`gotcha` — 2026-06-05) + +- **Rulesets-owned changes propagate by edit-local + send-copy + explanatory note.** A bug or enhancement that belongs to a rulesets-owned synced file (a workflow under `.ai/workflows/`, a skill, a rule under `.claude/rules/`, a script under `.ai/scripts/`) is handled by editing the local copy so it's usable now, then sending rulesets a copy of the edited file plus an explanatory note — a local edit alone is overwritten on the next template sync, so the canonical update is what makes it durable. The note covers: how the problem was hit, what outcomes the change should alter, any implementation recommendations, and any follow-up instructions (e.g. send a note back with more info). Send notes with the inbox-send script (`inbox-send rulesets --file <path>`). Offer the change proactively when it would help. (`pattern` — 2026-06-12) + +- **Manual-verification handoff: VERIFY child, close the originating task.** When a task's code is complete and the only thing left is Craig's hands-on check, don't leave the whole task stuck in DOING. File the manual check as a `VERIFY` child under the "Manual testing and validation" parent task, then close the originating task itself (DONE for a top-level task, or the dated-log rewrite for a sub-task, per `todo-format.md`). The VERIFY child carries the residual human check and surfaces in the agenda until Craig confirms; the implementation task is no longer held open by it. Replaces the prior habit of leaving the fixed task DOING with a `*** TODO` manual-test note under the parent. (`pattern` — 2026-06-13) + +- **`make test` runs with no `package-initialize` — defuns inside a `use-package :config` are void there.** The Makefile's `EMACS_TEST` is `emacs --batch --no-site-file --no-site-lisp` with no `package-initialize`, so elpa packages never load and a `use-package` block whose package isn't found never runs its `:config`. Any `defun` nested inside that `:config` is unbound under `make test` / `make test-file`. The per-edit PostToolUse hook *does* initialize packages, so such defuns load there — a test can pass on save under the hook yet fail `make test`. To unit-test logic that lives in a `:config` block, extract it into a top-level defun outside `use-package` (the `cj/dwim-shell--empty-dirs-command` / `cj/dwim-shell--dated-backup-command` pattern) and test that; keybindings or mode-wiring that must stay in `:config` get live-daemon verification instead. (`gotcha` — 2026-06-13) + +- **Mocking a C primitive (subr) in a test is fragile under native-comp; if you must, make the mock variadic — `(lambda (&rest _) ...)`.** When a test redefines a primitive (`cl-letf`/`fset`/`setf`/`advice-add`), native-comp routes natively-compiled callers through a per-primitive trampoline `.eln`, and that interaction fails three different ways depending on eln-cache state: (1) the trampoline `.eln` fails to build/load under `--batch` (`native-lisp-load-failed ... subr--trampoline-*.eln`); (2) when no trampoline is available the redefinition is *silently ignored* and native callers run the real primitive (a quiet false pass); (3) the trampoline calls the mock with the primitive's *maximum* arity, so a fixed-arity mock narrower than the primitive throws `wrong-number-of-arguments`. Mode 3 is the common one — a `(lambda (_) 200)` mock of `window-body-width` (a 0-2-arg subr) gets called with 2 args. Note many routinely-mocked functions are subrs (`message`, `completing-read`, `y-or-n-p`, `executable-find`, `save-buffer`, `byte-compile-file`), and those are fine *because* they're mocked variadically; the trap is the narrow fixed-arity ones. The rule, enforced by `tests/test-meta-subr-mock-arity.el` (fails `make test` on any arity-narrow subr mock): a subr mock must accept the primitive's max arity, so append `&rest _` (keep named args the body uses: `(lambda (cmd &rest _) ...)`). The durable fix the ecosystem and our own `elisp-testing.md` point to is *don't mock the primitive*: drive real state (a `make-temp-file` fixture, `insert`/`set-buffer-modified-p`) or extract a pure helper and test that. Full mechanism, the three modes, research, and decision: [[file:docs/native-comp-subr-mocking.org][docs/native-comp-subr-mocking.org]]. (`gotcha` — refined 2026-06-21 after re-enabling native-comp surfaced 170 latent arity-narrow mocks) + +- **`let`-binding another package's dynamic var in a `lexical-binding` file needs that var declared special at compile time, or the compiled code binds it lexically and silently no-ops.** `coverage-core.el` let-bound `json-object-type` / `json-array-type` / `json-key-type` around `json-read-file` to get string-keyed hash tables, with `(require 'json)` *inside* the function. Interpreted, that worked: the runtime require ran first, made the vars special, so the `let` bound them dynamically. Byte/native-compiled, the compiler had never seen json.el's `defvar`s (the require is a runtime form), so under `lexical-binding: t` it compiled them as *lexical* locals that never reach `json-read-file` — which then returned json.el's default symbol-keyed alist, and the parser's `maphash` over it signaled `wrong-type-argument hash-table-p`. The tell: passes interpreted / in the daemon, fails under `make test` (which loads the `.elc`). Same class as the existing "make test has no package-initialize" and native-comp gotchas — the compiled path diverges from the interpreted one. Fix: make the defvars visible to the compiler with `(eval-when-compile (require 'json))` at top level (or a bare `(defvar json-object-type)` for each), keeping the runtime `(require 'json)` so json stays off the load-time path. General rule: never `let`/`setq` a foreign special var in a lexical file without a compile-time `defvar`/`require` for it. (`gotcha` — 2026-06-24) |