sqlew 4.0.5 → 4.1.1

package/docs/MIGRATION_GUIDE_V3.9.0.md

@@ -1,371 +0,0 @@
-# Migration Guide: v3.9.0
-
-**Release Date:** 2025-11-14
-**Status:** Production Ready
-**Compatibility:** Fully backward compatible with v3.8.x
-
----
-
-## Overview
-
-v3.9.0 introduces the **Decision Intelligence System** with the new `suggest` tool, along with critical bug fixes for cross-database compatibility and improved test organization.
-
-### Quick Summary
-
-**✅ No Breaking Changes**
-**✅ Automatic Migration**
-**✅ Zero Downtime**
-**🆕 New suggest Tool**
-**🐛 PostgreSQL/MySQL Fixes**
-**🧪 Better Test Organization**
-
----
-
-## What's New
-
-### 1. Decision Intelligence System (suggest Tool)
-
-**Purpose:** Intelligent decision discovery, duplicate prevention, and consistency maintenance.
-
-**New Actions:**
-```typescript
-// Find decisions by key pattern
-suggest({ action: "by_key", key: "api/*/latency", limit: 5, min_score: 30 })
-
-// Find decisions by tag similarity
-suggest({ action: "by_tags", tags: ["performance", "api"], limit: 5 })
-
-// Combined search (key + tags + layer)
-suggest({ action: "by_context", key: "api/*", tags: ["performance"], layer: "infrastructure" })
-
-// Check for duplicates before creation
-suggest({ action: "check_duplicate", key: "api/users/get/latency", tags: ["api", "performance"] })
-```
-
-**Auto-Trigger Integration:**
-When policies have `suggest_similar=1`, suggestions are automatically triggered and returned in `decision.set` response:
-
-```typescript
-const result = await decision({
-  action: "set",
-  key: "security/cve/2024-001",
-  value: "critical",
-  tags: ["security", "vulnerability"]
-});
-
-// Response includes auto-triggered suggestions
-{
-  success: true,
-  key: "security/cve/2024-001",
-  version: "1.0.0",
-  suggestions: {
-    triggered_by: "security-policy",
-    reason: "Policy has suggest_similar enabled",
-    suggestions: [
-      {
-        key: "security/cve/2023-999",
-        similarity_score: 85,
-        tags: ["security", "vulnerability"],
-        layer: "cross-cutting"
-      }
-    ]
-  }
-}
-```
-
-**Use Cases:**
-- Prevent duplicate decisions
-- Find related decisions for consistency
-- Discover decisions by pattern (e.g., all API latency metrics)
-- Maintain architectural consistency across layers
-
----
-
-## Migration Steps
-
-### Step 1: Backup Your Database
-
-**IMPORTANT:** Always backup before upgrading.
-
-```bash
-# Backup SQLite database
-cp .sqlew/sqlew.db .sqlew/sqlew.db.backup-$(date +%Y%m%d)
-
-# Backup PostgreSQL (if using)
-pg_dump -h localhost -U sqlew_user sqlew_db > backup-$(date +%Y%m%d).sql
-
-# Backup MySQL (if using)
-mysqldump -h localhost -u sqlew_user -p sqlew_db > backup-$(date +%Y%m%d).sql
-```
-
-### Step 2: Update sqlew
-
-```bash
-# Update via npm
-npm update sqlew
-
-# Or reinstall specific version
-npm install sqlew@3.9.0
-
-# Or use npx (recommended)
-# Update .mcp.json:
-{
-  "mcpServers": {
-    "sqlew": {
-      "command": "npx",
-      "args": ["sqlew@3.9.0"]
-    }
-  }
-}
-```
-
-### Step 3: Restart Claude Code
-
-The server will automatically run migrations on startup.
-
-```bash
-# Restart Claude Code or MCP inspector
-# Migrations run automatically
-```
-
-### Step 4: Verify Migration
-
-Check migration status:
-
-```bash
-# Inspect database
-sqlite3 .sqlew/sqlew.db "SELECT * FROM knex_migrations ORDER BY id DESC LIMIT 5;"
-
-# Expected latest migrations:
-# - 20251114000000_fix_v_tagged_decisions_numeric_support
-# - 20251112000002_fix_task_pruned_files_schema_v3_9_0
-# - 20251112000001_fix_task_file_links_schema_v3_9_0
-```
-
-### Step 5: Test suggest Tool
-
-```bash
-# Test suggest tool
-npx @modelcontextprotocol/inspector npx sqlew
-
-# In inspector:
-suggest({ action: "help" })
-suggest({ action: "by_key", key: "*" })
-```
-
----
-
-## Bug Fixes Included
-
-### 1. PostgreSQL CAST Type Mismatch (Critical)
-
-**Issue:** PostgreSQL rejected `COALESCE(TEXT, NUMERIC)` in `v_tagged_decisions` view.
-
-**Fixed:**
-- Migration adds database-specific CAST syntax
-- SQL dump export converts views correctly
-- All 20 cross-database tests passing
-
-**Impact:** If you use PostgreSQL or export to PostgreSQL, this fixes import errors.
-
-### 2. FK Constraint Cleanup Order
-
-**Issue:** E2E tests failed with FK constraint violations during cleanup.
-
-**Fixed:**
-- Reordered cleanup to delete child records first
-- All 3 e2e workflow tests passing
-
-**Impact:** Better test reliability, no functional changes for users.
-
-### 3. Task File Links Schema
-
-**Issue:** UNIQUE constraint incorrectly configured on `t_task_file_links`.
-
-**Fixed:**
-- Migration `20251112000001_fix_task_file_links_schema_v3_9_0.ts`
-- Idempotent with existence checks
-
-**Impact:** Better data integrity for task file tracking.
-
----
-
-## Test Organization Changes
-
-### Docker Test Separation
-
-**Old Structure:**
-```
-src/tests/database/
-  ├── sql-dump/
-  │   ├── cross-database.test.ts  # Required Docker
-  │   └── ...
-  └── migrations/
-      └── schema-migration.test.ts  # Required Docker
-```
-
-**New Structure:**
-```
-src/tests/
-  ├── docker/  # NEW - Docker-dependent tests
-  │   ├── cross-database.test.ts
-  │   ├── schema-migration.test.ts
-  │   └── ... (7 tests total)
-  └── database/  # Unit tests only (no Docker)
-```
-
-**Commands:**
-```bash
-# Unit tests only (no Docker needed)
-npm test  # 481/481 tests, 0 failures
-
-# Docker tests (requires containers)
-npm run test:docker  # 7 test suites
-```
-
-**Impact:** Faster CI, clearer test failures, no Docker dependency for `npm test`.
-
----
-
-## Git Hook Enhancement
-
-### Pre-Commit Migration Check
-
-**Old Behavior:** Prevented editing any committed migration files.
-
-**New Behavior:** Prevents editing **PUSHED** migration files only.
-
-**Benefits:**
-- ✅ Edit locally committed migrations (not yet pushed)
-- ✅ Prevents editing pushed migrations (already deployed)
-- ✅ Auto-detects remote branch (origin/main, origin/master, origin/dev)
-- ✅ Graceful fallback for local-only repos
-
-**Example:**
-```bash
-# ✅ ALLOWED - Edit local migration (not pushed)
-git commit -m "Fix migration before push"
-
-# ❌ BLOCKED - Edit pushed migration
-# Error: PUSHED migration file was edited: src/config/knex/enhancements/20251114000000_fix_v_tagged_decisions_numeric_support.ts
-```
-
----
-
-## Rollback Procedure
-
-If you encounter issues:
-
-### Option 1: Restore Database Backup
-
-```bash
-# SQLite
-cp .sqlew/sqlew.db.backup-YYYYMMDD .sqlew/sqlew.db
-
-# PostgreSQL
-psql -h localhost -U sqlew_user sqlew_db < backup-YYYYMMDD.sql
-
-# MySQL
-mysql -h localhost -u sqlew_user -p sqlew_db < backup-YYYYMMDD.sql
-```
-
-### Option 2: Downgrade to v3.8.1
-
-```bash
-# Restore backup first (see above)
-
-# Then downgrade
-npm install sqlew@3.8.1
-
-# Or update .mcp.json
-{
-  "mcpServers": {
-    "sqlew": {
-      "command": "npx",
-      "args": ["sqlew@3.8.1"]
-    }
-  }
-}
-```
-
----
-
-## Known Issues
-
-**None reported as of v3.9.0 release.**
-
----
-
-## FAQ
-
-### Q: Do I need to update my code?
-
-**A:** No. v3.9.0 is fully backward compatible. The `suggest` tool is optional.
-
-### Q: Will my existing decisions/tasks work?
-
-**A:** Yes. All existing data is preserved and migrations are automatic.
-
-### Q: How do I use the suggest tool?
-
-**A:** Use `suggest({ action: "help" })` for documentation. See examples above.
-
-### Q: Do I need Docker for testing?
-
-**A:** No. `npm test` runs 481 unit tests without Docker. Docker tests are optional: `npm run test:docker`.
-
-### Q: Can I edit migrations locally?
-
-**A:** Yes, if not pushed yet. The pre-commit hook now allows editing local migrations.
-
-### Q: What if migration fails?
-
-**A:** Restore backup (see Rollback Procedure above) and report issue on GitHub.
-
----
-
-## Performance Notes
-
-### Code Reduction
-
-- **Deleted:** `src/utils/sql-dump.ts` (-1,799 lines)
-- **Added:** Suggest tool system (+765 lines)
-- **Net:** -239 lines (1.1% code reduction)
-
-### Test Coverage
-
-- **Unit Tests:** 481 tests, 64.85% coverage
-- **E2E Tests:** 3 workflows, 100% passing
-- **Cross-DB Tests:** 20 tests, 100% passing (MySQL, MariaDB, PostgreSQL)
-
----
-
-## Support
-
-**Issues:** https://github.com/anthropics/sqlew/issues
-**Documentation:** See CHANGELOG.md, CLAUDE.md, and docs/
-**Migration Assistance:** Open GitHub issue with error logs
-
----
-
-## Verification Checklist
-
-After migration, verify:
-
-- [ ] Server starts without errors
-- [ ] Existing decisions/tasks queryable
-- [ ] suggest tool available: `suggest({ action: "help" })`
-- [ ] Unit tests pass: `npm test` (if running locally)
-- [ ] Database migrations applied: Check `knex_migrations` table
-- [ ] No error logs in `.sqlew/logs/` (if logging enabled)
-
----
-
-## Next Steps
-
-1. **Explore suggest tool** - Try pattern searches and duplicate detection
-2. **Enable auto-trigger** - Add `suggest_similar=1` to policies
-3. **Update documentation** - Document decisions using suggest tool
-4. **Run Docker tests** - Verify cross-database compatibility (optional)
-
-**Welcome to v3.9.0! 🎉**

package/docs/SHARED_CONCEPTS.md

@@ -1,225 +0,0 @@
-# Shared Concepts Reference
-
-> **Single Source of Truth** - Common concepts used across all MCP-SQLEW documentation.
-
-## Table of Contents
-- [Architecture Layers](#architecture-layers)
-- [Enum Values Reference](#enum-values-reference)
-- [Atomic Mode](#atomic-mode)
-- [Action Parameter](#action-parameter)
-
----
-
-## Architecture Layers
-
-9-layer architecture for organizing decisions, constraints, file changes, and tasks:
-
-### FILE_REQUIRED Layers (6)
-
-#### 1. **presentation** - User Interface
-UI components, API endpoints, CLI handlers, forms, response formatting
-
-**Examples**: React components, REST controllers, web forms
-
-#### 2. **business** - Business Logic
-Core application logic, business rules, domain operations
-
-**Examples**: Service classes, domain models, workflows, validation rules
-
-#### 3. **data** - Data Access
-Data persistence and retrieval
-
-**Examples**: Database schemas, repositories, ORMs, queries
-
-#### 4. **infrastructure** - Infrastructure
-Technical capabilities and external services
-
-**Examples**: Auth, logging, message queues, caching, email/SMS services
-
-#### 5. **cross-cutting** - Cross-Cutting Concerns
-Aspects spanning multiple layers
-
-**Examples**: Error handling, security, performance, i18n, configuration
-
-#### 6. **documentation** - Documentation & Knowledge
-Project documentation, guides, API docs, code comments, design rationales
-
-**Examples**: README files, API documentation, architecture guides, inline comments
-
-### FILE_OPTIONAL Layers (3)
-
-#### 7. **planning** - Planning & Requirements
-Project planning, roadmap decisions, requirements gathering, estimation
-
-**Examples**: Roadmap items, feature specifications, sprint planning, estimation notes
-
-#### 8. **coordination** - Team Coordination
-Team communication, progress tracking, meeting notes, status updates
-
-**Examples**: Meeting notes, status updates, progress reports, team announcements
-
-#### 9. **review** - Review & Quality Assurance
-Code reviews, testing decisions, quality metrics, approval workflows
-
-**Examples**: Review comments, testing strategies, quality gates, approval notes
-
----
-
-## Enum Values Reference
-
-### layer (Architecture Layers)
-```typescript
-type Layer =
-  | "presentation"      // UI, API endpoints, user interaction
-  | "business"          // Core logic, domain models, workflows
-  | "data"              // Database, repositories, persistence
-  | "infrastructure"    // Auth, logging, external services
-  | "cross-cutting"     // Security, error handling, i18n
-  | "documentation"     // Project docs, guides, comments
-  | "planning"          // Planning, roadmap, requirements (file-optional)
-  | "coordination"      // Team communication, status updates (file-optional)
-  | "review"            // Code reviews, QA, approval (file-optional)
-```
-
-### status (Decision/Entity Status)
-```typescript
-type Status =
-  | "active"       // Currently in use and valid (default)
-  | "deprecated"   // Outdated but not removed, scheduled for removal
-  | "draft"        // Proposed but not yet approved/implemented
-```
-
-### msg_type (Message Type)
-```typescript
-type MessageType =
-  | "decision"     // Decision announcement or update
-  | "warning"      // Alert or cautionary message
-  | "request"      // Request for action or input
-  | "info"         // Informational message
-```
-
-### priority (Priority Level)
-```typescript
-type Priority =
-  | "low"          // Can be addressed later
-  | "medium"       // Normal priority (default)
-  | "high"         // Should be addressed soon
-  | "critical"     // Requires immediate attention
-```
-
-### change_type (File Change Type)
-```typescript
-type ChangeType =
-  | "created"      // New file added
-  | "modified"     // Existing file changed
-  | "deleted"      // File removed
-```
-
-### category (Constraint Categories)
-```typescript
-type ConstraintCategory =
-  | "performance"     // Performance requirements and limits
-  | "architecture"    // Architectural rules and patterns
-  | "security"        // Security policies and restrictions
-```
-
-### task_status (Kanban Task Status)
-```typescript
-type TaskStatus =
-  | "todo"             // Not started, ready to begin
-  | "in_progress"      // Currently being worked on
-  | "waiting_review"   // Completed, awaiting review/approval
-  | "blocked"          // Cannot proceed due to blocker
-  | "done"             // Completed and approved
-  | "archived"         // Archived for historical reference
-  | "rejected"         // Rejected/cancelled (v4.1.0)
-```
-
-**Valid Transitions** (v4.1.0 - relaxed rules):
-
-| Status Type | Statuses | Can Transition To |
-|-------------|----------|-------------------|
-| **Non-terminal** | todo, in_progress, waiting_review, blocked, done | Any status (including terminal) |
-| **Terminal** | archived, rejected | None (final states) |
-
-- Non-terminal statuses can freely move to any other status
-- Terminal statuses (`archived`, `rejected`) cannot transition
-- `rejected` requires optional `rejection_reason` parameter
-
-**Auto-Stale Detection & Auto-Archive**:
-- `in_progress` >2 hours → auto-move to `waiting_review`
-- `waiting_review` >24 hours → auto-move to `todo`
-- `done` >48 hours → auto-move to `archived` (weekend-aware)
-
----
-
-## Atomic Mode
-
-Determines batch operation failure handling:
-
-**`atomic: true`** (All-or-Nothing) - Default
-- ALL succeed or ALL fail
-- Database transaction with rollback
-- Guaranteed consistency
-
-**`atomic: false`** (Best-Effort)
-- Independent operations
-- Partial success possible
-- Failed items reported
-
-### When to Use
-
-**Use `atomic: true`** for:
-- Critical data consistency (financial, multi-step workflows)
-- All-or-nothing validation
-
-**Use `atomic: false`** for:
-- Bulk imports with expected failures
-- AI agent best-effort updates
-- Performance-critical operations
-
-### Supported Tools
-- `decision`: `set_batch`
-- `file`: `record_batch`
-- `task`: `create_batch`
-
----
-
-## Action Parameter
-
-**`action` parameter is REQUIRED in all tool calls**
-
-### Why Required?
-- Token efficiency: 96% reduction (20 tools → 7 tools)
-- Logical grouping of related operations
-- On-demand help via `action: "help"`
-
-### Common Error
-```json
-❌ ERROR: "Unknown action: undefined"
-
-// Fix: Always include action
-✅ { "action": "get", "key": "auth_method" }
-❌ { "key": "auth_method" }
-```
-
-### Available Actions
-
-- **decision**: set, get, list, search_tags, search_layer, versions, set_batch, help
-- **file**: record, get, check_lock, record_batch, help
-- **constraint**: add, get, deactivate, help
-- **stats**: layer_summary, db_stats, clear, help
-- **config**: get, update, help
-- **task**: create, update, get, list, move, link, archive, create_batch, help
-
----
-
-## Database Enum Mappings
-
-Enum values stored as integers (MCP tools auto-convert - use strings in calls):
-
-- **status**: 1=active, 2=deprecated, 3=draft
-- **msg_type**: 1=decision, 2=warning, 3=request, 4=info
-- **priority**: 1=low, 2=medium, 3=high, 4=critical
-- **change_type**: 1=created, 2=modified, 3=deleted
-- **task_status**: 1=todo, 2=in_progress, 3=waiting_review, 4=blocked, 5=done, 6=archived, 7=rejected

package/docs/SPECIALIZED_AGENTS.md

@@ -1,126 +0,0 @@
-# Specialized Agents (Deprecated)
-
-**Status**: Deprecated as of v4.1.0 - Replaced by unified `/sqlew` command
-
-This document is kept for reference. For current usage, see [SLASH_COMMANDS.md](SLASH_COMMANDS.md).
-
----
-
-## Migration to /sqlew Command
-
-As of v4.1.0, the custom agent system has been superseded by the unified `/sqlew` command with automatic intent detection.
-
-### Old Approach (v4.0 and earlier)
-
-```bash
-# Custom agents
-@sqlew-scrum-master "Create sprint plan"
-@sqlew-researcher "Find auth decisions"
-@sqlew-architect "Document OAuth2 decision"
-```
-
-### New Approach (v4.1.0+)
-
-```bash
-# Unified command with intent detection
-/sqlew plan sprint implementation
-/sqlew search for auth decisions
-/sqlew record OAuth2 decision for authentication
-```
-
----
-
-## Historical Agent System
-
-For reference, the v4.0.0 system included:
-
-| Agent | Role | Purpose |
-|-------|------|---------|
-| **Scrum Master** | Task coordination, sprint planning | Multi-agent task coordination |
-| **Researcher** | Query history, analyze patterns | Decision and constraint queries |
-| **Architect** | Document decisions, enforce constraints | Architectural decision documentation |
-
-### Why the Change?
-
-1. **Unified Interface**: Single `/sqlew` command instead of remembering three agent names
-2. **Automatic Intent Detection**: Command analyzes input and selects appropriate MCP tool
-3. **Natural Language**: No need to know about "agents" - just describe what you want
-4. **Better Discoverability**: One command in autocomplete instead of three agent references
-5. **Token Efficiency**: Reduced context overhead from agent system
-
----
-
-## Current Architecture (v4.1.0+)
-
-The `/sqlew` command provides all the functionality of the previous agent system:
-
-- **Intent Analysis** (replaces agent role selection)
-- **MCP Tool Invocation** (replaces direct agent calls)
-- **Automatic Routing** (replaces manual agent selection)
-
-See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for current usage patterns.
-
----
-
-## Configuration (Legacy - Not Used in v4.1.0+)
-
-The following configuration was used in v4.0 and is no longer applicable:
-
-```toml
-# DEPRECATED - v4.0.0 and earlier
-[agents]
-scrum_master = true
-researcher = true
-architect = true
-```
-
-All agent functionality is now handled by the `/sqlew` command with no additional configuration needed.
-
----
-
-## Related Documentation
-
-- [SLASH_COMMANDS.md](SLASH_COMMANDS.md) - Current `/sqlew` command documentation
-- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - MCP tools (underlying infrastructure)
-- [AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md) - Guidelines for AI agents using sqlew
-
----
-
-## Legacy Reference
-
-### Scrum Master (Historical)
-
-**Purpose**: Multi-agent coordination, task management, sprint planning
-
-Provided by `/sqlew` commands:
-```bash
-/sqlew plan <feature>        # Replace: /sqw-scrum plan
-/sqlew execute              # Replace: /sqw-scrum implement
-```
-
-### Researcher (Historical)
-
-**Purpose**: Query historical context, analyze patterns
-
-Provided by `/sqlew` commands:
-```bash
-/sqlew search <topic>       # Replace: /sqw-research
-```
-
-### Architect (Historical)
-
-**Purpose**: Document decisions, enforce constraints
-
-Provided by `/sqlew` commands:
-```bash
-/sqlew record <decision>    # Replace: /sqw-secretary
-/sqlew update <decision>    # Replaces modifications
-```
-
----
-
-**Version**: 4.1.0
-**Status**: Deprecated
-**Last Updated**: 2025-12-04
-
-See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for current documentation.