impulso 0.19.1

package/harnesses/claude/hooks/subagent-start.cjs

@@ -0,0 +1,83 @@
+// impulso subagent-start hook — Claude Code
+//
+// SubagentStart handler. Writes a role file to the sessions dir and injects
+// the DirectSpeech reinforcement line + a static role reminder as
+// additionalContext. Fail-open throughout — losing persona context (exit 2) is
+// worse than a missing role file.
+//
+// Role file: ${IMPULSO_SESSIONS_DIR}/<session_id>.json
+//   = { role: agent_type|null, at: ISO }
+// IMPULSO_SESSIONS_DIR env overrides the default (os.tmpdir()/impulso-sessions).
+//
+// additionalContext is byte-stable per agent_type — no timestamps in the
+// emitted text, so prompt caching is not broken.
+//
+// Hook: SubagentStart
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const dsConfig = require(path.join(__dirname, '../../../shared/directspeech-config.cjs'));
+
+function sessionsDir() {
+  return process.env.IMPULSO_SESSIONS_DIR || path.join(os.tmpdir(), 'impulso-sessions');
+}
+
+function main() {
+  let done = false;
+  const chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let c;
+    while ((c = process.stdin.read()) !== null) chunks.push(c);
+  });
+
+  function finish(raw) {
+    if (done) return;
+    done = true;
+    clearTimeout(timer); // safe: finish() is only called after const timer = ... executes
+
+    try {
+      const input = JSON.parse(raw || '{}');
+      const sessionId = input.session_id || null;
+      const role = input.agent_type || null;
+
+      // Write role file — best-effort; never block on failure
+      if (sessionId) {
+        try {
+          const dir = sessionsDir();
+          fs.mkdirSync(dir, { recursive: true });
+          const entry = { role, at: new Date().toISOString() };
+          fs.writeFileSync(path.join(dir, sessionId + '.json'), JSON.stringify(entry), 'utf8');
+        } catch (_e) {
+          // Intentionally swallowed — fail-open
+        }
+      }
+
+      // Emit additionalContext — byte-stable per role (no timestamps here)
+      const dsLine = dsConfig.reinforcementLine();
+      const roleLabel = role || 'generalist';
+      const roleLine = `IMPULSO ROLE: ${roleLabel}. Gates enforced by impulso-hub.`;
+
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'SubagentStart',
+            additionalContext: dsLine + '\n' + roleLine,
+          },
+        }) + '\n',
+      );
+    } catch (_e) {
+      // Fail-open — emit nothing rather than block the subagent
+    }
+
+    process.exit(0);
+  }
+
+  process.stdin.on('end', () => finish(chunks.join('')));
+  const timer = setTimeout(() => finish(chunks.join('')), 1000);
+}
+
+main();

package/harnesses/claude/hooks/task-exit.cjs

@@ -0,0 +1,189 @@
+// impulso task-exit hook — Claude Code
+//
+// SubagentStop handler. Two additive checks:
+//
+// 1. Status-block length check (all roles, fail-open): reads last_assistant_message
+//    from the SubagentStop payload (available since Claude Code added the field:
+//    "Added last_assistant_message field to Stop and SubagentStop hook inputs,
+//    providing the final assistant response text so hooks can access it without
+//    parsing transcript files."). If the report exceeds 15 lines, emits a
+//    visible violation via hookSpecificOutput.additionalContext on stdout —
+//    SubagentStop's non-blocking visible channel (source:
+//    https://code.claude.com/docs/en/hooks, SubagentStop hookSpecificOutput table:
+//    additionalContext "injected into Claude's conversation at the end of the turn").
+//    Stderr at exit-0 is discarded by Claude Code; only exit-2 stderr is relayed.
+//    Never truncates; never blocks (always continues after this check).
+//
+// 2. TDD gate (implementer roles only): for implementer roles with an active
+//    workspace and a current task in_progress, checks the TDD gate non-mutatively
+//    by reading state.json directly. If the red→green test cycle is not complete,
+//    exits 2 with a reason (blocking the subagent stop and feeding stderr back to
+//    the orchestrator).
+//
+// Fail-open on everything except the clear TDD gate-unmet case: missing role file,
+// no active workspace, no in-progress task, gate unclear → exit 0.
+//
+// Gate path: resolved relative to hook location (../../..) — same as tdd-observer.
+// Sessions dir: IMPULSO_SESSIONS_DIR env (default: os.tmpdir()/impulso-sessions).
+//
+// Hook: SubagentStop
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const IMPLEMENTER_ROLES = new Set(['implementer', 'implementer-frontend', 'implementer-infra']);
+
+const STATUS_BLOCK_LIMIT = 15;
+
+function reportLineCount(reportText) {
+  if (!reportText || typeof reportText !== 'string') return 0;
+  const lines = reportText.split('\n');
+  // Every \n-delimited segment counts — blank lines and code-fence markers (```) included.
+  // A lone trailing newline is NOT counted as an extra line.
+  return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+}
+
+function violatesLimit(reportText, limit = STATUS_BLOCK_LIMIT) {
+  return reportLineCount(reportText) > limit;
+}
+
+function sessionsDir() {
+  return process.env.IMPULSO_SESSIONS_DIR || path.join(os.tmpdir(), 'impulso-sessions');
+}
+
+function getRole(sessionId) {
+  if (!sessionId) return null;
+  try {
+    const p = path.join(sessionsDir(), sessionId + '.json');
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return data.role || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function main() {
+  let done = false;
+  const chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let c;
+    while ((c = process.stdin.read()) !== null) chunks.push(c);
+  });
+
+  function finish(raw) {
+    if (done) return;
+    done = true;
+    clearTimeout(timer); // safe: finish() is only called after const timer = ... executes
+
+    try {
+      const input = JSON.parse(raw || '{}');
+      const sessionId = input.session_id || null;
+      const role = getRole(sessionId);
+
+      // Status-block length check — additive, all roles, fail-open
+      try {
+        const report = input.last_assistant_message;
+        if (report && violatesLimit(report)) {
+          process.stdout.write(
+            JSON.stringify({
+              hookSpecificOutput: {
+                hookEventName: 'SubagentStop',
+                additionalContext:
+                  `[impulso] subagent report exceeds ${STATUS_BLOCK_LIMIT}-line limit: ` +
+                  `${reportLineCount(report)} lines. Trim the status block to ≤${STATUS_BLOCK_LIMIT} lines.`,
+              },
+            }) + '\n',
+          );
+        }
+      } catch (_e) {
+        // fail-open
+      }
+
+      // Only check for implementer roles
+      if (!role || !IMPLEMENTER_ROLES.has(role)) {
+        process.exit(0);
+        return;
+      }
+
+      // Check for active workspace
+      const cwd = process.cwd();
+      const activePath = path.join(cwd, '.impulso', 'active');
+      if (!fs.existsSync(activePath)) {
+        process.exit(0);
+        return;
+      }
+
+      // Read state non-mutatively
+      let slug;
+      try {
+        slug = fs.readFileSync(activePath, 'utf8').trim();
+      } catch (_e) {
+        process.exit(0);
+        return;
+      }
+
+      const statePath = path.join(cwd, '.impulso', 'work', slug, 'state.json');
+      let state;
+      try {
+        state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      } catch (_e) {
+        process.exit(0); // Fail-open if state unreadable
+        return;
+      }
+
+      // Find current in-progress task
+      const currentTask = state.currentTask;
+      if (!currentTask) {
+        process.exit(0);
+        return;
+      }
+
+      const taskInfo = state.tasks && state.tasks[String(currentTask)];
+      if (!taskInfo || taskInfo.status !== 'in_progress') {
+        process.exit(0);
+        return;
+      }
+
+      // Check TDD gate: must have at least one red, then a green, for this task
+      const taskTests = (state.tests || []).filter((t) => String(t.task) === String(currentTask));
+
+      let lastRedIdx = -1;
+      for (let i = 0; i < taskTests.length; i++) {
+        if (taskTests[i].exitCode !== 0) lastRedIdx = i;
+      }
+
+      if (lastRedIdx === -1) {
+        process.stderr.write(
+          `task ${currentTask}: TDD gate unmet — no failing test recorded. ` +
+            `Run failing tests before stopping: impulso-hub run-test\n`,
+        );
+        process.exit(2);
+        return;
+      }
+
+      const greenAfterRed = taskTests.slice(lastRedIdx + 1).some((t) => t.exitCode === 0);
+      if (!greenAfterRed) {
+        process.stderr.write(
+          `task ${currentTask}: TDD gate unmet — no passing test after the last failing test. ` +
+            `Make tests green before stopping: impulso-hub run-test\n`,
+        );
+        process.exit(2);
+        return;
+      }
+    } catch (_e) {
+      // Fail-open — never block on unclear state
+    }
+
+    process.exit(0);
+  }
+
+  process.stdin.on('end', () => finish(chunks.join('')));
+  const timer = setTimeout(() => finish(chunks.join('')), 1000);
+}
+
+if (require.main === module) main();
+
+module.exports = { reportLineCount, violatesLimit };

package/harnesses/claude/hooks/tdd-observer.cjs

@@ -0,0 +1,118 @@
+// impulso tdd-observer hook — Claude Code
+//
+// PostToolUse handler (matcher: Bash). If an active workspace exists and the
+// command matches the project's test_cmd, records the test exit code via
+// impulso-hub record-test.
+//
+// Exit code extraction: checks tool_response fields in order:
+//   exitCode → exit_code → code
+// If none is a number, skips recording — impulso-hub run-test is the primary
+// capture path and provides reliable exit codes; this hook is a best-effort
+// secondary observer.
+//
+// Gate path: resolved relative to hook location (../../..); if not found
+// (plugin installed standalone), falls back to 'impulso-hub' on PATH.
+//
+// Always exits 0 — never blocks tool use.
+//
+// Hook: PostToolUse (matcher: Bash)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const GATE_REL = path.resolve(__dirname, '..', '..', '..', 'scripts', 'impulso-hub.cjs');
+
+function main() {
+  let done = false;
+  const chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let c;
+    while ((c = process.stdin.read()) !== null) chunks.push(c);
+  });
+
+  function finish(raw) {
+    if (done) return;
+    done = true;
+    clearTimeout(timer); // safe: finish() is only called after const timer = ... executes
+
+    try {
+      const input = JSON.parse(raw || '{}');
+      const command = (input.tool_input && input.tool_input.command) || '';
+
+      // Check for active workspace from cwd
+      const cwd = process.cwd();
+      const activePath = path.join(cwd, '.impulso', 'active');
+      if (!fs.existsSync(activePath)) {
+        process.exit(0);
+        return;
+      }
+
+      // Read config to get test_cmd
+      const configPath = path.join(cwd, '.impulso', 'config.json');
+      let config;
+      try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      } catch (_e) {
+        process.exit(0);
+        return;
+      }
+
+      const testCmd = config.test_cmd;
+      if (!testCmd || !command.includes(testCmd)) {
+        process.exit(0);
+        return;
+      }
+
+      // Extract exit code from payload — check candidate fields in order.
+      // If none is a number, skip: run-test is the primary capture path.
+      const resp = input.tool_response || {};
+      let exitCode = null;
+      for (const field of ['exitCode', 'exit_code', 'code']) {
+        if (typeof resp[field] === 'number') {
+          exitCode = resp[field];
+          break;
+        }
+      }
+
+      if (exitCode === null) {
+        process.exit(0);
+        return;
+      }
+
+      // Invoke impulso-hub record-test (non-blocking best-effort)
+      const gateArg = fs.existsSync(GATE_REL) ? GATE_REL : null;
+      if (gateArg) {
+        spawnSync(
+          process.execPath,
+          [gateArg, 'record-test', '--cmd', command, '--exit-code', String(exitCode)],
+          {
+            stdio: 'ignore',
+            timeout: 5000,
+          },
+        );
+      } else {
+        // Plugin installed standalone — fall back to impulso-hub on PATH
+        spawnSync(
+          'impulso-hub',
+          ['record-test', '--cmd', command, '--exit-code', String(exitCode)],
+          {
+            stdio: 'ignore',
+            timeout: 5000,
+          },
+        );
+      }
+    } catch (_e) {
+      // Fail-open — never block tool use
+    }
+
+    process.exit(0);
+  }
+
+  process.stdin.on('end', () => finish(chunks.join('')));
+  const timer = setTimeout(() => finish(chunks.join('')), 1000);
+}
+
+main();

package/harnesses/claude/hooks/tokensave-stale.cjs

@@ -0,0 +1,63 @@
+// impulso tokensave-stale hook — Claude Code
+//
+// PostToolUse(Edit|Write) handler. On a successful Edit/Write, writes
+// .tokensave/stale containing a timestamp + the edited/written path so the
+// userpromptsubmit dispatcher can warn when the tokensave index is stale.
+//
+// Fail-open: always exits 0. Never blocks or throws. If .tokensave/ does not
+// exist, skips silently (no marker created).
+//
+// Tokensave dir resolution:
+//   1. TOKENSAVE_DIR env var — override for tests and CI
+//   2. process.cwd()/.tokensave — runtime default
+//
+// Hook: PostToolUse (matcher: Edit|Write)
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const chunks = [];
+let done = false;
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('readable', () => {
+  let c;
+  while ((c = process.stdin.read()) !== null) chunks.push(c);
+});
+
+function finish(raw) {
+  if (done) return;
+  done = true;
+  clearTimeout(timer);
+
+  try {
+    const input = JSON.parse(raw || '{}');
+    const toolName = input.tool_name || '';
+    if (toolName !== 'Edit' && toolName !== 'Write') {
+      process.exit(0);
+      return;
+    }
+
+    const filePath = (input.tool_input && input.tool_input.file_path) || '';
+    const tsDir = process.env.TOKENSAVE_DIR || path.join(process.cwd(), '.tokensave');
+
+    // Fail-open: skip if the dir does not exist
+    if (!fs.existsSync(tsDir)) {
+      process.exit(0);
+      return;
+    }
+
+    const ts = new Date().toISOString();
+    fs.writeFileSync(path.join(tsDir, 'stale'), ts + '\n' + filePath + '\n');
+  } catch (_) {
+    // Fail-open: never throw, never block the write
+  }
+
+  process.exit(0);
+}
+
+process.stdin.on('end', () => finish(chunks.join('')));
+// 1-second fallback: in case Claude Code's hook runner delays closing stdin
+const timer = setTimeout(() => finish(chunks.join('')), 1000);

package/harnesses/claude/hooks/userpromptsubmit.cjs

@@ -0,0 +1,42 @@
+// impulso userpromptsubmit dispatcher — Claude Code
+//
+// UserPromptSubmit dispatcher. Runs preflight binary check, then checks
+// tokensave freshness and injects directspeech context (with stale warning
+// appended when the index is stale). preflight's exit-2 (missing binary)
+// short-circuits before anything else.
+//
+// Hook: UserPromptSubmit
+
+'use strict';
+
+const path = require('node:path');
+const preflight = require(path.join(__dirname, 'preflight.cjs'));
+const directspeechContext = require(path.join(__dirname, 'directspeech-context.cjs'));
+const { reconcile } = require(path.join(__dirname, '../../../shared/tokensave-freshness.cjs'));
+
+// Stage 1: preflight — exit 2 if any required binary is missing
+const missing = preflight.missingBinaries();
+if (missing.length > 0) {
+  const lines = missing.map(({ bin, hint }) => `  ${bin} — install: ${hint}`);
+  process.stderr.write(
+    'impulso: hard-required binaries missing from PATH:\n' + lines.join('\n') + '\n',
+  );
+  process.exit(2);
+}
+
+// Stage 2: reconcile tokensave freshness (fail-open — never block prompt)
+const tsDir = process.env.TOKENSAVE_DIR || path.join(process.cwd(), '.tokensave');
+let stalenessLine = null;
+try {
+  const result = reconcile(tsDir);
+  if (result.stale) {
+    stalenessLine = `tokensave index stale since ${result.since}`;
+  }
+} catch (_) {}
+
+// Stage 3: directspeech context injection (stale warning appended when needed)
+const ctx = directspeechContext.contextObject();
+if (stalenessLine) {
+  ctx.hookSpecificOutput.additionalContext += '\n' + stalenessLine;
+}
+process.stdout.write(JSON.stringify(ctx) + '\n');

package/harnesses/claude/install.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Impulso claude install — creates an isolated profile dir, symlinks
+# skills/commands from this repo, copies AGENTS.md + CLAUDE.md, generates
+# settings.json from the self-boot config, and registers the tokensave MCP.
+# Idempotent — safe to rerun.
+#
+# Default profile dir: ~/.config/impulso-profile/claude
+# Override with: IMPULSO_CLAUDE_PROFILE=/some/dir ./install.sh
+#
+# To install into ~/.claude/ directly (shared with your normal Claude
+# Code config): IMPULSO_CLAUDE_PROFILE="$HOME/.claude" ./install.sh
+#
+# Launch with the isolated profile:
+#   CLAUDE_CONFIG_DIR=~/.config/impulso-profile/claude claude
+
+REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+PROFILE_DIR="${IMPULSO_CLAUDE_PROFILE:-${HOME}/.config/impulso-profile/claude}"
+ISOLATED=1
+if [[ "${PROFILE_DIR}" == "${HOME}/.claude" ]]; then
+  ISOLATED=0
+fi
+
+echo "==> Impulso install (claude)"
+echo "    Repo:    ${REPO}"
+echo "    Profile: ${PROFILE_DIR}"
+
+# --- Preflight: hard-required binaries (parity with opencode installer) -----
+
+require_bin() {
+  local bin="$1"
+  local hint="$2"
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "ERROR: '$bin' not found on PATH. Impulso requires it." >&2
+    echo "  $hint" >&2
+    exit 1
+  fi
+}
+
+require_bin rtk          "Install: brew install rtk-ai/tap/rtk  (see https://www.rtk-ai.app)"
+require_bin tokensave    "Install: brew install aovestdipaperino/tap/tokensave  (or: cargo install tokensave)"
+require_bin plannotator  "Install: curl -fsSL https://plannotator.ai/install.sh | bash"
+
+mkdir -p "${PROFILE_DIR}"
+
+# Symlink skills/, commands/, and agents/ into the profile — without clobbering.
+# Missing or already-a-symlink target: whole-dir symlink. Existing real
+# directory (shared profiles like ~/.claude have their own): link each
+# bundled entry individually inside it, never touching foreign entries.
+for sub in skills commands agents; do
+  link_path="${PROFILE_DIR}/${sub}"
+  target="${REPO}/${sub}"
+  if [[ -L "${link_path}" ]] || [[ ! -e "${link_path}" ]]; then
+    ln -sfn "${target}" "${link_path}"
+    echo "    Linked ${sub} -> ${target}"
+  else
+    for entry in "${target}"/*; do
+      ln -sfn "${entry}" "${link_path}/$(basename "${entry}")"
+    done
+    echo "    Linked ${sub}/* entries into existing ${link_path}"
+  fi
+done
+
+# Ruleset: copy as IMPULSO-AGENTS.md (never clobbers a user AGENTS.md) and
+# make sure CLAUDE.md imports it — created if missing, appended otherwise.
+# Claude Code reads CLAUDE.md, not AGENTS.md.
+cp -f "${REPO}/shared/AGENTS.md" "${PROFILE_DIR}/IMPULSO-AGENTS.md"
+if [[ ! -f "${PROFILE_DIR}/CLAUDE.md" ]]; then
+  printf '@IMPULSO-AGENTS.md\n' > "${PROFILE_DIR}/CLAUDE.md"
+  echo "    Wrote CLAUDE.md (@IMPULSO-AGENTS.md import)"
+elif ! grep -qF '@IMPULSO-AGENTS.md' "${PROFILE_DIR}/CLAUDE.md"; then
+  printf '\n@IMPULSO-AGENTS.md\n' >> "${PROFILE_DIR}/CLAUDE.md"
+  echo "    Appended @IMPULSO-AGENTS.md import to existing CLAUDE.md"
+else
+  echo "    CLAUDE.md already imports IMPULSO-AGENTS.md"
+fi
+
+# settings.json: generate from the self-boot config (single source of truth,
+# hooks pinned to this repo's absolute path) and MERGE into any existing
+# settings — foreign hooks and keys survive; stale impulso entries replaced.
+TMP_SETTINGS="$(mktemp)"
+sed "s|\$CLAUDE_CONFIG_DIR/\.\.|${REPO}|g" "${REPO}/claude/settings.json" > "${TMP_SETTINGS}"
+node "${REPO}/harnesses/claude/merge-settings.cjs" "${PROFILE_DIR}/settings.json" "${TMP_SETTINGS}"
+rm -f "${TMP_SETTINGS}"
+echo "    Merged settings.json (hooks -> ${REPO}/harnesses/claude/hooks)"
+
+# impulso-hub binary — copy matching bundled package binary
+node "${REPO}/scripts/install-hub.js"
+
+# Remove old impulso-gate binary if present (renamed to impulso-hub)
+OLD_GATE="${HOME}/.local/bin/impulso-gate"
+if [ -f "${OLD_GATE}" ] || [ -L "${OLD_GATE}" ]; then
+  rm -f "${OLD_GATE}" && echo "    Removed old impulso-gate binary"
+fi
+
+# Register the tokensave MCP server (user scope, idempotent).
+if command -v claude >/dev/null 2>&1; then
+  if CLAUDE_CONFIG_DIR="${PROFILE_DIR}" claude mcp get tokensave >/dev/null 2>&1; then
+    echo "    tokensave MCP already registered"
+  else
+    CLAUDE_CONFIG_DIR="${PROFILE_DIR}" claude mcp add --scope user tokensave -- tokensave serve
+    echo "    Registered tokensave MCP (user scope)"
+  fi
+else
+  echo "    WARN: claude CLI not found — register tokensave manually:"
+  echo "      CLAUDE_CONFIG_DIR=${PROFILE_DIR} claude mcp add --scope user tokensave -- tokensave serve"
+fi
+
+echo "==> Done."
+echo ""
+if [[ "${ISOLATED}" == "1" ]]; then
+  echo "    Launch with the isolated profile:"
+  echo "      CLAUDE_CONFIG_DIR=${PROFILE_DIR} claude"
+else
+  echo "    Launch Claude Code normally — hooks, skills, and commands are active."
+fi
+echo ""
+echo "    Plannotator requires the plannotator binary:"
+echo "      curl -fsSL https://plannotator.ai/install.sh | bash"

package/harnesses/claude/merge-settings.cjs

@@ -0,0 +1,71 @@
+// impulso — settings.json merge for shared-profile installs
+//
+// Installing into an existing profile (e.g. ~/.claude) must not clobber the
+// user's settings.json. mergeSettings() strips any previous impulso hook
+// entries (recognized by their harnesses/claude/hooks/ path) and appends the
+// current ones, leaving every foreign key and foreign hook untouched.
+// Idempotent: re-running the install replaces impulso entries in place.
+//
+// Also usable as a CLI (used by install.sh/uninstall.sh):
+//   node merge-settings.cjs <target-settings.json> <impulso-settings.json>
+//   node merge-settings.cjs --remove <target-settings.json>
+// Writes the merged result back to <target-settings.json>.
+
+const fs = require('node:fs');
+
+const IMPULSO_MARKER = 'harnesses/claude/hooks/';
+
+function isImpulsoHook(h) {
+  return h && typeof h.command === 'string' && h.command.includes(IMPULSO_MARKER);
+}
+
+// Remove impulso hook entries from a settings object (in a copy).
+// Drops matchers and events that end up empty.
+function stripImpulsoHooks(settings) {
+  const out = JSON.parse(JSON.stringify(settings || {}));
+  if (!out.hooks) return out;
+  for (const event of Object.keys(out.hooks)) {
+    const matchers = (out.hooks[event] || [])
+      .map((m) => ({ ...m, hooks: (m.hooks || []).filter((h) => !isImpulsoHook(h)) }))
+      .filter((m) => m.hooks.length > 0);
+    if (matchers.length > 0) {
+      out.hooks[event] = matchers;
+    } else {
+      delete out.hooks[event];
+    }
+  }
+  if (Object.keys(out.hooks).length === 0) delete out.hooks;
+  return out;
+}
+
+function mergeSettings(existing, impulso) {
+  const out = stripImpulsoHooks(existing);
+  out.hooks = out.hooks || {};
+  for (const [event, matchers] of Object.entries(impulso.hooks || {})) {
+    out.hooks[event] = [...(out.hooks[event] || []), ...JSON.parse(JSON.stringify(matchers))];
+  }
+  return out;
+}
+
+module.exports = { mergeSettings, stripImpulsoHooks };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const remove = args[0] === '--remove';
+  const targetPath = remove ? args[1] : args[0];
+  const impulsoPath = remove ? null : args[1];
+  if (!targetPath || (!remove && !impulsoPath)) {
+    console.error('usage: merge-settings.cjs <target> <impulso> | --remove <target>');
+    process.exit(1);
+  }
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  } catch (e) {
+    // Missing or empty target — start fresh.
+  }
+  const result = remove
+    ? stripImpulsoHooks(existing)
+    : mergeSettings(existing, JSON.parse(fs.readFileSync(impulsoPath, 'utf8')));
+  fs.writeFileSync(targetPath, JSON.stringify(result, null, 2) + '\n');
+}