sqlew 3.7.3 → 3.7.4

package/docs/HELP_PREVIEW_COMPARISON.md

@@ -1,259 +0,0 @@
-# Task Tool Help Documentation - Before/After Comparison
-
-## Overview
-This document shows the changes made to the task tool `help` action to expose the automatic file watching feature to AI agents.
-
----
-
-## BEFORE (Original Help Output)
-
-### Header Section
-```json
-{
-  "tool": "task",
-  "description": "Kanban Task Watcher for managing tasks with AI-optimized lifecycle states",
-  "note": "💡 TIP: Use action: \"example\" to see comprehensive usage scenarios and real-world examples for all task actions."
-}
-```
-
-**Missing:** No mention of automatic file watching feature
-
-### Link Action (Original)
-```json
-{
-  "link": {
-    "description": "Link task to decision/constraint/file",
-    "required_params": ["task_id", "link_type", "target_id"],
-    "optional_params": ["link_relation"],
-    "link_types": ["decision", "constraint", "file"],
-    "example": {
-      "action": "link",
-      "task_id": 5,
-      "link_type": "decision",
-      "target_id": "auth_method",
-      "link_relation": "implements"
-    }
-  }
-}
-```
-
-**Missing:** No indication that file linking activates watcher
-
-### Documentation Section (Original)
-```json
-{
-  "priority_levels": {
-    "1": "low",
-    "2": "medium (default)",
-    "3": "high",
-    "4": "critical"
-  },
-  "documentation": {
-    "task_overview": "docs/TASK_OVERVIEW.md - Lifecycle, status transitions, auto-stale detection (363 lines, ~10k tokens)",
-    "task_actions": "docs/TASK_ACTIONS.md - All action references with examples (854 lines, ~21k tokens)",
-    ...
-  }
-}
-```
-
-**Missing:** No auto_file_tracking section explaining the feature
-
----
-
-## AFTER (Updated Help Output)
-
-### Header Section ✅ ENHANCED
-```json
-{
-  "tool": "task",
-  "description": "Kanban Task Watcher for managing tasks with AI-optimized lifecycle states",
-  "note": "💡 TIP: Use action: \"example\" to see comprehensive usage scenarios and real-world examples for all task actions.",
-  "important": "🚨 AUTOMATIC FILE WATCHING: Linking files to tasks activates automatic file change monitoring and acceptance criteria validation. This provides 97% token reduction vs manual tracking. See auto_file_tracking section below."
-}
-```
-
-**✨ NEW:** Prominent warning about automatic file watching feature
-**🎯 Impact:** AI agents immediately see this critical feature exists
-
-### Link Action ✅ ENHANCED
-```json
-{
-  "link": {
-    "description": "Link task to decision/constraint/file",
-    "required_params": ["task_id", "link_type", "target_id"],
-    "optional_params": ["link_relation"],
-    "link_types": ["decision", "constraint", "file"],
-    "file_linking_behavior": "⚠️  IMPORTANT: When link_type=\"file\", this action ACTIVATES AUTOMATIC FILE WATCHING. The file watcher monitors linked files for changes and validates acceptance criteria when files are saved. This provides 97% token reduction compared to manual file change tracking.",
-    "example": {
-      "action": "link",
-      "task_id": 5,
-      "link_type": "decision",
-      "target_id": "auth_method",
-      "link_relation": "implements"
-    }
-  }
-}
-```
-
-**✨ NEW:** `file_linking_behavior` field with prominent warning
-**🎯 Impact:** AI agents understand that file linking is not passive documentation
-
-### Documentation Section ✅ ENHANCED
-```json
-{
-  "priority_levels": {
-    "1": "low",
-    "2": "medium (default)",
-    "3": "high",
-    "4": "critical"
-  },
-  "auto_file_tracking": {
-    "description": "Automatic file watching and acceptance criteria validation (97% token reduction)",
-    "how_it_works": [
-      "1. Link files to tasks using the link action with link_type=\"file\"",
-      "2. File watcher automatically activates and monitors linked files",
-      "3. When files are saved, watcher detects changes",
-      "4. If task has acceptance_criteria, watcher validates criteria against changes",
-      "5. Results appear in terminal output with pass/fail status"
-    ],
-    "requirements": [
-      "Task must have files linked via link action",
-      "File paths must be relative to project root (e.g., \"src/api/auth.ts\")",
-      "Watcher only monitors files explicitly linked to tasks"
-    ],
-    "token_efficiency": "File watching happens in background. No MCP tokens consumed until you query status. Manual file tracking would cost ~500-1000 tokens per file check.",
-    "documentation_reference": "docs/AUTO_FILE_TRACKING.md - Complete guide with examples"
-  },
-  "documentation": {
-    "task_overview": "docs/TASK_OVERVIEW.md - Lifecycle, status transitions, auto-stale detection (363 lines, ~10k tokens)",
-    "task_actions": "docs/TASK_ACTIONS.md - All action references with examples (854 lines, ~21k tokens)",
-    ...
-  }
-}
-```
-
-**✨ NEW:** Complete `auto_file_tracking` section with:
-- Clear description of the feature and token benefits
-- 5-step workflow explaining how it works
-- Requirements for activation
-- Token efficiency explanation
-- Reference to detailed documentation
-
-**🎯 Impact:** AI agents have complete understanding without reading external docs
-
----
-
-## Example Action Changes
-
-### BEFORE (Original Example)
-```json
-{
-  "scenario": "Link task to file",
-  "request": "{ action: \"link\", task_id: 5, link_type: \"file\", target_id: \"src/api/auth.ts\", link_relation: \"modifies\" }",
-  "explanation": "Indicate which files the task will modify"
-}
-```
-
-**❌ Problem:** Sounds passive - "Indicate" suggests documentation only
-
-### AFTER (Updated Example) ✅
-```json
-{
-  "scenario": "Link task to file",
-  "request": "{ action: \"link\", task_id: 5, link_type: \"file\", target_id: \"src/api/auth.ts\", link_relation: \"modifies\" }",
-  "explanation": "Activates automatic file watching for the task (97% token reduction vs manual tracking)",
-  "behavior": "File watcher monitors linked files and validates acceptance criteria when files change"
-}
-```
-
-**✨ NEW:**
-- Active voice: "Activates" (not "Indicate")
-- Token reduction benefit highlighted
-- Explicit behavior description
-
-**🎯 Impact:** AI agents understand this is an active feature, not passive documentation
-
----
-
-## Key Improvements Summary
-
-### 1. Discoverability ✅
-- **Before:** Feature completely hidden from MCP tool interface
-- **After:** Prominently displayed in 3 locations (header, link action, dedicated section)
-
-### 2. Understanding ✅
-- **Before:** No explanation of how/why to use file linking
-- **After:** 5-step workflow, requirements, and token efficiency clearly documented
-
-### 3. Motivation ✅
-- **Before:** No indication of benefits
-- **After:** "97% token reduction" mentioned 3 times to motivate usage
-
-### 4. Behavior Clarity ✅
-- **Before:** File linking sounded like passive documentation
-- **After:** Clearly stated as active feature that "activates" watching
-
----
-
-## Token Impact Analysis
-
-### Help Documentation Size
-- **Before:** ~1,200 tokens
-- **After:** ~1,400 tokens (+200 tokens)
-- **Increase:** 16.7%
-
-### Value Gained
-- **Feature discoverability:** Infinite value (feature was invisible before)
-- **Token savings per usage:** 500-1,000 tokens per file check avoided
-- **ROI:** First use of file watcher saves 3-5x the documentation cost
-
-### Net Token Efficiency
-If AI agents use file watching just **once**, they save more tokens than the documentation costs. The 200-token investment pays for itself immediately.
-
----
-
-## Files Modified
-
-1. **src/tools/tasks.ts** (lines 1184-1371)
-   - Added `important` field to header (line 1189)
-   - Added `file_linking_behavior` to link action (line 1258)
-   - Added `auto_file_tracking` section (lines 1355-1371)
-
-2. **src/index.ts** (lines 1370-1375)
-   - Updated file linking example explanation
-   - Added behavior description
-
----
-
-## Verification Checklist
-
-- [x] Header prominently mentions automatic file watching
-- [x] Link action clearly states watcher activation
-- [x] Complete auto_file_tracking section with workflow
-- [x] Example action uses active voice ("Activates")
-- [x] Token reduction benefit (97%) mentioned multiple times
-- [x] Documentation reference provided for deep dive
-- [x] All changes maintain existing help structure
-- [x] TypeScript compiles successfully (to be verified)
-
----
-
-## Expected AI Agent Behavior Change
-
-### Before These Changes
-```
-AI Agent: "I'll link the files to document which files this task affects"
-Result: Feature activation happens, but agent doesn't realize it or leverage it
-```
-
-### After These Changes
-```
-AI Agent: "I'll link these files to activate automatic file watching (97% token reduction).
-          The watcher will monitor changes and validate acceptance criteria automatically."
-Result: Feature activation is intentional and understood, agent can explain benefits to user
-```
-
----
-
-**Status:** Documentation updates complete ✅
-**Next Step:** Implement watcher status query action (task #93-95)

package/docs/MIGRATION_CHAIN.md

@@ -1,293 +0,0 @@
-# Migration Chain Documentation
-
-> **⚠️ HISTORICAL DOCUMENT (v1.0.0 - v2.1.0)**
->
-> This document describes the **old custom migration system** used before v3.6.2.
->
-> **As of v3.6.2**, sqlew uses **Knex.js migrations only**. See the migration files in:
-> - `src/migrations/knex/upgrades/` - Version upgrade paths
-> - `src/migrations/knex/bootstrap/` - Fresh install schema
-> - `src/migrations/knex/enhancements/` - Feature additions
->
-> This document is kept for historical reference only.
-
----
-
-This document describes the complete migration path from v1.0.0 to v2.1.0 for mcp-sqlew databases.
-
-## Schema Version History
-
-### v1.0.0 (Initial Release)
-- **Table Names:** No prefixes
-  - Master: `agents`, `files`, `context_keys`, `constraint_categories`, `layers`, `tags`, `scopes`
-  - Transaction: `decisions`, `decisions_numeric`, `decision_history`, `decision_tags`, `decision_scopes`, `agent_messages`, `file_changes`, `constraints`, `constraint_tags`
-  - Views: `tagged_decisions`, `active_context`, `layer_summary`, `unread_messages_by_priority`, `recent_file_changes`, `tagged_constraints`
-  - Triggers: `auto_delete_old_messages`, `auto_delete_old_file_changes`, `record_decision_history`
-- **Configuration:** No `config` table (hardcoded settings)
-- **Comments:** Japanese
-
-### v1.1.0 - v1.1.2 & v2.0.0 (Table Prefixes)
-- **Table Names:** WITH prefixes
-  - Master: `m_agents`, `m_files`, `m_context_keys`, `m_constraint_categories`, `m_layers`, `m_tags`, `m_scopes`, **`m_config` (NEW)**
-  - Transaction: `t_decisions`, `t_decisions_numeric`, `t_decision_history`, `t_decision_tags`, `t_decision_scopes`, `t_agent_messages`, `t_file_changes`, `t_constraints`, `t_constraint_tags`
-  - Views: `v_tagged_decisions`, `v_active_context`, `v_layer_summary`, `v_unread_messages_by_priority`, `v_recent_file_changes`, `v_tagged_constraints`
-  - Triggers: `trg_record_decision_history` (auto-delete triggers removed)
-- **Configuration:** `m_config` table added with weekend-aware auto-deletion settings
-- **Comments:** Japanese
-- **Notes:**
-  - v1.1.1: Hotfix for migration failure (creates m_config if missing)
-  - v1.1.2: Hotfix for schema validation (checks for prefixed names)
-  - v2.0.0: API changes only (20 tools → 6 action-based tools), **no schema changes**
-
-### v2.1.0 (Feature Release - Current)
-- **New Tables:**
-  - `t_activity_log` - Automatic activity logging (agent_id, action_type, target, layer_id, details, ts)
-  - `t_decision_templates` - Decision templates (name, defaults, required_fields, created_by, ts)
-- **New Triggers:**
-  - `trg_log_decision_set` - Auto-log decision creation
-  - `trg_log_decision_update` - Auto-log decision updates
-  - `trg_log_message_send` - Auto-log message sending
-  - `trg_log_file_record` - Auto-log file changes
-- **New Indexes:**
-  - `idx_activity_log_ts` - Time-based activity queries
-  - `idx_activity_log_agent` - Agent-based activity queries
-  - `idx_activity_log_action` - Action type filtering
-- **Comments:** English (translated from Japanese)
-- **Built-in Data:** 5 decision templates seeded
-
-## Migration Scripts
-
-### 1. v1.0.0 → v1.1.x: add-table-prefixes.ts
-**Purpose:** Rename all tables to add category-based prefixes and create m_config table
-
-**Actions:**
-1. Drop old views (they reference old table names)
-2. Drop old triggers
-3. Rename master tables (agents → m_agents, etc.)
-4. Rename transaction tables (decisions → t_decisions, etc.)
-5. Create m_config table if missing
-6. Insert default config values
-7. Schema initialization creates new views/triggers
-
-**Transaction:** Yes (rollback on failure)
-**Auto-detect:** Checks for existence of `agents` (old) and absence of `m_agents` (new)
-
-### 2. v1.1.x / v2.0.0 → v2.1.0: add-v2.1.0-features.ts
-**Purpose:** Add activity logging and template system
-
-**Actions:**
-1. Create `t_activity_log` table with 3 indexes
-2. Create `t_decision_templates` table
-3. Create 4 activity logging triggers
-4. Seed 5 built-in templates
-
-**Transaction:** Yes (rollback on failure)
-**Auto-detect:** Checks for absence of `t_activity_log` OR `t_decision_templates`
-
-## Migration Execution Order
-
-The migrations run automatically on server startup in this order:
-
-```
-1. Check v1.0.0 → v1.1.x migration (add-table-prefixes.ts)
-   ├─ If needed: Run migration
-   ├─ Run schema initialization (creates views/triggers)
-   └─ Continue to next check
-
-2. Check v1.1.x/v2.0.0 → v2.1.0 migration (add-v2.1.0-features.ts)
-   ├─ If needed: Run migration
-   └─ Continue
-
-3. Validate schema integrity
-   ├─ Check all required tables exist
-   ├─ Check all required views exist
-   ├─ Check all required triggers exist
-   ├─ Verify standard data (5 layers, 3 categories, 10+ tags)
-   └─ Exit with error if validation fails
-
-4. Start MCP server
-```
-
-## Complete Migration Paths
-
-### Path 1: v1.0.0 → v2.1.0 (Full Chain)
-```
-v1.0.0 (no prefixes, no config)
-  ↓ add-table-prefixes.ts
-v1.1.0 (prefixes, m_config added)
-  ↓ add-v2.1.0-features.ts
-v2.1.0 (activity_log, templates added)
-```
-
-**Steps:**
-1. Start server with v1.0.0 database
-2. Detects unprefixed tables → runs add-table-prefixes.ts
-3. Migration adds prefixes and m_config table
-4. Schema initialization creates new views/triggers
-5. Detects missing v2.1.0 tables → runs add-v2.1.0-features.ts
-6. Migration adds t_activity_log, t_decision_templates, 4 triggers
-7. Schema validation passes
-8. Server starts with v2.1.0 schema
-
-### Path 2: v1.1.x / v2.0.0 → v2.1.0 (Single Migration)
-```
-v1.1.0-v1.1.2 or v2.0.0 (prefixes, m_config present)
-  ↓ add-v2.1.0-features.ts
-v2.1.0 (activity_log, templates added)
-```
-
-**Steps:**
-1. Start server with v1.1.x or v2.0.0 database
-2. Detects prefixed tables exist → skips add-table-prefixes.ts
-3. Detects missing v2.1.0 tables → runs add-v2.1.0-features.ts
-4. Migration adds t_activity_log, t_decision_templates, 4 triggers
-5. Schema validation passes
-6. Server starts with v2.1.0 schema
-
-### Path 3: Fresh Install → v2.1.0 (No Migration)
-```
-Empty database
-  ↓ schema initialization
-v2.1.0 (full schema created)
-```
-
-**Steps:**
-1. Start server with empty/new database path
-2. No existing schema detected
-3. Schema initialization runs (executes assets/schema.sql)
-4. All tables, views, triggers created directly from v2.1.0 schema
-5. Schema validation passes
-6. Server starts with v2.1.0 schema
-
-## Schema Validation (v2.1.0 Requirements)
-
-The schema validator (`src/schema.ts`) checks for:
-
-**Tables (19 total):**
-- Master (8): m_agents, m_files, m_context_keys, m_constraint_categories, m_layers, m_tags, m_scopes, m_config
-- Transaction (11): t_decisions, t_decisions_numeric, t_decision_history, t_decision_tags, t_decision_scopes, t_agent_messages, t_file_changes, t_constraints, t_constraint_tags, **t_activity_log**, **t_decision_templates**
-
-**Views (6 total):**
-- v_tagged_decisions, v_active_context, v_layer_summary, v_unread_messages_by_priority, v_recent_file_changes, v_tagged_constraints
-
-**Triggers (5 total):**
-- trg_record_decision_history
-- **trg_log_decision_set** (NEW in v2.1.0)
-- **trg_log_decision_update** (NEW in v2.1.0)
-- **trg_log_message_send** (NEW in v2.1.0)
-- **trg_log_file_record** (NEW in v2.1.0)
-
-**Standard Data:**
-- 5 layers (presentation, business, data, infrastructure, cross-cutting)
-- 3 constraint categories (performance, architecture, security)
-- 10+ tags (authentication, authorization, performance, security, api, database, caching, testing, validation, error-handling)
-- 3+ config entries (autodelete_ignore_weekend, autodelete_message_hours, autodelete_file_history_days)
-
-## Testing Migration Chain
-
-### Test 1: v1.0.0 → v2.1.0
-```bash
-# Create v1.0.0 database (use git checkout)
-git checkout v1.0.0
-node dist/index.js --db-path=.test/v1.0.0.db
-# Let it initialize with v1.0.0 schema
-# Stop server (Ctrl+C)
-
-# Upgrade to v2.1.0
-git checkout main
-npm run build
-node dist/index.js --db-path=.test/v1.0.0.db
-# Should run BOTH migrations automatically
-# Check logs for:
-#   "Migration required: Adding table prefixes (v1.2.0 -> v1.3.0)"
-#   "Migration required: Adding v2.1.0 features (v2.0.0 -> v2.1.0)"
-```
-
-### Test 2: v2.0.0 → v2.1.0
-```bash
-# Create v2.0.0 database
-git checkout v2.0.0
-npm run build
-node dist/index.js --db-path=.test/v2.0.0.db
-# Stop server
-
-# Upgrade to v2.1.0
-git checkout main
-npm run build
-node dist/index.js --db-path=.test/v2.0.0.db
-# Should run ONLY v2.1.0 migration
-# Check logs for:
-#   "Migration required: Adding v2.1.0 features (v2.0.0 -> v2.1.0)"
-```
-
-### Test 3: Fresh v2.1.0
-```bash
-# Fresh install
-node dist/index.js --db-path=.test/fresh-v2.1.0.db
-# Should initialize directly to v2.1.0
-# No migration messages
-```
-
-## Rollback Strategy
-
-If a migration fails:
-1. **Transaction rollback** - All changes reverted automatically
-2. **Database unchanged** - Original schema preserved
-3. **Server exits** - Prevents running with corrupted schema
-4. **Error message displayed** - Clear indication of failure
-
-To manually rollback:
-```bash
-# Restore from backup (recommended)
-cp backup.db current.db
-
-# Or delete and reinitialize
-rm .sqlew/sqlew.db
-node dist/index.js  # Creates fresh v2.1.0 database
-```
-
-## Troubleshooting
-
-### Migration Doesn't Run
-- Check that database file exists and is accessible
-- Verify SQLite version supports required features
-- Check file permissions
-
-### Migration Fails Midway
-- Check error message in console
-- Database is automatically rolled back
-- No partial state - safe to retry
-
-### Schema Validation Fails After Migration
-- Report as bug (migration should guarantee valid schema)
-- Check logs for missing components
-- May need to restore from backup or delete database
-
-## Future Migrations
-
-When adding new features in future versions:
-
-1. Create new migration script: `src/migrations/add-vX.Y.Z-features.ts`
-2. Implement `needsMigration()`, `runMigration()`, `getMigrationInfo()`
-3. Import in `src/database.ts`
-4. Add check AFTER previous migrations, BEFORE schema validation
-5. Update `src/schema.ts` validation requirements
-6. Update `assets/schema.sql` with new schema
-7. Document in CHANGELOG.md and this file
-8. Test complete migration chain from oldest supported version
-
-## Backward Compatibility
-
-**Database:** v2.1.0 can read and migrate v1.0.0, v1.1.x, and v2.0.0 databases
-**API:** v2.0.0 tool calls work unchanged in v2.1.0 (backward compatible)
-**Forward Compatibility:** Older versions CANNOT read v2.1.0 databases (missing tables/triggers)
-
-## Summary
-
-- ✅ v1.0.0 → v2.1.0: Full migration chain supported
-- ✅ v1.1.x → v2.1.0: Single migration
-- ✅ v2.0.0 → v2.1.0: Single migration
-- ✅ Fresh install: Direct v2.1.0 schema
-- ✅ Transaction-based: Safe rollback on failure
-- ✅ Auto-detect: Runs only needed migrations
-- ✅ Schema validation: Ensures integrity