Cursor rule

1---
2description: Guidelines for managing task dependencies and relationships
3globs: scripts/modules/dependency-manager.js
4alwaysApply: false
5---
6 
7# Dependency Management Guidelines
8 
9## Dependency Structure Principles
10 
11- **Dependency References**:
12  - ✅ DO: Represent task dependencies as arrays of task IDs
13  - ✅ DO: Use numeric IDs for direct task references
14  - ✅ DO: Use string IDs with dot notation (e.g., "1.2") for subtask references
15  - ❌ DON'T: Mix reference types without proper conversion
16 
17```javascript
18  // ✅ DO: Use consistent dependency formats
19  // For main tasks
20  task.dependencies = [1, 2, 3]; // Dependencies on other main tasks
21  
22  // For subtasks
23  subtask.dependencies = [1, "3.2"]; // Dependency on main task 1 and subtask 2 of task 3
24```
25 
26- **Subtask Dependencies**:
27  - ✅ DO: Allow numeric subtask IDs to reference other subtasks within the same parent
28  - ✅ DO: Convert between formats appropriately when needed
29  - ❌ DON'T: Create circular dependencies between subtasks
30 
31```javascript
32  // ✅ DO: Properly normalize subtask dependencies
33  // When a subtask refers to another subtask in the same parent
34  if (typeof depId === 'number' && depId < 100) {
35    // It's likely a reference to another subtask in the same parent task
36    const fullSubtaskId = `${parentId}.${depId}`;
37    // Now use fullSubtaskId for validation
38  }
39```
40 
41## Dependency Validation
42 
43- **Existence Checking**:
44  - ✅ DO: Validate that referenced tasks exist before adding dependencies
45  - ✅ DO: Provide clear error messages for non-existent dependencies
46  - ✅ DO: Remove references to non-existent tasks during validation
47 
48```javascript
49  // ✅ DO: Check if the dependency exists before adding
50  if (!taskExists(data.tasks, formattedDependencyId)) {
51    log('error', `Dependency target ${formattedDependencyId} does not exist in tasks.json`);
52    process.exit(1);
53  }
54```
55 
56- **Circular Dependency Prevention**:
57  - ✅ DO: Check for circular dependencies before adding new relationships
58  - ✅ DO: Use graph traversal algorithms (DFS) to detect cycles
59  - ✅ DO: Provide clear error messages explaining the circular chain
60 
61```javascript
62  // ✅ DO: Check for circular dependencies before adding
63  const dependencyChain = [formattedTaskId];
64  if (isCircularDependency(data.tasks, formattedDependencyId, dependencyChain)) {
65    log('error', `Cannot add dependency ${formattedDependencyId} to task ${formattedTaskId} as it would create a circular dependency.`);
66    process.exit(1);
67  }
68```
69 
70- **Self-Dependency Prevention**:
71  - ✅ DO: Prevent tasks from depending on themselves
72  - ✅ DO: Handle both direct and indirect self-dependencies
73 
74```javascript
75  // ✅ DO: Prevent self-dependencies
76  if (String(formattedTaskId) === String(formattedDependencyId)) {
77    log('error', `Task ${formattedTaskId} cannot depend on itself.`);
78    process.exit(1);
79  }
80```
81 
82## Dependency Modification
83 
84- **Adding Dependencies**:
85  - ✅ DO: Format task and dependency IDs consistently
86  - ✅ DO: Check for existing dependencies to prevent duplicates
87  - ✅ DO: Sort dependencies for better readability
88 
89```javascript
90  // ✅ DO: Format IDs consistently when adding dependencies
91  const formattedTaskId = typeof taskId === 'string' && taskId.includes('.') 
92    ? taskId : parseInt(taskId, 10);
93  
94  const formattedDependencyId = formatTaskId(dependencyId);
95```
96 
97- **Removing Dependencies**:
98  - ✅ DO: Check if the dependency exists before removing
99  - ✅ DO: Handle different ID formats consistently
100  - ✅ DO: Provide feedback about the removal result
101 
102```javascript
103  // ✅ DO: Properly handle dependency removal
104  const dependencyIndex = targetTask.dependencies.findIndex(dep => {
105    // Convert both to strings for comparison
106    let depStr = String(dep);
107    
108    // Handle relative subtask references
109    if (typeof dep === 'number' && dep < 100 && isSubtask) {
110      const [parentId] = formattedTaskId.split('.');
111      depStr = `${parentId}.${dep}`;
112    }
113    
114    return depStr === normalizedDependencyId;
115  });
116  
117  if (dependencyIndex === -1) {
118    log('info', `Task ${formattedTaskId} does not depend on ${formattedDependencyId}, no changes made.`);
119    return;
120  }
121  
122  // Remove the dependency
123  targetTask.dependencies.splice(dependencyIndex, 1);
124```
125 
126## Dependency Cleanup
127 
128- **Duplicate Removal**:
129  - ✅ DO: Use Set objects to identify and remove duplicates
130  - ✅ DO: Handle both numeric and string ID formats
131 
132```javascript
133  // ✅ DO: Remove duplicate dependencies
134  const uniqueDeps = new Set();
135  const uniqueDependencies = task.dependencies.filter(depId => {
136    // Convert to string for comparison to handle both numeric and string IDs
137    const depIdStr = String(depId);
138    if (uniqueDeps.has(depIdStr)) {
139      log('warn', `Removing duplicate dependency from task ${task.id}: ${depId}`);
140      return false;
141    }
142    uniqueDeps.add(depIdStr);
143    return true;
144  });
145```
146 
147- **Invalid Reference Cleanup**:
148  - ✅ DO: Check for and remove references to non-existent tasks
149  - ✅ DO: Check for and remove self-references
150  - ✅ DO: Track and report changes made during cleanup
151 
152```javascript
153  // ✅ DO: Filter invalid task dependencies
154  task.dependencies = task.dependencies.filter(depId => {
155    const numericId = typeof depId === 'string' ? parseInt(depId, 10) : depId;
156    if (!validTaskIds.has(numericId)) {
157      log('warn', `Removing invalid task dependency from task ${task.id}: ${depId} (task does not exist)`);
158      return false;
159    }
160    return true;
161  });
162```
163 
164## Dependency Visualization
165 
166- **Status Indicators**:
167  - ✅ DO: Use visual indicators to show dependency status (✅/⏱️)
168  - ✅ DO: Format dependency lists consistently
169 
170```javascript
171  // ✅ DO: Format dependencies with status indicators
172  function formatDependenciesWithStatus(dependencies, allTasks) {
173    if (!dependencies || dependencies.length === 0) {
174      return 'None';
175    }
176    
177    return dependencies.map(depId => {
178      const depTask = findTaskById(allTasks, depId);
179      if (!depTask) return `${depId} (Not found)`;
180      
181      const isDone = depTask.status === 'done' || depTask.status === 'completed';
182      const statusIcon = isDone ? '✅' : '⏱️';
183      
184      return `${statusIcon} ${depId} (${depTask.status})`;
185    }).join(', ');
186  }
187```
188 
189## Cycle Detection
190 
191- **Graph Traversal**:
192  - ✅ DO: Use depth-first search (DFS) for cycle detection
193  - ✅ DO: Track visited nodes and recursion stack
194  - ✅ DO: Support both task and subtask dependencies
195 
196```javascript
197  // ✅ DO: Use proper cycle detection algorithms
198  function findCycles(subtaskId, dependencyMap, visited = new Set(), recursionStack = new Set()) {
199    // Mark the current node as visited and part of recursion stack
200    visited.add(subtaskId);
201    recursionStack.add(subtaskId);
202    
203    const cyclesToBreak = [];
204    const dependencies = dependencyMap.get(subtaskId) || [];
205    
206    for (const depId of dependencies) {
207      if (!visited.has(depId)) {
208        const cycles = findCycles(depId, dependencyMap, visited, recursionStack);
209        cyclesToBreak.push(...cycles);
210      } 
211      else if (recursionStack.has(depId)) {
212        // Found a cycle, add the edge to break
213        cyclesToBreak.push(depId);
214      }
215    }
216    
217    // Remove the node from recursion stack before returning
218    recursionStack.delete(subtaskId);
219    
220    return cyclesToBreak;
221  }
222```
223 
224Refer to [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines.