sqlew 3.2.5 → 3.5.3

package/CHANGELOG.md

@@ -5,6 +5,819 @@ All notable changes to sqlew will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.2] - 2025-10-24
+
+### Added - Two-Step Git-Aware Task Workflow 🎯
+
+**Major Feature: Automatic task completion and archiving based on Git staging and committing**
+
+Task transitions now align with Git workflow stages:
+- **Step 1 - Staging** (`git add`): `waiting_review` → `done` (work complete)
+- **Step 2 - Committing** (`git commit`): `done` → `archived` (work finalized, board clean)
+
+#### Key Benefits
+1. 🧹 Clean Task Board - Automatic archiving keeps active board focused
+2. ⚡ Fast Feedback - `git add` provides immediate completion signal
+3. 🔒 Finalized State - `git commit` represents permanent work
+4. 💰 Zero Token Cost - Fully automated, no manual MCP calls needed
+5. 🌍 Multi-VCS Support - Works with Git, Mercurial, and SVN
+
+#### Implementation Details
+- **VCS Adapter**: Added `getStagedFiles()` method to all adapters (Git/Mercurial/SVN)
+- **Detection Functions**: `detectAndCompleteOnStaging()` and `detectAndArchiveOnCommit()`
+- **File Watcher**: Enhanced to call both functions on VCS index change
+- **Configuration**: 4 new config keys for granular control
+
+#### Configuration (v3.5.2)
+- `git_auto_complete_on_stage` (default: `'1'`) - Enable staging-based completion
+- `git_auto_archive_on_commit` (default: `'1'`) - Enable commit-based archiving
+- `require_all_files_staged` (default: `'1'`) - Require ALL files staged (vs ANY)
+- `require_all_files_committed_for_archive` (default: `'1'`) - Require ALL files committed
+
+#### Example Workflow
+```bash
+# Create task
+task action=create title="Feature" watch_files=["src/feature.ts"]
+
+# Work on feature → todo → in_progress → waiting_review
+
+# Stage changes
+git add src/feature.ts  # → Task: waiting_review → done ✅
+
+# Commit changes
+git commit -m "Add feature"  # → Task: done → archived 📦
+```
+
+#### Migration from v3.4.0
+- **Backward Compatible** - No breaking changes
+- Config defaults enable two-step workflow automatically
+- Can be disabled via config if needed
+
+## [3.5.1] - 2025-10-24
+
+### Fixed - File Watcher WSL Compatibility and Path Matching
+
+**Bugfix: Upgraded chokidar from v3 to v4 + Fixed path normalization bug**
+
+File watcher was not detecting file changes on WSL due to two issues:
+1. Outdated chokidar v3.6.0 (requires manual polling configuration for WSL)
+2. Path mismatch bug: chokidar reports absolute paths but database stores relative paths
+
+#### Changes Made
+
+**1. Dependency Upgrade**
+- **chokidar**: `^3.6.0` → `^4.0.3`
+- **File**: `package.json`
+
+**2. Configuration Simplification**
+- Removed manual WSL detection and polling configuration
+- Removed `usePolling` and `interval` options (handled automatically by v4)
+- Updated error handler type: `Error` → `unknown` (chokidar v4 compatibility)
+- **File**: `src/watcher/file-watcher.ts`
+
+**3. Path Normalization Fix** (Critical Bug)
+- Fixed `normalizePath()` to convert absolute paths to relative paths
+- Chokidar reports: `/home/.../project/file.ts` (absolute)
+- Database stores: `file.ts` (relative)
+- **Before**: Map lookup failed (paths didn't match)
+- **After**: Both normalized to `file.ts` (matches correctly)
+- **File**: `src/watcher/file-watcher.ts:571-587`
+
+**4. Documentation Updates**
+- Updated version references to v3.5.1
+- Added note that chokidar v4 handles WSL automatically
+- **Files**: `src/watcher/file-watcher.ts`
+
+#### Problem Solved
+
+**Before v3.5.1:**
+```
+Issue 1 - WSL Detection:
+  Cause: chokidar v3 requires manual polling configuration
+  Result: File changes not detected on WSL
+
+Issue 2 - Path Matching:
+  Chokidar reports: /full/path/to/file.ts
+  Database stores: file.ts
+  Result: Map lookup fails, no auto-transition ❌
+```
+
+**After v3.5.1:**
+```
+WSL: chokidar v4 handles automatically
+Path: Both normalized to relative paths
+Result: Auto-tracking works correctly ✅
+```
+
+#### Testing
+- Verified on WSL with chokidar v4
+- Created task watching `test-watcher-v3.5.1.ts`
+- Edited file → Task auto-transitioned from todo → in_progress
+- TypeScript compilation successful
+
+## [3.5.0] - 2025-10-22
+
+### Added - Non-Existent File Auto-Pruning with Audit Trail 🔧
+
+**Major Feature: Automatic removal of non-existent watched files with project archaeology**
+
+Tasks watching planned files that were never created (renamed, deleted, or scope-reduced during implementation) no longer block quality gates. Auto-pruning maintains clean watch lists while preserving complete audit trail for post-mortem analysis and team handoffs.
+
+#### Core Implementation
+
+**1. Database Schema Migration**
+- **New Table**: `t_task_pruned_files` - Audit trail for pruned files
+- **Columns**: id, task_id, file_path, pruned_ts, linked_decision_id
+- **Indexes**: idx_pruned_task, idx_pruned_decision
+- **File**: `src/migrations/add-v3.5.0-pruned-files.ts`
+- **Persistence**: Audit records survive task archival for long-term archaeology
+
+**2. Core Pruning Logic**
+- **Function**: `pruneNonExistentFiles(db, taskId, projectRoot)`
+- **Safety Check**: Blocks transition if ALL files non-existent (prevents zero-work completion)
+- **Behavior**: Partial pruning (removes only non-existent files, keeps existing)
+- **Audit Trail**: Records every pruned file with timestamp
+- **File**: `src/utils/file-pruning.ts`
+
+**3. Integration into Quality Gates**
+- **Trigger Point**: During `in_progress → waiting_review` transition
+- **Timing**: BEFORE quality gate validation (Decision #161)
+- **Process**: Check existence → Prune non-existent → Validate remaining files
+- **File**: `src/utils/task-stale-detection.ts`
+- **Safety**: Cannot complete tasks with no work done (Decision #163)
+
+**4. MCP Actions**
+- **get_pruned_files**: Retrieve audit trail for a task
+  - Parameters: task_id, limit (optional)
+  - Returns: Pruned file records with timestamps and decision links
+- **link_pruned_file**: Attach WHY reasoning to pruned files
+  - Parameters: pruned_file_id, decision_key
+  - Purpose: Project archaeology and team handoffs
+- **File**: `src/tools/tasks.ts`, `src/index.ts`
+
+**5. Documentation**
+- **TASK_PRUNING.md**: Comprehensive 500+ line guide
+  - How it works, safety checks, audit trail
+  - MCP action reference with examples
+  - Use cases, best practices, troubleshooting
+  - Post-mortem analysis queries
+
+#### Problem Solved
+
+**Before v3.5.0:**
+```
+Task watches: ["src/feature-a.ts", "src/feature-b.ts"]
+During implementation: feature-b absorbed into feature-a
+Result: Task stuck in in_progress (file-b.ts doesn't exist)
+Resolution: Manual intervention required ❌
+```
+
+**After v3.5.0:**
+```
+Task watches: ["src/feature-a.ts", "src/feature-b.ts"]
+During implementation: feature-b absorbed into feature-a
+Auto-prune runs: Removes feature-b.ts from watch list
+Audit trail: Records why file-b wasn't created
+Result: Task proceeds to waiting_review ✅
+```
+
+#### Use Cases
+
+**Use Case 1: Endpoint Not Needed**
+- Planned: `/api/v2/users` endpoint
+- Actual: v1 endpoint sufficient
+- Auto-prune: Removes v2 files, links to decision explaining why
+
+**Use Case 2: Feature Absorbed into Existing Code**
+- Planned: `src/utils/new-helper.ts`
+- Actual: Functionality added to existing helper
+- Auto-prune: Removes new-helper.ts, preserves audit trail
+
+**Use Case 3: Test Strategy Changed**
+- Planned: Integration tests
+- Actual: Unit tests sufficient
+- Auto-prune: Removes integration test files, decision linked
+
+#### Safety Checks
+
+**Zero-Work Prevention**:
+```typescript
+// Example: ALL 3 watched files non-existent
+watchedFiles = ["a.ts", "b.ts", "c.ts"]  // all non-existent
+
+// Safety check triggers:
+Error: "Cannot prune files for task #42: ALL 3 watched files
+        are non-existent. This indicates no work was done."
+
+// Task stays in in_progress - manual review required
+```
+
+**Partial Pruning Allowed**:
+```typescript
+// Example: 2 of 3 files exist
+watchedFiles = ["a.ts", "b.ts", "c.ts"]
+// a.ts exists, b.ts exists, c.ts non-existent
+
+// Auto-prune: Removes only c.ts
+// Task continues with a.ts and b.ts
+```
+
+#### Configuration
+
+Auto-pruning works with existing quality gate configuration:
+- `review_idle_minutes`: Time before pruning check (default: 3)
+- `review_require_all_files_modified`: Quality gate for remaining files (default: true)
+
+#### Backward Compatibility
+
+- **Zero Breaking Changes**: Works with existing tasks
+- **Automatic Migration**: Runs on first startup of v3.5.0
+- **Idempotent**: Safe to upgrade and downgrade
+
+#### Token Efficiency
+
+- File paths stored as raw strings (not normalized to m_files)
+- Audit queries paginated with limit parameter
+- No upfront cost - pruning only when needed
+
+### Fixed - File Watcher Architectural Compliance (v3.3.0)
+
+**Critical architectural fix**: File watcher now monitors **all project files** with .gitignore filtering, as originally designed in v3.3.0 decision.
+
+**What Changed:**
+- ✅ Watches entire project root instead of individual files
+- ✅ Automatic monitoring of all files (selective task linking for transitions)
+- ✅ Removed explicit file add/remove operations (simplified architecture)
+- ✅ Better performance (single watch root vs many individual watches)
+
+**Impact:**
+- **Zero breaking changes** - External API unchanged
+- **Better performance** - Single chokidar watch root more efficient than 100+ individual file watches
+- **Automatic discovery** - New files automatically monitored when created
+- **Simpler code** - Removed watch control logic, `watchedFiles` map is now pure lookup
+
+**Technical Details:**
+- Modified `src/watcher/file-watcher.ts` line 80: `chokidar.watch(this.projectRoot)` instead of `chokidar.watch([])`
+- Removed explicit `watcher.add()` calls in `registerFile()` method
+- Removed explicit `watcher.unwatch()` calls in `unregisterFile()` method
+- Global watching with .gitignore filtering (lines 87-94) now fully utilized
+
+**Why This Matters:**
+The v3.3.0 architectural decision mandated "Watch all project files with .gitignore support instead of individual file registration" but the implementation was selective (only task-linked files). This fix ensures compliance with the original design, providing better performance and simpler architecture.
+
+## [3.4.1] - 2025-10-22
+
+### Changed - VCS Abstraction Layer Enhancement
+
+Extended v3.4.0 Git-aware auto-complete to support multiple version control systems through adapter pattern.
+
+**New VCS Support:**
+- ✅ **Mercurial (hg)** - Full support with `.hg/dirstate` watching
+- ✅ **SVN (Subversion)** - Periodic check support (no local index file)
+
+**Implementation:**
+- Created VCS adapter interface (`src/utils/vcs-adapter.ts`)
+- Implemented GitAdapter, MercurialAdapter, SVNAdapter
+- Auto-detection logic with priority: Git → Mercurial → SVN
+- Refactored `detectAndCompleteReviewedTasks()` to use VCS abstraction
+- Enhanced file watcher to support multiple VCS index files
+
+**Backward Compatible:** No breaking changes - fully compatible with Git-only workflows.
+
+**Future Support:** Perforce and Plastic SCM planned (see [#19](https://github.com/sin5ddd/mcp-sqlew/issues/19))
+
+## [3.4.0] - 2025-10-22
+
+### Added - Git-Aware Auto-Complete 🎯
+
+**Major Feature: Automatic Task Completion via Git Commits**
+
+Replace flawed auto-revert logic with intelligent git-commit-based task completion. When ALL watched files for a task are committed to Git, the task automatically transitions from `waiting_review` → `done`. Git commits serve as implicit review approval.
+
+#### Core Implementation
+
+**1. `detectAndCompleteReviewedTasks()` Function**
+- New core function for git-aware auto-complete detection
+- Uses `git log --since="@<task.created_ts>" --name-only` to query commit history
+- Validates ALL watched files are committed (configurable)
+- Gracefully handles non-git repositories (skips auto-complete)
+- **File**: `src/utils/task-stale-detection.ts`
+- **Token Efficiency**: Zero token cost - uses local git commands
+
+**2. Real-Time Git Index Watching**
+- File watcher monitors `.git/index` for changes
+- Detects `git add` and `git commit` operations in real-time
+- Triggers `detectAndCompleteReviewedTasks()` automatically on git operations
+- **Files**: `src/watcher/file-watcher.ts`, `src/watcher/index.ts`
+- **Benefit**: Immediate task completion without manual intervention
+
+**3. Periodic Git Checks**
+- `task.list()` action now checks for committed files before returning
+- Ensures eventual task completion even if file watcher missed events
+- **File**: `src/tools/tasks.ts`
+- **Response Fields**: `git_auto_completed` (count of auto-completed tasks)
+
+**5. Enhanced Inline Status (v3.4.0)**
+- `stats` tool now includes `review_status` section
+- Shows `awaiting_commit` count (tasks in waiting_review)
+- Shows `overdue_review` count (tasks in waiting_review >24h)
+- **File**: `src/tools/utils.ts`
+
+**6. Configuration Options**
+- `git_auto_complete_enabled` (default: '1') - Enable/disable feature
+- `require_all_files_committed` (default: '1') - ALL vs ANY files committed
+- `stale_review_notification_hours` (default: '48') - Notification threshold
+- **File**: `src/database.ts`
+
+#### Problem Solved
+
+**Before v3.4.0 (FLAWED):**
+```
+waiting_review (24h idle) → todo (work discarded ❌)
+```
+
+**After v3.4.0 (VCS-AWARE):**
+```
+waiting_review (all files committed) → done (work preserved ✅)
+```
+
+**Why This Matters:**
+- Tasks reaching `waiting_review` have passed quality gates (files modified, tests pass, compile success)
+- Work is essentially DONE - reverting to `todo` discarded completed work
+- VCS commits are a natural, persistent signal that code has been reviewed and approved
+- **Multi-VCS Support**: Works with Git, Mercurial, SVN - no configuration needed (auto-detection)
+
+#### Usage Examples
+
+**Example 1: Real-Time Auto-Complete**
+```typescript
+// 1. Task created with watched files
+task action=create
+  title: "Implement JWT auth"
+  watch_files: ["src/auth.ts", "src/auth.test.ts"]
+// Status: todo
+
+// 2. Edit files → auto-transition to in_progress
+// 3. Quality gates pass → auto-transition to waiting_review
+// 4. Developer commits files (any VCS):
+git commit -m "feat: Add JWT authentication"
+// OR: hg commit -m "feat: Add JWT authentication"
+// OR: svn commit -m "feat: Add JWT authentication"
+
+// 5. File watcher detects VCS index change (Git/Mercurial)
+// 6. Auto-complete runs → Task moves to 'done' ✅
+```
+
+**Example 2: Periodic Check**
+```typescript
+// Task in waiting_review, files committed yesterday
+task action=list
+// Response includes:
+{
+  tasks: [...],
+  git_auto_completed: 1,  // This task just auto-completed
+  ...
+}
+```
+
+### Changed
+
+**1. Removed Flawed Auto-Revert Logic**
+- **REMOVED**: `waiting_review` → `todo` after 24 hours
+- **Rationale**: Tasks in waiting_review have completed work; reverting discarded progress
+- **File**: `src/utils/task-stale-detection.ts` (lines 105-116 removed)
+
+**2. Updated Review Idle Time Default**
+- **Changed**: Default from 15 minutes → 3 minutes
+- **Rationale**: 3 minutes is sufficient for quality gate detection
+- **Config Key**: `review_idle_minutes`
+- **File**: `src/utils/task-stale-detection.ts`
+
+### Fixed
+
+- Zero-token overhead for git-aware auto-complete (uses local git commands)
+- Multi-agent compatible (git state shared across all agents)
+- Survives process restarts (git history is persistent)
+- Handles edge cases: no git repo, no watched files, partial commits
+
+### Documentation
+
+**Updated:**
+- `docs/TASK_OVERVIEW.md` - Git-aware workflow diagram and waiting_review behavior
+- `docs/AUTO_FILE_TRACKING.md` - Git integration explanation
+- `docs/CONFIGURATION.md` - New config keys documented
+- `README.md` - v3.4.0 feature highlights
+
+**New:**
+- `src/tests/git-aware-completion.test.ts` - Comprehensive test suite
+
+### Technical Details
+
+**Files Modified:**
+- `src/utils/task-stale-detection.ts` - Core git-aware logic, removed flawed auto-revert
+- `src/tools/tasks.ts` - Periodic git checks in list action
+- `src/tools/utils.ts` - Enhanced inline status with review_status
+- `src/watcher/file-watcher.ts` - Git index watching
+- `src/database.ts` - New v3.4.0 config keys
+
+**Dependencies:**
+- No new dependencies (uses Node.js built-in `child_process` for git commands)
+
+**Token Efficiency:**
+- Zero-token cost for git operations
+- Periodic checks piggyback on existing list operations
+- No additional API calls required
+
+### Migration
+
+**From v3.4.1 to v3.4.0:**
+- **Automatic**: Config keys auto-added on database initialization
+- **Breaking Change**: None - fully backward compatible
+- **Behavior Change**: Tasks in `waiting_review` no longer auto-revert to `todo`
+- **Action Required**: None - feature enabled by default
+
+**Configuration (Optional):**
+```toml
+# .sqlew/config.toml
+[tasks.review]
+git_auto_complete_enabled = true          # Default: true
+require_all_files_committed = true        # Default: true
+stale_review_notification_hours = 48      # Default: 48
+
+[tasks]
+review_idle_minutes = 3                   # Changed from 15 to 3
+```
+
+---
+
+## [3.4.1] - 2025-10-22
+
+### Added - File Watcher Redesign & Smart Filtering
+
+#### New Features
+
+**1. `watch_files` Parameter (task.create and task.update)**
+- Add files to watch when creating or updating tasks in one step
+- Replaces the need for separate `task.link(link_type="file")` calls
+- Batch file registration with atomic watcher updates
+- Example:
+  ```typescript
+  task action=create
+    title: "Implement auth"
+    watch_files: ["src/auth.ts", "src/auth.test.ts"]
+  ```
+- **Token Savings**: 75% fewer MCP calls (1 vs 4), 35% token reduction
+- **Files Modified**: `src/tools/tasks.ts`
+
+**2. GitIgnore Support & Smart File Filtering**
+- Automatic `.gitignore` parsing from project root
+- 70+ built-in ignore patterns (node_modules, dist, .env, etc.)
+- Prevents watching sensitive/build/dependency files
+- Zero configuration - works out of the box
+- Example patterns ignored:
+  - Version control: `.git`, `.gitignore`
+  - Dependencies: `node_modules`, `bower_components`
+  - Build outputs: `dist`, `build`, `.next`, `.nuxt`
+  - Logs: `*.log`, `npm-debug.log*`
+  - OS files: `.DS_Store`, `Thumbs.db`
+  - IDE files: `.vscode`, `.idea`, `*.swp`
+  - Environment: `.env`, `.env.local`
+  - Database: `*.db`, `.mcp-context`
+- **New Module**: `src/watcher/gitignore-parser.ts`
+- **Files Modified**: `src/watcher/file-watcher.ts`, `src/watcher/index.ts`
+- **Dependencies Added**: `ignore` npm package
+
+**3. `watch_files` Action**
+- Dedicated action for managing file watches dynamically
+- Three sub-actions: `watch`, `unwatch`, `list`
+- Batch operations support (multiple files in one call)
+- Example:
+  ```typescript
+  // Watch files
+  task action=watch_files task_id=123 action=watch file_paths=["src/file.ts"]
+
+  // Unwatch files
+  task action=watch_files task_id=123 action=unwatch file_paths=["src/file.ts"]
+
+  // List watched files
+  task action=watch_files task_id=123 action=list
+  ```
+- **Files Modified**: `src/tools/tasks.ts`
+
+**4. Updated Help Documentation**
+- `task.help()` now documents new `watch_files` parameter and action
+- Deprecation notices for `task.link(link_type="file")`
+- Updated examples to use v3.4.1 API
+- **Files Modified**: `src/tools/tasks.ts` (taskHelp function)
+
+**5. Auto-Archive for Done Tasks**
+- Automatic archiving of tasks in `done` status after 48 hours (2 days)
+- Weekend-aware retention logic (consistent with message/file cleanup)
+- Configurable via `auto_archive_done_days` setting (default: 2 days)
+- Runs on startup and before task operations (`list`, `move`)
+- Same-session context preservation: Tasks remain accessible for 1-2 day sprints
+- After 48 hours: Tasks archived to keep active list clean
+- Example:
+  ```
+  Friday 5pm: Task marked done
+  Tuesday 5pm: Auto-archived (skips weekend)
+  ```
+- **New Config Key**: `auto_archive_done_days` in m_config table
+- **New Function**: `autoArchiveOldDoneTasks()` in src/utils/task-stale-detection.ts
+- **New Function**: `calculateTaskArchiveCutoff()` in src/utils/retention.ts
+- **Files Modified**:
+  - `src/constants.ts` (added CONFIG_KEYS.AUTO_ARCHIVE_DONE_DAYS)
+  - `src/utils/retention.ts` (calculateTaskArchiveCutoff function)
+  - `src/utils/task-stale-detection.ts` (autoArchiveOldDoneTasks function, TASK_STATUS constants)
+  - `src/tools/tasks.ts` (listTasks, moveTask - integrated auto-archive calls)
+  - `src/database.ts` (initializeDatabase - runs auto-archive on startup)
+  - `assets/schema.sql` (default config value)
+
+**6. TOML Configuration File Support**
+- Load configuration from `.sqlew/config.toml` file
+- Database path configurable via config file
+- Hierarchical config structure with three sections:
+  - `[database]` - Database location settings
+  - `[autodelete]` - Retention policies (weekend-aware, message hours, file history)
+  - `[tasks]` - Task management settings (auto-archive, stale detection)
+- Priority system: CLI args > config.toml > database m_config > code defaults
+- Config validation with helpful error messages
+- Comprehensive example file: `.sqlew/config.toml.example`
+- All numeric settings have range validation:
+  - `message_hours`: 1-720 (1 hour to 30 days)
+  - `file_history_days`: 1-365 (1 day to 1 year)
+  - `auto_archive_done_days`: 1-365 (1 day to 1 year)
+  - `stale_hours_in_progress`: 1-168 (1 hour to 1 week)
+  - `stale_hours_waiting_review`: 1-720 (1 hour to 30 days)
+- Example config:
+  ```toml
+  [database]
+  path = ".sqlew/custom.db"
+
+  [autodelete]
+  ignore_weekend = true
+  message_hours = 48
+  file_history_days = 14
+
+  [tasks]
+  auto_archive_done_days = 2
+  stale_hours_in_progress = 2
+  stale_hours_waiting_review = 24
+  auto_stale_enabled = true
+  ```
+- **New Dependency**: `smol-toml@^1.4.2` - TOML parser
+- **New Files**:
+  - `src/config/types.ts` (TypeScript interfaces, DEFAULT_CONFIG)
+  - `src/config/loader.ts` (loadConfigFile, flattenConfig, validateConfig functions)
+  - `.sqlew/config.toml.example` (comprehensive example with documentation)
+- **Files Modified**:
+  - `src/database.ts` (initializeDatabase - loads config, validates, populates m_config)
+  - `package.json` (smol-toml dependency)
+
+**7. Smart Review Detection - Quality-Based Auto-Transition**
+- Automatic transition from `in_progress` → `waiting_review` when quality gates met
+- **Four Quality Gates** (all must pass):
+  1. **All Watched Files Modified**: Every file linked to task must be edited at least once
+  2. **TypeScript Compiles**: If .ts/.tsx files present, `tsc --noEmit` must succeed
+  3. **Tests Pass**: If test files exist (*.test.ts, *.spec.ts), tests must pass
+  4. **Idle Time**: No file modifications for 15 minutes (configurable)
+- **Purely Algorithmic**: No AI instructions needed - works automatically via FileWatcher
+- **Configurable Gates**: Enable/disable individual checks via `.sqlew/config.toml`
+- **Hybrid Mode**: Tasks with `acceptance_criteria` can skip `waiting_review` and go directly to `done`
+- **Configuration Keys**:
+  - `review_idle_minutes` (default: 15) - Idle time before checking
+  - `review_require_all_files_modified` (default: true) - Require all files edited
+  - `review_require_tests_pass` (default: true) - Require tests to pass
+  - `review_require_compile` (default: true) - Require TypeScript compilation
+- **Console Output**: Detailed feedback on quality check results (passed/failed)
+- **Example Flow**:
+  ```
+  File modified → Track modification → Wait 15min idle
+                                           ↓
+                              Check quality gates:
+                              ✓ All files modified?
+                              ✓ TypeScript compiles?
+                              ✓ Tests pass?
+                                           ↓
+                              All passed? → waiting_review
+                              Some failed? → stay in_progress
+  ```
+- **New Module**: `src/utils/quality-checks.ts`
+  - `checkAllFilesModified()` - Verify all watched files edited
+  - `checkTypeScriptCompiles()` - Run `tsc --noEmit` validation
+  - `checkTestsPass()` - Execute test command if test files exist
+  - `checkReadyForReview()` - Combine all checks based on config
+- **Files Modified**:
+  - `src/constants.ts` (added 4 CONFIG_KEYS: REVIEW_*)
+  - `src/config/types.ts` (added review_* fields to TaskConfig, FlatConfig, DEFAULT_CONFIG)
+  - `assets/schema.sql` (added 4 config defaults)
+  - `src/watcher/file-watcher.ts`:
+    - Added tracking maps: `lastModifiedTimes`, `filesModifiedSet`
+    - Added `checkAndTransitionToReview()` method
+    - Updated `handleFileChange()` to track modifications and schedule review check
+  - `docs/AUTO_FILE_TRACKING.md` (new "Smart Review Detection" section)
+  - `docs/TASK_OVERVIEW.md` (updated state machine diagram, auto-stale detection section)
+  - `README.md` (added Smart Review Detection to Key Features)
+
+### Fixed
+
+**1. MCP Router Missing Actions (Task #124)**
+- Added missing actions to task tool enum: `watch_files`, `add_dependency`, `remove_dependency`, `get_dependencies`, `watcher`
+- Added `watch_files` action handler in router switch statement
+- **Files Modified**: `src/index.ts`
+
+**2. MCP Schema watch_files Parameter (Task #131)**
+- Added `watch_files` array parameter to task tool input schema
+- Added `file_path` and `file_paths` parameters for watch_files action
+- Added dependency-related parameters for completeness
+- **Files Modified**: `src/index.ts`
+
+**3. MCP SDK Array Parameter Handling (Critical)**
+- **Issue**: MCP SDK converts JSON array string `'["file.txt"]'` to character array `['[', '"', 'f', ...']`
+- **Solution**: Auto-detection and reassembly of character arrays back to proper file path arrays
+- **Impact**: Fixes `watch_files` parameter storage corruption in createTask/updateTask
+- **Files Modified**: `src/tools/tasks.ts` (createTaskInternal, updateTask functions)
+
+**4. Missing Function Import (Build Error)**
+- Added missing `watchFiles` function to imports from `./tools/tasks.js`
+- Fixed `watch_files` action routing to call correct function instead of `linkTask`
+- **Files Modified**: `src/index.ts`
+
+**5. Verified Implementation (Tasks #125, #126, #127)**
+- Task #125: Confirmed watch_files parameter correctly stored via t_task_file_links table - no bug found
+- Task #126: Confirmed watcher query uses correct `f.path` column - no schema error
+- Task #127: Root cause identified - file watcher requires proper database initialization, not a watcher bug
+
+### Changed
+
+**1. Deprecated: `task.link(link_type="file")`**
+- Still works but shows deprecation warning in console and response
+- Warning message guides users to new API
+- Backward compatible - no breaking changes
+- Example warning:
+  ```
+  ⚠️  DEPRECATION WARNING: task.link(link_type="file") is deprecated as of v3.4.1.
+     Use task.create(watch_files=[...]) or watch_files action instead.
+  ```
+- **Files Modified**: `src/tools/tasks.ts` (linkTask function)
+
+### Documentation
+
+**1. NEW: `docs/MIGRATION_v3.3.md`**
+- Comprehensive migration guide from v3.2.x to v3.4.1
+- Step-by-step migration instructions
+- API comparison tables
+- Common migration patterns
+- Backward compatibility details
+- Testing and verification steps
+
+**2. NEW: `docs/CONFIGURATION.md`**
+- Complete configuration guide (800+ lines)
+- TOML config file format and structure
+- All configuration options with validation rules
+- Priority system explanation (CLI > config.toml > database > defaults)
+- Setup instructions and best practices
+- Common configurations (development, production, weekend-aware)
+- Troubleshooting section
+- Created by subagent during v3.4.1 development
+
+**3. Updated: `docs/AUTO_FILE_TRACKING.md`**
+- Restructured with Quick Start section first (67% token reduction for new users)
+- All examples updated to use v3.4.1 API
+- New "API Changes (v3.4.1)" section
+- Migration guidance for v3.2.x users
+- Deprecation notices throughout
+
+**4. Updated: `docs/TOOL_REFERENCE.md`**
+- Task tool parameter table updated with `watch_files`
+- New section: "File Watching with Tasks (v3.4.1)"
+- watch_files action documented
+- Migration examples
+- Deprecation notices
+
+**5. Updated: `docs/TASK_OVERVIEW.md`** (by subagent)
+- Auto-archive feature documentation
+- 48-hour retention policy
+- Weekend-aware archiving examples
+
+**6. Updated: `docs/TASK_ACTIONS.md`** (by subagent)
+- Auto-archive behavior in list/move actions
+- Updated status transition examples
+
+**7. Updated: `docs/ARCHITECTURE.md`** (by subagent)
+- Configuration system architecture
+- Config file loading and priority system
+
+**8. Updated: `README.md`** (by subagents)
+- Configuration section added (lines 129-168)
+- Auto-stale detection description updated
+- CONFIGURATION.md reference in documentation section
+
+**9. Updated: `CHANGELOG.md`**
+- This entry documenting v3.4.1 changes
+
+### Technical Details
+
+**Implementation:**
+- `createTaskInternal()`: Added watch_files parameter and file linking logic
+- `createTask()`: Added watch_files parameter to public API
+- `updateTask()`: Added watch_files parameter to public API
+- `watchFiles()`: New exported function handling watch/unwatch/list actions
+- `linkTask()`: Added deprecation warning for link_type="file"
+- `taskHelp()`: Updated documentation with v3.4.1 APIs
+
+**Backward Compatibility:**
+- ✅ All v3.2.x code works without changes
+- ✅ Database schema unchanged
+- ✅ File watcher behavior unchanged
+- ✅ No breaking changes
+
+**Performance:**
+- Creating task with 3 files: 4 MCP calls → 1 MCP call (75% reduction)
+- Token usage: ~1,400 → ~900 (35% reduction)
+- Batch file registration: More efficient watcher updates
+
+**Testing:**
+- All 19 existing tests pass
+- TypeScript compilation successful
+- No regression in v3.2.x functionality
+
+### Migration Path
+
+**Option 1: Gradual Migration (Recommended)**
+- Continue using existing v3.2.x code
+- Use v3.4.1 API for new tasks
+- Both APIs work simultaneously
+
+**Option 2: Full Migration**
+- Update all task creation to use `watch_files` parameter
+- Replace `task.link(file)` with `watch_files` action
+- See `docs/MIGRATION_v3.3.md` for detailed steps
+
+**Timeline:**
+- v3.4.1: Deprecation warning only
+- v3.4.x-v3.5.x: Backward compatibility maintained
+- v4.0.0: `task.link(file)` may be removed (planned)
+
+### Files Changed
+
+**New Files:**
+- `src/config/types.ts` - TypeScript interfaces for TOML config (88 lines)
+- `src/config/loader.ts` - Config loading, flattening, validation (173 lines)
+- `.sqlew/config.toml.example` - Comprehensive example config with documentation (87 lines)
+- `src/watcher/gitignore-parser.ts` - GitIgnore parsing module
+- `docs/MIGRATION_v3.3.md` - Migration guide for v3.2.x → v3.4.1
+- `docs/CONFIGURATION.md` - Complete configuration guide (800+ lines)
+
+**Modified Code Files:**
+- `src/index.ts` - Added missing MCP router actions, watch_files parameter schema
+- `src/tools/tasks.ts` - watch_files parameter/action, deprecation, auto-archive integration
+- `src/watcher/file-watcher.ts` - GitIgnore support integration
+- `src/watcher/index.ts` - Updated watcher initialization
+- `src/database.ts` - Config file loading, validation, auto-archive on startup
+- `src/constants.ts` - Added AUTO_ARCHIVE_DONE_DAYS config key
+- `src/utils/retention.ts` - Added calculateTaskArchiveCutoff function
+- `src/utils/task-stale-detection.ts` - Added autoArchiveOldDoneTasks function, TASK_STATUS constants
+- `assets/schema.sql` - Added auto_archive_done_days default config
+- `package.json` - Added smol-toml dependency, version bump
+
+**Modified Documentation Files:**
+- `docs/AUTO_FILE_TRACKING.md` - Restructured with Quick Start, v3.4.1 API examples
+- `docs/TOOL_REFERENCE.md` - Updated task tool parameter tables and examples
+- `docs/TASK_OVERVIEW.md` - Auto-archive documentation
+- `docs/TASK_ACTIONS.md` - Auto-archive behavior in list/move actions
+- `docs/ARCHITECTURE.md` - Configuration system architecture
+- `README.md` - Configuration section, auto-stale updates, CONFIGURATION.md reference
+- `CHANGELOG.md` - This comprehensive v3.4.1 changelog entry
+
+**Total Lines Changed:**
+- New Code: ~348 lines (config system)
+- Modified Code: ~200 lines (auto-archive + watch_files + gitignore)
+- New Documentation: ~800 lines (CONFIGURATION.md)
+- Modified Documentation: ~1,200 lines (multiple files updated by subagents)
+
+## [3.2.6] - 2025-10-21
+
+### Fixed
+
+#### Critical Bug Fix: Task Creation with Missing Agent
+- **Issue**: "NOT NULL constraint failed: t_activity_log.agent_id" error when creating tasks
+- **Root Cause**: `createTaskInternal()` function allowed NULL `created_by_agent_id`, but activity log trigger required valid agent_id
+- **Bug**: When task created without `created_by_agent` parameter, `created_by_agent_id` was NULL, causing trigger to fail
+- **Impact**: All task creations without explicit `created_by_agent` parameter would fail
+- **Solution**: Default to 'system' agent when no `created_by_agent` provided, ensuring valid agent_id always exists
+- **File**: `src/tools/tasks.ts:116-119`
+
+### Technical Details
+- Activity log trigger `trg_log_task_create` requires non-NULL agent_id
+- Trigger uses COALESCE to fall back to 'system' agent, but 'system' may not exist on first use
+- If both `created_by_agent_id` is NULL AND no 'system' agent exists, trigger fails with NOT NULL constraint
+- Fix: Always create/use 'system' agent as default when no `created_by_agent` provided
+- Now all tasks have a valid creator agent (explicit or 'system' default)
+- Task creation now works with or without `created_by_agent` parameter
+- All tests pass (19/19)
+- Backward compatible
+
 ## [3.2.5] - 2025-10-21
 
 ### Fixed
@@ -29,19 +842,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **After**: `key is required` (clear validation message)
 
 ### Technical Details
-
-**Constraint Bug:**
-- Schema-code mismatch - code was referencing non-existent columns
-- `m_constraint_categories` has `id` and `name` columns
-- Applied standard `INSERT OR IGNORE` + `SELECT` pattern consistent with other helper functions
-
-**Validator Bug:**
-- TypeScript type system doesn't prevent undefined at runtime for parameters from JSON/user input
-- Added defensive checks: undefined, null, type validation, then trim
-- Now provides helpful error messages for all invalid parameter scenarios
-- All validation errors are now user-friendly instead of JavaScript runtime errors
-
-**Testing:**
+- Schema-code mismatch fixed in constraint creation
+- TypeScript runtime safety added to validator
 - Both fixes verified with comprehensive test scripts
 - All existing tests pass (19/19)
 - Backward compatible - only fixes broken functionality