sqlew 3.1.2 → 3.2.3

package/docs/TASK_LINKING.md

@@ -1,7 +1,7 @@
 # Task Linking Guide
 
-**Version:** 3.0.0
-**Last Updated:** 2025-10-17
+**Version:** 3.2.0
+**Last Updated:** 2025-10-18
 
 ## Table of Contents
 
@@ -10,17 +10,19 @@
 3. [Decision Links](#decision-links)
 4. [Constraint Links](#constraint-links)
 5. [File Links](#file-links)
-6. [Querying Links](#querying-links)
-7. [Linking Strategies](#linking-strategies)
-8. [Best Practices](#best-practices)
-9. [Related Documentation](#related-documentation)
+6. [Task-to-Task Dependencies](#task-to-task-dependencies) (NEW in 3.2.0)
+7. [Querying Links](#querying-links)
+8. [Linking Strategies](#linking-strategies)
+9. [Best Practices](#best-practices)
+10. [Related Documentation](#related-documentation)
 
 ## Overview
 
-Tasks can be linked to three types of entities to establish context and relationships:
+Tasks can be linked to multiple types of entities to establish context and relationships:
 - **Decisions:** Track which architectural decisions relate to this task
 - **Constraints:** Associate performance/security/architecture constraints
 - **Files:** Connect to modified files for context
+- **Task Dependencies:** Blocking relationships between tasks (NEW in 3.2.0)
 
 **Benefits of Linking:**
 - **Context Preservation:** See related decisions/constraints/files when viewing task
@@ -401,6 +403,183 @@ Link tasks to files when:
 }
 ```
 
+## Task-to-Task Dependencies
+
+**NEW in v3.2.0:** Task dependencies are fundamentally different from other link types. While decision/constraint/file links provide **reference context**, task dependencies enforce **blocking relationships** for workflow coordination.
+
+### Key Differences
+
+| Aspect | Decision/Constraint/File Links | Task Dependencies |
+|--------|-------------------------------|-------------------|
+| **Purpose** | Reference context | Workflow coordination |
+| **Relationship** | Informational | Blocking (enforced) |
+| **Action Used** | `link` | `add_dependency` / `remove_dependency` |
+| **Direction** | One-way reference | Directional blocking |
+| **Validation** | Entity existence | Circular detection, archived check |
+| **Query Method** | Via `get` action | Via `get_dependencies` action |
+
+### When to Use Dependencies vs Links
+
+**Use Task Dependencies For:**
+- Sequential technical requirements (DB schema before ORM)
+- Ordered feature rollout (API before UI)
+- Hard blockers (auth must complete before protected routes)
+- Cross-layer dependencies (data → business → presentation)
+
+**Use Decision/Constraint/File Links For:**
+- Documenting architectural decisions related to task
+- Associating performance/security requirements
+- Tracking modified files for context
+- Reference material (not blocking)
+
+### Dependency Examples
+
+**Creating Dependencies:**
+```javascript
+// Task #1: Implement authentication
+{action: "create", title: "Implement JWT auth"}
+// Returns: {task_id: 1}
+
+// Task #2: Add user profile (depends on auth)
+{action: "create", title: "Add user profile page"}
+// Returns: {task_id: 2}
+
+// Add dependency (auth blocks profile)
+{
+  action: "add_dependency",
+  blocker_task_id: 1,
+  blocked_task_id: 2
+}
+// Task #2 cannot proceed until Task #1 is done
+```
+
+**Combining Dependencies with Links:**
+```javascript
+// Create infrastructure task
+{action: "create", title: "Setup PostgreSQL", layer: "data"}
+// Returns: {task_id: 10}
+
+// Link to decision (context)
+{
+  action: "link",
+  task_id: 10,
+  link_type: "decision",
+  link_key: "database_choice"
+}
+
+// Create dependent task
+{action: "create", title: "Create user schema", layer: "data"}
+// Returns: {task_id: 11}
+
+// Add dependency (PostgreSQL must be setup first)
+{
+  action: "add_dependency",
+  blocker_task_id: 10,
+  blocked_task_id: 11
+}
+
+// Result:
+// - Task #11 has context link to "database_choice" decision
+// - Task #11 is blocked by Task #10 (cannot start until DB setup)
+```
+
+**Querying Dependencies:**
+```javascript
+// Get what's blocking a task
+{
+  action: "get_dependencies",
+  task_id: 2
+}
+// Returns:
+// {
+//   task_id: 2,
+//   blockers: [1],    // Task #1 blocks this
+//   blocking: []      // This doesn't block anything
+// }
+
+// Get full task with all links AND dependencies
+{
+  action: "get",
+  task_id: 2,
+  include_dependencies: true
+}
+// Returns:
+// {
+//   task_id: 2,
+//   title: "Add user profile page",
+//   // ... other fields ...
+//   dependencies: {
+//     blockers: [1],
+//     blocking: []
+//   },
+//   decision_links: ["auth_method"],
+//   constraint_links: [],
+//   file_links: []
+// }
+```
+
+### Validation Rules
+
+Task dependencies have strict validation to prevent workflow deadlocks:
+
+1. **No Self-Dependencies**: Task cannot block itself
+2. **No Circular Dependencies**: Direct or transitive cycles rejected
+3. **Both Tasks Exist**: Blocker and blocked tasks must exist
+4. **Neither Archived**: Archived tasks cannot participate in dependencies
+
+**Example: Circular Detection**
+```javascript
+// Existing: Task #1 blocks Task #2
+// Existing: Task #2 blocks Task #3
+
+// ❌ Invalid (creates cycle)
+{
+  action: "add_dependency",
+  blocker_task_id: 3,
+  blocked_task_id: 1
+}
+// Error: "Circular dependency detected: Task #3 → 1 → 2 → 3"
+```
+
+### CASCADE Deletion
+
+When a task is deleted, all its dependencies are automatically removed:
+
+```javascript
+// Before:
+// Task #1 blocks Task #2
+// Task #1 blocks Task #3
+
+// Delete Task #1
+{action: "archive", task_id: 1}
+
+// After:
+// Dependencies automatically removed
+// Task #2 and #3 are now unblocked
+```
+
+### Best Practices
+
+**DO:**
+- Use dependencies for hard technical blockers
+- Keep dependency chains short (2-5 levels)
+- Use `get_dependencies` to visualize chains before adding
+- Combine with decision/constraint links for full context
+
+**DON'T:**
+- Use dependencies for organizational preferences
+- Create dense dependency graphs (many-to-many)
+- Use dependencies for parallel/independent features
+- Forget to remove dependencies when tasks complete
+
+### For More Details
+
+See **[TASK_DEPENDENCIES.md](TASK_DEPENDENCIES.md)** for comprehensive dependency management documentation including:
+- Circular dependency detection algorithm
+- Token efficiency strategies
+- Complete usage examples
+- Workflow coordination patterns
+
 ## Querying Links
 
 ### Get Task with Links
@@ -718,12 +897,13 @@ WHERE tcl.constraint_id = 5;
 
 - **[TASK_OVERVIEW.md](TASK_OVERVIEW.md)** - Task system overview and core concepts
 - **[TASK_ACTIONS.md](TASK_ACTIONS.md)** - Complete action reference with examples
+- **[TASK_DEPENDENCIES.md](TASK_DEPENDENCIES.md)** - Dependency management (NEW in 3.2.0)
 - **[TASK_MIGRATION.md](TASK_MIGRATION.md)** - Migrating from decision-based task tracking
 - **[TASK_SYSTEM.md](TASK_SYSTEM.md)** - Complete documentation (original)
 - **[AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md)** - Comprehensive AI agent guide
 
 ---
 
-**Version:** 3.0.0
+**Version:** 3.2.0
 **Last Updated:** 2025-10-17
 **Author:** sin5ddd

package/docs/TOOL_REFERENCE.md

@@ -87,7 +87,7 @@
 | Action | Required | Optional |
 |--------|----------|----------|
 | **set** | action, key, value, layer | agent, version, status, tags, scopes |
-| **get** | action, key | version |
+| **get** | action, key | version, include_context |
 | **list** | action | status, layer, tags, scope, tag_match, limit, offset |
 | **search_tags** | action, tags | match_mode, status, layer |
 | **search_layer** | action, layer | status, include_tags |
@@ -99,6 +99,8 @@
 | **set_from_template** | action, template, key, value, layer | agent, version, status, tags, scopes |
 | **create_template** | action, name, defaults | required_fields, created_by |
 | **list_templates** | action | - |
+| **add_decision_context** | action, key, rationale | alternatives_considered, tradeoffs, decided_by, related_task_id, related_constraint_id |
+| **list_decision_contexts** | action | decision_key, related_task_id, related_constraint_id, decided_by, limit, offset |
 
 ### `message` Tool
 
@@ -321,6 +323,161 @@
 
 ---
 
+## Decision Context System (v3.2.2)
+
+### What is Decision Context?
+
+Decision Context allows you to attach rich documentation to decisions, including:
+- **Rationale**: WHY the decision was made
+- **Alternatives Considered**: What options were evaluated and rejected
+- **Tradeoffs**: Pros and cons analysis
+
+### Key Features
+
+- **Multi-Session Development**: Preserve decision reasoning across days/weeks
+- **Architecture Reviews**: Document non-standard choices for future developers
+- **Team Handoffs**: Transfer knowledge with full context
+- **Linked Relationships**: Connect contexts to tasks and constraints
+
+### Adding Decision Context
+
+```javascript
+{
+  action: "add_decision_context",
+  key: "database_choice",
+  rationale: "Selected PostgreSQL because: (1) Complex relational queries required for reporting, (2) ACID compliance critical for financial data, (3) Team has strong SQL expertise",
+  alternatives_considered: [
+    {
+      option: "MongoDB",
+      reason: "Rejected due to weak consistency guarantees for financial data"
+    },
+    {
+      option: "MySQL",
+      reason: "Rejected due to limited JSON support needed for metadata"
+    }
+  ],
+  tradeoffs: {
+    pros: ["Strong consistency", "Complex queries", "Team expertise"],
+    cons: ["Less flexible schema", "Vertical scaling limitations"]
+  },
+  decided_by: "backend-team",
+  related_task_id: 42
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "context_id": 1,
+  "decision_key": "database_choice",
+  "message": "Decision context added successfully"
+}
+```
+
+### Retrieving Decision with Context
+
+```javascript
+// Standard get (backward compatible)
+{
+  action: "get",
+  key: "database_choice"
+}
+// → Returns: { key, value, layer, status, version, tags, ... }
+
+// Get with context
+{
+  action: "get",
+  key: "database_choice",
+  include_context: true
+}
+// → Returns: { key, value, ..., contexts: [{rationale, alternatives_considered, tradeoffs, ...}] }
+```
+
+### Listing Decision Contexts
+
+```javascript
+// List all contexts
+{
+  action: "list_decision_contexts",
+  limit: 50
+}
+
+// Filter by decision key
+{
+  action: "list_decision_contexts",
+  decision_key: "database_choice"
+}
+
+// Filter by related task
+{
+  action: "list_decision_contexts",
+  related_task_id: 42
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "contexts": [
+    {
+      "id": 1,
+      "decision_key": "database_choice",
+      "rationale": "Selected PostgreSQL because...",
+      "alternatives_considered": [...],
+      "tradeoffs": {...},
+      "decided_by": "backend-team",
+      "decision_date": "2025-10-18T06:48:00Z",
+      "related_task_id": 42,
+      "related_constraint_id": null
+    }
+  ],
+  "count": 1
+}
+```
+
+### Parameter Details
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| **key** | string | ✅ | Decision key to attach context to |
+| **rationale** | string | ✅ | WHY the decision was made |
+| **alternatives_considered** | JSON array | ❌ | List of {option, reason} objects |
+| **tradeoffs** | JSON object | ❌ | {pros: [...], cons: [...]} analysis |
+| **decided_by** | string | ❌ | Agent/team who made the decision |
+| **related_task_id** | number | ❌ | Link to implementation task |
+| **related_constraint_id** | number | ❌ | Link to system constraint |
+
+### When to Use Decision Context
+
+✅ **Use for:**
+- Architectural decisions with multiple viable options
+- Non-obvious implementation choices
+- Breaking changes that need justification
+- Security/performance trade-off analysis
+- Cross-team collaboration documentation
+
+❌ **Don't use for:**
+- Routine implementation details
+- Temporary decisions
+- Obvious or standard choices
+
+### Best Practices
+
+1. **Be Specific**: "Chose X because Y" not "Chose X"
+2. **Document Alternatives**: Show what was considered and rejected
+3. **Quantify Tradeoffs**: "5ms overhead acceptable for security" not "minor overhead"
+4. **Link to Tasks**: Connect decision context to implementation tasks
+5. **Update Over Time**: Add new contexts as decisions evolve
+
+### See Also
+
+- **[Decision Context Guide](DECISION_CONTEXT.md)** - Comprehensive examples and workflows (500+ lines)
+- **[Workflows](WORKFLOWS.md)** - Multi-step decision context workflows
+
+---
+
 ## Template System
 
 ### What are Templates?

package/docs/WORKFLOWS.md

@@ -564,12 +564,34 @@ async function pollForUpdates() {
 
 // Response:
 // {
+//   agents: 5,
+//   files: 42,
+//   context_keys: 156,
+//   active_decisions: 312,
 //   total_decisions: 342,
-//   total_messages: 1203,
-//   total_file_changes: 589,
+//   messages: 1203,
+//   file_changes: 589,
+//   active_constraints: 12,
 //   total_constraints: 15,
+//   tags: 10,
+//   scopes: 8,
+//   layers: 5,
 //   total_tasks: 47,
-//   db_size_kb: 1024
+//   active_tasks: 23,  // Excludes done and archived
+//   tasks_by_status: {
+//     todo: 15,
+//     in_progress: 5,
+//     waiting_review: 3,
+//     blocked: 0,
+//     done: 20,
+//     archived: 4
+//   },
+//   tasks_by_priority: {
+//     low: 10,
+//     medium: 25,
+//     high: 10,
+//     critical: 2
+//   }
 // }
 
 // If database too large, trigger cleanup

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlew",
-  "version": "3.1.2",
-  "description": "MCP server for efficient context sharing between Claude Code sub-agents with Kanban Task Watcher, auto-file-tracking, and 97% token reduction",
+  "version": "3.2.3",
+  "description": "MCP server for efficient context sharing between Claude Code sub-agents with Kanban Task Watcher, Decision Context, auto-file-tracking, and 96% token efficiency through API consolidation",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -26,6 +26,8 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "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"
   },
   "engines": {