make-runner-mcp 2.1.1 → 2.2.0

package/README.md

@@ -113,24 +113,41 @@ you expect actually show up.
 
 ### Fixing it automatically, not just diagnosing it
 
-The procedure above (find every Makefile, work out which ones
-make-runner-mcp can't currently see, add the `also-read` marker for them)
-is written once, at [`skills/fix-makefile-links/SKILL.md`](./skills/fix-makefile-links/SKILL.md),
-and reachable two ways:
+There's a broader compatibility procedure than just linking — a Makefile
+written for a human at a real terminal often has two other habits that
+break under make-runner-mcp too:
+
+- **Hardcoded interactive docker flags** — `docker exec -it`/`-itu ...`
+  (or `docker compose exec` without `-T`) requires a real TTY. It works
+  for a human, and fails or hangs when make-runner-mcp runs it (it always
+  spawns `make` with piped, non-tty stdio).
+- **`$(MAKECMDGOALS)`-style argument passing** — a `composer`-style target
+  that forwards `make composer install foo` via
+  `$(filter-out $@,$(MAKECMDGOALS))` can't take arguments through
+  make-runner-mcp at all: bare positional arguments are always rejected
+  (see [Passing arguments through to a target](#passing-arguments-through-to-a-target)
+  above) — only `ARGS=value` style works.
+
+All three (linking, TTY flags, `$(MAKECMDGOALS)`) are covered by one
+procedure, written once at
+[`skills/fix-makefile-compat/SKILL.md`](./skills/fix-makefile-compat/SKILL.md)
+— it finds every instance of each, shows you the full proposed changeset,
+and waits for your approval before writing anything. Reachable two ways:
 
 - **Already connected to this server** (the normal case — no extra setup):
-  it's exposed as an MCP **prompt** named `fix-makefile-links`. Any
+  it's exposed as an MCP **prompt** named `fix-makefile-compat`. Any
   MCP client that supports prompts (Claude Code's `/mcp` prompt picker,
-  etc.) can pull it straight from the running server — the prompt text
-  comes back with this project's own `PROJECT_DIR`, Makefile path, and a
-  ready-to-run `--diagnose` command already filled in, since the server
-  serving it already knows all three. Nothing to install.
+  Gemini CLI's automatic MCP-prompt-as-slash-command support, etc.) can
+  pull it straight from the running server — the prompt text comes back
+  with this project's own `PROJECT_DIR`, Makefile path, and a ready-to-run
+  `--diagnose` command already filled in, since the server serving it
+  already knows all three. Nothing to install.
 - **Not using make-runner-mcp as an MCP server here** (e.g. evaluating it,
   or just want the procedure without wiring up a client): install the same
   file as a standalone Claude Code skill —
-  `cp -r skills/fix-makefile-links ~/.claude/skills/` (every project) or
+  `cp -r skills/fix-makefile-compat ~/.claude/skills/` (every project) or
   into a single project's own `.claude/skills/` — then run
-  `/fix-makefile-links`. Slightly more manual (it has to search for a
+  `/fix-makefile-compat`. Slightly more manual (it has to search for a
   make-runner-mcp checkout itself to run `--diagnose`, rather than already
   knowing where one is), but requires nothing beyond Claude Code.
 
@@ -142,7 +159,7 @@ The server is the same everywhere — only the config file and its shape
 differ per client. Things that change between projects/teams:
 
 - `PROJECT_DIR` — the target project's root.
-- `#v2.1.1` — bump this to whatever tag you've actually released. Always
+- `#v2.2.0` — bump this to whatever tag you've actually released. Always
   pin to a release tag, never `#main`: for a tool that executes commands,
   an unpinned branch reference means a bad push could silently change what
   runs on everyone's machine.
@@ -157,7 +174,7 @@ differ per client. Things that change between projects/teams:
   "mcpServers": {
     "makeRunner": {
       "command": "npx",
-      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.1.1"],
+      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.2.0"],
       "env": { "PROJECT_DIR": "/path/to/project", "MCP_TRANSPORT": "stdio" }
     }
   }
@@ -171,13 +188,13 @@ Project-level `.mcp.json` at the repo root (checked in, shared with the team):
   "mcpServers": {
     "makeRunner": {
       "command": "npx",
-      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.1.1"],
+      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.2.0"],
       "env": { "PROJECT_DIR": "/path/to/project", "MCP_TRANSPORT": "stdio" }
     }
   }
 }
 ```
-Or via the CLI: `claude mcp add makeRunner -e PROJECT_DIR=/path/to/project -e MCP_TRANSPORT=stdio -- npx -y github:davindermahal/make-runner-mcp#v2.1.1`
+Or via the CLI: `claude mcp add makeRunner -e PROJECT_DIR=/path/to/project -e MCP_TRANSPORT=stdio -- npx -y github:davindermahal/make-runner-mcp#v2.2.0`
 
 ### Claude Desktop
 `claude_desktop_config.json` (Settings → Developer → Edit Config):
@@ -186,7 +203,7 @@ Or via the CLI: `claude mcp add makeRunner -e PROJECT_DIR=/path/to/project -e MC
   "mcpServers": {
     "makeRunner": {
       "command": "npx",
-      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.1.1"],
+      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.2.0"],
       "env": { "PROJECT_DIR": "/path/to/project", "MCP_TRANSPORT": "stdio" }
     }
   }
@@ -200,7 +217,7 @@ Or via the CLI: `claude mcp add makeRunner -e PROJECT_DIR=/path/to/project -e MC
   "mcpServers": {
     "makeRunner": {
       "command": "npx",
-      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.1.1"],
+      "args": ["-y", "github:davindermahal/make-runner-mcp#v2.2.0"],
       "env": { "PROJECT_DIR": "/path/to/project", "MCP_TRANSPORT": "stdio" }
     }
   }
@@ -232,7 +249,7 @@ on this machine):
 PROJECT_DIR=/path/to/project \
 MCP_HTTP_TOKEN=$(openssl rand -hex 24) \
 MCP_HTTP_PORT=8791 \
-npx -y github:davindermahal/make-runner-mcp#v2.1.1
+npx -y github:davindermahal/make-runner-mcp#v2.2.0
 ```
 
 Generate a real random token (`openssl rand -hex 24` or equivalent) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "make-runner-mcp",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "type": "module",
   "description": "Scoped MCP server that discovers a project's Makefile targets and exposes each one as an individual MCP tool.",
   "main": "server.js",

package/server.js

@@ -88,15 +88,15 @@ const CONFIG_PATH =
   process.env.MCP_MAKE_CONFIG || path.join(PROJECT_DIR, ".mcp-make-config.json");
 
 // This server's own location, not the target project's — used to serve the
-// "fix-makefile-links" MCP prompt (below) straight from the same checkout
+// "fix-makefile-compat" MCP prompt (below) straight from the same checkout
 // this server is running from, and to point that prompt's own verification
 // step back at this exact server.js rather than asking whoever receives
 // the prompt to go find one.
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
-const FIX_MAKEFILE_LINKS_SKILL_PATH = path.join(
+const FIX_MAKEFILE_COMPAT_SKILL_PATH = path.join(
   path.dirname(SCRIPT_PATH),
   "skills",
-  "fix-makefile-links",
+  "fix-makefile-compat",
   "SKILL.md"
 );
 
@@ -621,7 +621,7 @@ function runDiagnostics() {
   console.log(lines.join("\n"));
 }
 
-// Serves skills/fix-makefile-links/SKILL.md (the same file distributed for
+// Serves skills/fix-makefile-compat/SKILL.md (the same file distributed for
 // manual/Claude-Code-skill installs — see README) as an MCP prompt, so
 // simply connecting to this server is enough to get it: no separate file
 // to copy into ~/.claude/skills first. One file stays the source of truth
@@ -630,18 +630,19 @@ function runDiagnostics() {
 // PROJECT_DIR/Makefile/script path) so whoever receives the prompt doesn't
 // need to search for a make-runner-mcp checkout the way a cold read of the
 // skill file on its own would require.
-function buildFixMakefileLinksPrompt() {
+function buildFixMakefileCompatPrompt() {
   let raw;
   try {
-    raw = readFileSync(FIX_MAKEFILE_LINKS_SKILL_PATH, "utf8");
+    raw = readFileSync(FIX_MAKEFILE_COMPAT_SKILL_PATH, "utf8");
   } catch (err) {
-    console.error(`Failed to read ${FIX_MAKEFILE_LINKS_SKILL_PATH}: ${err.message}`);
+    console.error(`Failed to read ${FIX_MAKEFILE_COMPAT_SKILL_PATH}: ${err.message}`);
     return (
-      `Could not load the fix-makefile-links procedure from this server's own ` +
-      `checkout (expected at ${FIX_MAKEFILE_LINKS_SKILL_PATH}). Run ` +
+      `Could not load the fix-makefile-compat procedure from this server's own ` +
+      `checkout (expected at ${FIX_MAKEFILE_COMPAT_SKILL_PATH}). Run ` +
       `\`PROJECT_DIR=${PROJECT_DIR} node ${SCRIPT_PATH} --diagnose\` and fix any ` +
       `gaps it reports using MAKEFILE-GUIDE.md's guidance on include/forwarding/` +
-      `also-read links.`
+      `also-read links, hardcoded interactive docker flags, and $(MAKECMDGOALS)` +
+      `-style argument passing.`
     );
   }
   // Strip the leading YAML frontmatter block — it's Claude Code skill
@@ -651,10 +652,10 @@ function buildFixMakefileLinksPrompt() {
   const context =
     `You are receiving this as an MCP prompt served directly by the ` +
     `make-runner-mcp server already configured for this project — you ` +
-    `already have everything Step 5 asks you to go find:\n\n` +
+    `already have everything Step 8's live verification asks you to go find:\n\n` +
     `Project root (PROJECT_DIR): ${PROJECT_DIR}\n` +
     `Root Makefile: ${MAKEFILE}\n` +
-    `This server's own script, for Step 5's live verification: ${SCRIPT_PATH}\n` +
+    `This server's own script, for Step 8's live verification: ${SCRIPT_PATH}\n` +
     `  e.g. PROJECT_DIR="${PROJECT_DIR}" node "${SCRIPT_PATH}" --diagnose\n\n` +
     `---\n\n`;
   return context + body;
@@ -880,33 +881,36 @@ function createServer() {
     }
   });
 
-  // A single prompt, "fix-makefile-links": see buildFixMakefileLinksPrompt()
+  // A single prompt, "fix-makefile-compat": see buildFixMakefileCompatPrompt()
   // above for what it actually serves and why. This is what makes it
   // reachable to any MCP client without a separate skill-file install —
   // connecting to this server is enough.
   server.setRequestHandler(ListPromptsRequestSchema, async () => ({
     prompts: [
       {
-        name: "fix-makefile-links",
+        name: "fix-makefile-compat",
         description:
-          "Find every Makefile in this project, check which ones make-runner-mcp can " +
-          "actually discover, and add the missing `also-read` link automatically for " +
-          "any that are orphaned — instead of just reporting the gap.",
+          "Find everything in this project's Makefile(s) that keeps make-runner-mcp from " +
+          "discovering or correctly running a target — an unlinked secondary Makefile, " +
+          "hardcoded interactive docker flags (-it/-itu) that only work for a human at a " +
+          "real terminal, and $(MAKECMDGOALS)-style argument passing this server's " +
+          "security model rejects outright — and fix each one, with your approval before " +
+          "writing anything.",
       },
     ],
   }));
 
   server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     const { name } = request.params;
-    if (name !== "fix-makefile-links") {
+    if (name !== "fix-makefile-compat") {
       throw new Error(`Unknown prompt: ${name}`);
     }
     return {
-      description: "Diagnose and fix why make-runner-mcp isn't discovering a secondary Makefile's targets.",
+      description: "Diagnose and fix why a Makefile target isn't discoverable by, or compatible with, make-runner-mcp.",
       messages: [
         {
           role: "user",
-          content: { type: "text", text: buildFixMakefileLinksPrompt() },
+          content: { type: "text", text: buildFixMakefileCompatPrompt() },
         },
       ],
     };

package/skills/fix-makefile-compat/SKILL.md

@@ -0,0 +1,346 @@
+---
+description: Find everything in this project's Makefile(s) that keeps make-runner-mcp from discovering or correctly running a target — a secondary Makefile that isn't linked in, hardcoded interactive docker flags (`-it`/`-itu`) that only work for a human at a real terminal, and bare-word `$(MAKECMDGOALS)`-style argument passing that make-runner-mcp's security model rejects outright — and fix each one, showing you every change and waiting for your approval before writing anything. Only run when explicitly invoked as /fix-makefile-compat.
+argument-hint: [optional: path to a local make-runner-mcp checkout, for live --diagnose verification]
+disable-model-invocation: true
+allowed-tools: Read Glob Grep Bash Edit AskUserQuestion
+---
+
+# Make this project's Makefile(s) work for both a human and make-runner-mcp
+
+Input: $ARGUMENTS (optional path to a make-runner-mcp checkout — see Step 6)
+
+Goal: a human typing `make <target>` at their own terminal keeps getting
+exactly the experience they already have — colored output, an interactive
+shell, a live progress bar, whatever the Makefile already does for them —
+while the *same* target also works when make-runner-mcp invokes it, which
+happens through a real `make` process that has no terminal at all and
+whose security model flatly refuses to run anything but the one named
+target with only flag/`VAR=value` arguments. This skill finds every place
+that assumption breaks and fixes it, three categories at a time, with your
+approval before any file changes.
+
+This does **not** cover everything `MAKEFILE-GUIDE.md` checks — denylist
+false positives, reliance on reserved make variables, and description
+backfilling are separate, higher-judgment concerns. Mention any you notice
+along the way in your final report, but don't act on them here.
+
+## Step 0: Preconditions
+
+- Confirm a root `Makefile` exists at the project root (where this was
+  invoked, or a directory named in $ARGUMENTS/the conversation). If not,
+  stop and say so — make-runner-mcp requires `<project root>/Makefile` to
+  exist; there's nothing to fix yet.
+- `git status --porcelain` (if this is a git repo). If dirty, proceed
+  anyway, but say so in your final report — your edits will land alongside
+  whatever's already uncommitted.
+
+## Step 1: Inventory every Makefile in the project
+
+```bash
+find . -name Makefile \
+  -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' \
+  -not -path '*/.venv/*' -not -path '*/venv/*'
+```
+
+Read every file this finds. Set aside the root one; everything else is a
+**candidate secondary Makefile**. Every check below (Steps 2–5) applies to
+the root Makefile and to every file reached from it (Step 2), not just the
+root file in isolation — a target defined in a real-`include`d file is
+just as much make-runner-mcp's problem as one in the root file itself.
+
+## Step 2: Resolve what the root Makefile already reaches (for the linking check)
+
+Read the root Makefile (and recurse into anything it reaches, same as
+below) and classify every line into one of three link mechanisms — this
+mirrors exactly what make-runner-mcp's own parser does, so a file found
+here is one make-runner-mcp already discovers today:
+
+1. **Real include**: a line matching `^\s*(-|s)?include\s+(.+)$`. Each
+   whitespace-separated path on the line, resolved relative to the
+   *including* file's own directory. A path containing `$(` can't be
+   resolved by make-runner-mcp either — note it as **unresolvable
+   include** in your final report rather than treating it as reachable.
+2. **Catch-all forwarding**: a rule whose target is bare `%:` (not
+   `%.o:` or `docker-%:` — those are ordinary pattern rules, not this
+   idiom), whose recipe (the tab-indented lines immediately after it)
+   contains `$(MAKE) ... -C <dir>`. Reaches `<dir>/Makefile`. A `-C`
+   value containing `$(` similarly can't be resolved — note it the same
+   way as an unresolvable include.
+3. **The marker this skill itself manages**: a comment line matching
+   `^\s*#{1,2}\s*make-runner:\s*also-read\s+(.+)$`. Each
+   whitespace-separated path, resolved the same way as `include`.
+
+For every file reached via (1) or (3), recurse into it too — apply the
+same three checks to its contents, since an included/linked file can
+itself `include` or mark further files. (Forwarding targets, (2), are a
+Makefile invoked by a live `$(MAKE)` at build time in a fresh directory
+context, not textually processed further here — don't recurse into them
+for more forwarding/include chains; treat the forwarded file itself as
+reached and stop there, matching what make-runner-mcp's own parser does.)
+
+Build the **reached set**: the realpath of every file resolved this way,
+starting from the root Makefile itself. Any candidate secondary Makefile
+from Step 1 whose realpath is **not** in this set is **orphaned** —
+make-runner-mcp cannot see its targets at all right now.
+
+## Step 3: Fix orphaned Makefiles (linking)
+
+For each orphaned Makefile, the default and safest fix is to add this line
+to the root Makefile (near any existing `include`/`also-read` lines if
+present, otherwise near the top, after any leading variable assignments):
+
+```makefile
+## make-runner: also-read <path, relative to the root Makefile's directory>
+```
+
+This is a plain comment — it changes nothing about what a human running
+`make` by hand experiences, and it works regardless of *why* the file was
+orphaned. Prefer it over adding a real `include` here: a real `include`
+would need you to verify the whole orphaned file is safe to textually pull
+into the root Makefile's namespace (no colliding variable/target names, no
+assumption about running from a different `cwd`), which is exactly the
+kind of judgment call this skill should not make silently.
+
+**Exception — flag instead of fixing:** before proposing the marker for a
+given orphaned file, grep its recipes for `$(UPPERCASE_VAR)`-style tokens
+and check whether each one is assigned *only* in the root Makefile and not
+in the orphaned file itself (excluding standard built-ins like `$(MAKE)`,
+`$(CC)`, `$(SHELL)`). If you find one, the `also-read` marker would run
+this file without that variable defined — likely breaking or silently
+changing its recipe. For that file only: don't propose an edit, add it to
+**NEEDS HUMAN DECISION** in your final report with the variable name and
+where it's defined. This is a heuristic, not exhaustive — say so.
+
+## Step 4: Find hardcoded interactive docker flags
+
+```bash
+grep -nE '\bdocker (exec|run)\b|\bdocker compose (exec|run)\b|\bdocker-compose (exec|run)\b' Makefile
+```
+
+(Run across every file from Step 1, not just the root.) For every line
+this returns, look for a **short-option token containing `t`** (a single
+`-` followed by one or more letters, e.g. `-it`, `-ti`, `-itu`, `-t`,
+`-dit`) or the long form `--tty` (check separately: `grep -n -- '--tty'
+Makefile`). That's Docker's "allocate a pseudo-TTY" flag. A recipe using
+it only works when `make` itself has a real terminal on its own stdin — a
+human running `make <target>` directly. It fails outright ("the input
+device is not a TTY") or, if `-i`/`--interactive` survives without `-t`,
+can hang waiting on stdin that's never closed — whenever `make` is
+invoked non-interactively: through make-runner-mcp (which always spawns
+`make` with piped, non-tty stdio), through most CI systems, and through
+several coding-agent shell tools.
+
+**Before proposing a fix, check whether the file already has a variable
+for this** — grep for an existing `$(shell [ -t 0 ]` / `test -t 0` /
+`tty -s`-style expression already assigned to a variable. If one exists,
+reuse its exact name in the substitutions below instead of introducing a
+second one.
+
+If none exists, propose adding this once per file that needs it (near the
+top, after other variable declarations, before the first target — name it
+`DOCKER_IT` unless that collides with an existing variable in the file, in
+which case pick another short, clear name and use it consistently):
+
+```makefile
+# `-t` requires a real TTY to allocate a pseudo-terminal against; without one, docker either
+# errors ("the input device is not a TTY") or hangs. Empty here (no `-it`) whenever stdin isn't a
+# real terminal -- e.g. make-runner-mcp, which always spawns `make` this way, or a non-interactive
+# CI/agent shell. A human running `make <target>` directly still gets identical behavior to before.
+DOCKER_IT := $(shell [ -t 0 ] && echo -it)
+```
+
+Then, for every matched line, replace the interactive-flag token with
+`$(DOCKER_IT)`, unbundling any *other* flags in that same token so they
+stay literal and always applied:
+
+```makefile
+# BEFORE
+some-target:
+	docker exec -itu $(shell id -u):$(shell id -g) $(CONTAINER) some-command
+
+# AFTER
+some-target:
+	docker exec $(DOCKER_IT) -u $(shell id -u):$(shell id -g) $(CONTAINER) some-command
+```
+
+A bare `-it`/`-ti`/`--interactive --tty` (no other bundled letters)
+becomes exactly `$(DOCKER_IT)` with nothing else added. Drop **both** `i`
+and `t` into the variable together, not just `t` — an `-i`-only mode with
+no real tty can still hang on an open, never-closed stdin pipe (exactly
+how make-runner-mcp spawns `make`), so there's no safe reason to keep `-i`
+alone when there's no `-t` to go with it. A target whose entire purpose is
+opening an interactive shell (e.g. a `bash`/`sh` target with no other
+arguments) will still get the same variable — running it through
+make-runner-mcp will simply do nothing useful and time out, which is
+correct: an interactive shell isn't meaningful through an agent either
+way, and this isn't something to solve further here.
+
+If this project already has parallel "-ci" or "-noninteractive"-suffixed
+duplicate targets working around this exact problem (check target names
+and comments for it), **do not delete or rename them** — they may be
+referenced elsewhere (CI config, docs, muscle memory). Leave them exactly
+as they are; they become redundant but harmless once the primary targets
+are fixed.
+
+## Step 5: Find and convert `$(MAKECMDGOALS)`-style argument passing
+
+```bash
+grep -n "MAKECMDGOALS" Makefile
+grep -n 'filter-out \$@' Makefile
+grep -n "wordlist" Makefile
+grep -n "^%:" Makefile
+```
+
+(Run across every file from Step 1.) Any hit means at least one target
+relies on bare-word passthrough — make-runner-mcp always rejects a bare
+positional argument outright (it would be treated as an *additional build
+goal*, which could smuggle a second, unvetted target onto the same
+invocation), so a target using this pattern simply can't take arguments
+through the MCP tool at all right now, even though it works fine for a
+human typing `make composer require some/package` directly.
+
+For each hit, find which real target's recipe consumes it (read a few
+lines above/below the match) and add it to a list: **targets to
+convert**.
+
+A `^%:` hit whose recipe contains `$(MAKE)` with a `-C` flag (forwarding
+any undefined goal to another directory's Makefile) is a *different*,
+already-supported idiom — make-runner-mcp discovers and exposes those
+forwarded targets automatically. Do not add it to **targets to convert**.
+Only a `%:` rule that swallows bare-word `$(MAKECMDGOALS)` arguments
+(typically paired with an `@:` no-op recipe, no `$(MAKE) -C ...` call) is
+the pattern this step converts.
+
+For each target on the list:
+
+1. Replace every use of `$(MAKECMDGOALS)`, `$(filter-out $@,$(MAKECMDGOALS))`,
+   or similar with a single variable named `ARGS`.
+2. Rewrite (or write, if missing) its `##` comment: `## <what it does>.
+   Pass args via ARGS, e.g. ARGS="<realistic example>"`.
+
+```makefile
+# BEFORE
+composer: ## Run composer
+	docker compose exec app composer $(filter-out $@,$(MAKECMDGOALS))
+
+# AFTER
+composer: ## Run composer inside the app container. Pass args via ARGS, e.g. ARGS="install symfony/console --no-dev"
+	docker compose exec app composer $(ARGS)
+```
+
+Do not rename the target. Do not change what command it runs beyond this
+substitution. If a target also had a hardcoded interactive flag (Step 4),
+apply both fixes to the same recipe line in one edit.
+
+After converting every target on the list, check whether the bare `%:`
+catch-all rule (and its `@:` no-op recipe, and any `.PHONY` entry naming
+it) is now dead code — nothing else still using `$(MAKECMDGOALS)`. If so,
+propose removing it too, as part of the same changeset.
+
+**Skip if the example value doesn't fit the safe character set:** check
+each `ARGS="..."` example against `^[A-Za-z0-9 _.,+/@:^~=-]*$` (letters,
+digits, spaces, and `` _ . , + / @ : ^ ~ = - ``). If your chosen example
+doesn't match, pick a different, representative one — if nothing
+realistic fits, leave that target unconverted and add it to **NEEDS HUMAN
+DECISION** instead, per `MAKEFILE-GUIDE.md` §8's guidance not to invent a
+workaround (no encoding tricks).
+
+## Step 6: Show the full changeset and get approval before writing anything
+
+Assemble every proposed change from Steps 3–5 into one list — file,
+category (linking / TTY / ARGS), and a short before/after snippet for
+each. Show this to the user as a single summary and ask for explicit
+approval before editing any file — e.g. via `AskUserQuestion`, or by
+plainly asking "Apply these N changes?" and waiting for a clear yes. If
+the user approves some categories but not others, apply only what was
+approved. Don't treat your own tool permissions (if file edits happen to
+be pre-approved in this session) as a substitute for this — ask anyway.
+
+If there is nothing to fix in any category, say so plainly ("Already
+compatible — nothing to change") and stop; don't invent work.
+
+## Step 7: Apply the approved changes
+
+Write exactly what was approved, nothing more.
+
+## Step 8: Verify
+
+- **Linking**: re-run Step 2's classification against the now-edited root
+  Makefile and confirm every previously-orphaned file (other than ones
+  left for human decision) now appears in the reached set.
+- **TTY flags**: run `make -n <target> ...` for at least one fixed target,
+  from your own shell. Your own shell is itself non-interactive (this is
+  exactly the condition make-runner-mcp always runs under), so the printed
+  command should show *no* `-it`/`-t`/`--tty` — confirm that directly in
+  the output.
+- **ARGS conversion**: for every target converted in Step 5, run
+  `make -n <target> ARGS="<the example value from its comment>"` and
+  confirm the printed command substitutes `ARGS` in the right place and
+  the target isn't silently doing nothing.
+- **Live check, if available**: if $ARGUMENTS names a local
+  make-runner-mcp checkout (a directory containing `server.js`), or
+  `command -v make-runner-mcp` resolves to something, run:
+  ```bash
+  PROJECT_DIR="$(pwd)" node <path-to-that-checkout>/server.js --diagnose
+  ```
+  Confirm newly-linked targets appear in `EXPOSED TARGETS`, and its
+  `UNRESOLVED ... PATHS` / `FILES REJECTED` sections are empty for files
+  you just fixed. If unavailable, say so and note the checks above stand
+  in for it.
+
+Do **not** invoke any real `make <target>` recipe with side effects
+(anything that isn't `-n`/dry-run) to test — that executes real commands,
+which is outside what this skill is for.
+
+## Step 9: Report
+
+```
+MAKEFILES FOUND:
+- <path>: <root | already linked via include/forwarding/also-read | orphaned>
+
+LINKING FIXED (also-read marker added):
+- <path>
+
+TTY FLAGS FIXED:
+- <target>: <e.g. "docker exec -itu ... -> docker exec $(DOCKER_IT) -u ...">
+
+ARGS CONVERTED (MAKECMDGOALS -> ARGS):
+- <target>: <one line: what changed>
+
+DEAD CODE REMOVED:
+- <catch-all rule removed, or "none">
+
+NEEDS HUMAN DECISION:
+- <target/file>: <exact reason>
+
+VERIFIED:
+- <target>: <"dry-run only" | "dry-run + live --diagnose" | "not tested -- reason">
+
+NOT TOUCHED (and why):
+- <target>: <e.g. "already uses ARGS and no interactive flags, no change needed">
+```
+
+Also mention, once, that the `also-read` marker and any of these fixes
+only take effect with a make-runner-mcp version that includes them — if
+this project's MCP client config pins an older release tag, the fix won't
+apply until that tag is bumped.
+
+## Guardrails — do not do these, under any circumstance
+
+- **Don't rename or restructure a target to dodge the hard-coded
+  denylist** (`deploy`, `destroy`, `prod`, `publish`, `release`, `rm-*`).
+  That's a separate, higher-judgment concern outside this skill's scope —
+  mention it in your report if you notice it, don't act on it.
+- **Don't try to route around the `VAR=value` character restriction** in
+  Step 5 — no encoding tricks, no alternate delimiters. If a target's real
+  arguments don't fit, leave it as `NEEDS HUMAN DECISION`.
+- **Don't edit `.mcp-make-config.json`** as a substitute for fixing a
+  target — it only narrows what's exposed, it doesn't change how a target
+  runs or receives arguments.
+- **Don't edit make-runner-mcp's own `server.js`** from inside a target
+  project's repo. If something here genuinely needs a change to
+  make-runner-mcp itself, report it, don't make it from here.
+- **Don't mark something as tested if you didn't actually run a command
+  and see its output.** If you couldn't test (missing tooling, no
+  container running, etc.), say so plainly in Step 9 rather than guessing
+  that it probably works.

package/skills/fix-makefile-links/SKILL.md

@@ -1,169 +0,0 @@
----
-description: Find every Makefile in the current project, check which ones make-runner-mcp can actually discover (via a real `include`/`-include` directive, the `%:` catch-all forwarding idiom, or a `## make-runner: also-read <path>` marker), and add the missing link automatically for any that are orphaned — instead of just reporting the gap. Only run when explicitly invoked as /fix-makefile-links.
-argument-hint: [optional: path to a local make-runner-mcp checkout, to run --diagnose for live verification]
-disable-model-invocation: true
-allowed-tools: Read Glob Grep Bash Edit AskUserQuestion
----
-
-# Fix make-runner-mcp Makefile linking
-
-Input: $ARGUMENTS (optional path to a make-runner-mcp checkout — see Step 5)
-
-Goal: make sure every Makefile in this project that defines real targets is
-actually reachable from `<project root>/Makefile` — the only file
-make-runner-mcp reads — and fix it automatically where it isn't, rather
-than just telling the user their Makefile isn't being picked up.
-
-This handles **linking/discovery only**. It does not touch recipe bodies,
-convert `$(MAKECMDGOALS)`-style argument passing, or fix denylist false
-positives — those are separate, higher-judgment concerns covered by
-make-runner-mcp's own `MAKEFILE-GUIDE.md`; mention it in your final report
-if you notice any of those along the way, but don't act on them here.
-
-## Step 0: Preconditions
-
-- Confirm a root `Makefile` exists at the project root (where this was
-  invoked, or a directory the user named in $ARGUMENTS/the conversation).
-  If not, stop and say so — make-runner-mcp requires
-  `<project root>/Makefile` to exist; there's nothing to link yet.
-- `git status --porcelain` (if this is a git repo). If dirty, proceed
-  anyway — the only edit this skill makes is appending comment lines to
-  the root Makefile — but mention in the final report that the edit will
-  land alongside whatever else is already uncommitted.
-
-## Step 1: Inventory every Makefile in the project
-
-```bash
-find . -name Makefile \
-  -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' \
-  -not -path '*/.venv/*' -not -path '*/venv/*'
-```
-
-Read every file this finds. Set aside the root one; everything else is a
-**candidate secondary Makefile**.
-
-If this returns only the root Makefile, stop here and report: "Only one
-Makefile in this project — nothing to link." Don't invent work.
-
-## Step 2: Resolve what the root Makefile already reaches
-
-Read the root Makefile (and recurse into anything it reaches, same as
-below) and classify every line into one of three link mechanisms —
-this mirrors exactly what make-runner-mcp's own parser does, so a file
-found here is one make-runner-mcp already discovers today:
-
-1. **Real include**: a line matching `^\s*(-|s)?include\s+(.+)$`. Each
-   whitespace-separated path on the line, resolved relative to the
-   *including* file's own directory. A path containing `$(` can't be
-   resolved by make-runner-mcp either — note it as **unresolvable
-   include** (see Step 4) rather than treating it as reachable.
-2. **Catch-all forwarding**: a rule whose target is bare `%:` (not
-   `%.o:` or `docker-%:` — those are ordinary pattern rules, not this
-   idiom), whose recipe (the tab-indented lines immediately after it)
-   contains `$(MAKE) ... -C <dir>`. Reaches `<dir>/Makefile`. A `-C`
-   value containing `$(` similarly can't be resolved — note it the same
-   way as an unresolvable include.
-3. **The marker this skill itself manages**: a comment line matching
-   `^\s*#{1,2}\s*make-runner:\s*also-read\s+(.+)$`. Each
-   whitespace-separated path, resolved the same way as `include`.
-
-For every file reached via (1) or (3), recurse into it too — apply the
-same three checks to its contents, since an included/linked file can
-itself `include` or mark further files. (Forwarding targets, (2), are a
-Makefile invoked by a live `$(MAKE)` at build time in a fresh directory
-context, not textually processed further here — don't recurse into them
-for more forwarding/include chains; treat the forwarded file itself as
-reached and stop there, matching what make-runner-mcp's own parser does.)
-
-Build the **reached set**: the realpath of every file resolved this way,
-starting from the root Makefile itself.
-
-## Step 3: Compute the gap
-
-Any candidate secondary Makefile from Step 1 whose realpath is **not** in
-the reached set from Step 2 is **orphaned** — make-runner-mcp cannot see
-its targets right now, regardless of why (never referenced at all, or
-referenced only via an unresolvable `$(VAR)` path).
-
-If the gap is empty: report "All Makefiles are already correctly linked —
-nothing to fix" and stop.
-
-## Step 4: Fix each orphaned file
-
-For each orphaned Makefile, the default and safest fix is to append this
-line to the root Makefile (near any existing `include`/`also-read` lines
-if present, otherwise near the top, after any leading variable
-assignments):
-
-```makefile
-## make-runner: also-read <path, relative to the root Makefile's directory>
-```
-
-This is a plain comment — it changes nothing about what a human running
-`make` by hand experiences, and it works regardless of *why* the file was
-orphaned. Prefer it over adding a real `include` here: a real `include`
-would need you to verify the whole orphaned file is safe to textually pull
-into the root Makefile's namespace (no colliding variable/target names,
-no assumption about running from a different `cwd`), which is exactly the
-kind of judgment call this skill should not make silently.
-
-**Exception — flag instead of auto-fixing:** before applying the marker to
-a given orphaned file, grep its recipes for `$(UPPERCASE_VAR)`-style
-tokens and check whether each one is assigned *only* in the root Makefile
-and not in the orphaned file itself (excluding standard built-ins like
-`$(MAKE)`, `$(CC)`, `$(SHELL)`). If you find one, the `also-read` marker
-would run this file without that variable defined — likely breaking or
-silently changing its recipe. For that file only: don't edit anything,
-add it to a **NEEDS HUMAN DECISION** list in your final report with the
-variable name and where it's defined, and suggest either (a) defining that
-variable directly in the orphaned file too, or (b) using a real `include`
-once a human has verified there's no namespace collision. This is a
-heuristic, not exhaustive — say so.
-
-Apply the marker fix for every other orphaned file in one edit to the root
-Makefile (one line per file), then move on.
-
-## Step 5: Verify
-
-Re-run Step 2's classification by hand against the now-edited root
-Makefile and confirm every previously-orphaned file (other than ones left
-for human decision) now appears in the reached set.
-
-If $ARGUMENTS names a local make-runner-mcp checkout (a directory
-containing `server.js`), or `command -v make-runner-mcp` resolves to
-something, run the real thing for a live check instead of trusting your
-own by-hand classification alone:
-
-```bash
-PROJECT_DIR="$(pwd)" node <path-to-that-checkout>/server.js --diagnose
-```
-
-Check its `EXPOSED TARGETS` section lists targets from the newly-linked
-file(s), and its `UNRESOLVED ... PATHS` / `FILES REJECTED` sections are
-empty for the files you just fixed. If no checkout is available, say so in
-the report and note that the by-hand verification above stands in for it.
-
-Do **not** invoke any actual `make <target>` to test — that executes real
-recipes, which is outside what this skill is for.
-
-## Step 6: Report
-
-State plainly, in this shape:
-
-```
-MAKEFILES FOUND:
-- <path>: <root | already linked via include/forwarding/also-read | orphaned>
-
-FIXED (also-read marker added to root Makefile):
-- <path>
-
-NEEDS HUMAN DECISION:
-- <path>: <reason — e.g. "recipe uses $(FOO), only defined in root Makefile">
-
-VERIFIED: <"live --diagnose output matches" | "by-hand classification only — no make-runner-mcp checkout available to confirm">
-```
-
-Also mention, once, that the `also-read` marker only works with a
-make-runner-mcp version that supports it — if this project's MCP client
-config pins an older release tag, the fix won't take effect until that
-tag is bumped.