sqlew 3.2.5 → 3.6.0

package/docs/TASK_SYSTEM.md

@@ -763,10 +763,15 @@ Auto-stale detection automatically transitions idle tasks to prevent them from g
 
 The logic:
 1. Check if enabled via `task_auto_stale_enabled` config
-2. Get threshold hours from config (2h for in_progress, 24h for waiting_review)
+2. Get threshold hours/days from config
 3. Run SQL UPDATE to transition stale tasks based on `updated_ts`
 4. Return count of transitioned tasks
 
+**Transition Rules:**
+1. **`in_progress` → `waiting_review`** (>2 hours idle)
+2. **`waiting_review` → `todo`** (>24 hours idle)
+3. **`done` → `archived`** (>48 hours idle, weekend-aware) - **Auto-Archive**
+
 SQL Pattern:
 ```sql
 UPDATE t_tasks
@@ -779,38 +784,67 @@ WHERE status_id = ? AND updated_ts < unixepoch() - ?
 1. **Before `list` action**
    - Ensures stale tasks show correct status
    - Returns `stale_tasks_transitioned` count
+   - Returns `archived_tasks` count
 
 2. **Before `move` action**
    - Prevents moving already-stale tasks
    - Ensures status consistency
 
+3. **On database startup**
+   - Maintenance on initialization
+   - Cleans up stale/old tasks
+
 ### Configuration
 
-**Enable/Disable:**
+**Via MCP Tool (config):**
+```javascript
+// Update auto-archive threshold
+{
+  action: "update",
+  auto_archive_done_days: "3"  // Archive after 3 days instead of 2
+}
+
+// Enable weekend-aware mode (affects auto-archive, messages, files)
+{
+  action: "update",
+  autodelete_ignore_weekend: "1"
+}
+```
+
+**Via .sqlew/config.toml:**
+```toml
+[tasks]
+auto_archive_done_days = 3          # Archive after 3 days
+stale_hours_in_progress = 4         # in_progress → waiting_review after 4 hours
+stale_hours_waiting_review = 48     # waiting_review → todo after 48 hours
+auto_stale_enabled = true
+
+[autodelete]
+ignore_weekend = true               # Weekend-aware mode (shared setting)
+```
+
+**Via SQL (Advanced):**
 ```sql
+-- Enable/Disable
 UPDATE m_config SET value = '1' WHERE key = 'task_auto_stale_enabled';  -- Enable
 UPDATE m_config SET value = '0' WHERE key = 'task_auto_stale_enabled';  -- Disable
-```
 
-**Adjust Thresholds:**
-```sql
--- in_progress → waiting_review after 4 hours
-UPDATE m_config SET value = '4' WHERE key = 'task_stale_hours_in_progress';
+-- Adjust auto-archive threshold
+UPDATE m_config SET value = '3' WHERE key = 'auto_archive_done_days';  -- 3 days
 
--- waiting_review → todo after 48 hours
+-- Adjust stale detection thresholds
+UPDATE m_config SET value = '4' WHERE key = 'task_stale_hours_in_progress';
 UPDATE m_config SET value = '48' WHERE key = 'task_stale_hours_waiting_review';
-```
 
-**Check Current Config:**
-```sql
-SELECT key, value FROM m_config WHERE key LIKE 'task_%';
+-- Check current config
+SELECT key, value FROM m_config WHERE key LIKE 'task_%' OR key LIKE 'auto_%';
 ```
 
 ### Monitoring
 
 Track transitions via `t_activity_log` table:
 ```sql
--- Recent transitions
+-- Recent transitions (including auto-archive)
 SELECT * FROM t_activity_log
 WHERE entity_type = 'task' AND action_type = 'status_change'
 ORDER BY ts DESC LIMIT 20;
@@ -819,8 +853,44 @@ ORDER BY ts DESC LIMIT 20;
 SELECT task_id, COUNT(*) as stale_count FROM t_activity_log
 WHERE entity_type = 'task' AND json_extract(details, '$.new_status') = 3
 GROUP BY task_id HAVING stale_count > 2;
+
+-- Recently auto-archived tasks
+SELECT * FROM t_activity_log
+WHERE entity_type = 'task'
+  AND action_type = 'status_change'
+  AND json_extract(details, '$.new_status') = 6  -- ARCHIVED status
+ORDER BY ts DESC LIMIT 20;
+
+-- Count of archived tasks per day
+SELECT date(ts, 'unixepoch') as day, COUNT(*) as archived_count
+FROM t_activity_log
+WHERE entity_type = 'task'
+  AND action_type = 'status_change'
+  AND json_extract(details, '$.new_status') = 6
+GROUP BY day
+ORDER BY day DESC;
 ```
 
+### Weekend-Aware Behavior
+
+When `autodelete_ignore_weekend` is enabled (via config.toml or MCP tool):
+
+**Example 1 - Task Completed on Friday:**
+- Task marked `done`: Friday 5:00 PM
+- Default 48 hours: Would archive Sunday 5:00 PM
+- **Weekend-aware**: Archives Tuesday 5:00 PM (skips Sat/Sun)
+
+**Example 2 - Task Completed on Wednesday:**
+- Task marked `done`: Wednesday 2:00 PM
+- Default 48 hours: Would archive Friday 2:00 PM
+- **Weekend-aware**: Archives Friday 2:00 PM (no weekend in between)
+
+**Why Weekend-Aware Mode?**
+- Teams/AI agents may not work on weekends
+- Prevents premature archiving during weekend breaks
+- Consistent with message/file retention behavior
+- Configurable: Disable if you work 7 days/week
+
 ## Linking System
 
 ### Overview

package/docs/TOOL_REFERENCE.md

@@ -149,14 +149,19 @@
 
 | Action | Required | Optional |
 |--------|----------|----------|
-| **create** | action, title | description, acceptance_criteria, notes, priority, assigned_agent, created_by_agent, layer, tags, status |
-| **update** | action, task_id | title, priority, assigned_agent, layer, description, acceptance_criteria, notes |
-| **get** | action, task_id | - |
-| **list** | action | status, assigned_agent, layer, tags, limit, offset |
+| **create** | action, title | description, acceptance_criteria, notes, priority, assigned_agent, created_by_agent, layer, tags, status, **watch_files** (v3.4.1) |
+| **update** | action, task_id | title, priority, assigned_agent, layer, description, acceptance_criteria, notes, **watch_files** (v3.4.1) |
+| **get** | action, task_id | include_dependencies |
+| **list** | action | status, assigned_agent, layer, tags, limit, offset, include_dependency_counts |
 | **move** | action, task_id, new_status | - |
-| **link** | action, task_id, link_type, target_id | link_relation |
+| **link** | action, task_id, link_type, target_id | link_relation (⚠️ link_type="file" deprecated in v3.4.1) |
 | **archive** | action, task_id | - |
 | **batch_create** | action, tasks | atomic |
+| **add_dependency** | action, blocker_task_id, blocked_task_id | - |
+| **remove_dependency** | action, blocker_task_id, blocked_task_id | - |
+| **get_dependencies** | action, task_id | include_details |
+| **watch_files** (v3.4.1) | action, task_id, action (watch/unwatch/list) | file_paths |
+| **watcher** | action | subaction (status/list_files/list_tasks/help) |
 
 ---
 
@@ -323,6 +328,89 @@
 
 ---
 
+## File Watching with Tasks (v3.4.1)
+
+### New: watch_files Parameter
+
+**Replaces:** `task.link(link_type="file")` (deprecated in v3.4.1)
+
+Create tasks with automatic file monitoring in one step:
+
+```javascript
+{
+  action: "create",
+  title: "Implement user authentication",
+  watch_files: ["src/auth.ts", "src/auth.test.ts"],
+  acceptance_criteria: [
+    {type: "tests_pass", command: "npm test auth", expected_pattern: "passing"},
+    {type: "code_contains", file: "src/auth.ts", pattern: "export class AuthService"}
+  ],
+  priority: 3,
+  assigned_agent: "backend-dev"
+}
+```
+
+**Benefits:**
+- 75% fewer MCP calls (1 call vs 4 calls in v3.2.x)
+- 35% token reduction
+- Clearer intent
+- Atomic file registration
+
+### New: watch_files Action
+
+Manage file watches dynamically:
+
+```javascript
+// Watch files
+{
+  action: "watch_files",
+  task_id: 123,
+  action: "watch",
+  file_paths: ["src/auth.ts", "src/middleware/jwt.ts"]
+}
+
+// Unwatch files
+{
+  action: "watch_files",
+  task_id: 123,
+  action: "unwatch",
+  file_paths: ["src/middleware/jwt.ts"]
+}
+
+// List watched files
+{
+  action: "watch_files",
+  task_id: 123,
+  action: "list"
+}
+// Response: { files: ["src/auth.ts"], files_count: 1 }
+```
+
+### Migration from v3.2.x
+
+**Before (deprecated):**
+```javascript
+// Create task
+{action: "create", title: "Feature"}
+// Link files (separate calls)
+{action: "link", task_id: 123, link_type: "file", target_id: "src/file1.ts"}
+{action: "link", task_id: 123, link_type: "file", target_id: "src/file2.ts"}
+```
+
+**After (v3.4.1):**
+```javascript
+// Create task with files in one call
+{
+  action: "create",
+  title: "Feature",
+  watch_files: ["src/file1.ts", "src/file2.ts"]
+}
+```
+
+**See Also:** [MIGRATION_v3.3.md](./MIGRATION_v3.3.md) for complete migration guide.
+
+---
+
 ## Decision Context System (v3.2.2)
 
 ### What is Decision Context?
@@ -590,7 +678,7 @@ Quick reference:
 - **waiting_review**: Completed, awaiting review
 - **blocked**: Cannot proceed due to blocker
 - **done**: Completed successfully
-- **archived**: No longer relevant
+- **archived**: Completed and archived (auto-archived after 48 hours)
 
 ### Constraint Categories
 

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.2.5",
-  "description": "MCP server for efficient context sharing between Claude Code sub-agents with Kanban Task Watcher, Decision Context, auto-file-tracking, and 60-75% token reduction in multi-session projects",
+  "version": "3.6.0",
+  "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": {
@@ -28,7 +28,15 @@
     "rebuild": "npm run clean && npm run build",
     "test": "npm run build && node --test dist/tests/tasks.dependencies.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"
@@ -55,13 +63,19 @@
   "author": "sin5ddd",
   "license": "AGPL-3.0",
   "dependencies": {
-    "better-sqlite3": "^11.0.0",
     "@modelcontextprotocol/sdk": "latest",
-    "chokidar": "^3.6.0"
+    "better-sqlite3": "^11.0.0",
+    "chokidar": "^4.0.3",
+    "ignore": "^7.0.5",
+    "knex": "^3.1.0",
+    "smol-toml": "^1.4.2",
+    "sqlite3": "^5.1.7"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
     "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^20.0.0"
+    "@types/knex": "^0.15.2",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.0.0"
   }
 }