mapify-cli 1.1.0__tar.gz → 1.2.0__tar.gz

mapify_cli-1.2.0/.claude/hooks/README.md

@@ -0,0 +1,271 @@
+# MAP Framework - Claude Code Hooks
+
+This directory contains Claude Code hooks for the MAP Framework.
+
+## Active Hooks
+
+### UserPromptSubmit - Playbook Auto-Injection
+
+**Hook**: `user-prompt-submit.sh`
+**Triggers**: Before user prompt is submitted to Claude Code
+**Purpose**: Automatically injects relevant playbook bullets to enhance context
+
+**How It Works**:
+1. Extracts keywords from user message (filters stop words, handles unicode)
+2. Queries local playbook using `mapify playbook query` CLI
+3. Formats top 5 relevant bullets as markdown
+4. Injects as `additionalContext` field in JSON response
+
+**Configuration** (edit `user-prompt-submit.sh`):
+```bash
+MAX_BULLETS=5          # Number of bullets to inject (default: 5)
+MIN_QUERY_LENGTH=10    # Minimum message length (default: 10 chars)
+```
+
+**Example Output**:
+```json
+{
+  "continue": true,
+  "additionalContext": "# Relevant Playbook Patterns\n\n## 1. [impl-0042] ...\n"
+}
+```
+
+**Edge Cases Handled**:
+- Short messages (<10 chars) → Skip injection
+- No playbook database → Skip injection gracefully
+- mapify CLI not found → Skip injection gracefully
+- Query timeout (>10s) → Skip injection gracefully
+- No relevant bullets → Skip injection (no additionalContext)
+
+**Performance**: <2s typical latency (keyword extraction + FTS5 query)
+
+**Testing**: See [TESTING.md](TESTING.md) for comprehensive test guide
+
+---
+
+### SessionStart - MAP Workflow Context Restoration
+
+**Hook**: `session-start.sh`
+**Triggers**: At session start (before first user interaction)
+**Purpose**: Automatically restores `.map/current_plan.md` checkpoint to maintain workflow continuity after context compaction
+
+**How It Works**:
+1. SessionStart event triggers hook execution
+2. Checks if `.map/current_plan.md` checkpoint file exists
+3. Calls validator helper script (`helpers/validate_checkpoint_file.py`)
+4. Validator performs 4-layer security validation (path, size, UTF-8, sanitization)
+5. Strips control characters while preserving newlines and tabs
+6. Returns JSON with `additionalContext` containing sanitized checkpoint
+7. Claude receives restored plan automatically before first interaction
+
+**Example Output** (Successful Injection):
+```json
+{
+  "continue": true,
+  "additionalContext": "# 🔄 MAP Workflow Context Restored\n\nThis context was automatically restored from your previous session's checkpoint.\nThe plan below reflects your current task progress and helps maintain workflow continuity after context compaction.\n\n---\n\n# Current Task: feat_auth\n## Progress: 3/5 completed\n## Subtask 3: Implement JWT token validation"
+}
+```
+
+**Example Output** (No Checkpoint - New Session):
+```json
+{
+  "continue": true
+}
+```
+
+**Edge Cases Handled**:
+- No checkpoint file → Skip injection gracefully (new session)
+- Checkpoint >256KB → Reject, log error to stderr, skip injection
+- Path traversal (`../../../etc/passwd`) → Reject, log error to stderr, skip injection
+- Invalid UTF-8 encoding → Reject, log error to stderr, skip injection
+- Binary files → Rejected by UTF-8 validation
+- Control characters (ESC codes, NULL bytes) → Sanitized automatically (preserves \n and \t)
+- Empty content after sanitization → Skip injection
+- Validator script missing → Skip injection gracefully, fallback to manual Phase 1
+- Validator script fails → Skip injection gracefully, log error
+
+**Security Validations** (4 Layers - Defense-in-Depth):
+1. **Path Security**: Blocks path traversal attacks (`../`, absolute paths outside `.map/`)
+2. **Size Bomb Protection**: Rejects files >256KB before reading into memory
+3. **UTF-8 Validation**: Ensures file is text (blocks binary files like images, executables)
+4. **Content Sanitization**: Strips control characters (prevents terminal injection, escape code attacks)
+
+**Performance**:
+- Typical: <0.5s for small checkpoints (5KB)
+- Maximum: <2s for large checkpoints (100KB)
+- Timeout: 5s (Claude Code hook timeout limit)
+- Validation overhead: ~0.1s (path + size + UTF-8 checks)
+
+**Testing**:
+- **Unit Tests**: `tests/hooks/test_validate_checkpoint_file.py` (41 test cases covering all security layers)
+- **Integration Tests**: `tests/hooks/test_session_start_integration.py` (23 test cases for full hook workflow)
+
+**Manual Testing**:
+```bash
+# Test with valid checkpoint
+echo '{}' | .claude/hooks/session-start.sh
+
+# Test with large file (size bomb attack)
+dd if=/dev/zero of=.map/current_plan.md bs=1M count=1
+echo '{}' | .claude/hooks/session-start.sh
+
+# Test with path traversal (security)
+ln -s /etc/passwd .map/current_plan.md
+echo '{}' | .claude/hooks/session-start.sh
+
+# Test with no checkpoint (new session)
+rm -f .map/current_plan.md
+echo '{}' | .claude/hooks/session-start.sh
+```
+
+---
+
+### PreToolUse - Template Variable Validation
+
+**Hook**: `validate-agent-templates.sh`
+**Triggers**: Before `Edit` or `Write` operations on `.claude/agents/*.md` files
+**Purpose**: Prevents accidental removal of critical template variables
+
+**Template Variables Protected**:
+- `{{language}}` - Programming language context
+- `{{project_name}}` - Project name
+- `{{framework}}` - Framework context
+- `{{#if playbook_bullets}}` - ACE learning system
+- `{{#if feedback}}` - Monitor→Actor retry loops
+- `{{subtask_description}}` - Task specification
+
+**How It Works**:
+1. Detects when agent files are being modified
+2. Checks staged content for required template variables
+3. Blocks commit if variables are missing
+4. Provides clear error message
+
+**Override** (use carefully):
+```bash
+git commit --no-verify
+```
+
+---
+
+### Stop - Quality Gates (#NoMessLeftBehind)
+
+**Hook**: `stop.sh`
+**Triggers**: After `Write` or `Edit` operations on code files
+**Purpose**: Runs automated quality checks before response submission
+
+**Supported Languages**:
+- **Python** (.py): `python -m py_compile` + `pytest` for related tests
+- **Go** (.go): `go fmt` + `go vet` for formatting and static analysis
+- **TypeScript** (.ts, .tsx): `tsc --noEmit` for type checking
+- **Rust** (.rs): `rustc` syntax validation
+
+**Checks Performed**:
+1. **Syntax validation**: Language-specific syntax checker
+2. **Related tests** (Python only): Runs pytest on:
+   - Corresponding test file (e.g., `test_foo.py` for `foo.py`)
+   - Test file itself (if already a test file)
+   - All tests (if file is in `src/` or `mapify_cli/`)
+
+**Configuration**:
+```bash
+# Disable quality gates entirely
+export QUALITY_GATES_ENABLED=false
+
+# Adjust timeout (default: 30s)
+export QUALITY_GATES_TIMEOUT=60
+```
+
+**How It Works**:
+1. Detects Python file modifications (Write/Edit tools)
+2. Runs syntax check with `py_compile`
+3. Finds and runs related pytest tests
+4. Reports results to stderr (non-blocking)
+5. Always exits 0 (warnings only, never blocks)
+
+**Example Output** (Success):
+```
+[stop/quality-gates] ========== Quality Gates Results ==========
+File: tests/test_playbook_manager.py
+Status: PASSED
+Summary: All 2 check(s) passed, 0 skipped
+
+✅ python_syntax: Syntax check passed
+✅ pytest: Tests passed: tests/test_playbook_manager.py
+[stop/quality-gates] ===========================================
+[stop/quality-gates] ✅ All quality checks passed
+```
+
+**Example Output** (Failure - non-blocking warning):
+```
+[stop/quality-gates] ========== Quality Gates Results ==========
+File: src/mapify_cli/example.py
+Status: FAILED
+Summary: 1 check(s) failed, 1 passed, 0 skipped
+
+❌ python_syntax: Syntax error in src/mapify_cli/example.py
+   SyntaxError: unterminated string literal (detected at line 2)
+
+✅ pytest: Tests passed
+[stop/quality-gates] ===========================================
+[stop/quality-gates] ⚠️  Some quality checks FAILED - review output above
+[stop/quality-gates] Note: This is non-blocking, response will be submitted
+```
+
+**Edge Cases Handled**:
+- Non-Python files → Skipped
+- Read/Glob tools → Skipped (no file modifications)
+- pytest not installed → Test check skipped
+- No related tests → Test check skipped
+- Timeout (>30s) → Aborted gracefully
+- Syntax errors → Reported, response still submitted
+
+**Performance**: <5s for syntax check, <30s total (with tests)
+
+**Testing**:
+```bash
+# Test with valid Python file
+echo '{"tool": "Write", "parameters": {"file_path": "tests/test_playbook_manager.py"}}' | \
+  .claude/hooks/stop.sh
+
+# Test with syntax error
+echo '{"tool": "Write", "parameters": {"file_path": "/tmp/broken.py"}}' | \
+  .claude/hooks/stop.sh
+
+# Test with quality gates disabled
+QUALITY_GATES_ENABLED=false \
+  echo '{"tool": "Write", "parameters": {"file_path": "test.py"}}' | \
+  .claude/hooks/stop.sh
+```
+
+**Extending for Other Languages**:
+Edit `.claude/hooks/helpers/quality_gates.py` to add support for TypeScript, Go, Rust, etc.
+Update file extension regex in `stop.sh`:
+```bash
+# Current: if [[ ! "$FILE_PATH" =~ \.(py)$ ]]; then
+# Add TypeScript: if [[ ! "$FILE_PATH" =~ \.(py|ts|tsx)$ ]]; then
+```
+
+## Removed Hooks
+
+The following hooks were removed because **bash hooks cannot call MCP tools**:
+
+- ❌ `auto-store-knowledge.sh` (PostToolUse) - Tried to call cipher MCP
+- ❌ `enrich-context.sh` (UserPromptSubmit) - Tried to search cipher MCP
+- ❌ `session-init.sh` (SessionStart) - Tried to load from cipher MCP
+- ❌ `track-metrics.sh` (SubagentStop) - Tried to store metrics in cipher MCP
+
+**Why Removed**: Bash hooks execute outside Claude Code's context and cannot invoke MCP tools.
+
+**Alternative**: Call MCP tools directly within agent prompts or slash commands.
+
+## Best Practices
+
+**DO Use Hooks For**:
+- ✅ File validation (grep, regex)
+- ✅ Git operations (status, diff)
+- ✅ Static analysis (linters)
+
+**DON'T Use Hooks For**:
+- ❌ MCP tool calls
+- ❌ Interactive prompts
+- ❌ Long operations (>10s timeout)

{mapify_cli-1.1.0 → mapify_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
 Project-URL: Homepage, https://github.com/azalio/map-framework
 Project-URL: Repository, https://github.com/azalio/map-framework.git

{mapify_cli-1.1.0 → mapify_cli-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "1.1.0"
+version = "1.2.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-1.1.0 → mapify_cli-1.2.0}/src/mapify_cli/__init__.py

@@ -1170,6 +1170,18 @@ def install_hooks(project_path: Path, with_hooks: bool = True) -> int:
         dest_file.chmod(dest_file.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
         hooks_count += 1
 
+    # Copy helpers directory (Python helper scripts)
+    helpers_src = hooks_template_dir / "helpers"
+    if helpers_src.exists() and helpers_src.is_dir():
+        helpers_dest = hooks_dir / "helpers"
+        if helpers_dest.exists():
+            shutil.rmtree(helpers_dest)
+        shutil.copytree(helpers_src, helpers_dest)
+        # Make Python scripts executable
+        for py_file in helpers_dest.glob("*.py"):
+            if py_file.name != "__init__.py":
+                py_file.chmod(py_file.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
     # Copy README.md
     readme_src = hooks_template_dir / "README.md"
     if readme_src.exists():
@@ -1898,6 +1910,171 @@ def recitation_clear():
     manager.clear_plan()
     console.print_json(data={"status": "success", "message": "Plan cleared"})
 
+
+@recitation_app.command("generate-context")
+def recitation_generate_context():
+    """Generate context.md from project metadata and playbook"""
+    from mapify_cli.recitation_manager import RecitationManager
+    manager = RecitationManager(Path.cwd())
+    try:
+        context_file = manager.generate_context_md()
+        console.print_json(data={
+            "status": "success",
+            "message": "Generated context.md",
+            "file": context_file
+        })
+    except Exception as e:
+        console.print_json(data={
+            "status": "error",
+            "message": f"Failed to generate context.md: {str(e)}"
+        })
+        raise typer.Exit(1)
+
+
+@recitation_app.command("generate-tasks")
+def recitation_generate_tasks():
+    """Regenerate tasks.md from current plan"""
+    from mapify_cli.recitation_manager import RecitationManager
+    manager = RecitationManager(Path.cwd())
+    try:
+        plan = manager.get_plan()
+        if not plan:
+            console.print_json(data={
+                "status": "error",
+                "message": "No active plan to generate tasks from"
+            })
+            raise typer.Exit(1)
+
+        manager._generate_tasks_md(plan)
+        console.print_json(data={
+            "status": "success",
+            "message": "Generated tasks.md",
+            "file": str(manager.tasks_file)
+        })
+    except Exception as e:
+        console.print_json(data={
+            "status": "error",
+            "message": f"Failed to generate tasks.md: {str(e)}"
+        })
+        raise typer.Exit(1)
+
+
+@recitation_app.command("get-docs")
+def recitation_get_docs():
+    """Get all dev docs content (plan + context + tasks)"""
+    from mapify_cli.recitation_manager import RecitationManager
+    manager = RecitationManager(Path.cwd())
+    try:
+        docs = manager.get_dev_docs()
+        console.print_json(data={
+            "status": "success",
+            "docs": docs
+        })
+    except Exception as e:
+        console.print_json(data={
+            "status": "error",
+            "message": f"Failed to get dev docs: {str(e)}"
+        })
+        raise typer.Exit(1)
+
+
+@recitation_app.command("checkpoint")
+def recitation_checkpoint():
+    """Show current MAP workflow state and recovery instructions for post-compaction"""
+    from mapify_cli.recitation_manager import RecitationManager
+    import os
+
+    manager = RecitationManager(Path.cwd())
+    map_dir = Path.cwd() / ".map"
+
+    # Check if .map directory exists
+    if not map_dir.exists():
+        console.print("[yellow]⚠️  No active MAP workflow found[/yellow]")
+        console.print("\nThe `.map/` directory doesn't exist yet.")
+        console.print("Start a MAP workflow with: [cyan]/map-feature[/cyan], [cyan]/map-debug[/cyan], or [cyan]/map-refactor[/cyan]")
+        raise typer.Exit(0)
+
+    # Define files to check
+    files_to_check = {
+        "plan_json": manager.plan_json,
+        "plan_md": manager.plan_file,
+        "context_md": manager.context_file,
+        "tasks_md": manager.tasks_file
+    }
+
+    # Check which files exist
+    existing_files = {name: path for name, path in files_to_check.items() if path.exists()}
+
+    if not existing_files:
+        console.print("[yellow]⚠️  MAP workflow directory exists but no state files found[/yellow]")
+        console.print(f"\nDirectory: {map_dir.absolute()}")
+        console.print("Expected files are missing. The workflow may not have been initialized properly.")
+        raise typer.Exit(0)
+
+    # Print checkpoint header
+    console.print("\n[bold green]📍 MAP Workflow Checkpoint[/bold green]")
+    console.print("=" * 60)
+
+    # Print file locations
+    console.print("\n[bold]📁 State Files (absolute paths):[/bold]")
+    for name, path in existing_files.items():
+        file_size = path.stat().st_size
+        console.print(f"  • {path.absolute()} ([dim]{file_size} bytes[/dim])")
+
+    # Show current task status if plan exists
+    if "plan_json" in existing_files:
+        try:
+            plan = manager.get_plan()
+            if plan:
+                console.print(f"\n[bold]🎯 Current Task:[/bold] {plan.goal}")
+                console.print(f"[bold]📊 Progress:[/bold] {plan.current_subtask_id}/{len(plan.subtasks)} subtasks")
+
+                # Show current subtask
+                current = next((s for s in plan.subtasks if s.id == plan.current_subtask_id), None)
+                if current:
+                    console.print(f"[bold]▶️  Active:[/bold] {current.description} [{current.status}]")
+        except Exception as e:
+            console.print(f"[yellow]⚠️  Could not parse plan: {str(e)}[/yellow]")
+
+    # Print file contents with headers
+    console.print("\n[bold]📄 File Contents:[/bold]")
+    console.print("-" * 60)
+
+    for name, path in existing_files.items():
+        console.print(f"\n[bold cyan]### {path.name}[/bold cyan]")
+        try:
+            content = path.read_text()
+            # Truncate very long files
+            if len(content) > 2000:
+                console.print(content[:2000])
+                console.print(f"\n[dim]... (truncated, {len(content) - 2000} more chars)[/dim]")
+            else:
+                console.print(content)
+        except Exception as e:
+            console.print(f"[red]Error reading file: {str(e)}[/red]")
+
+    # Print recovery instructions
+    console.print("\n" + "=" * 60)
+    console.print("[bold green]🔄 Recovery Instructions (for post-compaction):[/bold green]")
+    console.print("\nAfter context compaction, paste this to Claude:\n")
+
+    recovery_message = f"""```
+Continue MAP workflow from checkpoint:
+
+@{manager.plan_file.absolute()}"""
+
+    if "context_md" in existing_files:
+        recovery_message += f"\n@{manager.context_file.absolute()}"
+    if "tasks_md" in existing_files:
+        recovery_message += f"\n@{manager.tasks_file.absolute()}"
+
+    recovery_message += "\n```"
+
+    console.print(recovery_message)
+    console.print("\n[dim]Claude will automatically resume from where you left off.[/dim]")
+    console.print("=" * 60 + "\n")
+
+
 # Playbook commands
 
 @playbook_app.command("stats")

{mapify_cli-1.1.0 → mapify_cli-1.2.0}/src/mapify_cli/playbook_manager.py

@@ -46,6 +46,9 @@ QUALITY_SCORE_MAX = 10.0  # Typical max quality score for bullets
 RELEVANCE_WEIGHT = 0.7    # Weight for relevance in combined score
 QUALITY_WEIGHT = 0.3      # Weight for quality in combined score
 
+# Schema version constants
+CURRENT_SCHEMA_VERSION = '2.1'  # Added executable_scripts field
+
 
 class PlaybookManager:
     """Manages ACE-style playbook with incremental delta updates."""
@@ -73,6 +76,9 @@ class PlaybookManager:
         # Enable WAL mode for better concurrency
         self.db_conn.execute("PRAGMA journal_mode=WAL")
 
+        # Run schema migrations if needed
+        self._migrate_schema()
+
         # Load playbook structure from SQLite for backward compatibility
         self.playbook = self._load_playbook_from_db()
 
@@ -163,7 +169,8 @@ class PlaybookManager:
                 deprecated INTEGER DEFAULT 0,
                 deprecation_reason TEXT,
                 tags TEXT,
-                related_bullets TEXT
+                related_bullets TEXT,
+                executable_scripts TEXT
             )
         """)
 
@@ -222,12 +229,54 @@ class PlaybookManager:
         cursor.execute("INSERT OR IGNORE INTO metadata VALUES ('version', '1.0')")
         cursor.execute(f"INSERT OR IGNORE INTO metadata VALUES ('last_updated', '{now}')")
         cursor.execute("INSERT OR IGNORE INTO metadata VALUES ('total_bullets', '0')")
-        cursor.execute("INSERT OR IGNORE INTO metadata VALUES ('schema_version', '2.0')")
+        cursor.execute(f"INSERT OR IGNORE INTO metadata VALUES ('schema_version', '{CURRENT_SCHEMA_VERSION}')")
         cursor.execute("INSERT OR IGNORE INTO metadata VALUES ('top_k', '5')")
 
         conn.commit()
         conn.close()
 
+    def _migrate_schema(self) -> None:
+        """
+        Run schema migrations to upgrade database to current version.
+
+        Migrations are idempotent and safe to run multiple times.
+        Each migration checks schema_version before applying changes.
+        """
+        cursor = self.db_conn.cursor()
+
+        # Get current schema version
+        cursor.execute("SELECT value FROM metadata WHERE key = 'schema_version'")
+        result = cursor.fetchone()
+        current_version = result[0] if result else '2.0'  # Default for old DBs without version
+
+        # Migration: 2.0 -> 2.1 (add executable_scripts field)
+        if current_version == '2.0':
+            print("Migrating schema from 2.0 to 2.1 (adding executable_scripts field)...", file=sys.stderr)
+
+            # Check if column already exists (idempotency)
+            cursor.execute("PRAGMA table_info(bullets)")
+            columns = [row[1] for row in cursor.fetchall()]
+
+            if 'executable_scripts' not in columns:
+                # Add new column with NULL default (backward compatible)
+                cursor.execute("ALTER TABLE bullets ADD COLUMN executable_scripts TEXT")
+                print("✓ Added executable_scripts column to bullets table", file=sys.stderr)
+            else:
+                print("✓ executable_scripts column already exists, skipping", file=sys.stderr)
+
+            # Update schema version
+            cursor.execute("UPDATE metadata SET value = '2.1' WHERE key = 'schema_version'")
+            self.db_conn.commit()
+            print("✓ Schema migration complete (2.0 -> 2.1)", file=sys.stderr)
+
+        elif current_version == CURRENT_SCHEMA_VERSION:
+            # Already at current version, no migration needed
+            pass
+
+        else:
+            # Future version or unknown version
+            print(f"Warning: Unknown schema version {current_version}, expected {CURRENT_SCHEMA_VERSION}", file=sys.stderr)
+
     def _migrate_json_to_sqlite(self) -> None:
         """
         Migrate existing playbook.json to SQLite database.
@@ -266,8 +315,8 @@ class PlaybookManager:
                                               helpful_count, harmful_count,
                                               created_at, last_used_at,
                                               deprecated, deprecation_reason,
-                                              tags, related_bullets)
-                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                                              tags, related_bullets, executable_scripts)
+                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                     """, (
                         bullet['id'],
                         section_name,
@@ -280,7 +329,8 @@ class PlaybookManager:
                         1 if bullet.get('deprecated', False) else 0,
                         bullet.get('deprecation_reason'),
                         json.dumps(bullet.get('tags', [])),
-                        json.dumps(bullet.get('related_bullets', []))
+                        json.dumps(bullet.get('related_bullets', [])),
+                        json.dumps(bullet.get('executable_scripts', [])) if bullet.get('executable_scripts') else None
                     ))
                     total_bullets += 1
                 except sqlite3.IntegrityError as e:
@@ -334,7 +384,7 @@ class PlaybookManager:
             SELECT section, id, content, code_example,
                    helpful_count, harmful_count, quality_score,
                    created_at, last_used_at, deprecated, deprecation_reason,
-                   tags, related_bullets
+                   tags, related_bullets, executable_scripts
             FROM bullets
             ORDER BY section, quality_score DESC
         """)
@@ -371,6 +421,8 @@ class PlaybookManager:
                 bullet['tags'] = json.loads(row['tags'])
             if row['related_bullets']:
                 bullet['related_bullets'] = json.loads(row['related_bullets'])
+            if row['executable_scripts']:
+                bullet['executable_scripts'] = json.loads(row['executable_scripts'])
 
             sections[section_name]['bullets'].append(bullet)
 
@@ -422,7 +474,8 @@ class PlaybookManager:
                         content=op["content"],
                         code_example=op.get("code_example"),
                         related_to=op.get("related_to", []),
-                        tags=op.get("tags", [])
+                        tags=op.get("tags", []),
+                        executable_scripts=op.get("executable_scripts", [])
                     )
                     summary["added"] += 1
 
@@ -461,7 +514,8 @@ class PlaybookManager:
         content: str,
         code_example: Optional[str] = None,
         related_to: List[str] = None,
-        tags: List[str] = None
+        tags: List[str] = None,
+        executable_scripts: List[str] = None
     ) -> str:
         """Add new bullet to section (saves to SQLite)."""
         if section not in self.playbook["sections"]:
@@ -477,8 +531,8 @@ class PlaybookManager:
                                   helpful_count, harmful_count,
                                   created_at, last_used_at,
                                   deprecated, deprecation_reason,
-                                  tags, related_bullets)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                                  tags, related_bullets, executable_scripts)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """, (
             bullet_id,
             section,
@@ -491,7 +545,8 @@ class PlaybookManager:
             0,  # deprecated
             None,
             json.dumps(tags or []),
-            json.dumps(related_to or [])
+            json.dumps(related_to or []),
+            json.dumps(executable_scripts) if executable_scripts else None
         ))
 
         # Update metadata
@@ -514,6 +569,9 @@ class PlaybookManager:
             "deprecated": False,
             "deprecation_reason": None
         }
+        if executable_scripts:
+            bullet["executable_scripts"] = executable_scripts
+
         self.playbook["sections"][section]["bullets"].append(bullet)
         self.playbook["metadata"]["total_bullets"] += 1
 
@@ -949,6 +1007,10 @@ class PlaybookManager:
         import string
         fts_query = params.query
 
+        # FTS5 tokenizer splits hyphens at index time ("session-start" → ["session", "start"])
+        # Align query tokenization by replacing hyphens with spaces
+        fts_query = fts_query.replace('-', ' ')
+
         # Remove FTS5 special characters: @ # ( ) " ' :
         fts_special_chars = '@#()"\':'
         for char in fts_special_chars: