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

mcp_bridge/config/MANIFEST_SCHEMA.md

@@ -0,0 +1,305 @@
+# Stravinsky Manifest Schema Documentation
+
+## Overview
+
+The manifest files (`hooks_manifest.json` and `skills_manifest.json`) track version information, integrity, and metadata for all Stravinsky-provided hooks and skills. These manifests enable:
+
+- **Integrity Verification**: Detect unauthorized or accidental modifications
+- **Update Management**: Determine which files need updating during package upgrades
+- **User Customization**: Distinguish between official Stravinsky files and user modifications
+- **Dependency Tracking**: Understand hook dependencies and required relationships
+
+## File Locations
+
+```
+mcp_bridge/config/
+├── hooks_manifest.json      # Official hook metadata
+├── skills_manifest.json     # Slash command metadata
+└── MANIFEST_SCHEMA.md       # This documentation
+```
+
+## Manifest Structure
+
+### Common Fields
+
+Both manifests share these top-level fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `schema_version` | string | Manifest format version (e.g., "1.0.0") |
+| `manifest_version` | string | Stravinsky package version this manifest was generated for |
+| `description` | string | Brief description of manifest purpose |
+| `generated_date` | ISO 8601 | Timestamp when manifest was created/updated |
+| `schema` | object | Field definitions and their meanings |
+| `[items]` | object | Collection of hooks or skills with metadata |
+| `usage` | object | Integration notes for `update_manager.py` |
+
+### hooks_manifest.json Schema
+
+Each hook entry has these fields:
+
+```json
+{
+  "hook_name": {
+    "version": "0.2.63",
+    "source": "mcp_bridge/hooks/hook_name.py",
+    "description": "Brief description of hook purpose",
+    "hook_type": "PreToolUse|PostToolUse|UserPromptSubmit|Notification|SubagentStop|PreCompact|package|manager|session_idle|session_manager",
+    "checksum": "sha256_first_12_chars",
+    "lines_of_code": 150,
+    "updatable": true,
+    "priority": "critical|high|medium|low",
+    "required": true,
+    "dependencies": ["manager.py", "other_hook.py"]
+  }
+}
+```
+
+### skills_manifest.json Schema
+
+Each skill entry has these fields:
+
+```json
+{
+  "skill_name": {
+    "file_path": "strav.md or str/search.md",
+    "description": "Description from skill frontmatter",
+    "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|delphi|stravinsky|implementation_lead|code_reviewer",
+    "blocking": true,
+    "requires_auth": true,
+    "version_first_added": "0.1.0",
+    "notes": "Additional context or special considerations"
+  }
+}
+```
+
+## Field Definitions
+
+### `version`
+Semantic version of the hook/skill implementation. Format: `X.Y.Z` (e.g., `0.2.63`).
+
+### `source` / `file_path`
+Absolute path (hooks) or relative path from `.claude/commands/` (skills).
+
+### `description`
+One-line functional description of what the hook/skill does.
+
+### `hook_type` (hooks only)
+Claude Code hook type that this hook implements:
+- **PreToolUse**: Runs before tool execution (can block with exit code 2)
+- **PostToolUse**: Runs after tool completes
+- **UserPromptSubmit**: Runs when user submits prompt
+- **Notification**: Runs on notification events
+- **SubagentStop**: Runs when agent completes
+- **PreCompact**: Runs before context compaction
+- **package**: Module/package initialization
+- **manager**: Hook management infrastructure
+- **session_idle**: Session idle detection
+
+### `category` (skills only)
+Skill category for organization:
+- **core**: Essential orchestration features
+- **research**: Documentation and code search
+- **implementation**: Development workflows (test, review, deploy)
+- **architecture**: Strategic advice and complex debugging
+
+### `checksum`
+SHA-256 hash (first 12 characters) for integrity verification.
+
+**How to verify/generate:**
+```bash
+# Generate checksum
+sha256sum mcp_bridge/hooks/hook_name.py | awk '{print substr($1,1,12)}'
+
+# Verify file hasn't been modified
+sha256sum -c <<< "checksum_value mcp_bridge/hooks/hook_name.py"
+```
+
+### `updatable`
+- **true**: Official Stravinsky file - can be auto-updated by `update_manager.py`
+- **false**: User customization or user-provided hook - skip during updates
+
+**CRITICAL**: User hooks from `.claude/hooks/` should ALWAYS have `updatable: false` in the internal manifest comparison.
+
+### `priority`
+Update urgency level:
+- **critical**: Security fixes, core functionality - update immediately
+- **high**: New features, important improvements - include in next release
+- **medium**: Enhancements, can batch with other updates
+- **low**: Optional improvements, can defer
+
+### `required`
+- **true**: Hook is essential for core functionality and cannot be disabled
+- **false**: Optional hook that provides enhanced behavior but isn't critical
+
+### `blocking` (skills only)
+- **true**: Skill blocks execution until completion
+- **false**: Skill runs asynchronously in background
+
+### `agent_type` (skills only)
+Primary agent spawned by this skill:
+- **stravinsky**: Task orchestration
+- **explore**: Codebase search
+- **dewey**: Documentation research
+- **delphi**: Strategic architecture advisor
+- **frontend**: UI/UX design
+- **implementation_lead**: Coordinates implementation
+- **code_reviewer**: Quality analysis
+
+### `requires_auth` (skills only)
+- **true**: Skill requires OAuth setup (Gemini or OpenAI)
+- **false**: Skill works without authentication
+
+### `dependencies`
+List of other files this hook/skill depends on:
+- Hooks typically depend on `manager.py`
+- Some hooks depend on other hooks they coordinate with
+- Skills may list dependent tools or agents
+
+## Integration with update_manager.py
+
+The `update_manager.py` module should use these manifests to:
+
+### 1. Version Checking
+```python
+# Load installed manifest
+installed_manifest = load_manifest("hooks_manifest.json")
+
+# Compare with remote version
+if installed_manifest.version < remote_manifest.version:
+    # Updates available
+    pass
+```
+
+### 2. Integrity Verification
+```python
+# Before updating, verify file hasn't been locally modified
+current_checksum = compute_sha256(file_path)
+expected_checksum = manifest[hook_name].checksum
+
+if current_checksum != expected_checksum and manifest[hook_name].updatable:
+    # Local modifications detected - warn user or skip
+    skip_update(hook_name)
+```
+
+### 3. Selective Updates
+```python
+# Only update files marked updatable=true
+for hook_name, hook_info in manifest.items():
+    if hook_info.updatable and should_update(hook_info.priority):
+        update_hook(hook_name, new_version)
+```
+
+### 4. Dependency Resolution
+```python
+# Ensure dependencies are met before updating
+for dependency in hook_info.dependencies:
+    if not is_dependency_installed(dependency):
+        error("Missing dependency: " + dependency)
+```
+
+## Usage Examples
+
+### Checking Hook Status
+```bash
+# Find all critical hooks needing updates
+jq '.hooks | to_entries[] | select(.value.priority == "critical")' \
+  mcp_bridge/config/hooks_manifest.json
+
+# Check if a hook is required
+jq '.hooks.parallel_enforcer.required' \
+  mcp_bridge/config/hooks_manifest.json
+```
+
+### Verifying File Integrity
+```bash
+# Verify all hooks match expected checksums
+python -c "
+import json
+from pathlib import Path
+
+with open('mcp_bridge/config/hooks_manifest.json') as f:
+    manifest = json.load(f)
+
+for hook_name, info in manifest['hooks'].items():
+    file_path = info['source']
+    if Path(file_path).exists():
+        # Compute checksum and compare
+        pass
+"
+```
+
+### Listing Available Skills
+```bash
+# Extract all skills with their agents
+jq '.skills | to_entries[] | {name: .key, agent: .value.agent_type, blocking: .value.blocking}' \
+  mcp_bridge/config/skills_manifest.json
+```
+
+## Best Practices
+
+### For Stravinsky Maintainers
+
+1. **Update on Release**: Regenerate manifests when releasing a new version
+2. **Verify Checksums**: Ensure all checksums are current and accurate
+3. **Document Changes**: Add notes to skills when updating functionality
+4. **Priority Assignment**: Use priority levels consistently across releases
+5. **Dependency Tracking**: Keep dependency lists current and accurate
+
+### For Package Users
+
+1. **Don't Modify Manifests**: Let `update_manager.py` handle manifest updates
+2. **Preserve Customizations**: Don't modify hooks marked as required=true without good reason
+3. **Check Auth Requirements**: Ensure OAuth is configured for skills requiring authentication
+4. **Monitor Critical Updates**: Subscribe to updates for hooks marked priority=critical
+
+### For Developers
+
+1. **Custom Hooks**: Create custom hooks in `.claude/hooks/` (not in package)
+2. **Hook Testing**: Always test hooks with sample input before deploying
+3. **Checksum Calculation**: Update checksums when modifying hook files
+4. **Dependency Management**: Clearly document all hook dependencies
+
+## Schema Evolution
+
+### Version 1.0.0 (Current)
+- Initial manifest format
+- Hook and skill metadata tracking
+- Integrity verification via checksums
+- Priority-based update strategy
+
+### Future Versions
+- Will be tracked in `schema_version`
+- Backward compatibility maintained where possible
+- Migration guides provided for breaking changes
+
+## Troubleshooting
+
+### Checksum Mismatch
+**Problem**: Hook has been modified locally
+**Solution**:
+- If intentional: Update manifest checksum or move to custom hooks
+- If accidental: Restore original file from package
+
+### Missing Dependencies
+**Problem**: Hook dependency is not installed
+**Solution**: Ensure all required hooks in `dependencies` list are installed
+
+### Update Failures
+**Problem**: `update_manager.py` fails to update a hook
+**Solution**:
+- Check file permissions
+- Verify checksum hasn't changed unexpectedly
+- Check for read-only files
+
+## Related Files
+
+- `mcp_bridge/cli/install_hooks.py` - Hook installation script
+- `mcp_bridge/config/hooks.py` - Hook configuration utilities
+- `mcp_bridge/hooks/manager.py` - Hook execution manager
+- `.claude/settings.json` - Claude Code hook configuration

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.