sqlew 3.5.3 → 3.6.1

package/docs/TOOL_SELECTION.md

@@ -1,51 +1,6 @@
 # Tool Selection Guide
 
-**Quick reference for choosing the right sqlew tool for your task**
-
-## Understanding Tool Purposes
-
-Each tool serves a distinct purpose in the MCP sqlew ecosystem:
-
-```
-┌──────────────────────────────────────────────────────────┐
-│ What do you need to do?                                  │
-└────────────────┬─────────────────────────────────────────┘
-                 │
-                 ├─ Record a CHOICE that was made?
-                 │  └─> Use `decision` tool
-                 │      • Examples: "We chose JWT auth", "Selected PostgreSQL"
-                 │      • Key: Captures PAST decisions
-                 │      • Supports: versioning, tags, layers, scopes
-                 │
-                 ├─ Communicate with other agents?
-                 │  └─> Use `message` tool
-                 │      • Examples: Task updates, warnings, requests
-                 │      • Key: Real-time communication
-                 │      • Supports: priority, broadcast, read tracking
-                 │
-                 ├─ Define a REQUIREMENT that must be followed?
-                 │  └─> Use `constraint` tool
-                 │      • Examples: "API must be <100ms", "Code coverage >80%"
-                 │      • Key: Enforces RULES
-                 │      • Supports: priority, categories, layers
-                 │
-                 ├─ Track WORK to be done?
-                 │  └─> Use `task` tool
-                 │      • Examples: "Implement feature X", "Fix bug Y"
-                 │      • Key: Tracks TODO items and progress
-                 │      • Supports: status transitions, auto-stale, linking
-                 │
-                 ├─ Record file modifications?
-                 │  └─> Use `file` tool
-                 │      • Examples: Track changes, check locks
-                 │      • Key: File change history
-                 │      • Supports: layers, change types, lock detection
-                 │
-                 └─ Get statistics or manage data?
-                    └─> Use `stats` or `config` tools
-                        • stats: Database metrics, cleanup, activity logs
-                        • config: Retention settings, auto-deletion
-```
+**Quick reference for choosing the right tool**
 
 ## Tool Comparison Table
 
@@ -61,219 +16,57 @@ Each tool serves a distinct purpose in the MCP sqlew ecosystem:
 
 ## Decision vs Constraint vs Task
 
-This is the most common confusion. Here's the distinction:
-
-| Concept | Definition | Example | Tool |
-|---------|------------|---------|------|
-| **Decision** | A choice that WAS made | "We chose JWT authentication" | `decision` |
-| **Constraint** | A requirement that MUST be followed | "Response time must be <100ms" | `constraint` |
-| **Task** | Work that NEEDS to be done | "Implement JWT authentication" | `task` |
-
-## ⚠️ Decision vs Task: WHY vs WHAT
-
-**Critical distinction**: `decision` stores WHY (reasoning), `task` stores WHAT (work status).
-
-| Question | Answer | Tool |
-|----------|--------|------|
-| **WHY** did we choose this approach? | "Chose JWT because stateless auth scales horizontally" | **decision** |
-| **WHAT** needs to be done? | "Implement JWT authentication (status: in_progress)" | **task** |
-| **WHY** was this bug introduced? | "Nested transaction bug: setDecision wraps in transaction, batch also wraps" | **decision** |
-| **WHAT** is the completion status? | "Fixed nested transaction bug (status: done)" | **task** |
-
-### Common Mistakes
-
-```javascript
-// ❌ WRONG - Using decision for task completion
-{
-  action: "set",
-  key: "jwt-implementation-complete",
-  value: "JWT authentication implemented. All tests passing."
-}
-// This is WHAT was done (completion status), not WHY decisions were made.
-// FIX: Use task tool for tracking implementation progress.
-
-// ✅ CORRECT - Using decision for architectural reasoning
-{
-  action: "set",
-  key: "api/auth/jwt-choice",
-  value: "Chose JWT over sessions because: (1) Stateless design scales, (2) Mobile clients cache tokens, (3) Microservice auth requires distributed validation."
-}
-// This explains WHY JWT was chosen with architectural reasoning.
-
-// ✅ CORRECT - Using task for work tracking
-{
-  action: "create",
-  title: "Implement JWT authentication with refresh tokens",
-  status: "in_progress",
-  assigned_agent: "backend-agent"
-}
-// This tracks WHAT work is being done and its current status.
-```
-
-💡 **See [BEST_PRACTICES.md](BEST_PRACTICES.md#critical-what-to-store-in-decisions) for detailed examples of WHY vs WHAT.**
-
-## Scenario-Based Tool Selection
-
-### Scenario 1: Breaking API Change
-
-```javascript
-// 1. Record the decision (WHY the change was necessary)
-{
-  action: "set",
-  key: "api/v2/versioning-decision",
-  value: "Moved /users to /v2/users because: (1) Enables backward compatibility via versioning, (2) Allows gradual client migration without breaking production apps, (3) Future API changes won't force all clients to update simultaneously. Trade-off: More complex routing layer, but necessary for production stability with 50+ client apps.",
-  layer: "presentation",
-  tags: ["api", "versioning", "architecture-decision"]
-}
-
-// 2. Add a constraint (requirement going forward)
-{
-  action: "add",
-  category: "architecture",
-  constraint_text: "All API endpoints must include version prefix",
-  layer: "presentation",
-  tags: ["api", "versioning"]
-}
-
-// 3. Create migration task
-{
-  action: "create",
-  title: "Migrate clients to /v2/users endpoint",
-  status: "todo",
-  layer: "presentation",
-  tags: ["migration", "v2.0.0"]
-}
-
-// 4. Notify other agents
-{
-  action: "send",
-  from_agent: "api-agent",
-  msg_type: "warning",
-  message: "Breaking change: /users moved to /v2/users",
-  priority: "critical"
-}
-```
-
-### Scenario 2: Performance Issue
-
-```javascript
-// 1. Record the analysis and solution decision (WHY this approach)
-{
-  action: "set",
-  key: "db/user_sessions/index-strategy",
-  value: "Adding composite index (user_id, created_at DESC) to user_sessions table because: (1) Query analysis shows 300% latency increase from full table scans on 10M+ rows, (2) 95% of queries filter by user_id + sort by timestamp, (3) Index reduces query time from 850ms to <50ms in staging tests. Trade-off: 15% slower inserts and 200MB additional storage, but read performance critical for user experience.",
-  layer: "data",
-  tags: ["performance", "database", "indexing-strategy"]
-}
-
-// 2. Add performance constraint
-{
-  action: "add",
-  category: "performance",
-  constraint_text: "Database queries must complete within 50ms",
-  priority: "high",
-  layer: "data"
-}
-
-// 3. Create optimization task
-{
-  action: "create",
-  title: "Add indexes to user_sessions table",
-  status: "in_progress",
-  priority: 4,
-  layer: "data",
-  tags: ["performance", "database"]
-}
-```
-
-### Scenario 3: Security Vulnerability
+| Concept | Definition | Example |
+|---------|------------|---------|
+| **Decision** | A choice that WAS made | "We chose JWT authentication" |
+| **Constraint** | A requirement that MUST be followed | "Response time must be <100ms" |
+| **Task** | Work that NEEDS to be done | "Implement JWT authentication" |
 
-```javascript
-// 1. Record the solution decision (WHY this mitigation approach)
-{
-  action: "set",
-  key: "security/jwt/timing-attack-mitigation",
-  value: "Upgrading JWT library to v9.2.0+ and implementing constant-time comparison because: (1) CVE-2025-1234 timing attack allows token forgery via timing analysis, (2) Library v9.2.0+ includes constant-time string comparison preventing timing leaks, (3) Alternative approach (rewriting auth layer) would take 3 weeks vs 2-day upgrade. Trade-off: Breaking change requires updating all microservices, but security risk is critical and affects all user sessions.",
-  layer: "business",
-  tags: ["security", "authentication", "mitigation-strategy"]
-}
+## Decision vs Task: WHY vs WHAT
 
-// 2. Add security constraint
-{
-  action: "add",
-  category: "security",
-  constraint_text: "All auth tokens must use constant-time comparison",
-  priority: "critical",
-  layer: "business"
-}
+**Critical**: `decision` = WHY (reasoning), `task` = WHAT (work status)
 
-// 3. Create fix task
-{
-  action: "create",
-  title: "Upgrade JWT library and implement constant-time comparison",
-  status: "in_progress",
-  priority: 4,
-  assigned_agent: "security-agent",
-  layer: "business"
-}
+| Question | Tool |
+|----------|------|
+| WHY did we choose this? | **decision** |
+| WHAT needs to be done? | **task** |
+| WHY was this bug introduced? | **decision** |
+| WHAT is the completion status? | **task** |
 
-// 4. Alert all agents
-{
-  action: "send",
-  from_agent: "security-agent",
-  to_agent: null,  // Broadcast
-  msg_type: "warning",
-  message: "URGENT: Auth vulnerability found, fix in progress",
-  priority: "critical"
-}
-```
+## Common Scenarios
 
-## Search Actions Decision Tree
+**Breaking API Change:**
+1. `decision` - Record WHY change was necessary with reasoning
+2. `constraint` - Add requirement for version prefixes going forward
+3. `task` - Create migration work item
+4. `message` - Alert other agents
 
-### When to use which search action?
+**Performance Issue:**
+1. `decision` - Record analysis and WHY this solution
+2. `constraint` - Add performance requirement
+3. `task` - Create optimization work item
 
-```
-┌─────────────────────────────────────┐
-│ What do you want to search by?     │
-└──────────┬──────────────────────────┘
-           │
-           ├─ Simple filters (status, layer, tags)?
-           │  └─> Use action: "list"
-           │
-           ├─ Primarily by tags?
-           │  └─> Use action: "search_tags"
-           │      • match_mode: "AND" (all tags) or "OR" (any tag)
-           │
-           ├─ Primarily by layer?
-           │  └─> Use action: "search_layer"
-           │
-           ├─ Complex multi-filter query?
-           │  └─> Use action: "search_advanced"
-           │      • Multiple layers (OR)
-           │      • Tag combinations (AND/OR)
-           │      • Temporal filtering
-           │      • Full-text search
-           │      • Pagination
-           │
-           └─ Need version history?
-              └─> Use action: "versions"
-```
+**Security Vulnerability:**
+1. `decision` - Record WHY this mitigation approach
+2. `constraint` - Add security requirement
+3. `task` - Create fix work item
+4. `message` - Alert all agents
 
-### Detailed Search Comparison
+## Search Action Selection
 
-| Action | Use When | Key Features |
-|--------|----------|--------------|
-| **list** | Basic filtering | Simple status/layer/tag filters, no pagination |
-| **search_tags** | Tag-focused search | AND/OR logic for tags, optional status/layer |
-| **search_layer** | Layer-focused search | Get all decisions in specific layer(s) |
-| **search_advanced** | Complex queries | Full filtering, pagination, sorting, text search |
-| **versions** | History tracking | Get all versions of a specific decision |
+| Action | Use For |
+|--------|---------|
+| **list** | Simple status/layer/tag filters |
+| **search_tags** | Tag-focused with AND/OR logic |
+| **search_layer** | Layer-focused queries |
+| **search_advanced** | Complex multi-filter, pagination, full-text |
+| **versions** | Version history of specific decision |
 
 ---
 
 ## Related Documentation
 
-- **[TOOL_REFERENCE.md](TOOL_REFERENCE.md)** - Complete parameter reference for all tools
-- **[WORKFLOWS.md](WORKFLOWS.md)** - Multi-step workflow examples
-- **[BEST_PRACTICES.md](BEST_PRACTICES.md)** - Common errors and best practices
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Layer definitions and system architecture
+- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - Parameter reference
+- [WORKFLOWS.md](WORKFLOWS.md) - Multi-step workflows
+- [BEST_PRACTICES.md](BEST_PRACTICES.md) - Common errors
+- [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) - Layers, enums, concepts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlew",
-  "version": "3.5.3",
-  "description": "MCP server for efficient context sharing between Claude Code sub-agents with Kanban Task Watcher, auto-pruning for non-existent files, Git-aware auto-complete, Decision Context, auto-file-tracking, and 60-75% token reduction in multi-session projects",
+  "version": "3.6.1",
+  "description": "MCP server for efficient context sharing between Claude Code sub-agents with database-driven help system (60-70% token reduction), Kanban Task Watcher, Git-aware auto-complete, Decision Context, and streamlined documentation",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -27,8 +27,17 @@
     "clean": "rm -rf dist",
     "rebuild": "npm run clean && npm run build",
     "test": "npm run build && node --test dist/tests/tasks.dependencies.test.js",
+    "test:all-features": "npm run build && node dist/tests/all-features.test.js",
     "test:migrations": "npm run build && node dist/tests/migrations/test-v3.2-migration.js",
-    "prepublishOnly": "npm run rebuild"
+    "prepublishOnly": "npm run rebuild",
+    "knex": "tsx node_modules/.bin/knex --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",
+    "migrate:rollback:all": "npm run knex migrate:rollback --all",
+    "migrate:status": "npm run knex migrate:status",
+    "seed:make": "npm run knex seed:make",
+    "seed:run": "npm run knex seed:run"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -59,11 +68,15 @@
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.3",
     "ignore": "^7.0.5",
-    "smol-toml": "^1.4.2"
+    "knex": "^3.1.0",
+    "smol-toml": "^1.4.2",
+    "sqlite3": "^5.1.7"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",
+    "@types/knex": "^0.15.2",
     "@types/node": "^20.0.0",
+    "tsx": "^4.20.6",
     "typescript": "^5.0.0"
   }
 }