feed-the-machine 1.0.0 → 1.1.0

package/bin/install.mjs

@@ -1,13 +1,13 @@
 #!/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 } from "fs";
 import { join, basename, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
@@ -19,6 +19,7 @@ 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");
 
 function log(msg) {
   console.log(`  ${msg}`);
@@ -106,8 +107,38 @@ 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("");
-  console.log(`Done. ${ymlFiles.length} skills linked.`);
   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
+```

package/ftm-dashboard/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ftm-dashboard
+description: Session and weekly analytics dashboard for the FTM skill ecosystem. Reads events.log and blackboard state to show skills invoked, plans presented, approval rates, experiences recorded, and patterns promoted. Use when user says "dashboard", "analytics", "stats", "ftm-dashboard", "show session stats", or "how's the system doing".
+---
+
+# FTM Dashboard
+
+Provides analytics about FTM system usage by reading the event log and blackboard state.
+
+## Commands
+
+### `/ftm-dashboard` (default: current session)
+
+Shows stats for the current session:
+
+```
+━━━━━━━━━━━ FTM Session Dashboard ━━━━━━━━━━━
+
+Session started: [timestamp]
+Duration: [hours:minutes]
+
+Skills Invoked:
+  ftm-mind      ████████████  12
+  ftm-debug     ████          4
+  ftm-executor  ██            2
+  ftm-brainstorm █            1
+
+Plans:
+  Presented: 5
+  Approved: 4 (80%)
+  Modified before approval: 2
+  Saved as playbook: 1
+
+Experiences Recorded:
+  Total: 8
+  From LLM: 5 (rich)
+  From git hook: 3 (minimal)
+
+Patterns:
+  Active: 12
+  Reinforced this session: 3
+  Aging (>30 days): 2
+  Decayed: 0
+
+Context Budget:
+  Orient mode: Full (conversation ~25% used)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### `/ftm-dashboard week`
+
+Shows aggregate stats for the past 7 days:
+
+```
+━━━━━━━━━━ FTM Weekly Dashboard ━━━━━━━━━━━━━
+
+Period: [date] — [date]
+
+Tasks by Complexity:
+  Micro:  ██████████████████  18
+  Small:  ████████████        12
+  Medium: ██████              6
+  Large:  ██                  2
+
+Top Skills:
+  1. ftm-mind (45 invocations)
+  2. ftm-executor (12 invocations)
+  3. ftm-debug (8 invocations)
+  4. ftm-brainstorm (6 invocations)
+  5. ftm-audit (4 invocations)
+
+Playbooks:
+  Created: 2
+  Reused: 3
+  Parameterized: 0
+
+Learning:
+  Experiences recorded: 38
+  Patterns promoted: 1
+  Patterns decayed: 0
+  Sizing corrections: 0
+
+Approval Rate: 85% (34/40 plans approved on first presentation)
+Average plan modifications: 1.2 per plan
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Data Sources
+
+### events.log (`~/.claude/ftm-state/events.log`)
+- JSONL format, one entry per line
+- Each entry has: timestamp, event_type, tool_name, session_id, skill_context
+- Filter by session_id for current session, by date range for weekly
+
+### Blackboard State
+- `~/.claude/ftm-state/blackboard/context.json` — current session metadata
+- `~/.claude/ftm-state/blackboard/experiences/index.json` — experience counts and types
+- `~/.claude/ftm-state/blackboard/patterns.json` — pattern health
+
+### Playbooks (`~/.ftm/playbooks/`)
+- Count `.yml` files for total playbooks
+- Check `use_count` field for reuse stats
+- Check `parameterized` field for parameterization stats
+
+## Implementation
+
+1. Read the relevant data sources
+2. Compute aggregates
+3. Render as markdown tables with ASCII bar charts
+4. Output directly — no approval gates needed (read-only operation)
+
+## Rendering
+
+- Use Unicode block characters for bar charts: █ ▓ ░
+- Tables in markdown format for terminal rendering
+- Keep output concise — one screen max
+- If data sources are empty (fresh install), show: "No data yet. Use FTM for a few sessions and check back."
+
+## Events
+
+### Listens To
+- `task_completed` — for session stats tracking
+
+### Blackboard Read
+- `context.json` — session metadata
+- `experiences/index.json` — experience inventory
+- `patterns.json` — pattern health

package/ftm-map/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: ftm-map
+description: Persistent code knowledge graph powered by tree-sitter and SQLite with FTS5 full-text search. Builds structural dependency graphs for blast radius analysis, dependency chains, and keyword search. Use when user asks "what breaks if I change X", "blast radius", "what depends on", "where do we handle", "map codebase", "index project", "what calls", "dependency chain", "ftm-map".
+---
+
+# ftm-map
+
+Persistent code knowledge graph powered by tree-sitter and SQLite with FTS5 full-text search. Parses the local codebase into a structural dependency graph stored in `.ftm-map/map.db`, then answers structural queries (blast radius, dependency chains, symbol lookup) and keyword searches without re-reading the source tree on every question.
+
+## Events
+
+### Emits
+- `map_updated` — when the graph database has been updated (bootstrap or incremental)
+  - Payload: `{ project_path, symbols_count, edges_count, files_parsed, duration_ms, mode }`
+- `task_completed` — when any ftm-map operation finishes
+
+### Listens To
+- `code_committed` — run incremental index on changed files, then emit `map_updated`
+- `task_received` — begin bootstrap or query when ftm-mind routes a mapping/search request
+
+## Config Read
+
+Read `~/.claude/ftm-config.yml`:
+- Check `skills.ftm-map.enabled` (default: true)
+- Use `execution` model from active profile for indexing agents
+
+## Blackboard Read
+
+On startup, load context from the FTM blackboard:
+1. Load `~/.claude/ftm-blackboard/context.json`
+2. Filter experiences by `task_type: "map"`
+3. Load matching experience files to inform index scope and query routing
+4. Check for prior bootstrap records to determine if incremental mode is appropriate
+
+## Mode Detection
+
+Three modes, detected from request context:
+
+```
+Bootstrap:    "map this codebase" / "index this project" / no map.db exists yet
+              Full scan of all source files. Builds graph from scratch.
+
+Incremental:  Triggered by code_committed event or PostToolUse hook
+              Parses only changed files and updates their graph entries.
+
+Query:        Structural or keyword question about existing graph
+              Detects query type and runs appropriate script.
+```
+
+If `.ftm-map/map.db` does not exist when a query arrives, fall back to offering bootstrap (see Graceful Degradation below).
+
+## Mode 1: Bootstrap (full scan)
+
+Trigger: user says "map this codebase" or "index this project", or `.ftm-map/map.db` does not yet exist.
+
+1. Run `ftm-map/scripts/setup.sh` to ensure virtualenv and tree-sitter dependencies are installed
+2. Run `ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --bootstrap <project_root>`
+3. Capture and report stats from stdout:
+   - Files parsed
+   - Symbols found
+   - Edges created
+   - Time elapsed
+4. Emit `map_updated` with `mode: "bootstrap"`
+
+Example invocation:
+```
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --bootstrap .
+```
+
+## Mode 2: Incremental (post-commit)
+
+Trigger: `code_committed` event fires, or PostToolUse hook detects a write to a source file.
+
+1. Get changed files:
+   ```
+   git diff --name-only HEAD~1
+   ```
+2. Filter to source files only (skip docs, configs, lockfiles)
+3. Run incremental index on changed files:
+   ```
+   ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --incremental --files <file1> <file2> ...
+   ```
+4. Emit `map_updated` with `mode: "incremental"` and count of updated entries
+
+## Mode 3: Query (answer structural and search questions)
+
+Trigger: user asks a structural or keyword question about the codebase.
+
+### Query Type Detection
+
+| User says | Query type | Script flag |
+|-----------|-----------|-------------|
+| "what breaks if I change X" | blast radius | `--blast-radius X` |
+| "blast radius of X" | blast radius | `--blast-radius X` |
+| "what depends on X" | dependency chain | `--deps X` |
+| "what calls X" | dependency chain (callers) | `--deps X` |
+| "where do we handle X" | FTS5 keyword search | `--search "X"` |
+| "find X in the codebase" | FTS5 keyword search | `--search "X"` |
+| "tell me about function X" | symbol info | `--info X` |
+| "show dependencies for X" | dependency chain | `--deps X` |
+
+### Execution
+
+Run the appropriate query script with the venv python:
+```
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --blast-radius <symbol>
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --deps <symbol>
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --search "<keywords>"
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --info <symbol>
+```
+
+### Output Formatting
+
+Scripts return JSON. Render as readable markdown:
+
+**Blast radius** — tree of affected symbols with file paths and line numbers:
+```
+Blast radius of `authenticateUser`:
+  direct callers (3):
+    • loginHandler       src/handlers/auth.ts:42
+    • refreshSession     src/handlers/session.ts:17
+    • testAuthFlow       src/tests/auth.test.ts:88
+  transitive (5):
+    • routeMiddleware    src/middleware/index.ts:12
+    ...
+```
+
+**Dependency chain** — ordered list of dependencies (callee direction):
+```
+Dependencies of `authenticateUser`:
+  1. validateToken       src/auth/tokens.ts:8
+  2. decodeJWT           src/auth/jwt.ts:22
+  3. createSession       src/auth/session.ts:45
+  4. storeSession        src/auth/session.ts:67
+```
+
+**FTS5 search** — BM25-ranked list with file:line references:
+```
+Results for "rate limit" (6 matches, ranked by relevance):
+  1. applyRateLimit      src/middleware/ratelimit.ts:14      score: 0.94
+  2. RateLimitConfig     src/config/types.ts:88              score: 0.81
+  3. checkRateLimit      src/handlers/base.ts:203            score: 0.77
+  ...
+```
+
+**Symbol info** — full details card:
+```
+Symbol: authenticateUser
+  Kind:       function
+  File:       src/auth/index.ts:34
+  Signature:  authenticateUser(token: string, opts?: AuthOptions) → Promise<Session>
+  Callers:    3 direct, 5 transitive
+  Callees:    validateToken, decodeJWT, createSession
+  Dependents: 8 symbols total
+```
+
+## Graceful Degradation
+
+If `.ftm-map/map.db` does not exist when a query is requested:
+
+1. Explain that the graph has not been indexed yet
+2. Offer to bootstrap: "Run `ftm-map bootstrap` to index this codebase?"
+3. If user confirms, switch to Bootstrap mode immediately
+4. Do not attempt to answer structural queries by reading source files directly — the graph is the source of truth for structural questions
+
+## Python Script Interface
+
+All heavy lifting is done by Python scripts in `ftm-map/scripts/`. The skill orchestrates: detects mode, runs the right script with venv python, formats the output.
+
+| Script | Purpose |
+|--------|---------|
+| `setup.sh` | Creates virtualenv, installs tree-sitter and dependencies |
+| `db.py` | SQLite schema, CRUD operations, graph traversal queries |
+| `parser.py` | tree-sitter parsing and symbol/edge extraction |
+| `index.py` | Full bootstrap scan and incremental file indexing |
+| `query.py` | Blast radius, dependency chain, FTS5 keyword search, symbol info |
+| `views.py` | INTENT.md and .mmd generation from graph data |
+
+Always use the venv python — never the system python — to ensure tree-sitter bindings are available:
+```
+ftm-map/scripts/.venv/bin/python3 <script> <args>
+```
+
+## Integration Points
+
+**ftm-intent** may call ftm-map to retrieve caller/callee relationships when writing the `Relationships` field of INTENT.md entries. ftm-map returns structured JSON that ftm-intent formats into human-readable relationship text.
+
+**ftm-diagram** may call ftm-map to retrieve the dependency graph for a module when generating DIAGRAM.mmd files. ftm-map returns edge data that ftm-diagram renders as mermaid nodes and edges.
+
+Both integrations use `query.py --deps` and `query.py --info` to retrieve graph data without re-parsing source.
+
+## Blackboard Write
+
+After `map_updated` or session end:
+1. Update `~/.claude/ftm-blackboard/context.json` with map session summary
+2. Write experience file: `~/.claude/ftm-blackboard/experiences/map-[timestamp].json`
+   - Fields: project_path, mode, symbols_count, edges_count, files_parsed, duration_ms
+3. Update `~/.claude/ftm-blackboard/index.json` with new experience entry
+4. Emit `task_completed` event
+
+## Rules
+
+- NEVER stop to ask for input. Make decisions and keep going.
+- ALWAYS commit after completing with a clear message.
+- ALWAYS review after commit: run `git diff HEAD~1`.
+- Never reference AI/Claude in commit messages.
+- Stay in your worktree.
+- ALWAYS use the venv python (`ftm-map/scripts/.venv/bin/python3`), never the system python.
+- For query mode, ALWAYS run `setup.sh` first if `.venv` does not exist.