feed-the-machine 1.2.0 → 1.3.0

package/bin/install.mjs

@@ -3,8 +3,13 @@
 /**
  * npx feed-the-machine — installs ftm skills into ~/.claude/skills/
  *
- * Works by finding the npm package root (where the skill files live)
- * and symlinking them into the Claude Code skills directory.
+ * Full install: skills, hooks, settings.json merge, and verification.
+ * Safe to re-run — idempotent.
+ *
+ * Flags:
+ *   --with-inbox    Also install the inbox service
+ *   --no-hooks      Skip hooks entirely
+ *   --skip-merge    Install hook files but don't touch settings.json
  */
 
 import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
@@ -21,15 +26,25 @@ const SKILLS_DIR = join(HOME, ".claude", "skills");
 const STATE_DIR = join(HOME, ".claude", "ftm-state");
 const CONFIG_DIR = join(HOME, ".claude");
 const HOOKS_DIR = join(HOME, ".claude", "hooks");
+const SETTINGS_FILE = join(CONFIG_DIR, "settings.json");
 const INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
 
 const ARGS = process.argv.slice(2);
 const WITH_INBOX = ARGS.includes("--with-inbox");
+const NO_HOOKS = ARGS.includes("--no-hooks");
+const SKIP_MERGE = ARGS.includes("--skip-merge");
+
+let warnCount = 0;
 
 function log(msg) {
   console.log(`  ${msg}`);
 }
 
+function warn(msg) {
+  console.log(`  WARN: ${msg}`);
+  warnCount++;
+}
+
 function ensureDir(dir) {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
@@ -52,7 +67,212 @@ function safeSymlink(src, dest) {
   log(`LINK ${name}`);
 }
 
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandVersion(cmd, flag = "--version") {
+  try {
+    return execSync(`${cmd} ${flag}`, { encoding: "utf8" }).trim().split("\n")[0];
+  } catch {
+    return "unknown";
+  }
+}
+
+// --- Preflight ---
+
+function preflight() {
+  console.log("Preflight checks...");
+
+  if (!NO_HOOKS) {
+    // jq is required for all shell hooks (they parse JSON stdin via jq)
+    if (!commandExists("jq")) {
+      console.log("");
+      console.log("  ERROR: jq is required for FTM hooks.");
+      console.log("");
+      console.log("  Install it:");
+      console.log("    macOS:   brew install jq");
+      console.log("    Ubuntu:  sudo apt-get install jq");
+      console.log("    Alpine:  apk add jq");
+      console.log("");
+      console.log("  Or skip hooks: npx feed-the-machine --no-hooks");
+      process.exit(1);
+    }
+    log(`jq: ${commandVersion("jq")}`);
+    log(`node: ${process.version}`);
+  } else {
+    log("hooks skipped (--no-hooks)");
+  }
+
+  console.log("");
+}
+
+// --- Settings Merge ---
+
+function mergeHooksIntoSettings() {
+  const templatePath = join(REPO_DIR, "hooks", "settings-template.json");
+  if (!existsSync(templatePath)) {
+    warn("hooks/settings-template.json not found — hooks installed but not registered");
+    return;
+  }
+
+  console.log("");
+  console.log("Registering hooks in settings.json...");
+
+  // Read and expand ~ to actual home directory
+  const rawTemplate = readFileSync(templatePath, "utf8");
+  const expandedTemplate = rawTemplate.replace(/~\/.claude/g, join(HOME, ".claude"));
+  const template = JSON.parse(expandedTemplate);
+  const templateHooks = template.hooks || {};
+
+  if (!existsSync(SETTINGS_FILE)) {
+    // No settings.json — create one with just the hooks
+    writeFileSync(SETTINGS_FILE, JSON.stringify({ hooks: templateHooks }, null, 2) + "\n");
+    log("CREATED settings.json with FTM hooks");
+    return;
+  }
+
+  // Read existing settings
+  const existing = JSON.parse(readFileSync(SETTINGS_FILE, "utf8"));
+
+  // Backup
+  const ts = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  const backupPath = `${SETTINGS_FILE}.ftm-backup-${ts}`;
+  copyFileSync(SETTINGS_FILE, backupPath);
+  log(`BACKUP ${backupPath}`);
+
+  // Ensure hooks key exists
+  if (!existing.hooks) {
+    existing.hooks = {};
+  }
+
+  // Merge each event type
+  const events = ["PreToolUse", "UserPromptSubmit", "PostToolUse", "Stop"];
+  for (const event of events) {
+    const templateEntries = templateHooks[event] || [];
+    const existingEntries = existing.hooks[event] || [];
+
+    if (templateEntries.length === 0) continue;
+
+    // Check if FTM hooks are already present by looking for ftm- in command paths
+    const existingCommands = JSON.stringify(existingEntries);
+    const alreadyPresent = templateEntries.some((entry) => {
+      const hooks = entry.hooks || [];
+      return hooks.some((h) => {
+        const cmd = h.command || "";
+        const cmdBase = basename(cmd.split(" ").pop()); // handle "node foo.mjs"
+        return existingCommands.includes(cmdBase);
+      });
+    });
+
+    if (alreadyPresent) {
+      log(`SKIP ${event} hooks (already configured)`);
+      continue;
+    }
+
+    existing.hooks[event] = [...existingEntries, ...templateEntries];
+    log(`MERGE ${event} hooks`);
+  }
+
+  writeFileSync(SETTINGS_FILE, JSON.stringify(existing, null, 2) + "\n");
+  log("UPDATED settings.json");
+  console.log("");
+  log("Hooks are active.");
+}
+
+// --- Verification ---
+
+function verify(skillCount, hookCount) {
+  console.log("");
+  console.log("Verifying installation...");
+
+  let errors = 0;
+
+  // Check skill symlinks resolve
+  let brokenLinks = 0;
+  const skillEntries = readdirSync(SKILLS_DIR).filter((f) => f.startsWith("ftm"));
+  for (const entry of skillEntries) {
+    const fullPath = join(SKILLS_DIR, entry);
+    try {
+      if (lstatSync(fullPath).isSymbolicLink() && !existsSync(fullPath)) {
+        warn(`broken symlink: ${entry}`);
+        brokenLinks++;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  if (brokenLinks === 0) {
+    log(`Skills: ${skillCount} linked, all symlinks valid`);
+  } else {
+    errors++;
+  }
+
+  // Check blackboard state
+  const contextFile = join(STATE_DIR, "blackboard", "context.json");
+  const patternsFile = join(STATE_DIR, "blackboard", "patterns.json");
+  if (existsSync(contextFile) && existsSync(patternsFile)) {
+    log("Blackboard: initialized");
+  } else {
+    warn("blackboard state incomplete");
+    errors++;
+  }
+
+  // Check config
+  if (existsSync(join(CONFIG_DIR, "ftm-config.yml"))) {
+    log("Config: present");
+  } else {
+    warn("ftm-config.yml missing");
+    errors++;
+  }
+
+  // Check hooks
+  if (!NO_HOOKS && hookCount > 0) {
+    const hookFiles = readdirSync(HOOKS_DIR).filter((f) => f.startsWith("ftm-"));
+    const allExecutable = hookFiles
+      .filter((f) => f.endsWith(".sh"))
+      .every((f) => {
+        try {
+          const stat = lstatSync(join(HOOKS_DIR, f));
+          return (stat.mode & 0o111) !== 0;
+        } catch {
+          return false;
+        }
+      });
+
+    if (allExecutable) {
+      log(`Hooks: ${hookCount} installed, all executable`);
+    } else {
+      warn("some hook files not executable");
+      errors++;
+    }
+
+    // Verify settings.json has FTM hooks
+    if (!SKIP_MERGE && existsSync(SETTINGS_FILE)) {
+      const settingsContent = readFileSync(SETTINGS_FILE, "utf8");
+      const ftmMatches = (settingsContent.match(/ftm-/g) || []).length;
+      if (ftmMatches > 0) {
+        log(`Settings: ${ftmMatches} FTM entries in settings.json`);
+      } else {
+        warn("no FTM hooks found in settings.json");
+        errors++;
+      }
+    }
+  }
+
+  return { errors };
+}
+
+// --- Main ---
+
 function main() {
+  preflight();
+
   console.log(`Installing ftm skills from: ${REPO_DIR}`);
   console.log(`Linking into: ${SKILLS_DIR}`);
   console.log("");
@@ -82,9 +302,13 @@ function main() {
     safeSymlink(join(REPO_DIR, dir), join(SKILLS_DIR, dir));
   }
 
+  console.log("");
+  log(`${ymlFiles.length} skills linked.`);
+
   // Set up blackboard state (copy templates, don't overwrite existing data)
   const bbDir = join(REPO_DIR, "ftm-state", "blackboard");
   if (existsSync(bbDir)) {
+    console.log("");
     ensureDir(join(STATE_DIR, "blackboard", "experiences"));
 
     const jsonFiles = readdirSync(bbDir).filter((f) => f.endsWith(".json"));
@@ -113,39 +337,62 @@ function main() {
   }
 
   // Install hooks
-  const hooksDir = join(REPO_DIR, "hooks");
   let hookCount = 0;
-  if (existsSync(hooksDir)) {
-    ensureDir(HOOKS_DIR);
+
+  if (NO_HOOKS) {
     console.log("");
-    console.log("Installing hooks...");
-
-    const hookFiles = readdirSync(hooksDir).filter(
-      (f) => f.startsWith("ftm-") && (f.endsWith(".sh") || f.endsWith(".mjs"))
-    );
-    for (const hook of hookFiles) {
-      const src = join(hooksDir, hook);
-      const dest = join(HOOKS_DIR, hook);
-      const action = existsSync(dest) ? "UPDATE" : "INSTALL";
-      copyFileSync(src, dest);
-      if (hook.endsWith(".sh")) {
-        chmodSync(dest, 0o755);
+    console.log("Skipping hooks (--no-hooks).");
+  } else {
+    const hooksDir = join(REPO_DIR, "hooks");
+    if (existsSync(hooksDir)) {
+      ensureDir(HOOKS_DIR);
+      console.log("");
+      console.log("Installing hooks...");
+
+      const hookFiles = readdirSync(hooksDir).filter(
+        (f) => f.startsWith("ftm-") && (f.endsWith(".sh") || f.endsWith(".mjs"))
+      );
+      for (const hook of hookFiles) {
+        const src = join(hooksDir, hook);
+        const dest = join(HOOKS_DIR, hook);
+        const action = existsSync(dest) ? "UPDATE" : "INSTALL";
+        copyFileSync(src, dest);
+        if (hook.endsWith(".sh")) {
+          chmodSync(dest, 0o755);
+        }
+        log(`${action} ${hook}`);
+        hookCount++;
       }
-      log(`${action} ${hook}`);
-      hookCount++;
+
+      console.log("");
+      log(`${hookCount} hooks installed to ${HOOKS_DIR}`);
+    }
+
+    // Merge hooks into settings.json
+    if (SKIP_MERGE) {
+      console.log("");
+      log("Skipping settings.json merge (--skip-merge).");
+      log("Add entries from hooks/settings-template.json to ~/.claude/settings.json manually.");
+    } else {
+      mergeHooksIntoSettings();
     }
   }
 
+  // Verification
+  const { errors } = verify(ymlFiles.length, hookCount);
+
+  // Summary
   console.log("");
-  console.log(`Done. ${ymlFiles.length} skills linked, ${hookCount} hooks installed.`);
-  console.log("");
-  console.log("To activate hooks, add them to ~/.claude/settings.json");
-  console.log("  Option A: ./install.sh --setup-hooks (auto-merge)");
-  console.log("  Option B: Copy entries from hooks/settings-template.json manually");
-  console.log("  See docs/HOOKS.md for details.");
+  if (errors === 0 && warnCount === 0) {
+    console.log(`Done. ${ymlFiles.length} skills, ${hookCount} hooks. Everything checks out.`);
+  } else {
+    console.log(`Done. ${ymlFiles.length} skills, ${hookCount} hooks. ${warnCount} warning(s).`);
+  }
   console.log("");
+  console.log("Restart Claude Code (or start a new session) to pick up the skills.");
 
   if (WITH_INBOX) {
+    console.log("");
     installInbox();
   } else {
     console.log("Try: /ftm help");

package/hooks/ftm-blackboard-enforcer.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
 # ftm-blackboard-enforcer.sh
-# Stop hook that checks if meaningful work was done but no blackboard
-# experience was recorded. If so, blocks the stop and tells Claude
-# to write the experience first.
+# Stop hook that nudges Claude to record an experience if meaningful work
+# was done but no blackboard entry was written.
 #
-# "Meaningful work" = 3+ tool uses detected by the edit counter,
+# Uses additionalContext (not "decision: block") so Claude can still act on
+# the reminder. A blocking stop creates a deadlock — Claude can't write files
+# after the user ends the conversation.
+#
+# "Meaningful work" = 3+ edits tracked by the edit counter,
 # or ftm skills were invoked (checked via context.json).
 #
 # Hook: Stop
@@ -13,29 +16,23 @@ set -euo pipefail
 
 INPUT=$(cat)
 
-# Prevent infinite loop — if this hook already fired, let Claude stop
-STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
-if [[ "$STOP_HOOK_ACTIVE" == "true" ]]; then
-  exit 0
-fi
-
 STATE_DIR="$HOME/.claude/ftm-state"
 BB_DIR="$STATE_DIR/blackboard"
 EDIT_COUNTER="$STATE_DIR/.edit-count"
 CONTEXT_FILE="$BB_DIR/context.json"
 EXPERIENCES_DIR="$BB_DIR/experiences"
-EXPERIENCE_INDEX="$EXPERIENCES_DIR/index.json"
-
-CURRENT_SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
 # Check 1: Were there meaningful edits this session?
+# Edit counter contains just a number now (no session ID).
+# If the counter file is recent (< 4 hours) and >= 3, count as meaningful.
 HAD_EDITS=false
 if [[ -f "$EDIT_COUNTER" ]]; then
-  STORED=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0:unknown")
-  STORED_SESSION=$(echo "$STORED" | cut -d: -f2)
-  STORED_COUNT=$(echo "$STORED" | cut -d: -f1)
-  if [[ "$STORED_SESSION" == "$CURRENT_SESSION" && "$STORED_COUNT" -ge 3 ]]; then
-    HAD_EDITS=true
+  COUNTER_AGE=$(( $(date +%s) - $(stat -c %Y "$EDIT_COUNTER" 2>/dev/null || stat -f %m "$EDIT_COUNTER" 2>/dev/null || echo "0") ))
+  if [[ "$COUNTER_AGE" -lt 14400 ]]; then
+    STORED_COUNT=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0")
+    if [[ "$STORED_COUNT" -ge 3 ]]; then
+      HAD_EDITS=true
+    fi
   fi
 fi
 
@@ -48,8 +45,10 @@ if [[ -f "$CONTEXT_FILE" ]]; then
   fi
 fi
 
-# If no meaningful work detected, allow stop
+# If no meaningful work detected, allow stop quietly
 if [[ "$HAD_EDITS" == "false" && "$HAD_SKILLS" == "false" ]]; then
+  # Clean up session markers
+  rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
   exit 0
 fi
 
@@ -58,19 +57,17 @@ TODAY=$(date +%Y-%m-%d)
 HAS_EXPERIENCE=false
 
 if [[ -d "$EXPERIENCES_DIR" ]]; then
-  # Check for experience files created today
   TODAY_EXPERIENCE=$(find "$EXPERIENCES_DIR" -name "${TODAY}*" -type f 2>/dev/null | head -1)
   if [[ -n "$TODAY_EXPERIENCE" ]]; then
     HAS_EXPERIENCE=true
   fi
 fi
 
-# Also check if context.json was updated this session (recent_decisions not empty)
+# Also check if context.json was updated today (recent_decisions not empty)
 if [[ -f "$CONTEXT_FILE" ]]; then
   DECISIONS_COUNT=$(jq -r '.recent_decisions | length' "$CONTEXT_FILE" 2>/dev/null || echo "0")
   LAST_UPDATED=$(jq -r '.session_metadata.last_updated // ""' "$CONTEXT_FILE" 2>/dev/null || echo "")
   if [[ "$DECISIONS_COUNT" -gt 0 && -n "$LAST_UPDATED" ]]; then
-    # Check if last_updated is from today
     if [[ "$LAST_UPDATED" == *"$TODAY"* ]]; then
       HAS_EXPERIENCE=true
     fi
@@ -78,17 +75,21 @@ if [[ -f "$CONTEXT_FILE" ]]; then
 fi
 
 if [[ "$HAS_EXPERIENCE" == "true" ]]; then
-  # Blackboard was written, allow stop
-  # Clean up session markers
+  # Blackboard was written, clean up and allow stop
   rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
   exit 0
 fi
 
-# Work was done but no blackboard write — block the stop
+# Work was done but no blackboard write — nudge (don't block)
 cat <<'JSON'
 {
-  "decision": "block",
-  "reason": "[ftm-blackboard-enforcer] You did meaningful work this session (3+ edits or ftm skills used) but did not record an experience to the blackboard. Before stopping, you MUST: (1) Update ~/.claude/ftm-state/blackboard/context.json with current_task status and recent_decisions. (2) Write an experience file to ~/.claude/ftm-state/blackboard/experiences/ with task_type, tags, outcome, lessons, files_touched, stakeholders, and decisions_made. (3) Update ~/.claude/ftm-state/blackboard/experiences/index.json with the new entry. This is how ftm learns — skipping it means the next session starts from zero."
+  "hookSpecificOutput": {
+    "hookEventName": "Stop",
+    "additionalContext": "[ftm-blackboard-enforcer] You did meaningful work this session but did not record an experience to the blackboard. Before finishing, please: (1) Update ~/.claude/ftm-state/blackboard/context.json with current_task status and recent_decisions. (2) Write an experience file to ~/.claude/ftm-state/blackboard/experiences/ with task_type, tags, outcome, and lessons. (3) Update ~/.claude/ftm-state/blackboard/experiences/index.json with the new entry. This is how ftm learns — skipping it means the next session starts from zero."
+  }
 }
 JSON
+
+# Clean up session markers regardless — don't let stale state carry over
+rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
 exit 0

package/hooks/ftm-plan-gate.sh

@@ -2,14 +2,13 @@
 # ftm-plan-gate.sh
 # PreToolUse hook for Edit/Write tools.
 #
-# Checks if a plan has been presented and approved for this session before
-# allowing code edits. If no plan marker exists and the session involves
-# a medium+ task (detected by ftm-state), injects additionalContext
+# Checks if a plan has been presented this session before allowing code edits.
+# If no plan marker exists and the edit count is climbing, injects warnings
 # telling Claude to stop and present a plan first.
 #
-# The marker file is created by Claude when it presents a plan — we check
-# for it here. If the marker doesn't exist but edits are happening, it
-# means Claude skipped the planning step.
+# The marker file (~/.claude/ftm-state/.plan-presented) is created by Claude
+# when it presents a plan. Any non-empty content counts as "plan presented".
+# The file is cleaned up by the blackboard enforcer at session end.
 #
 # Hook: PreToolUse (matcher: Edit|Write)
 
@@ -25,9 +24,7 @@ fi
 
 STATE_DIR="$HOME/.claude/ftm-state"
 PLAN_MARKER="$STATE_DIR/.plan-presented"
-SESSION_MARKER="$STATE_DIR/.session-id"
 EDIT_COUNTER="$STATE_DIR/.edit-count"
-SKILL_FILES_DIR="$HOME/.claude/skills"
 
 # Get the file being edited
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
@@ -47,37 +44,36 @@ if [[ "$FILE_PATH" == *".claude/skills/"* ]] || \
   exit 0
 fi
 
-# If plan marker exists and matches current session, allow
-CURRENT_SESSION="${CLAUDE_SESSION_ID:-unknown}"
-if [[ -f "$PLAN_MARKER" ]]; then
-  MARKER_SESSION=$(cat "$PLAN_MARKER" 2>/dev/null || echo "")
-  if [[ "$MARKER_SESSION" == "$CURRENT_SESSION" ]]; then
-    exit 0  # Plan was presented this session, allow edits
+# If plan marker exists (any content), allow edits
+if [[ -f "$PLAN_MARKER" ]] && [[ -s "$PLAN_MARKER" ]]; then
+  exit 0
+fi
+
+# Reset edit counter if it's stale (older than 4 hours = likely a new session)
+if [[ -f "$EDIT_COUNTER" ]]; then
+  COUNTER_AGE=$(( $(date +%s) - $(stat -c %Y "$EDIT_COUNTER" 2>/dev/null || echo "0") ))
+  if [[ "$COUNTER_AGE" -gt 14400 ]]; then
+    rm -f "$EDIT_COUNTER"
   fi
 fi
 
-# Count edits this session (without a plan marker)
+# Count edits without a plan marker
 EDIT_COUNT=0
 if [[ -f "$EDIT_COUNTER" ]]; then
-  STORED=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0:unknown")
-  STORED_SESSION=$(echo "$STORED" | cut -d: -f2)
-  if [[ "$STORED_SESSION" == "$CURRENT_SESSION" ]]; then
-    EDIT_COUNT=$(echo "$STORED" | cut -d: -f1)
-  fi
+  EDIT_COUNT=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0")
 fi
 
 EDIT_COUNT=$((EDIT_COUNT + 1))
-echo "${EDIT_COUNT}:${CURRENT_SESSION}" > "$EDIT_COUNTER"
+echo "$EDIT_COUNT" > "$EDIT_COUNTER"
 
-# First 2 edits get a warning injected as context (don't block — could be micro tasks)
+# First 2 edits get a soft reminder (don't block — could be micro tasks)
 # After 3+ edits without a plan marker, escalate the warning
 if [[ $EDIT_COUNT -le 2 ]]; then
-  # Soft reminder — inject context but allow
   cat <<'JSON'
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
-    "additionalContext": "[ftm-plan-gate] You are editing files without having presented a plan this session. If this task is medium+ (touches 3+ files, involves external systems, or has stakeholder coordination), you MUST present a numbered plan and get user approval BEFORE editing code. If this is a micro/small task, you can proceed — but create the plan marker by writing the current session ID to ~/.claude/ftm-state/.plan-presented after confirming the task is genuinely small. To create the marker: Write tool → ~/.claude/ftm-state/.plan-presented with content being the session ID."
+    "additionalContext": "[ftm-plan-gate] You are editing files without having presented a plan this session. If this task is medium+ (touches 3+ files, involves external systems, or has stakeholder coordination), you MUST present a numbered plan and get user approval BEFORE editing code. If this is a micro/small task, you can proceed — but create the plan marker: write any content to ~/.claude/ftm-state/.plan-presented to acknowledge you've considered it."
   }
 }
 JSON
@@ -89,7 +85,7 @@ cat <<'JSON'
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
-    "additionalContext": "[ftm-plan-gate WARNING] You have made 3+ file edits this session without presenting a plan. This is exactly the 'grinding without a plan' pattern that ftm-mind is supposed to prevent. STOP editing and do one of: (1) Present a numbered plan to the user and wait for approval, then write the session ID to ~/.claude/ftm-state/.plan-presented. (2) If the user explicitly said 'just do it' or this is genuinely a micro task, write the plan marker to acknowledge you've considered it. Do NOT continue editing without addressing this."
+    "additionalContext": "[ftm-plan-gate WARNING] You have made 3+ file edits this session without presenting a plan. This is exactly the 'grinding without a plan' pattern that ftm-mind is supposed to prevent. STOP editing and do one of: (1) Present a numbered plan to the user and wait for approval, then write any content to ~/.claude/ftm-state/.plan-presented. (2) If the user explicitly said 'just do it' or this is genuinely a micro task, write the plan marker to acknowledge you've considered it. Do NOT continue editing without addressing this."
   }
 }
 JSON

package/install.sh

@@ -3,11 +3,13 @@ set -euo pipefail
 
 # FTM Skills Installer
 # Creates symlinks from this repo into ~/.claude/skills/ so slash commands work.
-# Safe to re-run — idempotent. Run after cloning or adding new skills.
+# Installs hooks, merges them into settings.json, and verifies the result.
+# Safe to re-run — idempotent.
 #
 # Usage:
-#   ./install.sh              # Install skills, hooks, and state templates
-#   ./install.sh --setup-hooks  # Also merge hook config into settings.json
+#   ./install.sh              # Full install (skills + hooks + settings merge)
+#   ./install.sh --no-hooks   # Skills and state only, skip hooks entirely
+#   ./install.sh --skip-merge # Install hook files but don't touch settings.json
 
 REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILLS_DIR="$HOME/.claude/skills"
@@ -16,13 +18,64 @@ CONFIG_DIR="$HOME/.claude"
 HOOKS_DIR="$HOME/.claude/hooks"
 SETTINGS_FILE="$CONFIG_DIR/settings.json"
 
-SETUP_HOOKS=false
+NO_HOOKS=false
+SKIP_MERGE=false
 for arg in "$@"; do
   case "$arg" in
-    --setup-hooks) SETUP_HOOKS=true ;;
+    --no-hooks) NO_HOOKS=true ;;
+    --skip-merge) SKIP_MERGE=true ;;
+    # Keep --setup-hooks for backwards compat (now a no-op since merge is default)
+    --setup-hooks) ;;
   esac
 done
 
+WARN_COUNT=0
+warn() {
+  echo "  WARN: $1"
+  WARN_COUNT=$((WARN_COUNT + 1))
+}
+
+# --- Preflight Checks ---
+
+echo "Preflight checks..."
+
+# Check jq (required for hooks and settings merge)
+if ! command -v jq &>/dev/null; then
+  if [ "$NO_HOOKS" = true ]; then
+    echo "  jq not found (ok — hooks skipped)"
+  else
+    echo ""
+    echo "  ERROR: jq is required for FTM hooks."
+    echo ""
+    echo "  Install it:"
+    echo "    macOS:   brew install jq"
+    echo "    Ubuntu:  sudo apt-get install jq"
+    echo "    Alpine:  apk add jq"
+    echo ""
+    echo "  Or skip hooks: ./install.sh --no-hooks"
+    exit 1
+  fi
+else
+  echo "  jq: $(jq --version)"
+fi
+
+# Check node (required for event logger hook)
+if ! command -v node &>/dev/null; then
+  if [ "$NO_HOOKS" = true ]; then
+    echo "  node not found (ok — hooks skipped)"
+  else
+    echo ""
+    echo "  ERROR: Node.js is required for the FTM event logger hook."
+    echo ""
+    echo "  Install it: https://nodejs.org/"
+    echo "  Or skip hooks: ./install.sh --no-hooks"
+    exit 1
+  fi
+else
+  echo "  node: $(node --version)"
+fi
+
+echo ""
 echo "Installing FTM skills from: $REPO_DIR"
 echo "Linking into: $SKILLS_DIR"
 echo ""
@@ -98,134 +151,208 @@ fi
 
 # --- Hooks ---
 
-echo ""
-echo "Installing hooks..."
-
-if [ -d "$REPO_DIR/hooks" ]; then
-  mkdir -p "$HOOKS_DIR"
-  HOOK_COUNT=0
-
-  # Install shell hooks
-  for hook in "$REPO_DIR/hooks"/ftm-*.sh; do
-    [ -f "$hook" ] || continue
-    name=$(basename "$hook")
-    target="$HOOKS_DIR/$name"
-    if [ -f "$target" ]; then
-      cp "$hook" "$target"
-      chmod +x "$target"
-      echo "  UPDATE $name"
-    else
-      cp "$hook" "$target"
-      chmod +x "$target"
-      echo "  INSTALL $name"
-    fi
-    HOOK_COUNT=$((HOOK_COUNT + 1))
-  done
-
-  # Install Node.js hooks
-  for hook in "$REPO_DIR/hooks"/ftm-*.mjs; do
-    [ -f "$hook" ] || continue
-    name=$(basename "$hook")
-    target="$HOOKS_DIR/$name"
-    if [ -f "$target" ]; then
-      cp "$hook" "$target"
-      echo "  UPDATE $name"
-    else
-      cp "$hook" "$target"
-      echo "  INSTALL $name"
-    fi
-    HOOK_COUNT=$((HOOK_COUNT + 1))
-  done
+HOOK_COUNT=0
 
+if [ "$NO_HOOKS" = true ]; then
   echo ""
-  echo "  $HOOK_COUNT hooks installed to $HOOKS_DIR"
-fi
-
-# --- Hook Config Merge (--setup-hooks) ---
-
-if [ "$SETUP_HOOKS" = true ]; then
+  echo "Skipping hooks (--no-hooks)."
+else
   echo ""
-  echo "Setting up hook configuration in settings.json..."
+  echo "Installing hooks..."
+
+  if [ -d "$REPO_DIR/hooks" ]; then
+    mkdir -p "$HOOKS_DIR"
+
+    # Install shell hooks
+    for hook in "$REPO_DIR/hooks"/ftm-*.sh; do
+      [ -f "$hook" ] || continue
+      name=$(basename "$hook")
+      target="$HOOKS_DIR/$name"
+      if [ -f "$target" ]; then
+        cp "$hook" "$target"
+        chmod +x "$target"
+        echo "  UPDATE $name"
+      else
+        cp "$hook" "$target"
+        chmod +x "$target"
+        echo "  INSTALL $name"
+      fi
+      HOOK_COUNT=$((HOOK_COUNT + 1))
+    done
 
-  TEMPLATE="$REPO_DIR/hooks/settings-template.json"
-  if [ ! -f "$TEMPLATE" ]; then
-    echo "  ERROR: hooks/settings-template.json not found"
-    exit 1
-  fi
+    # Install Node.js hooks
+    for hook in "$REPO_DIR/hooks"/ftm-*.mjs; do
+      [ -f "$hook" ] || continue
+      name=$(basename "$hook")
+      target="$HOOKS_DIR/$name"
+      if [ -f "$target" ]; then
+        cp "$hook" "$target"
+        echo "  UPDATE $name"
+      else
+        cp "$hook" "$target"
+        echo "  INSTALL $name"
+      fi
+      HOOK_COUNT=$((HOOK_COUNT + 1))
+    done
 
-  if ! command -v jq &>/dev/null; then
-    echo "  ERROR: jq is required for --setup-hooks. Install with: brew install jq"
-    exit 1
+    echo ""
+    echo "  $HOOK_COUNT hooks installed to $HOOKS_DIR"
   fi
 
-  # Expand ~ to $HOME in the template (jq doesn't expand shell paths)
-  EXPANDED_TEMPLATE=$(sed "s|~/.claude|$HOME/.claude|g" "$TEMPLATE")
+  # --- Hook Config Merge (default behavior now) ---
 
-  if [ ! -f "$SETTINGS_FILE" ]; then
-    # No settings.json — create one from the template hooks section
-    echo "$EXPANDED_TEMPLATE" | jq '{hooks: .hooks}' > "$SETTINGS_FILE"
-    echo "  CREATED $SETTINGS_FILE with FTM hooks"
+  if [ "$SKIP_MERGE" = true ]; then
+    echo ""
+    echo "  Skipping settings.json merge (--skip-merge)."
+    echo "  Add entries from hooks/settings-template.json to ~/.claude/settings.json manually."
   else
-    # Merge FTM hooks into existing settings.json
-    # Strategy: for each hook event type, append FTM entries that don't already exist
-    BACKUP="$SETTINGS_FILE.ftm-backup-$(date +%Y%m%d%H%M%S)"
-    cp "$SETTINGS_FILE" "$BACKUP"
-    echo "  BACKUP $BACKUP"
+    echo ""
+    echo "Registering hooks in settings.json..."
 
-    # Extract the hooks section from the template
-    TEMPLATE_HOOKS=$(echo "$EXPANDED_TEMPLATE" | jq '.hooks')
+    TEMPLATE="$REPO_DIR/hooks/settings-template.json"
+    if [ ! -f "$TEMPLATE" ]; then
+      warn "hooks/settings-template.json not found — hooks installed but not registered"
+    else
+      # Expand ~ to $HOME in the template (jq doesn't expand shell paths)
+      EXPANDED_TEMPLATE=$(sed "s|~/.claude|$HOME/.claude|g" "$TEMPLATE")
+
+      if [ ! -f "$SETTINGS_FILE" ]; then
+        # No settings.json — create one from the template hooks section
+        echo "$EXPANDED_TEMPLATE" | jq '{hooks: .hooks}' > "$SETTINGS_FILE"
+        echo "  CREATED $SETTINGS_FILE with FTM hooks"
+      else
+        # Merge FTM hooks into existing settings.json
+        BACKUP="$SETTINGS_FILE.ftm-backup-$(date +%Y%m%d%H%M%S)"
+        cp "$SETTINGS_FILE" "$BACKUP"
+        echo "  BACKUP $BACKUP"
+
+        # Extract the hooks section from the template
+        TEMPLATE_HOOKS=$(echo "$EXPANDED_TEMPLATE" | jq '.hooks')
+
+        # Read existing settings
+        EXISTING=$(cat "$SETTINGS_FILE")
+
+        # Ensure hooks key exists
+        if echo "$EXISTING" | jq -e '.hooks' >/dev/null 2>&1; then
+          : # hooks key exists
+        else
+          EXISTING=$(echo "$EXISTING" | jq '. + {hooks: {}}')
+        fi
 
-    # Read existing settings
-    EXISTING=$(cat "$SETTINGS_FILE")
+        # Merge each hook event type
+        for EVENT in PreToolUse UserPromptSubmit PostToolUse Stop; do
+          TEMPLATE_ENTRIES=$(echo "$TEMPLATE_HOOKS" | jq --arg e "$EVENT" '.[$e] // []')
+          EXISTING_ENTRIES=$(echo "$EXISTING" | jq --arg e "$EVENT" '.hooks[$e] // []')
+
+          # Check if any FTM hooks are already present (by checking command paths)
+          FTM_COMMANDS=$(echo "$TEMPLATE_ENTRIES" | jq -r '.[].hooks[]?.command // empty' 2>/dev/null)
+          ALREADY_PRESENT=false
+
+          for cmd in $FTM_COMMANDS; do
+            cmd_basename=$(basename "$cmd")
+            if echo "$EXISTING_ENTRIES" | jq -r '.[].hooks[]?.command // empty' 2>/dev/null | grep -q "$cmd_basename"; then
+              ALREADY_PRESENT=true
+              break
+            fi
+          done
+
+          if [ "$ALREADY_PRESENT" = true ]; then
+            echo "  SKIP $EVENT hooks (already configured)"
+            continue
+          fi
+
+          # Append template entries to existing
+          MERGED=$(jq -n --argjson existing "$EXISTING_ENTRIES" --argjson template "$TEMPLATE_ENTRIES" '$existing + $template')
+          EXISTING=$(echo "$EXISTING" | jq --arg e "$EVENT" --argjson m "$MERGED" '.hooks[$e] = $m')
+          echo "  MERGE $EVENT hooks"
+        done
+
+        echo "$EXISTING" | jq '.' > "$SETTINGS_FILE"
+        echo "  UPDATED $SETTINGS_FILE"
+      fi
 
-    # Ensure hooks key exists
-    if echo "$EXISTING" | jq -e '.hooks' >/dev/null 2>&1; then
-      : # hooks key exists
-    else
-      EXISTING=$(echo "$EXISTING" | jq '. + {hooks: {}}')
+      echo ""
+      echo "  Hooks are active."
     fi
+  fi
+fi
 
-    # Merge each hook event type
-    for EVENT in PreToolUse UserPromptSubmit PostToolUse Stop; do
-      TEMPLATE_ENTRIES=$(echo "$TEMPLATE_HOOKS" | jq --arg e "$EVENT" '.[$e] // []')
-      EXISTING_ENTRIES=$(echo "$EXISTING" | jq --arg e "$EVENT" '.hooks[$e] // []')
+# --- Verification ---
 
-      # Check if any FTM hooks are already present (by checking command paths)
-      FTM_COMMANDS=$(echo "$TEMPLATE_ENTRIES" | jq -r '.[].hooks[]?.command // empty' 2>/dev/null)
-      ALREADY_PRESENT=false
+echo ""
+echo "Verifying installation..."
 
-      for cmd in $FTM_COMMANDS; do
-        cmd_basename=$(basename "$cmd")
-        if echo "$EXISTING_ENTRIES" | jq -r '.[].hooks[]?.command // empty' 2>/dev/null | grep -q "$cmd_basename"; then
-          ALREADY_PRESENT=true
-          break
-        fi
-      done
+ERRORS=0
 
-      if [ "$ALREADY_PRESENT" = true ]; then
-        echo "  SKIP $EVENT hooks (already configured)"
-        continue
-      fi
+# Check skill symlinks resolve
+BROKEN_LINKS=0
+for link in "$SKILLS_DIR"/ftm*; do
+  [ -L "$link" ] || continue
+  if [ ! -e "$link" ]; then
+    warn "broken symlink: $link"
+    BROKEN_LINKS=$((BROKEN_LINKS + 1))
+  fi
+done
+if [ "$BROKEN_LINKS" -eq 0 ]; then
+  echo "  Skills: $SKILL_COUNT linked, all symlinks valid"
+else
+  ERRORS=$((ERRORS + 1))
+fi
 
-      # Append template entries to existing
-      MERGED=$(jq -n --argjson existing "$EXISTING_ENTRIES" --argjson template "$TEMPLATE_ENTRIES" '$existing + $template')
-      EXISTING=$(echo "$EXISTING" | jq --arg e "$EVENT" --argjson m "$MERGED" '.hooks[$e] = $m')
-      echo "  MERGE $EVENT hooks"
-    done
+# Check blackboard state
+if [ -f "$STATE_DIR/blackboard/context.json" ] && [ -f "$STATE_DIR/blackboard/patterns.json" ]; then
+  echo "  Blackboard: initialized"
+else
+  warn "blackboard state incomplete"
+  ERRORS=$((ERRORS + 1))
+fi
 
-    echo "$EXISTING" | jq '.' > "$SETTINGS_FILE"
-    echo "  UPDATED $SETTINGS_FILE"
+# Check config
+if [ -f "$CONFIG_DIR/ftm-config.yml" ]; then
+  echo "  Config: present"
+else
+  warn "ftm-config.yml missing"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# Check hooks (if installed)
+if [ "$NO_HOOKS" = false ] && [ "$HOOK_COUNT" -gt 0 ]; then
+  # Verify hook files exist and are executable
+  HOOK_OK=true
+  for hook in "$HOOKS_DIR"/ftm-*.sh; do
+    [ -f "$hook" ] || continue
+    if [ ! -x "$hook" ]; then
+      warn "$(basename "$hook") not executable"
+      HOOK_OK=false
+    fi
+  done
+
+  if [ "$HOOK_OK" = true ]; then
+    echo "  Hooks: $HOOK_COUNT installed, all executable"
+  else
+    ERRORS=$((ERRORS + 1))
   fi
 
-  echo ""
-  echo "  Hooks are now active. See docs/HOOKS.md for details."
-else
-  echo ""
-  echo "  To activate hooks, run: ./install.sh --setup-hooks"
-  echo "  Or manually add entries from hooks/settings-template.json to ~/.claude/settings.json"
-  echo "  See docs/HOOKS.md for details."
+  # Verify settings.json has FTM hooks registered
+  if [ "$SKIP_MERGE" = false ] && [ -f "$SETTINGS_FILE" ]; then
+    FTM_REGISTERED=$(grep -c 'ftm-' "$SETTINGS_FILE" 2>/dev/null || echo "0")
+    if [ "$FTM_REGISTERED" -gt 0 ]; then
+      echo "  Settings: $FTM_REGISTERED FTM entries in settings.json"
+    else
+      warn "no FTM hooks found in settings.json"
+      ERRORS=$((ERRORS + 1))
+    fi
+  fi
 fi
 
+# --- Summary ---
+
+echo ""
+if [ "$ERRORS" -eq 0 ] && [ "$WARN_COUNT" -eq 0 ]; then
+  echo "Done. $SKILL_COUNT skills, $HOOK_COUNT hooks. Everything checks out."
+else
+  echo "Done. $SKILL_COUNT skills, $HOOK_COUNT hooks. $WARN_COUNT warning(s)."
+fi
 echo ""
-echo "Done. $SKILL_COUNT skills, $HOOK_COUNT hooks."
+echo "Restart Claude Code (or start a new session) to pick up the skills."
 echo "Try: /ftm help"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feed-the-machine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A unified intelligence layer for Claude Code — 22 skills with OODA-based reasoning, persistent memory, multi-model deliberation, and optional operator cockpit inbox",
   "license": "MIT",
   "author": "kkudumu",