feat(dev-fkeys): add project-aware F4 compile/run dispatcher

I added a new module `modules/dev-fkeys.el` that owns the dev F-key block. F4 prompts via `completing-read` with a candidate set filtered by project type (compiled / interpreted / unknown). C-F4 is the compile-only fast path. M-F4 is clean + rebuild. It runs a heuristic clean command derived from the project markers (go.mod, Cargo.toml, Eask, Makefile, CMakeLists.txt) and chains `projectile-compile-project` on success. S-F4 stays on `recompile` and now lives globally instead of duplicated across prog-general.el and prog-c.el. F6 is bound globally to `projectile-test-project` as a Phase 1 stopgap. Phase 2 replaces it with the polyglot test runner spec'd in todo.org.

Project-type detection runs against the projectile root and falls back to `unknown` when no marker matches. Interpreted markers are checked first so a Python or Node project with a Makefile for tasks classifies as interpreted instead of compiled. Compile + Run sequencing uses a one-shot `compilation-finish-functions` hook that self-removes on first invocation and only fires the follow-up when the status string starts with `finished`.

Cleanup in the same commit:
- Dropped F4/F5/F6 from `prog-general.el`'s prog-mode-hook. They are now global.
- Dropped F6→format bindings from prog-c.el / prog-python.el / prog-shell.el. C-; f was already bound in each, so this is pure removal.
- Dropped the duplicate S-F4 from prog-c.el. The global binding covers it.
- Updated the keybinding header in prog-general.el and the workflow comments in prog-c.el / prog-shell.el.
- Wired `(require 'dev-fkeys)` in init.el alongside coverage-core.

TDD: 73 tests across 11 files, one per helper. Production code is split into small testable internals (`cj/--detect-project-type`, `cj/--f4-candidates`, `cj/--f4-derive-clean-cmd`, `cj/--f4-make-once-hook`, `cj/--f4-dispatch`, `cj/--f4-compile-and-run-impl`, `cj/--f4-clean-rebuild-impl`, `cj/--f4-project-root`) plus three thin interactive wrappers. Smoke tests confirm bindings register on load.

Known limitation: if another `compilation-finish-functions` hook fires between my add-hook and the compile finishing, the chain can fire on the wrong compile. The hook self-removes on first invocation regardless of which compile it sees. Documented in the impl docstring. Acceptable for v1.

Phase 2 will replace F6 with the polyglot test runner (tree-sitter queries for Python/Go/TS, sexp scan for Elisp, buffer-local last-test memory).

5 files changed, 236 insertions, 43 deletions

diff --git a/modules/dev-fkeys.el b/modules/dev-fkeys.el
new file mode 100644
index 00000000..d2c70131
--- /dev/null
+++ b/modules/dev-fkeys.el
@@ -0,0 +1,208 @@
+;;; dev-fkeys.el --- Developer F-key dispatchers -*- lexical-binding: t -*-
+
+;;; Commentary:
+;; Project-aware F-key block for developer workflows:
+;;
+;;   F4    completing-read of compile/run candidates filtered by project type
+;;   C-F4  fast path: compile only (no-op on interpreted projects)
+;;   M-F4  fast path: clean + rebuild (no-op on interpreted projects)
+;;   S-F4  recompile (built-in)
+;;   F6    project tests (Phase 1 stopgap; Phase 2 will replace with the
+;;         polyglot test runner spec'd in todo.org)
+;;
+;; Project-type detection runs against the projectile root and falls back to
+;; 'unknown when no marker matches. Interpreted markers are checked before
+;; compiled markers, so a Python or Node project that also has a Makefile
+;; for tasks classifies as interpreted.
+;;
+;; F7 (coverage) is wired in coverage-core.el. F5 is reserved for the debug
+;; ticket and intentionally left unbound here.
+
+;;; Code:
+
+(require 'cl-lib)
+
+(declare-function projectile-compile-project "projectile" (arg))
+(declare-function projectile-run-project "projectile" (arg))
+(declare-function projectile-project-root "projectile" (&optional dir))
+(declare-function projectile-test-project "projectile" (arg))
+(declare-function recompile "compile" (&optional edit-command))
+
+;; ---------- Project root ----------
+
+(defun cj/--f4-project-root ()
+  "Return projectile project root, or nil. Never errors.
+Some projectile configurations signal an error when called outside a
+known project; this wrapper degrades to nil so the F4 dispatcher routes
+to the \\='unknown branch instead of crashing."
+  (when (fboundp 'projectile-project-root)
+    (condition-case nil
+        (projectile-project-root)
+      (error nil))))
+
+;; ---------- Project-type detection ----------
+
+(defconst cj/--f4-interpreted-markers
+  '("pyproject.toml" "requirements.txt" "Pipfile" "package.json")
+  "Markers that classify a project as interpreted (Run-only menu).")
+
+(defconst cj/--f4-compiled-markers
+  '("go.mod" "Cargo.toml" "CMakeLists.txt" "Makefile" "Eask")
+  "Markers that classify a project as compiled (full Compile/Run/Clean menu).")
+
+(defun cj/--f4-any-marker-p (root markers)
+  "Return non-nil if any of MARKERS exists at ROOT."
+  (cl-some (lambda (m) (file-exists-p (expand-file-name m root))) markers))
+
+(defun cj/--detect-project-type (root)
+  "Classify project at ROOT as \\='compiled, \\='interpreted, or \\='unknown.
+Interpreted markers are checked before compiled markers, so a Python or
+Node project that also has a Makefile for tasks classifies as interpreted.
+Returns \\='unknown when ROOT is nil or no marker matches."
+  (cond
+   ((not root) 'unknown)
+   ((cj/--f4-any-marker-p root cj/--f4-interpreted-markers) 'interpreted)
+   ((cj/--f4-any-marker-p root cj/--f4-compiled-markers) 'compiled)
+   (t 'unknown)))
+
+;; ---------- Clean command derivation ----------
+
+(defun cj/--f4-derive-clean-cmd (root)
+  "Pick a clean shell command for the project at ROOT, or nil.
+First marker matched wins. ROOT may be nil; nil and a path with no
+recognized markers both return nil."
+  (when root
+    (cond
+     ((file-exists-p (expand-file-name "go.mod" root))         "go clean ./...")
+     ((file-exists-p (expand-file-name "Cargo.toml" root))     "cargo clean")
+     ((file-exists-p (expand-file-name "Eask" root))           "eask clean")
+     ((file-exists-p (expand-file-name "Makefile" root))       "make clean")
+     ((file-exists-p (expand-file-name "CMakeLists.txt" root)) "cmake --build build --target clean"))))
+
+;; ---------- Action handlers ----------
+
+(defun cj/--f4-compile-and-run-impl ()
+  "Run `projectile-compile-project', then `projectile-run-project' on success.
+Installs a one-shot `compilation-finish-functions' hook to chain the run."
+  (add-hook 'compilation-finish-functions
+            (cj/--f4-make-once-hook
+             (lambda () (projectile-run-project nil))))
+  (projectile-compile-project nil))
+
+(defun cj/--f4-dispatch (action)
+  "Route ACTION (a symbol from `cj/--f4-candidates') to its handler.
+Signals `user-error' on an unrecognized symbol or nil."
+  (pcase action
+    ('compile-only    (projectile-compile-project nil))
+    ('run-only        (projectile-run-project nil))
+    ('compile-and-run (cj/--f4-compile-and-run-impl))
+    ('clean-rebuild   (cj/--f4-clean-rebuild-impl (cj/--f4-project-root)))
+    ('compile-plain   (call-interactively #'compile))
+    (_ (user-error "Unknown F4 action: %s" action))))
+
+(defun cj/--f4-clean-rebuild-impl (root)
+  "Run the heuristic clean for project at ROOT, then rebuild on success.
+Signals `user-error' when no clean command can be derived. The rebuild
+side reuses `projectile-compile-project' so the per-project compile
+command (prompted-and-cached by projectile) drives the build."
+  (let ((clean-cmd (cj/--f4-derive-clean-cmd root)))
+    (unless clean-cmd
+      (user-error "Clean + Rebuild: no clean command for this project type"))
+    (add-hook 'compilation-finish-functions
+              (cj/--f4-make-once-hook
+               (lambda () (projectile-compile-project nil))))
+    (let ((default-directory root))
+      (compile clean-cmd))))
+
+;; ---------- One-shot compilation-finish hook ----------
+
+(defun cj/--f4-make-once-hook (then-fn)
+  "Build a one-shot `compilation-finish-functions' hook that chains THEN-FN.
+The returned lambda removes itself from `compilation-finish-functions' on
+first invocation regardless of status, then calls THEN-FN only if the
+status string starts with \"finished\" (the convention used by compile.el
+for a successful compile)."
+  (let (hook)
+    (setq hook
+          (lambda (_buf status)
+            (remove-hook 'compilation-finish-functions hook)
+            (when (and (stringp status)
+                       (string-prefix-p "finished" status))
+              (funcall then-fn))))
+    hook))
+
+;; ---------- Candidate menus ----------
+
+(defun cj/--f4-candidates (project-type)
+  "Return alist of (LABEL . ACTION) for the F4 menu given PROJECT-TYPE.
+The first entry is the default, selected on RET in completing-read.
+Compiled projects get the full menu, interpreted projects get Run only,
+anything else (including nil and unrecognized symbols) falls through to
+a single Compile entry that calls plain `compile'."
+  (pcase project-type
+    ('compiled    '(("Compile + Run"   . compile-and-run)
+                    ("Compile"         . compile-only)
+                    ("Run"             . run-only)
+                    ("Clean + Rebuild" . clean-rebuild)))
+    ('interpreted '(("Run"             . run-only)))
+    (_            '(("Compile"         . compile-plain)))))
+
+;; ---------- Interactive wrappers ----------
+
+(defun cj/f4-compile-and-run ()
+  "Project-aware F4 dispatcher.
+Prompts via `completing-read' with a candidate set filtered by project
+type (compiled / interpreted / unknown), then dispatches the chosen
+label's action."
+  (interactive)
+  (let* ((root (cj/--f4-project-root))
+         (project-type (cj/--detect-project-type root))
+         (candidates (cj/--f4-candidates project-type))
+         (default (caar candidates))
+         (label (completing-read
+                 (format "F4 (%s): " project-type)
+                 (mapcar #'car candidates) nil t nil nil default))
+         (action (cdr (assoc label candidates))))
+    (cj/--f4-dispatch action)))
+
+(defun cj/f4-compile-only ()
+  "C-F4 fast path: compile only.
+Compiled projects run `projectile-compile-project'. Interpreted projects
+get a no-op message. Outside any project, falls back to interactive
+`compile'."
+  (interactive)
+  (let* ((root (cj/--f4-project-root))
+         (project-type (cj/--detect-project-type root)))
+    (pcase project-type
+      ('compiled    (projectile-compile-project nil))
+      ('interpreted (message "C-F4: not a compiled language"))
+      (_            (call-interactively #'compile)))))
+
+(defun cj/f4-clean-rebuild ()
+  "M-F4 fast path: clean + rebuild.
+Compiled projects run the heuristic clean + projectile-compile-project
+chain. Interpreted projects and unrecognized projects get a no-op
+message."
+  (interactive)
+  (let* ((root (cj/--f4-project-root))
+         (project-type (cj/--detect-project-type root)))
+    (pcase project-type
+      ('compiled    (cj/--f4-clean-rebuild-impl root))
+      ('interpreted (message "M-F4: not a compiled language"))
+      (_            (message "M-F4: no project detected")))))
+
+;; ---------- Bindings ----------
+
+(keymap-global-set "<f4>"   #'cj/f4-compile-and-run)
+(keymap-global-set "C-<f4>" #'cj/f4-compile-only)
+(keymap-global-set "M-<f4>" #'cj/f4-clean-rebuild)
+(keymap-global-set "S-<f4>" #'recompile)
+;; Phase 1 stopgap. Phase 2 replaces this with the polyglot test runner
+;; spec'd in todo.org. Without a global F6 binding here, the per-language
+;; F6→format bindings in prog-c/python/shell would have nothing to fall
+;; back on after this commit drops them, leaving F6 on its useless Emacs
+;; default (`2C-command').
+(keymap-global-set "<f6>" #'projectile-test-project)
+
+(provide 'dev-fkeys)
+;;; dev-fkeys.el ends here.
diff --git a/modules/prog-c.el b/modules/prog-c.el
index d9191bf4..df32b76a 100644
--- a/modules/prog-c.el
+++ b/modules/prog-c.el
@@ -16,12 +16,12 @@
 ;;
 ;; Workflow Example:
 ;;   1. Open a .c file → LSP auto-starts, provides completions
-;;   2. S-<f2> → Compile (auto-detects Makefile/CMake/single file)
-;;   3. <f5> → Quick recompile
-;;   4. S-<f3> → Start GDB with multi-window layout
-;;   5. <f6> or C-c f → Format code with clang-format
-;;   6. M-. → Jump to function definition
-;;   7. C-c l → Access LSP commands (rename, find references, etc.)
+;;   2. F4 → compile + run dispatcher (dev-fkeys.el)
+;;   3. S-F4 → recompile (repeat last)
+;;   4. S-F6 → start GDB
+;;   5. C-; f → format code with clang-format
+;;   6. M-. → jump to function definition
+;;   7. C-c l → LSP commands (rename, find references, etc.)
 
 ;;; Code:
 
@@ -95,7 +95,6 @@
 (use-package clang-format
   :if (executable-find clang-format-path)
   :bind (:map c-mode-base-map
-              ("<f6>" . clang-format-buffer)
               ("C-; f" . clang-format-buffer)))
 
 ;; -------------------------------- Compilation --------------------------------
@@ -135,11 +134,8 @@
 ;; -------------------------------- Keybindings --------------------------------
 
 (defun cj/c-mode-keybindings ()
-  "Set up keybindings for C programming.
-Overrides default prog-mode keybindings with C-specific commands."
-  ;; S-f4: Recompile (override default - C uses this more than projectile-compile)
-  (local-set-key (kbd "S-<f4>") #'recompile)
-
+  "Set up C-specific S-modifier overrides on the dev F-keys.
+S-F4 (recompile) is global, owned by dev-fkeys.el — not duplicated here."
   ;; S-f5: Static analysis placeholder (could add clang-tidy, cppcheck, etc.)
   (local-set-key (kbd "S-<f5>") #'cj/disabled)
 
diff --git a/modules/prog-general.el b/modules/prog-general.el
index 0ae6aa82..46599cc9 100644
--- a/modules/prog-general.el
+++ b/modules/prog-general.el
@@ -8,28 +8,22 @@
 ;;
 ;; Keybinding Scheme:
 ;; ------------------
-;; Unified keybindings across all programming languages using Projectile
-;; for project-aware operations with language-specific overrides.
+;; The F4–F7 dev block is owned by dev-fkeys.el (global bindings). Per-
+;; language modules only set S-F5 / S-F6 overrides for static analysis
+;; and debugging. F5 is reserved for the debug ticket.
 ;;
-;; Global Keybindings (all prog-mode buffers):
-;;   F4     - projectile-compile-project (smart compilation)
-;;   S-F4   - recompile (repeat last compile)
-;;   F5     - projectile-test-project (run tests)
-;;   S-F5   - Language-specific static analysis
-;;   F6     - projectile-run-project (run/execute)
-;;   S-F6   - Language-specific debugger
-;;   C-; f  - Language-specific formatter
+;; Global (dev-fkeys.el):
+;;   F4 / C-F4 / M-F4   compile + run dispatcher / compile only / clean + rebuild
+;;   S-F4               recompile (repeat last)
+;;   F6                 project tests (Phase 1 stopgap; Phase 2 = polyglot dispatcher)
+;;   F7                 coverage report (coverage-core.el)
+;;   C-; f              language-specific formatter
 ;;
-;; Quick Reference Table:
-;; | Key   | Global   | C             | Go          | Python      | Shell       |
-;; |-------|----------|---------------|-------------|-------------|-------------|
-;; | F4    | compile  | compile       | compile     | compile     | compile     |
-;; | S-F4  | recompile| recompile     | (projectile)| (projectile)| (projectile)|
-;; | F5    | test     | test          | test        | test        | test        |
-;; | S-F5  | (none)   | disabled      | staticcheck | mypy        | shellcheck  |
-;; | F6    | run      | run           | run         | run         | run         |
-;; | S-F6  | (none)   | gdb           | dlv         | pdb         | disabled    |
-;; | C-; f | format   | clang-format  | gofmt       | blacken     | shfmt       |
+;; Per-language S-modifier overrides:
+;; | Key  | C        | Go          | Python | Shell      |
+;; |------|----------|-------------|--------|------------|
+;; | S-F5 | disabled | staticcheck | mypy   | shellcheck |
+;; | S-F6 | gdb      | dlv         | pdb    | disabled   |
 
 ;;; Code:
 
@@ -79,11 +73,9 @@
   (auto-fill-mode)                              ;; auto wrap at the fill column set
   (local-set-key (kbd "M-;") 'comment-dwim)     ;; comment/uncomment region as appropriate
 
-  ;; Project-wide commands (can be overridden by language-specific modes)
-  (local-set-key (kbd "<f4>") 'projectile-compile-project)   ;; compile project
-  (local-set-key (kbd "S-<f4>") 'recompile)                  ;; recompile (repeat last)
-  (local-set-key (kbd "<f5>") 'projectile-test-project)      ;; run tests
-  (local-set-key (kbd "<f6>") 'projectile-run-project))      ;; run project
+  ;; F4–F6 are global, owned by dev-fkeys.el. F5 is reserved for the
+  ;; debug ticket (separate work).
+  )
 
 (add-hook 'prog-mode-hook #'cj/general-prog-settings)
 (add-hook 'html-mode-hook #'cj/general-prog-settings)
diff --git a/modules/prog-python.el b/modules/prog-python.el
index 3b85bafd..a26b9760 100644
--- a/modules/prog-python.el
+++ b/modules/prog-python.el
@@ -128,7 +128,6 @@ Overrides default prog-mode keybindings with Python-specific commands."
   (blacken-skip-string-normalization t)
   :hook (python-ts-mode . blacken-mode)
   :bind (:map python-ts-mode-map
-              ("<f6>" . blacken-buffer)
               ("C-; f" . blacken-buffer)))
 
 ;; ---------------------------------- Numpydoc ---------------------------------
diff --git a/modules/prog-shell.el b/modules/prog-shell.el
index cb9598db..57347cc6 100644
--- a/modules/prog-shell.el
+++ b/modules/prog-shell.el
@@ -17,9 +17,9 @@
 ;;
 ;; Workflow:
 ;;   1. Open .sh file → LSP auto-starts, ShellCheck runs
-;;   2. <f6> → Format with shfmt
-;;   3. C-c ! l → Show all ShellCheck diagnostics
-;;   4. Save → Auto-set executable bit if script has shebang
+;;   2. C-; f → format with shfmt
+;;   3. C-c ! l → show all ShellCheck diagnostics
+;;   4. Save → auto-set executable bit if script has shebang
 
 ;;; Code:
 
@@ -143,10 +143,8 @@ Overrides default prog-mode keybindings with shell-specific commands."
   :if (executable-find shfmt-path)
   :hook ((sh-mode bash-ts-mode) . shfmt-on-save-mode)
   :bind ((:map sh-mode-map
-               ("<f6>" . shfmt-buffer)
                ("C-; f" . shfmt-buffer))
          (:map bash-ts-mode-map
-               ("<f6>" . shfmt-buffer)
                ("C-; f" . shfmt-buffer)))
   :custom
   (shfmt-arguments '("-i" "2"      ;; indent with 2 spaces