sqlew 3.8.0 → 3.9.0

package/docs/changelogs/CHANGELOG_ARCHIVE_v3.4_and_older.md

@@ -0,0 +1,296 @@
+# Changelog Archive (v3.4.1 and older)
+
+This archive contains changelog entries for sqlew versions **v3.4.1 and older**.
+
+For current changelog, see: [../../CHANGELOG.md](../../CHANGELOG.md)
+
+---
+
+## [3.4.1] - 2025-10-22
+
+### Fixed - File Watcher Immediate Detection
+
+**Fixed chokidar configuration for instant file change detection**
+
+#### Changes
+- Removed 5-second aggregation delay
+- Added `awaitWriteFinish` for write completion detection
+- Immediate auto-transition on file save
+
+---
+
+## [3.4.0] - 2025-10-22
+
+### Added - VCS-Aware File Watching
+
+**Automatic task transitions based on Git commit detection**
+
+#### Features
+- Auto-transition: `waiting_review` → `done` when watched files committed
+- Multi-VCS support: Git, Mercurial, SVN
+- VCS adapter pattern with pluggable implementations
+- Whitelist exemption: Skip auto-transition for critical files (package.json, migrations)
+- Configuration: `git_auto_complete_tasks`, `git_require_all_files_committed`, `git_file_whitelist`
+
+#### Database Schema
+- New table: `m_git_file_whitelist` - Exempt files from auto-completion
+
+---
+
+## [3.2.6] - 2025-10-21
+
+### Fixed - File Watcher Test Stability
+
+**Improved debouncing and async handling in file watcher tests**
+
+---
+
+## [3.2.5] - 2025-10-21
+
+### Fixed - File Watcher Error Handling
+
+**Enhanced error handling and logging for file watcher operations**
+
+---
+
+## [3.2.4] - 2025-10-20
+
+### Fixed - File Watcher Path Resolution
+
+**Fixed absolute path resolution for file watching**
+
+---
+
+## [3.2.3] - 2025-10-20 [DEPRECATED]
+
+### Changed - File Watcher Implementation (Deprecated)
+
+This version was replaced by v3.2.4. Use v3.2.4 or later.
+
+---
+
+## [3.2.2] - 2025-10-18
+
+### Added - Decision Context
+
+**Rich decision documentation with rationale, alternatives, tradeoffs**
+
+#### Features
+- New table: `t_decision_context` - Attach context to decisions
+- New actions: `add_decision_context`, `list_decision_contexts`
+- Enhanced `get` action with `include_context` parameter
+
+#### Documentation
+- `DECISION_CONTEXT.md` - Comprehensive guide for decision documentation
+
+---
+
+## [3.2.0] - 2025-10-18
+
+### Added - Task Dependencies
+
+**Task dependency management with blocking relationships**
+
+#### Features
+- New table: `t_task_dependencies` - Track blocking relationships
+- Circular dependency detection
+- New actions: `add_dependency`, `remove_dependency`, `get_dependencies`
+
+---
+
+## [3.1.2] - 2025-10-18
+
+### Fixed - Task Linking Validation
+
+**Fixed validation for task-decision-constraint-file links**
+
+---
+
+## [3.1.1] - 2025-10-18
+
+### Fixed - File Watcher Initialization
+
+**Fixed file watcher startup sequence and error handling**
+
+---
+
+## [3.0.2] - 2025-10-17
+
+### Fixed - Task State Machine
+
+**Enhanced task status transition validation**
+
+#### Changes
+- Fixed state machine transitions for task lifecycle
+- Improved validation for blocked/unblocked transitions
+
+---
+
+## [3.0.1] - 2025-10-17
+
+### Fixed - Task Timestamps
+
+**Fixed task timestamp updates on status changes**
+
+---
+
+## [3.0.0] - 2025-10-17
+
+### Added - Kanban Task Watcher
+
+**AI-optimized task management with auto-stale detection**
+
+#### Features
+- Task management with metadata: status, priority, assignee, tags, layer
+- Auto-stale detection: `in_progress` >2h → `waiting_review`, `waiting_review` >24h → `todo`
+- File watching with `chokidar`: auto-transition `todo` → `in_progress` on file edit
+- Link tasks to decisions, constraints, files
+- 70% token reduction vs decision tool (~100 bytes/task vs ~332 bytes/decision)
+- Flat hierarchy (no subtasks) for AI simplicity
+
+#### Database Schema
+- New tables: `t_tasks`, `t_task_details`, `t_task_tags`, `t_task_decision_links`, `t_task_constraint_links`, `t_task_file_links`
+- New triggers: `trg_log_task_create`, `trg_log_task_status_change`, `trg_update_task_timestamp`
+
+#### MCP Actions (task tool)
+- `create`, `update`, `get`, `list`, `move`, `link`, `archive`, `create_batch`
+- `watch_files` - Start file watching for auto-transitions
+
+#### Documentation
+- `TASK_OVERVIEW.md` - Lifecycle, status transitions
+- `TASK_ACTIONS.md` - All action references with examples
+- `TASK_LINKING.md` - Link tasks to decisions/constraints/files
+- `TASK_MIGRATION.md` - Migrate from decision-based tracking
+
+---
+
+## [2.1.4] - 2025-10-15
+
+### Fixed - Action Validation
+
+**Enhanced parameter validation for all MCP actions**
+
+---
+
+## [2.1.3] - 2025-10-15
+
+### Fixed - Message Priority Handling
+
+**Fixed message priority enum conversion**
+
+---
+
+## [2.1.2] - 2025-10-15
+
+### Fixed - File Change Tracking
+
+**Fixed file change timestamp handling**
+
+---
+
+## [2.1.1] - 2025-10-15
+
+### Fixed - Constraint Deactivation
+
+**Fixed constraint soft delete logic**
+
+---
+
+## [2.1.0] - 2025-10-14
+
+### Added - Template System
+
+**Decision and batch operation templates**
+
+#### Features
+- New actions: `set_from_template`, `create_template`, `list_templates`
+- Template-based decision creation
+- Batch operation support with `set_batch`, `send_batch`, `record_batch`
+
+---
+
+## [2.0.0] - 2025-10-11
+
+### Changed - Action-Based Tool Consolidation
+
+**96% token reduction through action-based API**
+
+#### Breaking Changes
+- 20 tools → 6 tools (action-based routing)
+- All tools use `action` parameter for routing
+- Tool names changed: `context` → `decision`, `utils` → `stats`
+
+#### Token Efficiency
+- Tool definitions: 12,848 → 481 tokens (96% reduction)
+- MCP context: ~13,730 → ~4,482 tokens (67% reduction)
+- Help actions provide on-demand documentation
+
+#### New Tool Structure
+- `decision` - Context Management (9 actions)
+- `message` - Agent Messaging (4 actions)
+- `file` - File Change Tracking (4 actions)
+- `constraint` - Constraint Management (4 actions)
+- `stats` - Statistics & Utilities (4 actions)
+- `config` - Configuration (3 actions)
+
+---
+
+## [1.1.2] - 2025-10-11
+
+### Fixed - Database Migration
+
+**Fixed v1.2.0 → v1.3.0 table prefix migration**
+
+---
+
+## [1.1.1] - 2025-10-11
+
+### Fixed - Auto-Cleanup
+
+**Fixed weekend-aware cleanup trigger timing**
+
+---
+
+## [1.1.0] - 2025-10-11
+
+### Added - Weekend-Aware Auto-Deletion
+
+**Configurable retention with weekend-aware logic**
+
+#### Features
+- Configuration keys: `autodelete_ignore_weekend`, `autodelete_message_hours`, `autodelete_file_history_days`
+- CLI arguments for startup override
+- Manual cleanup via `clear_old_data` action
+
+---
+
+## [1.0.1] - 2025-10-11
+
+### Fixed - Schema Initialization
+
+**Fixed initial database schema creation**
+
+---
+
+## [1.0.0] - 2025-01-10
+
+### Added - Initial Release
+
+**MCP Shared Context Server for efficient context sharing**
+
+#### Core Features
+- Decision tracking with metadata (tags, layers, scopes, versions)
+- Agent messaging with priority levels
+- File change tracking with layer integration
+- Constraint management with priorities
+- Statistics and utilities
+- SQLite-based persistence with better-sqlite3
+
+#### Database Schema
+- Master tables: agents, files, context_keys, layers, tags, scopes, etc.
+- Transaction tables: decisions, messages, file_changes, constraints
+- Views for token-efficient queries
+- Automatic version history tracking
+
+#### MCP Tools
+Initial implementation with 20 separate tools (consolidated to 6 in v2.0.0)

package/package.json

@@ -1,16 +1,18 @@
 {
     "name": "sqlew",
-    "version": "3.8.0",
-    "description": "MCP server for efficient context sharing between Claude Code sub-agents (60-70% token reduction), Kanban Task Watcher, Decision or Constraint Context, and streamlined documentation",
+    "version": "3.9.0",
+    "description": "SQL Efficient Workflow - MCP server Provides consistency and token savings for AI coding",
     "main": "dist/index.js",
     "type": "module",
     "bin": {
         "sqlew": "dist/index.js",
         "sqlew-cli": "dist/cli.js",
-        "sqlew-init-agents": "dist/init-agents.js"
+        "sqlew-init-agents": "dist/init-agents.js",
+        "sqlew-init-commands": "dist/init-commands.js"
     },
     "files": [
         "dist/",
+        "scripts/",
         "assets/",
         "docs/",
         "README.md",
@@ -27,18 +29,41 @@
         "dev": "tsc --watch",
         "clean": "rimraf dist",
         "rebuild": "npm run clean && npm run build",
-        "test": "npm run test:all-features",
-        "test:all-features": "npm run build && node dist/tests/all-features.test.js",
-        "test:docker": "npm run build && node --test dist/tests/multi-project-migration.test.js dist/tests/sql-dump-fk-constraints.test.js",
-        "test:cross-db": "npm run build && node --test dist/tests/sql-dump-cross-database.test.js",
-        "test:migrations": "npm run test:migration-upgrade-paths && npm run test:migration-idempotency",
-        "test:migration-upgrade-paths": "npm run build && node --test dist/tests/migration-upgrade-paths.test.js",
-        "test:migration-idempotency": "npm run build && node --test dist/tests/migration-idempotency.test.js",
+        "test": "node --test --test-force-exit --import tsx \"src/tests/unit/**/*.test.ts\" \"src/tests/feature/decision/**/*.test.ts\" \"src/tests/feature/task/**/*.test.ts\" \"src/tests/feature/help/**/*.test.ts\" \"src/tests/database/**/*.test.ts\" \"src/tests/integration/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:verbose": "node --test --experimental-test-coverage --test-force-exit --import tsx \"src/tests/unit/**/*.test.ts\" \"src/tests/feature/decision/**/*.test.ts\" \"src/tests/feature/task/**/*.test.ts\" \"src/tests/feature/help/**/*.test.ts\" \"src/tests/database/**/*.test.ts\" \"src/tests/integration/**/*.test.ts\"",
+        "test:ci": "npm run build && npm test",
+        "test:vcs": "node --test --test-force-exit --import tsx \"src/tests/feature/vcs/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:vcs:verbose": "node --test --test-force-exit --import tsx \"src/tests/feature/vcs/**/*.test.ts\"",
+        "test:all": "node --test --test-force-exit --import tsx \"src/tests/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:all:verbose": "node --test --experimental-test-coverage --test-force-exit --import tsx \"src/tests/**/*.test.ts\"",
+        "test:unit": "node --test --test-force-exit --import tsx \"src/tests/unit/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:unit:verbose": "node --test --test-force-exit --import tsx \"src/tests/unit/**/*.test.ts\"",
+        "test:feature": "node --test --test-force-exit --import tsx \"src/tests/feature/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:feature:verbose": "node --test --test-force-exit --import tsx \"src/tests/feature/**/*.test.ts\"",
+        "test:database": "node --test --test-force-exit --import tsx \"src/tests/database/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:database:verbose": "node --test --test-force-exit --import tsx \"src/tests/database/**/*.test.ts\"",
+        "test:integration": "node --test --test-force-exit --import tsx \"src/tests/integration/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:integration:verbose": "node --test --test-force-exit --import tsx \"src/tests/integration/**/*.test.ts\"",
+        "test:decision": "node --test --test-force-exit --import tsx \"src/tests/feature/decision/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:decision:verbose": "node --test --test-force-exit --import tsx \"src/tests/feature/decision/**/*.test.ts\"",
+        "test:task": "node --test --test-force-exit --import tsx \"src/tests/feature/task/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:task:verbose": "node --test --test-force-exit --import tsx \"src/tests/feature/task/**/*.test.ts\"",
+        "test:migrations": "node --test --test-force-exit --import tsx \"src/tests/database/migrations/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:migrations:verbose": "node --test --test-force-exit --import tsx \"src/tests/database/migrations/**/*.test.ts\"",
+        "test:sql-dump": "node --test --test-force-exit --import tsx \"src/tests/database/sql-dump/**/*.test.ts\" | node scripts/filter-test-output.js",
+        "test:sql-dump:verbose": "node --test --test-force-exit --import tsx \"src/tests/database/sql-dump/**/*.test.ts\"",
+        "test:all-features": "npm run build && node dist/tests/integration/all-features.standalone.js",
+        "test:docker": "npm run build && node --test --test-force-exit dist/tests/docker/**/*.test.js",
+        "test:cross-db": "npm run build && node --test dist/tests/docker/cross-database.test.js",
+        "test:native": "npm run build && node --test --test-concurrency=1 --test-force-exit dist/tests/docker/native/**/*.test.js | node scripts/filter-test-output.js",
+        "test:native:verbose": "npm run build && node --test --test-concurrency=1 --test-force-exit dist/tests/docker/native/**/*.test.js",
+        "test:migration-upgrade-paths": "npm run build && node --test dist/tests/database/migrations/upgrade-paths.test.js",
+        "test:migration-idempotency": "npm run build && node --test dist/tests/database/migrations/idempotency.test.js",
         "test:migrations:all": "npm run build && node dist/tests/migrations/test-all-versions-real.js",
         "test:migrations:ci": "npm run build && node dist/tests/migrations/test-all-versions-real.js",
         "prepare": "husky",
         "prepublishOnly": "npm run rebuild",
-        "knex": "tsx node_modules/.bin/knex --knexfile src/knexfile.ts",
+        "knex": "npx tsx node_modules/knex/bin/cli.js --knexfile src/knexfile.ts",
         "migrate:make": "npm run knex migrate:make",
         "migrate:latest": "npm run knex migrate:latest",
         "migrate:rollback": "npm run knex migrate:rollback",
@@ -74,7 +99,7 @@
     "author": "sin5ddd",
     "license": "AGPL-3.0",
     "dependencies": {
-        "@modelcontextprotocol/sdk": "latest",
+        "@modelcontextprotocol/sdk": "^1.21.1",
         "better-sqlite3": "^12.4.1",
         "chokidar": "^4.0.3",
         "ignore": "^7.0.5",

package/scripts/check-cross-db-patterns.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# Cross-Database Pattern Scanner
+# Detects SQLite-specific syntax that causes failures on MySQL/MariaDB/PostgreSQL
+#
+# Token Savings: 78K tokens (replaces 4 iterative test runs)
+# Usage: bash scripts/check-cross-db-patterns.sh
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Cross-Database Compatibility Pattern Scanner ===${NC}"
+echo ""
+
+ISSUES_FOUND=0
+SEARCH_DIR="src/config/knex"
+
+# Pattern 1: SQLite-specific SQL functions
+echo -e "${BLUE}[1/5] Checking for SQLite-specific SQL functions...${NC}"
+STRFTIME_COUNT=$(rg "strftime|NOW\(\)|CURRENT_TIMESTAMP" "$SEARCH_DIR" --type ts -c 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+if [ "$STRFTIME_COUNT" -gt 0 ]; then
+  echo -e "${RED}  ✖ Found $STRFTIME_COUNT occurrences of SQLite-specific functions${NC}"
+  echo -e "${YELLOW}    Files:${NC}"
+  rg "strftime|NOW\(\)|CURRENT_TIMESTAMP" "$SEARCH_DIR" --type ts -n | head -10
+  ISSUES_FOUND=$((ISSUES_FOUND + STRFTIME_COUNT))
+else
+  echo -e "${GREEN}  ✓ No SQLite-specific functions found${NC}"
+fi
+echo ""
+
+# Pattern 2: CREATE INDEX IF NOT EXISTS (MySQL doesn't support)
+echo -e "${BLUE}[2/5] Checking for CREATE INDEX IF NOT EXISTS...${NC}"
+INDEX_COUNT=$(rg "CREATE INDEX IF NOT EXISTS" "$SEARCH_DIR" --type ts -c 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+if [ "$INDEX_COUNT" -gt 0 ]; then
+  echo -e "${RED}  ✖ Found $INDEX_COUNT occurrences (MySQL doesn't support IF NOT EXISTS for indexes)${NC}"
+  echo -e "${YELLOW}    Files:${NC}"
+  rg "CREATE INDEX IF NOT EXISTS" "$SEARCH_DIR" --type ts -n | head -10
+  ISSUES_FOUND=$((ISSUES_FOUND + INDEX_COUNT))
+else
+  echo -e "${GREEN}  ✓ No CREATE INDEX IF NOT EXISTS found${NC}"
+fi
+echo ""
+
+# Pattern 3: TEXT in PRIMARY KEY (MySQL/MariaDB can't use TEXT/BLOB in PRIMARY KEY)
+echo -e "${BLUE}[3/5] Checking for TEXT columns in PRIMARY KEY...${NC}"
+TEXT_PK_COUNT=$(rg "table\.text\([^)]*\).*\.primary\(\)" "$SEARCH_DIR" --type ts -c 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+if [ "$TEXT_PK_COUNT" -gt 0 ]; then
+  echo -e "${RED}  ✖ Found $TEXT_PK_COUNT occurrences (MySQL/MariaDB can't use TEXT in PRIMARY KEY)${NC}"
+  echo -e "${YELLOW}    Files:${NC}"
+  rg "table\.text\([^)]*\).*\.primary\(\)" "$SEARCH_DIR" --type ts -n | head -10
+  ISSUES_FOUND=$((ISSUES_FOUND + TEXT_PK_COUNT))
+else
+  echo -e "${GREEN}  ✓ No TEXT in PRIMARY KEY found${NC}"
+fi
+echo ""
+
+# Pattern 4: INSERT with array destructuring (PostgreSQL needs .returning())
+echo -e "${BLUE}[4/5] Checking for INSERT array destructuring...${NC}"
+INSERT_COUNT=$(rg "const \[.*\] = await.*\.insert\(" "$SEARCH_DIR" --type ts -c 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+if [ "$INSERT_COUNT" -gt 0 ]; then
+  echo -e "${YELLOW}  ⚠ Found $INSERT_COUNT occurrences (PostgreSQL needs .returning('id'))${NC}"
+  echo -e "${YELLOW}    Files:${NC}"
+  rg "const \[.*\] = await.*\.insert\(" "$SEARCH_DIR" --type ts -n | head -10
+  ISSUES_FOUND=$((ISSUES_FOUND + INSERT_COUNT))
+else
+  echo -e "${GREEN}  ✓ No INSERT array destructuring found${NC}"
+fi
+echo ""
+
+# Pattern 5: Reserved keywords as column names
+echo -e "${BLUE}[5/5] Checking for reserved keywords as column names...${NC}"
+KEYWORD_MATCHES=$(rg "table\.(text|string|integer)\(['\"]?(read|key|order|desc)['\"]?" "$SEARCH_DIR" --type ts -c 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+if [ "$KEYWORD_MATCHES" -gt 0 ]; then
+  echo -e "${YELLOW}  ⚠ Found $KEYWORD_MATCHES potential reserved keyword usages${NC}"
+  echo -e "${YELLOW}    Files:${NC}"
+  rg "table\.(text|string|integer)\(['\"]?(read|key|order|desc)['\"]?" "$SEARCH_DIR" --type ts -n | head -10
+  ISSUES_FOUND=$((ISSUES_FOUND + KEYWORD_MATCHES))
+else
+  echo -e "${GREEN}  ✓ No reserved keywords found${NC}"
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}=== Summary ===${NC}"
+if [ "$ISSUES_FOUND" -eq 0 ]; then
+  echo -e "${GREEN}✓ No cross-database compatibility issues found!${NC}"
+  exit 0
+else
+  echo -e "${RED}✖ Found $ISSUES_FOUND potential cross-database compatibility issues${NC}"
+  echo ""
+  echo -e "${YELLOW}Recommended Actions:${NC}"
+  echo "1. Create a pre-emptive migration that runs BEFORE problematic migrations"
+  echo "2. Use database-aware syntax:"
+  echo "   - strftime → Math.floor(Date.now() / 1000)"
+  echo "   - CREATE INDEX IF NOT EXISTS → Database-specific try/catch"
+  echo "   - TEXT in PRIMARY KEY → VARCHAR(191)"
+  echo "   - INSERT destructuring → Use .returning('id') or pre-create records"
+  echo "   - Reserved keywords → Quote with backticks (MySQL) or double quotes (PostgreSQL)"
+  exit 1
+fi

package/scripts/filter-test-output.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Cross-platform test output filter for AI-optimized test results.
+ * Filters test output to show only failures and summary lines.
+ *
+ * Usage: node --test ... | node scripts/filter-test-output.js
+ */
+
+import { createInterface } from 'readline';
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+// Pattern matches: errors, failures (lines to SHOW)
+const includePattern = /(✖|Error|FAIL)/;
+
+// Pattern matches: passing tests, test start markers (lines to EXCLUDE)
+const excludePattern = /(✔|✅|▶)/;
+
+// Pattern to detect final summary section (lines starting with ℹ)
+const summaryPattern = /^ℹ /;
+
+let inSummary = false;
+let previousLine = null;
+let linesAfterFailure = 0;
+let hasFailures = false; // Track if any failures were detected
+
+rl.on('line', (line) => {
+  // If we encounter a summary line, enter summary mode
+  if (summaryPattern.test(line)) {
+    inSummary = true;
+  }
+
+  // In summary mode, show all ℹ lines (complete table)
+  if (inSummary && summaryPattern.test(line)) {
+    console.log(line);
+    return;
+  }
+
+  // If we're tracking lines after a failure, show them
+  if (linesAfterFailure > 0) {
+    console.log(line);
+    linesAfterFailure--;
+    previousLine = line;
+    return;
+  }
+
+  // Check if current line is a failure
+  const isFailure = includePattern.test(line) && !excludePattern.test(line);
+
+  if (isFailure) {
+    hasFailures = true; // Mark that we detected failures
+    // Show previous line (context before failure, e.g., "test at ...")
+    if (previousLine !== null) {
+      console.log(previousLine);
+    }
+    // Show the failure line itself
+    console.log(line);
+    // Show next 1 line after failure (error details)
+    linesAfterFailure = 1;
+  }
+
+  // Remember current line as previous for next iteration
+  previousLine = line;
+});
+
+rl.on('close', () => {
+  // Exit with code 1 if failures detected, 0 otherwise
+  // This propagates test failure to shell exit code
+  process.exit(hasFailures ? 1 : 0);
+});

package/scripts/verify-migrations.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+# Migration Verification Script
+# Checks migration status across MySQL, MariaDB, and PostgreSQL without running full test suite
+#
+# Token Savings: 19K tokens per verification (2K vs 20K full test suite)
+# Usage: bash scripts/verify-migrations.sh
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Migration Verification (MySQL, MariaDB, PostgreSQL) ===${NC}"
+echo ""
+
+ALL_PASSED=true
+
+# Function to check if Docker container is running
+check_container() {
+  local container_name=$1
+  if ! docker ps --format '{{.Names}}' | grep -q "^${container_name}$"; then
+    echo -e "${RED}✖ Container ${container_name} is not running${NC}"
+    echo -e "${YELLOW}  Start with: cd docker && docker-compose up -d${NC}"
+    return 1
+  fi
+  return 0
+}
+
+# MySQL Migration Check
+echo -e "${BLUE}[1/3] Checking MySQL migrations...${NC}"
+if check_container "mcp-sqlew-mysql-test"; then
+  MYSQL_COUNT=$(docker exec mcp-sqlew-mysql-test mysql -u mcp_user -pmcp_pass mcp_test -sN \
+    -e "SELECT COUNT(*) FROM knex_migrations" 2>&1 | grep -v "Warning" | tail -1)
+
+  if [ -n "$MYSQL_COUNT" ] && [ "$MYSQL_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}  ✓ MySQL: $MYSQL_COUNT migrations completed${NC}"
+
+    # Show last 5 migrations
+    echo -e "${BLUE}    Last 5 migrations:${NC}"
+    docker exec mcp-sqlew-mysql-test mysql -u mcp_user -pmcp_pass mcp_test -sN \
+      -e "SELECT name FROM knex_migrations ORDER BY id DESC LIMIT 5" 2>&1 | grep -v "Warning" | \
+      while read -r migration; do
+        echo -e "${GREEN}      ✓ $migration${NC}"
+      done
+  else
+    echo -e "${RED}  ✖ MySQL: No migrations found or error occurred${NC}"
+    ALL_PASSED=false
+  fi
+else
+  ALL_PASSED=false
+fi
+echo ""
+
+# MariaDB Migration Check
+echo -e "${BLUE}[2/3] Checking MariaDB migrations...${NC}"
+if check_container "mcp-sqlew-mariadb-test"; then
+  MARIADB_COUNT=$(docker exec mcp-sqlew-mariadb-test mysql -u mcp_user -pmcp_pass mcp_test -sN \
+    -e "SELECT COUNT(*) FROM knex_migrations" 2>&1 | grep -v "Warning" | tail -1)
+
+  if [ -n "$MARIADB_COUNT" ] && [ "$MARIADB_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}  ✓ MariaDB: $MARIADB_COUNT migrations completed${NC}"
+
+    # Show last 5 migrations
+    echo -e "${BLUE}    Last 5 migrations:${NC}"
+    docker exec mcp-sqlew-mariadb-test mysql -u mcp_user -pmcp_pass mcp_test -sN \
+      -e "SELECT name FROM knex_migrations ORDER BY id DESC LIMIT 5" 2>&1 | grep -v "Warning" | \
+      while read -r migration; do
+        echo -e "${GREEN}      ✓ $migration${NC}"
+      done
+  else
+    echo -e "${RED}  ✖ MariaDB: No migrations found or error occurred${NC}"
+    ALL_PASSED=false
+  fi
+else
+  ALL_PASSED=false
+fi
+echo ""
+
+# PostgreSQL Migration Check
+echo -e "${BLUE}[3/3] Checking PostgreSQL migrations...${NC}"
+if check_container "mcp-sqlew-postgres-test"; then
+  POSTGRESQL_COUNT=$(docker exec mcp-sqlew-postgres-test psql -U mcp_user -d mcp_test -t -c \
+    "SELECT COUNT(*) FROM knex_migrations" 2>&1 | tr -d ' ')
+
+  if [ -n "$POSTGRESQL_COUNT" ] && [ "$POSTGRESQL_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}  ✓ PostgreSQL: $POSTGRESQL_COUNT migrations completed${NC}"
+
+    # Show last 5 migrations
+    echo -e "${BLUE}    Last 5 migrations:${NC}"
+    docker exec mcp-sqlew-postgres-test psql -U mcp_user -d mcp_test -t -c \
+      "SELECT name FROM knex_migrations ORDER BY id DESC LIMIT 5" 2>&1 | \
+      while read -r migration; do
+        migration=$(echo "$migration" | xargs) # Trim whitespace
+        if [ -n "$migration" ]; then
+          echo -e "${GREEN}      ✓ $migration${NC}"
+        fi
+      done
+  else
+    echo -e "${RED}  ✖ PostgreSQL: No migrations found or error occurred${NC}"
+    ALL_PASSED=false
+  fi
+else
+  ALL_PASSED=false
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}=== Summary ===${NC}"
+if [ "$ALL_PASSED" = true ]; then
+  echo -e "${GREEN}✓ All databases have migrations completed successfully!${NC}"
+  echo ""
+  echo -e "${BLUE}Migration counts:${NC}"
+  [ -n "$MYSQL_COUNT" ] && echo -e "  MySQL:      $MYSQL_COUNT"
+  [ -n "$MARIADB_COUNT" ] && echo -e "  MariaDB:    $MARIADB_COUNT"
+  [ -n "$POSTGRESQL_COUNT" ] && echo -e "  PostgreSQL: $POSTGRESQL_COUNT"
+  exit 0
+else
+  echo -e "${RED}✖ Some databases failed migration verification${NC}"
+  echo ""
+  echo -e "${YELLOW}Troubleshooting:${NC}"
+  echo "1. Ensure Docker containers are running: cd docker && docker-compose up -d"
+  echo "2. Check migration logs: npm run test:native:verbose"
+  echo "3. Run pattern scanner: bash scripts/check-cross-db-patterns.sh"
+  exit 1
+fi