stravinsky 0.2.67__py3-none-any.whl → 0.4.18__py3-none-any.whl

mcp_bridge/config/README.md

@@ -0,0 +1,276 @@
+# Stravinsky Configuration & Manifest System
+
+## Overview
+
+The `mcp_bridge/config/` directory contains:
+
+1. **hooks_manifest.json** - Version tracking for 32 official hooks
+2. **skills_manifest.json** - Metadata for 16 slash commands/skills
+3. **MANIFEST_SCHEMA.md** - Detailed schema documentation
+4. **hooks.py** - Hook configuration utilities
+5. **README.md** - This file
+
+## Quick Start
+
+### For Users
+No action needed. Manifests are automatically managed by the Stravinsky package.
+
+### For Maintainers
+When releasing a new version:
+
+```bash
+# 1. Update version in pyproject.toml and mcp_bridge/__init__.py
+# 2. Regenerate manifests (if hooks/skills changed)
+python scripts/generate_manifests.py
+
+# 3. Commit changes
+git add mcp_bridge/config/*.json
+git commit -m "chore: update manifests for v0.3.X"
+```
+
+## File Descriptions
+
+### hooks_manifest.json
+Tracks all 32 official hooks provided by Stravinsky:
+
+- **Core execution hooks** (3): `parallel_execution`, `stravinsky_mode`, `todo_delegation`
+- **Context hooks** (6): `context`, `todo_continuation`, `todo_enforcer`, `directory_context`, `rules_injector`, `pre_compact`
+- **Tool enhancement hooks** (6): `tool_messaging`, `edit_recovery`, `truncator`, `empty_message_sanitizer`, `comment_checker`, `compaction`
+- **Agent lifecycle hooks** (4): `notification_hook`, `subagent_stop`, `session_recovery`, `task_validator`
+- **Advanced optimization** (5): `preemptive_compaction`, `parallel_enforcer`, `auto_slash_command`, `agent_reminder`, `budget_optimizer`
+- **Execution context** (3): `keyword_detector`, `git_noninteractive`, `session_idle`, `session_notifier`, `tmux_manager`
+
+**Key Metrics:**
+- 9 required hooks (critical path)
+- 23 optional hooks (enhanced behavior)
+- 2 critical priority, 11 high, 12 medium, 7 low
+
+### skills_manifest.json
+Tracks all 16 slash commands (skills):
+
+**Core Skills (4):**
+- `/strav` - Task orchestration
+- `/strav:loop` - Continuation loop management
+- `/strav:cancel-loop` - Loop cancellation
+- `/version` - Diagnostic info
+
+**Implementation Skills (4):**
+- `/commit` - Git commit orchestration
+- `/review` - Code review
+- `/verify` - Testing and deployment verification
+- `/publish` - PyPI deployment
+
+**Research Skills (7):**
+- `/dewey` - Documentation research
+- `/index` - Semantic search indexing
+- `/str:index` - Detailed semantic indexing
+- `/str:search` - Semantic code search
+- `/str:start_filewatch` - File watching
+- `/str:stop_filewatch` - Stop file watching
+- `/str:stats` - Index statistics
+
+**Architecture Skills (1):**
+- `/delphi` - Strategic advisor
+
+**Key Metrics:**
+- 6 blocking skills (immediate execution)
+- 10 async skills (background execution)
+- All skills marked updatable=true (user customizable)
+
+## Integration with update_manager.py
+
+The manifests enable smart update workflows:
+
+### Version Checking
+```python
+# Load manifest from installed package
+manifest = load_manifest_from_package()
+
+# Compare with remote version
+if manifest.manifest_version < remote_version:
+    # Updates available
+    show_update_notification()
+```
+
+### Integrity Verification
+```python
+# Before updating a hook, verify it hasn't been modified
+current_hash = compute_sha256(hook_file)
+expected_hash = manifest[hook_name].checksum
+
+if current_hash != expected_hash:
+    # User has customized this hook
+    if manifest[hook_name].updatable:
+        warn_about_modifications()
+```
+
+### Selective Updates
+```python
+# Only update files marked updatable=true
+# Respect user customizations in .claude/hooks/
+for hook_name, hook_info in manifest.hooks.items():
+    if hook_info.updatable and hook_info.priority in ["critical", "high"]:
+        update_hook(hook_name)
+```
+
+### Dependency Resolution
+```python
+# Ensure all dependencies are installed
+for dependency in hook_info.dependencies:
+    if not is_installed(dependency):
+        error(f"Missing dependency: {dependency}")
+```
+
+## Manifest Fields Reference
+
+### Hook Entry
+```json
+{
+  "hook_name": {
+    "version": "0.2.63",
+    "source": "mcp_bridge/hooks/hook_name.py",
+    "description": "What this hook does",
+    "hook_type": "PreToolUse|PostToolUse|UserPromptSubmit|...",
+    "checksum": "sha256_first_12_chars",
+    "lines_of_code": 150,
+    "updatable": true,
+    "priority": "critical|high|medium|low",
+    "required": true,
+    "dependencies": ["manager.py"]
+  }
+}
+```
+
+### Skill Entry
+```json
+{
+  "skill_name": {
+    "file_path": "strav.md or str/search.md",
+    "description": "What this skill does",
+    "category": "core|research|implementation|architecture",
+    "checksum": "sha256_first_12_chars",
+    "lines_of_code": 200,
+    "updatable": true,
+    "priority": "critical|high|medium|low",
+    "agent_type": "explore|dewey|frontend|...",
+    "blocking": true,
+    "requires_auth": true,
+    "version_first_added": "0.1.0"
+  }
+}
+```
+
+See **MANIFEST_SCHEMA.md** for complete field documentation.
+
+## Checksum Verification
+
+### Generate Checksums
+```bash
+# For a single file
+sha256sum mcp_bridge/hooks/parallel_execution.py | awk '{print substr($1,1,12)}'
+
+# For all hooks
+for f in mcp_bridge/hooks/*.py; do
+  echo "$(basename $f): $(sha256sum $f | awk '{print substr($1,1,12)}')"
+done
+```
+
+### Verify File Integrity
+```bash
+# Check if a file has been modified
+current=$(sha256sum mcp_bridge/hooks/parallel_execution.py | awk '{print substr($1,1,12)}')
+expected=$(jq -r '.hooks.parallel_execution.checksum' mcp_bridge/config/hooks_manifest.json)
+
+if [ "$current" != "$expected" ]; then
+  echo "File has been modified locally"
+fi
+```
+
+## Update Strategy
+
+### Priority Levels
+- **critical**: Security, core functionality - update immediately
+- **high**: New features, important improvements - include in next release
+- **medium**: Enhancements - can batch together
+- **low**: Optional improvements - can defer
+
+### Update Workflow
+1. Check `manifest_version` against installed version
+2. If newer version available, proceed to verify step
+3. For each hook/skill:
+   - Compute current checksum
+   - Compare with manifest checksum
+   - If modified: warn user or skip (respect customizations)
+   - If unmodified and priority is high/critical: update
+4. After updates, recompute checksums
+5. Update manifest with new version
+
+## Best Practices
+
+### For Stravinsky Maintainers
+1. **Always update manifests on release** - Use `scripts/generate_manifests.py`
+2. **Document hook changes** - Update descriptions if functionality changes
+3. **Keep checksums current** - Run verification script before commits
+4. **Track dependencies** - Add any new hook dependencies to manifest
+5. **Test manifest generation** - Validate JSON before commit
+
+### For Package Users
+1. **Don't edit manifests manually** - Let automated tools manage them
+2. **Preserve customizations** - Store custom hooks in `.claude/hooks/` instead
+3. **Check authentication** - Skills requiring auth need OAuth setup
+4. **Review update notes** - Read manifest notes for important context
+
+### For Hook Developers
+1. **Add to manifest immediately** - New hooks must be in manifest
+2. **Include checksum** - Use `sha256sum | awk '{print substr($1,1,12)}'`
+3. **Document dependencies** - List all other hooks/modules needed
+4. **Test locally** - Verify hook works before adding to manifest
+5. **Update version field** - Bump manifest version on release
+
+## Troubleshooting
+
+### Manifest JSON is invalid
+```bash
+# Validate JSON syntax
+python -m json.tool mcp_bridge/config/hooks_manifest.json > /dev/null
+```
+
+### Checksums don't match
+```bash
+# Regenerate checksums
+python scripts/generate_manifests.py --recalc-checksums
+```
+
+### Missing hooks in manifest
+```bash
+# List all hooks not in manifest
+diff <(ls mcp_bridge/hooks/*.py | sed 's/.*\///' | sort) \
+     <(jq -r '.hooks | keys[]' mcp_bridge/config/hooks_manifest.json | sort)
+```
+
+### Update fails for a hook
+1. Check file permissions: `ls -l mcp_bridge/hooks/hook_name.py`
+2. Verify checksum: Compare current vs manifest
+3. Check dependencies: Ensure all are installed
+4. Review logs: Look for error messages in update output
+
+## Related Files
+
+- `mcp_bridge/__init__.py` - Package version
+- `mcp_bridge/hooks/manager.py` - Hook execution system
+- `mcp_bridge/cli/install_hooks.py` - Hook installation
+- `.claude/settings.json` - Hook configuration
+- `pyproject.toml` - Package metadata
+
+## Version History
+
+### v1.0.0 (Current)
+- Initial manifest schema
+- 32 hooks tracked
+- 16 skills tracked
+- SHA-256 checksum verification
+- Priority-based update strategy
+
+## Questions?
+
+See **MANIFEST_SCHEMA.md** for detailed documentation.

mcp_bridge/config/hook_config.py

@@ -0,0 +1,249 @@
+"""
+Hook configuration with selective disabling support.
+
+Provides batteries-included defaults with user-configurable overrides.
+Users can disable specific hooks via ~/.stravinsky/disable_hooks.txt
+"""
+
+import os
+from pathlib import Path
+from typing import Set, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Default locations for disable hooks config
+DISABLE_HOOKS_PATHS = [
+    Path.home() / ".stravinsky" / "disable_hooks.txt",
+    Path(".stravinsky") / "disable_hooks.txt",
+    Path(".claude") / "disable_hooks.txt",
+]
+
+
+def get_disabled_hooks() -> Set[str]:
+    """
+    Load disabled hooks from config files.
+
+    Checks (in order):
+    1. ~/.stravinsky/disable_hooks.txt (user global)
+    2. .stravinsky/disable_hooks.txt (project local)
+    3. .claude/disable_hooks.txt (claude project local)
+
+    Returns:
+        Set of hook names that should be disabled.
+    """
+    disabled = set()
+
+    for path in DISABLE_HOOKS_PATHS:
+        if path.exists():
+            try:
+                content = path.read_text()
+                for line in content.splitlines():
+                    line = line.strip()
+                    # Skip comments and empty lines
+                    if line and not line.startswith("#"):
+                        disabled.add(line)
+                logger.debug(f"Loaded disabled hooks from {path}: {disabled}")
+            except Exception as e:
+                logger.warning(f"Failed to read {path}: {e}")
+
+    return disabled
+
+
+def is_hook_enabled(hook_name: str) -> bool:
+    """
+    Check if a specific hook is enabled.
+
+    Args:
+        hook_name: Name of the hook (e.g., 'comment_checker', 'session_recovery')
+
+    Returns:
+        True if the hook is enabled (not in disable list), False otherwise.
+    """
+    disabled = get_disabled_hooks()
+    return hook_name not in disabled
+
+
+def get_hook_config_path() -> Path:
+    """
+    Get the path to the user's hook config directory.
+    Creates it if it doesn't exist.
+    """
+    config_dir = Path.home() / ".stravinsky"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir
+
+
+def create_sample_disable_hooks() -> Optional[Path]:
+    """
+    Create a sample disable_hooks.txt file with documentation.
+
+    Returns:
+        Path to the created file, or None if it already exists.
+    """
+    config_dir = get_hook_config_path()
+    disable_file = config_dir / "disable_hooks.txt"
+
+    if disable_file.exists():
+        return None
+
+    sample_content = """# Stravinsky Hook Disabling Configuration
+# Add hook names (one per line) to disable them.
+# Lines starting with # are comments.
+#
+# Available hooks:
+# ================
+# 
+# PreToolUse Hooks:
+# - comment_checker       (checks git commit comments for quality)
+# - stravinsky_mode       (blocks direct tool calls, forces delegation)
+# - notification_hook     (displays agent spawn notifications)
+#
+# PostToolUse Hooks:
+# - session_recovery      (detects API errors and logs recovery info)
+# - parallel_execution    (injects parallel execution instructions)
+# - todo_delegation       (enforces parallel Task spawning for todos)
+# - tool_messaging        (user-friendly MCP tool messages)
+# - edit_recovery         (suggests recovery for Edit failures)
+# - truncator             (truncates long responses)
+# - subagent_stop         (handles subagent completion)
+#
+# UserPromptSubmit Hooks:
+# - context               (injects CLAUDE.md content)
+# - todo_continuation     (reminds about incomplete todos)
+#
+# PreCompact Hooks:
+# - pre_compact           (preserves critical context before compaction)
+#
+# Example - to disable the comment checker:
+# comment_checker
+#
+# Example - to disable ultrawork mode detection:
+# parallel_execution
+"""
+
+    disable_file.write_text(sample_content)
+    logger.info(f"Created sample disable_hooks.txt at {disable_file}")
+    return disable_file
+
+
+# Hook metadata for batteries-included config
+HOOK_DEFAULTS = {
+    # PreToolUse hooks
+    "comment_checker": {
+        "type": "PreToolUse",
+        "description": "Checks git commit comments for quality issues",
+        "default_enabled": True,
+        "exit_on_block": 0,  # Warn but don't block
+    },
+    "stravinsky_mode": {
+        "type": "PreToolUse",
+        "description": "Blocks direct tool calls, forces Task delegation",
+        "default_enabled": True,
+        "exit_on_block": 2,  # Hard block
+    },
+    "notification_hook": {
+        "type": "PreToolUse",
+        "description": "Displays agent spawn notifications",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    # PostToolUse hooks
+    "session_recovery": {
+        "type": "PostToolUse",
+        "description": "Detects API errors and logs recovery suggestions",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "parallel_execution": {
+        "type": "PostToolUse",
+        "description": "Injects parallel execution and ULTRAWORK mode",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "todo_delegation": {
+        "type": "PostToolUse",
+        "description": "Enforces parallel Task spawning for 2+ todos",
+        "default_enabled": True,
+        "exit_on_block": 2,  # Hard block in stravinsky mode
+    },
+    "tool_messaging": {
+        "type": "PostToolUse",
+        "description": "User-friendly messages for MCP tools",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "edit_recovery": {
+        "type": "PostToolUse",
+        "description": "Suggests recovery for Edit failures",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "truncator": {
+        "type": "PostToolUse",
+        "description": "Truncates responses longer than 30k chars",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "subagent_stop": {
+        "type": "SubagentStop",
+        "description": "Handles subagent completion events",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    # UserPromptSubmit hooks
+    "context": {
+        "type": "UserPromptSubmit",
+        "description": "Injects CLAUDE.md content to prompts",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    "todo_continuation": {
+        "type": "UserPromptSubmit",
+        "description": "Reminds about incomplete todos",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+    # PreCompact hooks
+    "pre_compact": {
+        "type": "PreCompact",
+        "description": "Preserves critical context before compaction",
+        "default_enabled": True,
+        "exit_on_block": 0,
+    },
+}
+
+
+def get_enabled_hooks() -> dict:
+    """
+    Get all enabled hooks with their configuration.
+
+    Returns:
+        Dict of hook_name -> hook_config for enabled hooks only.
+    """
+    disabled = get_disabled_hooks()
+    enabled = {}
+
+    for hook_name, config in HOOK_DEFAULTS.items():
+        if hook_name not in disabled and config.get("default_enabled", True):
+            enabled[hook_name] = config
+
+    return enabled
+
+
+def list_hooks() -> str:
+    """
+    List all hooks with their status.
+
+    Returns:
+        Formatted string showing hook status.
+    """
+    disabled = get_disabled_hooks()
+    lines = ["# Stravinsky Hooks Status", ""]
+
+    for hook_name, config in sorted(HOOK_DEFAULTS.items()):
+        status = "DISABLED" if hook_name in disabled else "enabled"
+        icon = "" if hook_name in disabled else ""
+        lines.append(f"{icon} {hook_name}: {status} - {config['description']}")
+
+    return "\n".join(lines)

mcp_bridge/config/hooks_manifest.json

@@ -0,0 +1,138 @@
+{
+  "schema_version": "1.0.0",
+  "manifest_version": "0.3.9",
+  "description": "Stravinsky hooks for Claude Code integration",
+  "generated_date": "2026-01-08T23:53:08.836595Z",
+  "hooks": {
+    "context.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/context.py",
+      "description": "Project context injection from local files",
+      "checksum": "2411ea9d7ef9",
+      "lines_of_code": 38,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "context_monitor.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/context_monitor.py",
+      "description": "Pre-emptive context optimization at 70% threshold",
+      "checksum": "7a8d0615af4f",
+      "lines_of_code": 153,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "edit_recovery.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/edit_recovery.py",
+      "description": "Edit/MultiEdit error recovery helper",
+      "checksum": "d4e5a96f7bfc",
+      "lines_of_code": 46,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "notification_hook.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/notification_hook.py",
+      "description": "Agent spawn message formatting",
+      "checksum": "184947c5a227",
+      "lines_of_code": 103,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "parallel_execution.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/parallel_execution.py",
+      "description": "Pre-emptive parallel execution enforcement",
+      "checksum": "9c820d3d19be",
+      "lines_of_code": 111,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "pre_compact.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/pre_compact.py",
+      "description": "Context preservation before compaction",
+      "checksum": "4177023bd901",
+      "lines_of_code": 123,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "stop_hook.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/stop_hook.py",
+      "description": "Continuation loop handler",
+      "checksum": "820aef797e2e",
+      "lines_of_code": 234,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "stravinsky_mode.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/stravinsky_mode.py",
+      "description": "Hard blocking of native tools",
+      "checksum": "5968a95ebcbe",
+      "lines_of_code": 146,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "subagent_stop.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/subagent_stop.py",
+      "description": "Subagent completion handler",
+      "checksum": "1943d8dc5355",
+      "lines_of_code": 98,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "todo_continuation.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/todo_continuation.py",
+      "description": "Todo continuation enforcer",
+      "checksum": "b6685355f319",
+      "lines_of_code": 90,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "todo_delegation.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/todo_delegation.py",
+      "description": "Parallel task spawning enforcement",
+      "checksum": "b4e004d51600",
+      "lines_of_code": 88,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "tool_messaging.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/tool_messaging.py",
+      "description": "User-friendly tool messaging",
+      "checksum": "04a10e76f890",
+      "lines_of_code": 263,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    },
+    "truncator.py": {
+      "version": "0.3.9",
+      "source": "mcp_bridge/hooks/truncator.py",
+      "description": "Tool response truncation at 30k chars",
+      "checksum": "87785bf2c657",
+      "lines_of_code": 23,
+      "updatable": true,
+      "priority": "high",
+      "required": true
+    }
+  }
+}