feed-the-machine 1.0.0 → 1.2.0

package/bin/generate-manifest.mjs

@@ -131,10 +131,214 @@ function extractBlackboardPaths(lines) {
   return paths;
 }
 
+// ---------------------------------------------------------------------------
+// New section parsers for the 6 structured YAML contracts
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses the ## Requirements section.
+ * Format: - type: `name` | required|optional | description
+ * Returns: Array of { type, name, required, description }
+ */
+function parseRequirements(lines) {
+  const requirements = [];
+  // Match lines like: - tool: `knip` | required | static analysis engine
+  // or: - config: `knip.config.ts` | optional | custom knip config
+  const reqRegex = /^-\s+(tool|config|reference|env):\s+`([^`]+)`\s*\|\s*(required|optional)\s*\|\s*(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(reqRegex);
+    if (match) {
+      requirements.push({
+        type: match[1],
+        name: match[2],
+        required: match[3] === 'required',
+        description: match[4].trim(),
+      });
+    }
+  }
+
+  return requirements;
+}
+
+/**
+ * Parses the ## Risk section.
+ * Format:
+ *   - level: read_only | low_write | medium_write | high_write | destructive
+ *   - scope: description
+ *   - rollback: description
+ * Returns: { level, scope, rollback }
+ */
+function parseRisk(lines) {
+  let level = null;
+  let scope = null;
+  let rollback = null;
+
+  for (const line of lines) {
+    const levelMatch = line.match(/^-\s+level:\s+(.+)/);
+    const scopeMatch = line.match(/^-\s+scope:\s+(.+)/);
+    const rollbackMatch = line.match(/^-\s+rollback:\s+(.+)/);
+
+    if (levelMatch) level = levelMatch[1].trim();
+    if (scopeMatch) scope = scopeMatch[1].trim();
+    if (rollbackMatch) rollback = rollbackMatch[1].trim();
+  }
+
+  return { level, scope, rollback };
+}
+
+/**
+ * Parses the ## Approval Gates section.
+ * Format:
+ *   - trigger: condition | action: what happens
+ *   - complexity_routing: micro → auto | small → auto | ...
+ * Returns: { gates: Array<{ trigger, action }>, complexity_routing: object }
+ */
+function parseApprovalGates(lines) {
+  const gates = [];
+  let complexity_routing = null;
+
+  for (const line of lines) {
+    // complexity_routing line
+    const crMatch = line.match(/^-\s+complexity_routing:\s+(.+)/);
+    if (crMatch) {
+      // Parse: micro → auto | small → auto | medium → plan_first | ...
+      const routing = {};
+      const parts = crMatch[1].split('|').map(s => s.trim());
+      for (const part of parts) {
+        const arrowMatch = part.match(/^(\w+)\s+[→>-]+\s+(.+)/);
+        if (arrowMatch) {
+          routing[arrowMatch[1].trim()] = arrowMatch[2].trim();
+        }
+      }
+      complexity_routing = routing;
+      continue;
+    }
+
+    // trigger/action line
+    const triggerMatch = line.match(/^-\s+trigger:\s+(.+?)\s*\|\s*action:\s+(.+)/);
+    if (triggerMatch) {
+      gates.push({
+        trigger: triggerMatch[1].trim(),
+        action: triggerMatch[2].trim(),
+      });
+    }
+  }
+
+  return { gates, complexity_routing };
+}
+
+/**
+ * Parses the ## Fallbacks section.
+ * Format: - condition: description | action: what happens
+ * Returns: Array of { condition, action }
+ */
+function parseFallbacks(lines) {
+  const fallbacks = [];
+  const fallbackRegex = /^-\s+condition:\s+(.+?)\s*\|\s*action:\s+(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(fallbackRegex);
+    if (match) {
+      fallbacks.push({
+        condition: match[1].trim(),
+        action: match[2].trim(),
+      });
+    }
+  }
+
+  return fallbacks;
+}
+
+/**
+ * Parses the ## Capabilities section.
+ * Format: - mcp|cli|env: `name` | required|optional | description
+ * Returns: Array of { type, name, required, description }
+ */
+function parseCapabilities(lines) {
+  const capabilities = [];
+  const capRegex = /^-\s+(mcp|cli|env):\s+`([^`]+)`\s*\|\s*(required|optional)\s*\|\s*(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(capRegex);
+    if (match) {
+      capabilities.push({
+        type: match[1],
+        name: match[2],
+        required: match[3] === 'required',
+        description: match[4].trim(),
+      });
+    }
+  }
+
+  return capabilities;
+}
+
+/**
+ * Parses the ## Event Payloads section.
+ * Format:
+ *   ### event_name
+ *   - field: type — description
+ * Returns: object mapping event_name -> Array<{ field, type, description }>
+ */
+function parseEventPayloads(content) {
+  const payloads = {};
+
+  // We need to parse ### sub-sections within ## Event Payloads.
+  // Find the section start, then extract up to the next ## heading or end of string.
+  // Using manual indexing is more reliable than regex for the "last section" case.
+  const sectionStart = content.indexOf('\n## Event Payloads\n');
+  if (sectionStart < 0) return payloads;
+
+  const afterHeading = content.substring(sectionStart + '\n## Event Payloads\n'.length);
+  const nextH2 = afterHeading.indexOf('\n## ');
+  const sectionContent = nextH2 >= 0 ? afterHeading.substring(0, nextH2) : afterHeading;
+  const lines = sectionContent.split('\n');
+
+  let currentEvent = null;
+
+  for (const line of lines) {
+    // ### event_name header
+    const h3Match = line.match(/^###\s+(.+)/);
+    if (h3Match) {
+      currentEvent = h3Match[1].trim();
+      payloads[currentEvent] = [];
+      continue;
+    }
+
+    if (!currentEvent) continue;
+
+    // - field: type — description
+    const fieldMatch = line.match(/^-\s+(\w+):\s+([\w\[\]|]+)\s+[—-]+\s+(.+)/);
+    if (fieldMatch) {
+      payloads[currentEvent].push({
+        field: fieldMatch[1],
+        type: fieldMatch[2],
+        description: fieldMatch[3].trim(),
+      });
+    }
+  }
+
+  return payloads;
+}
+
 // ---------------------------------------------------------------------------
 // Per-skill metadata extraction
 // ---------------------------------------------------------------------------
 
+/**
+ * Required sections for the structured YAML contract.
+ * Used to generate warnings when sections are missing.
+ */
+const REQUIRED_CONTRACT_SECTIONS = [
+  'Requirements',
+  'Risk',
+  'Approval Gates',
+  'Fallbacks',
+  'Capabilities',
+  'Event Payloads',
+];
+
 function processSkill({ skillFile, skillDir, triggerFile }) {
   const raw = fs.readFileSync(skillFile, 'utf8');
   const stat = fs.statSync(skillFile);
@@ -151,6 +355,24 @@ function processSkill({ skillFile, skillDir, triggerFile }) {
   const blackboardReads = extractBlackboardPaths(sections['Blackboard Read'] || []);
   const blackboardWrites = extractBlackboardPaths(sections['Blackboard Write'] || []);
 
+  // New structured contract sections
+  const requirements = parseRequirements(sections['Requirements'] || []);
+  const risk = parseRisk(sections['Risk'] || []);
+  const { gates: approval_gates, complexity_routing } = parseApprovalGates(
+    sections['Approval Gates'] || []
+  );
+  const fallbacks = parseFallbacks(sections['Fallbacks'] || []);
+  const capabilities = parseCapabilities(sections['Capabilities'] || []);
+  const event_payloads = parseEventPayloads(parsed.content);
+
+  // Warnings — flag any missing required contract sections
+  const warnings = [];
+  for (const section of REQUIRED_CONTRACT_SECTIONS) {
+    if (!sections[section]) {
+      warnings.push(`Missing required section: ## ${section}`);
+    }
+  }
+
   // References directory
   const referencesDir = path.join(ROOT, skillDir, 'references');
   let references = [];
@@ -178,8 +400,16 @@ function processSkill({ skillFile, skillDir, triggerFile }) {
     events_listens: eventsListens,
     blackboard_reads: blackboardReads,
     blackboard_writes: blackboardWrites,
+    requirements,
+    risk,
+    approval_gates,
+    complexity_routing,
+    fallbacks,
+    capabilities,
+    event_payloads,
     references,
     has_evals: hasEvals,
+    warnings,
     size_bytes: stat.size,
     enabled: true,
   };
@@ -196,15 +426,38 @@ function main() {
   // Sort alphabetically by name
   skills.sort((a, b) => a.name.localeCompare(b.name));
 
+  // Collect manifest-level warnings for skills with missing sections
+  const manifestWarnings = [];
+  for (const skill of skills) {
+    if (skill.warnings && skill.warnings.length > 0) {
+      manifestWarnings.push({
+        skill: skill.name,
+        warnings: skill.warnings,
+      });
+    }
+  }
+
   const manifest = {
     generated_at: new Date().toISOString(),
     skills,
+    warnings: manifestWarnings,
   };
 
   const outputPath = path.join(ROOT, 'ftm-manifest.json');
   fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
   process.stderr.write(`Generated manifest for ${skills.length} skills\n`);
+
+  if (manifestWarnings.length > 0) {
+    process.stderr.write(
+      `Warnings: ${manifestWarnings.length} skill(s) missing required contract sections\n`
+    );
+    for (const w of manifestWarnings) {
+      process.stderr.write(`  ${w.skill}: ${w.warnings.join(', ')}\n`);
+    }
+  } else {
+    process.stderr.write(`All ${skills.length} skills have complete contract sections\n`);
+  }
 }
 
 main();

package/bin/install.mjs

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * npx ftm-skills — installs ftm skills into ~/.claude/skills/
+ * 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.
  */
 
-import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
 import { join, basename, dirname } from "path";
-import { homedir } from "os";
+import { homedir, platform } from "os";
 import { fileURLToPath } from "url";
+import { execSync, spawnSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -19,6 +20,11 @@ const HOME = homedir();
 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 INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
+
+const ARGS = process.argv.slice(2);
+const WITH_INBOX = ARGS.includes("--with-inbox");
 
 function log(msg) {
   console.log(`  ${msg}`);
@@ -106,8 +112,132 @@ function main() {
     log("INIT ftm-config.yml (from default template)");
   }
 
+  // Install hooks
+  const hooksDir = join(REPO_DIR, "hooks");
+  let hookCount = 0;
+  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++;
+    }
+  }
+
+  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.");
+  console.log("");
+
+  if (WITH_INBOX) {
+    installInbox();
+  } else {
+    console.log("Try: /ftm help");
+    console.log("     To also install the inbox service: npx feed-the-machine --with-inbox");
+  }
+}
+
+function installInbox() {
+  const inboxSrc = join(REPO_DIR, "ftm-inbox");
+  if (!existsSync(inboxSrc)) {
+    console.error("ERROR: ftm-inbox/ not found in package. Cannot install inbox service.");
+    process.exit(1);
+  }
+
+  console.log("Installing ftm-inbox service...");
+  console.log(`  Source:      ${inboxSrc}`);
+  console.log(`  Destination: ${INBOX_INSTALL_DIR}`);
+  console.log("");
+
+  // Copy ftm-inbox/ to ~/.claude/ftm-inbox/
+  ensureDir(INBOX_INSTALL_DIR);
+  cpSync(inboxSrc, INBOX_INSTALL_DIR, { recursive: true });
+  log("COPY ftm-inbox → ~/.claude/ftm-inbox/");
+
+  // Make shell scripts executable
+  const binDir = join(INBOX_INSTALL_DIR, "bin");
+  const scripts = ["start.sh", "stop.sh", "status.sh"];
+  for (const script of scripts) {
+    const scriptPath = join(binDir, script);
+    if (existsSync(scriptPath)) {
+      chmodSync(scriptPath, 0o755);
+      log(`CHMOD +x bin/${script}`);
+    }
+  }
+
+  // Install Node deps if package.json exists
+  const pkgJson = join(INBOX_INSTALL_DIR, "package.json");
+  if (existsSync(pkgJson)) {
+    console.log("");
+    console.log("Installing Node.js dependencies...");
+    const npmResult = spawnSync("npm", ["install", "--prefix", INBOX_INSTALL_DIR], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (npmResult.status !== 0) {
+      console.warn("WARNING: npm install failed. Check Node.js version and try manually.");
+    }
+  }
+
+  // Install Python deps if requirements.txt exists
+  const reqTxt = join(INBOX_INSTALL_DIR, "requirements.txt");
+  if (existsSync(reqTxt)) {
+    console.log("");
+    console.log("Installing Python dependencies...");
+    const pipResult = spawnSync("pip3", ["install", "-r", reqTxt], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (pipResult.status !== 0) {
+      console.warn("WARNING: pip3 install failed. Check Python 3 and try manually:");
+      console.warn(`  pip3 install -r ${reqTxt}`);
+    }
+  }
+
+  // Run setup wizard
+  console.log("");
+  console.log("Running setup wizard...");
+  const setupScript = join(binDir, "setup.mjs");
+  if (existsSync(setupScript)) {
+    const setupResult = spawnSync("node", [setupScript], { stdio: "inherit" });
+    if (setupResult.status !== 0) {
+      console.warn("WARNING: Setup wizard exited with errors.");
+      console.warn(`Re-run manually: node ${setupScript}`);
+    }
+  } else {
+    console.warn("WARNING: setup.mjs not found. Run setup manually.");
+  }
+
+  // Offer LaunchAgent (macOS only)
+  if (platform() === "darwin") {
+    console.log("");
+    console.log("macOS detected. To auto-start ftm-inbox on login, run:");
+    console.log(`  node ${join(binDir, "launchagent.mjs")}`);
+  }
+
+  console.log("");
+  console.log("ftm-inbox installed.");
+  console.log(`  Start:  ${join(binDir, "start.sh")}`);
+  console.log(`  Stop:   ${join(binDir, "stop.sh")}`);
+  console.log(`  Status: ${join(binDir, "status.sh")}`);
   console.log("");
-  console.log(`Done. ${ymlFiles.length} skills linked.`);
+  console.log("See docs/INBOX.md for full documentation.");
   console.log("Try: /ftm help");
 }
 

package/docs/HOOKS.md

@@ -0,0 +1,243 @@
+# FTM Hooks — Programmatic Guardrails
+
+Hooks are shell scripts that run at specific points in Claude Code's lifecycle. Unlike skill instructions (which the model can rationalize past), hooks execute as real programs and can block actions, inject reminders, or enforce workflows.
+
+## Installation
+
+Hooks are installed automatically by `install.sh` into `~/.claude/hooks/`. To activate them, you need to add the hook configuration to your `~/.claude/settings.json`.
+
+**Option A: Automatic (recommended)**
+```bash
+./install.sh --setup-hooks
+```
+This merges the FTM hook entries into your existing settings.json without overwriting your other configuration.
+
+**Option B: Manual**
+Copy the entries from `hooks/settings-template.json` into the `hooks` section of your `~/.claude/settings.json`.
+
+## Hook Lifecycle
+
+```
+User types prompt
+  └→ UserPromptSubmit hooks fire
+  │    ├─ ftm-discovery-reminder.sh (nudge for external system work)
+  │    ├─ ftm-pending-sync-check.sh (detect out-of-session commits)
+  │    └─ ftm-map-autodetect.sh (detect unmapped projects)
+  └→ Claude processes prompt
+      └→ PreToolUse hooks fire before each tool
+      │    ├─ ftm-plan-gate.sh (block edits without a plan)
+      │    └─ ftm-drafts-gate.sh (block sends without a draft)
+      └→ Tool executes
+          └→ PostToolUse hooks fire after each tool
+          │    ├─ ftm-event-logger.mjs (log tool use for analytics)
+          │    └─ ftm-post-commit-trigger.sh (sync map + docs on commit)
+          └→ Claude finishes response
+              └→ Stop hook fires
+                   └─ ftm-blackboard-enforcer.sh (enforce experience recording)
+```
+
+## Hooks Reference
+
+### PreToolUse Hooks
+
+These fire **before** a tool executes. They can inject context (nudges) or block the tool call.
+
+---
+
+#### ftm-plan-gate.sh
+
+**Event:** PreToolUse | **Matcher:** `Edit|Write`
+
+Prevents Claude from grinding through file edits without presenting a plan first. Tracks edit count per session — soft reminder on edits 1-2, escalated warning on 3+.
+
+**How it works:**
+- Checks for a plan marker at `~/.claude/ftm-state/.plan-presented`
+- If no marker exists and edits are happening, injects context telling Claude to stop and plan
+- Claude creates the marker after presenting a plan to the user
+
+**Bypasses (always allowed):**
+- Skill files (`~/.claude/skills/`)
+- FTM state files (`~/.claude/ftm-state/`)
+- Drafts (`.ftm-drafts/`)
+- Documentation files (INTENT.md, ARCHITECTURE.mmd, STYLE.md, DEBUG.md, CLAUDE.md, .gitignore)
+
+**State files:**
+- `~/.claude/ftm-state/.plan-presented` — session ID marker
+- `~/.claude/ftm-state/.edit-count` — edit counter per session
+
+---
+
+#### ftm-drafts-gate.sh
+
+**Event:** PreToolUse | **Matcher:** `mcp__slack__slack_post_message|mcp__slack__slack_reply_to_thread|mcp__gmail__send_email`
+
+Hard-blocks outbound messages unless a draft was saved to `.ftm-drafts/` in the last 30 minutes. Creates an audit trail of all messages Claude drafts on your behalf.
+
+**How it works:**
+- Checks for `.md` files modified in the last 30 minutes in:
+  - `<project>/.ftm-drafts/` (project-level)
+  - `~/.claude/ftm-drafts/` (global fallback)
+- If no recent draft found: returns `permissionDecision: deny`
+- If draft exists: allows through
+
+**Pairs with:** ftm-mind section 3.5 (draft-before-send protocol)
+
+---
+
+### UserPromptSubmit Hooks
+
+These fire when you press Enter on a prompt, **before** Claude sees it. They inject `additionalContext` that influences Claude's response.
+
+---
+
+#### ftm-discovery-reminder.sh
+
+**Event:** UserPromptSubmit
+
+Detects when a prompt involves external systems or stakeholder coordination and injects a reminder about the discovery interview before Claude starts work.
+
+**Trigger patterns:**
+- System changes: reroute, migrate, update integration, change endpoint, switch from/to
+- Coordination: draft message, notify about, check with, coordinate with
+- Workflow changes: jira automation, freshservice automation, update workflow
+
+**Skip signals (no reminder injected):**
+- "just do it", "no questions", "skip the interview"
+- "here's the slack thread", "per the conversation"
+
+**Pairs with:** ftm-mind Orient section 10 (Discovery Interview)
+
+---
+
+#### ftm-pending-sync-check.sh
+
+**Event:** UserPromptSubmit
+
+Checks for commits made outside of Claude sessions (e.g., you pushed from the terminal or another tool). If pending syncs exist, injects a reminder to run ftm-map incremental on those files.
+
+**How it works:**
+- Reads `~/.claude/ftm-state/.pending-commit-syncs`
+- If the file exists and has entries, injects context with the list
+- Consumes the file on read — only fires once per batch
+
+**State files:**
+- `~/.claude/ftm-state/.pending-commit-syncs` — written by external git hooks or CI
+
+---
+
+#### ftm-map-autodetect.sh
+
+**Event:** UserPromptSubmit
+
+Detects when you invoke any FTM skill in a project that hasn't been indexed by ftm-map yet. Classifies the project and injects bootstrap instructions.
+
+**Classification:**
+
+| Type | Criteria |
+|---|---|
+| Greenfield | ≤5 source files, ≤3 commits |
+| Small brownfield | ≤50 source files |
+| Medium brownfield | ≤200 source files |
+| Large brownfield | 200+ source files |
+
+**One-shot behavior:** Writes `.ftm-map/.offered` so it only fires **once per project**. Delete the marker to re-trigger.
+
+**Trigger keywords:** `/ftm`, `ftm-`, `brainstorm`, `research`, `debug this`, `audit`, `deep dive`, `investigate`
+
+---
+
+### PostToolUse Hooks
+
+These fire **after** a tool executes. They observe what happened and react.
+
+---
+
+#### ftm-event-logger.mjs
+
+**Event:** PostToolUse | **Matcher:** (all tools — empty matcher)
+
+Logs tool use to `~/.claude/ftm-state/events.log` as structured JSONL. This is the data source for `/ftm-dashboard`.
+
+**Performance:**
+- Debounced — only fires every 3rd tool use
+- Auto-rotates logs older than 30 days into `~/.claude/ftm-state/event-archives/`
+
+**Requires:** Node.js (runs as `node ~/.claude/hooks/ftm-event-logger.mjs`)
+
+---
+
+#### ftm-post-commit-trigger.sh
+
+**Event:** PostToolUse | **Matcher:** `Bash|mcp__git__git_commit`
+
+Detects git commits and triggers the documentation sync chain. Only fires if the project has been indexed by ftm-map (`.ftm-map/map.db` exists).
+
+**Injects instructions to:**
+1. Run ftm-map incremental on changed files
+2. Update INTENT.md via ftm-intent
+3. Update ARCHITECTURE.mmd via ftm-diagram
+
+This is what keeps the documentation layer in sync with code changes automatically.
+
+---
+
+### Stop Hooks
+
+These fire when Claude finishes responding (before the next user prompt).
+
+---
+
+#### ftm-blackboard-enforcer.sh
+
+**Event:** Stop
+
+Prevents Claude from ending a session without recording what it learned to the blackboard. If meaningful work was done (3+ edits or FTM skills invoked) but no experience was recorded, blocks the stop.
+
+**How it works:**
+- Checks edit counter and `context.json` for skills_invoked
+- If meaningful work detected, checks for today's experience files
+- If no experience recorded: blocks stop with instructions to write the blackboard
+- Has infinite-loop guard via `stop_hook_active` check
+
+**State files checked:**
+- `~/.claude/ftm-state/.edit-count`
+- `~/.claude/ftm-state/blackboard/context.json`
+- `~/.claude/ftm-state/blackboard/experiences/` (looks for today's files)
+
+---
+
+## Dependencies
+
+All shell hooks require `jq` for JSON parsing. The event logger requires Node.js.
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+```
+
+## Troubleshooting
+
+**Hook not firing:**
+- Check it's in `~/.claude/settings.json` under the correct event key
+- Check the script is executable: `chmod +x ~/.claude/hooks/ftm-*.sh`
+- Check the matcher regex matches the tool name exactly
+
+**Hook blocking unexpectedly:**
+- Plan gate: `rm ~/.claude/ftm-state/.plan-presented` to reset
+- Map autodetect: `rm .ftm-map/.offered` to re-trigger
+- Blackboard enforcer: has built-in infinite-loop guard
+
+**Testing a hook manually:**
+```bash
+# Test plan gate
+echo '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test.py"}}' | ~/.claude/hooks/ftm-plan-gate.sh
+
+# Test map autodetect
+echo '{"prompt":"/ftm brainstorm auth design"}' | ~/.claude/hooks/ftm-map-autodetect.sh
+
+# Test post-commit trigger
+echo '{"tool_name":"Bash","tool_input":{"command":"git commit -m test"}}' | ~/.claude/hooks/ftm-post-commit-trigger.sh
+```