@e0ipso/ai-task-manager 1.26.1 → 1.26.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e0ipso/ai-task-manager",
-  "version": "1.26.1",
+  "version": "1.26.3",
   "description": "Task management for AI coding assistants",
   "main": "dist/index.js",
   "bin": {
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.14.0"
   },
   "files": [
     "dist/",
@@ -67,9 +67,9 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.5",
-    "@semantic-release/npm": "^12.0.2",
-    "@semantic-release/release-notes-generator": "^12.1.0",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/diff": "^5.2.3",
     "@types/fs-extra": "^11.0.4",
     "@types/inquirer": "^9.0.9",
@@ -83,7 +83,7 @@
     "husky": "^9.1.7",
     "jest": "^30.1.2",
     "prettier": "^3.6.2",
-    "semantic-release": "^24.2.7",
+    "semantic-release": "^25.0.2",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2"

package/templates/ai-task-manager/config/hooks/PRE_PLAN.md

@@ -2,14 +2,6 @@
 
 This hook provides pre-planning guidance to ensure scope control, simplicity principles, and proper validation requirements are established before comprehensive plan creation.
 
-<details>
-<summary>
-[IMPORTANT] Only for assistants that support assistant skills: Claude
-</summary>
-
-Analyze the current prompt in order to engage any relevant skills as necessary (either global or project skills).
-</details>
-
 ## Scope Control Guidelines
 
 **Critical: Implement ONLY what is explicitly requested**
@@ -48,4 +40,4 @@ Analyze the current prompt in order to engage any relevant skills as necessary (
 - Prioritize accuracy over speed
 - Consider both technical and non-technical aspects
 - Use the plan template in .ai/task-manager/config/templates/PLAN_TEMPLATE.md
-- DO NOT create or list any tasks or phases during the plan creation. This will be done in a later step. Stick to writing the PRD (Project Requirements Document).
+- DO NOT create or list any tasks or phases during the plan creation. This will be done in a later step. Stick to writing the PRD (Project Requirements Document).

package/templates/ai-task-manager/config/scripts/check-task-dependencies.cjs

@@ -10,6 +10,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const { execSync } = require('child_process');
+const { parseFrontmatter } = require('./shared-utils.cjs');
 
 // Chalk instance - loaded dynamically to handle ESM module
 let chalkInstance = null;
@@ -149,33 +150,6 @@ const findTaskFile = (planDir, taskId) => {
     return null;
 };
 
-// Function to parse YAML frontmatter
-const parseFrontmatter = (content) => {
-    const lines = content.split('\n');
-    let inFrontmatter = false;
-    let frontmatterEnd = false;
-    let delimiterCount = 0;
-    const frontmatterLines = [];
-
-    for (const line of lines) {
-        if (line.trim() === '---') {
-            delimiterCount++;
-            if (delimiterCount === 1) {
-                inFrontmatter = true;
-                continue;
-            } else if (delimiterCount === 2) {
-                frontmatterEnd = true;
-                break;
-            }
-        }
-
-        if (inFrontmatter && !frontmatterEnd) {
-            frontmatterLines.push(line);
-        }
-    }
-
-    return frontmatterLines.join('\n');
-};
 
 // Function to extract dependencies from frontmatter
 const extractDependencies = (frontmatter) => {
@@ -354,4 +328,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { main };
+module.exports = { main };

package/templates/ai-task-manager/config/scripts/get-next-plan-id.cjs

@@ -2,20 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-// Enable debug logging via environment variable
-const DEBUG = process.env.DEBUG === 'true';
-
-/**
- * Debug logging utility
- * @param {string} message - Debug message
- * @param {...any} args - Additional arguments to log
- */
-function debugLog(message, ...args) {
-  if (DEBUG) {
-    console.error(`[DEBUG] ${message}`, ...args);
-  }
-}
+const { findTaskManagerRoot, extractIdFromFrontmatter } = require('./shared-utils.cjs');
 
 /**
  * Error logging utility
@@ -26,213 +13,6 @@ function errorLog(message, ...args) {
   console.error(`[ERROR] ${message}`, ...args);
 }
 
-/**
- * Find the task manager root directory by traversing up from current working directory
- * @returns {string|null} Path to task manager root or null if not found
- */
-function findTaskManagerRoot() {
-  // Start from the actual current working directory, not process.cwd()
-  // This ensures we start from the correct context where the script is being executed
-  let currentPath = process.cwd();
-  const filesystemRoot = path.parse(currentPath).root;
-
-  debugLog(`Starting search for task manager root from: ${currentPath}`);
-  debugLog(`Filesystem root: ${filesystemRoot}`);
-
-  // Traverse upward through parent directories until we reach the filesystem root
-  while (currentPath !== filesystemRoot) {
-    const taskManagerPlansPath = path.join(currentPath, '.ai', 'task-manager', 'plans');
-    debugLog(`Checking for task manager at: ${taskManagerPlansPath}`);
-
-    try {
-      // Check if this is a valid task manager directory
-      if (fs.existsSync(taskManagerPlansPath)) {
-        // Verify it's a directory, not a file
-        const stats = fs.lstatSync(taskManagerPlansPath);
-        if (stats.isDirectory()) {
-          const taskManagerRoot = path.join(currentPath, '.ai', 'task-manager');
-          debugLog(`Found valid task manager root at: ${taskManagerRoot}`);
-          return taskManagerRoot;
-        } else {
-          debugLog(`Path exists but is not a directory: ${taskManagerPlansPath}`);
-        }
-      } else {
-        debugLog(`Task manager path does not exist: ${taskManagerPlansPath}`);
-      }
-    } catch (err) {
-      // Handle permission errors or other filesystem issues gracefully
-      // Continue searching in parent directories
-      if (err.code === 'EPERM' || err.code === 'EACCES') {
-        const warningMsg = `Warning: Permission denied accessing ${taskManagerPlansPath}`;
-        console.warn(warningMsg);
-        debugLog(`Permission error: ${err.message}`);
-      } else {
-        debugLog(`Filesystem error checking ${taskManagerPlansPath}: ${err.message}`);
-      }
-    }
-
-    // Move up to parent directory
-    const parentPath = path.dirname(currentPath);
-
-    // Safety check: if path.dirname returns the same path, we've reached the root
-    if (parentPath === currentPath) {
-      debugLog(`Reached filesystem root, stopping traversal`);
-      break;
-    }
-
-    currentPath = parentPath;
-    debugLog(`Moving up to parent directory: ${currentPath}`);
-  }
-
-  // Check the filesystem root as the final attempt
-  try {
-    const rootTaskManagerPlans = path.join(filesystemRoot, '.ai', 'task-manager', 'plans');
-    debugLog(`Final check at filesystem root: ${rootTaskManagerPlans}`);
-
-    if (fs.existsSync(rootTaskManagerPlans)) {
-      const stats = fs.lstatSync(rootTaskManagerPlans);
-      if (stats.isDirectory()) {
-        const taskManagerRoot = path.join(filesystemRoot, '.ai', 'task-manager');
-        debugLog(`Found task manager root at filesystem root: ${taskManagerRoot}`);
-        return taskManagerRoot;
-      }
-    }
-  } catch (err) {
-    debugLog(`Error checking filesystem root: ${err.message}`);
-  }
-
-  debugLog(`Task manager root not found in any parent directory`);
-  return null;
-}
-
-/**
- * Parse YAML frontmatter for ID with comprehensive error handling and debug logging
- * @param {string} content - File content
- * @param {string} [filePath] - Optional file path for error context
- * @returns {number|null} Extracted ID or null
- */
-function extractIdFromFrontmatter(content, filePath = 'unknown') {
-  debugLog(`Attempting to extract ID from frontmatter in: ${filePath}`);
-
-  // Check for frontmatter block existence
-  const frontmatterMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
-  if (!frontmatterMatch) {
-    debugLog(`No frontmatter block found in: ${filePath}`);
-    return null;
-  }
-
-  const frontmatterText = frontmatterMatch[1];
-  debugLog(`Found frontmatter block in ${filePath}:\n${frontmatterText}`);
-
-  // Enhanced patterns to handle various YAML formats and edge cases:
-  // - id: 5                    (simple numeric)
-  // - id: "5"                  (double quoted)
-  // - id: '5'                  (single quoted)
-  // - "id": 5                  (quoted key)
-  // - 'id': 5                  (single quoted key)
-  // - id : 5                   (extra spaces)
-  // - id: 05                   (zero-padded)
-  // - id: +5                   (explicit positive)
-  // - Mixed quotes: 'id': "5"  (different quote types)
-  const patterns = [
-    // Most flexible pattern - handles quoted/unquoted keys and values with optional spaces
-    {
-      regex: /^\s*["']?id["']?\s*:\s*["']?([+-]?\d+)["']?\s*(?:#.*)?$/mi,
-      description: 'Flexible pattern with optional quotes and comments'
-    },
-    // Simple numeric with optional whitespace and comments
-    {
-      regex: /^\s*id\s*:\s*([+-]?\d+)\s*(?:#.*)?$/mi,
-      description: 'Simple numeric with optional comments'
-    },
-    // Double quoted values
-    {
-      regex: /^\s*["']?id["']?\s*:\s*"([+-]?\d+)"\s*(?:#.*)?$/mi,
-      description: 'Double quoted values'
-    },
-    // Single quoted values
-    {
-      regex: /^\s*["']?id["']?\s*:\s*'([+-]?\d+)'\s*(?:#.*)?$/mi,
-      description: 'Single quoted values'
-    },
-    // Mixed quotes - quoted key, unquoted value
-    {
-      regex: /^\s*["']id["']\s*:\s*([+-]?\d+)\s*(?:#.*)?$/mi,
-      description: 'Quoted key, unquoted value'
-    },
-    // YAML-style with pipe or greater-than indicators (edge case)
-    {
-      regex: /^\s*id\s*:\s*[|>]\s*([+-]?\d+)\s*$/mi,
-      description: 'YAML block scalar indicators'
-    }
-  ];
-
-  // Try each pattern in order
-  for (let i = 0; i < patterns.length; i++) {
-    const { regex, description } = patterns[i];
-    debugLog(`Trying pattern ${i + 1} (${description}) on ${filePath}`);
-
-    const match = frontmatterText.match(regex);
-    if (match) {
-      debugLog(`Pattern ${i + 1} matched in ${filePath}: "${match[0].trim()}"`);
-
-      const rawId = match[1];
-      const id = parseInt(rawId, 10);
-
-      // Validate the parsed ID
-      if (isNaN(id)) {
-        errorLog(`Invalid ID value "${rawId}" in ${filePath} - not a valid number`);
-        continue;
-      }
-
-      if (id < 0) {
-        errorLog(`Invalid ID value ${id} in ${filePath} - ID must be non-negative`);
-        continue;
-      }
-
-      if (id > Number.MAX_SAFE_INTEGER) {
-        errorLog(`Invalid ID value ${id} in ${filePath} - ID exceeds maximum safe integer`);
-        continue;
-      }
-
-      debugLog(`Successfully extracted ID ${id} from ${filePath}`);
-      return id;
-    } else {
-      debugLog(`Pattern ${i + 1} did not match in ${filePath}`);
-    }
-  }
-
-  // If no patterns matched, try to identify common issues
-  debugLog(`All patterns failed for ${filePath}. Analyzing frontmatter for common issues...`);
-
-  // Check for 'id' field existence (case-insensitive)
-  const hasIdField = /^\s*["']?id["']?\s*:/mi.test(frontmatterText);
-  if (!hasIdField) {
-    debugLog(`No 'id' field found in frontmatter of ${filePath}`);
-  } else {
-    // ID field exists but didn't match - might be malformed
-    const idLineMatch = frontmatterText.match(/^\s*["']?id["']?\s*:.*$/mi);
-    if (idLineMatch) {
-      const idLine = idLineMatch[0].trim();
-      errorLog(`Found malformed ID line in ${filePath}: "${idLine}"`);
-
-      // Check for common formatting issues
-      if (idLine.includes('null') || idLine.includes('undefined')) {
-        errorLog(`ID field has null/undefined value in ${filePath}`);
-      } else if (idLine.match(/:\s*$/)) {
-        errorLog(`ID field has missing value in ${filePath}`);
-      } else if (idLine.includes('[') || idLine.includes('{')) {
-        errorLog(`ID field appears to be array/object instead of number in ${filePath}`);
-      } else {
-        errorLog(`ID field has unrecognized format in ${filePath}`);
-      }
-    }
-  }
-
-  errorLog(`Failed to extract ID from frontmatter in ${filePath}`);
-  return null;
-}
-
 /**
  * Get the next available plan ID by scanning existing plan files
  * @returns {number} Next available plan ID
@@ -251,181 +31,56 @@ function getNextPlanId() {
     process.exit(1);
   }
 
-  debugLog(`Task manager root found: ${taskManagerRoot}`);
-
   const plansDir = path.join(taskManagerRoot, 'plans');
   const archiveDir = path.join(taskManagerRoot, 'archive');
 
-  debugLog(`Scanning directories: ${plansDir}, ${archiveDir}`);
-
   let maxId = 0;
-  let filesScanned = 0;
-  let errorsEncountered = 0;
 
   // Scan both plans and archive directories
   [plansDir, archiveDir].forEach(dir => {
-    const dirName = path.basename(dir);
-    debugLog(`Scanning directory: ${dir}`);
-
     if (!fs.existsSync(dir)) {
-      debugLog(`Directory does not exist: ${dir}`);
       return;
     }
 
     try {
       const entries = fs.readdirSync(dir, { withFileTypes: true });
-      debugLog(`Found ${entries.length} entries in ${dir}`);
 
       entries.forEach(entry => {
         if (entry.isDirectory() && entry.name.match(/^\d+--/)) {
           // This is a plan directory, look for plan files inside
           const planDirPath = path.join(dir, entry.name);
-          debugLog(`Scanning plan directory: ${planDirPath}`);
 
           try {
             const planDirEntries = fs.readdirSync(planDirPath, { withFileTypes: true });
 
             planDirEntries.forEach(planEntry => {
               if (planEntry.isFile() && planEntry.name.match(/^plan-\d+--.*\.md$/)) {
-                filesScanned++;
                 const filePath = path.join(planDirPath, planEntry.name);
-                debugLog(`Processing plan file: ${filePath}`);
-
-                // Extract ID from directory name as primary source
-                const dirMatch = entry.name.match(/^(\d+)--/);
-                let dirId = null;
-                if (dirMatch) {
-                  dirId = parseInt(dirMatch[1], 10);
-                  if (!isNaN(dirId)) {
-                    debugLog(`Extracted ID ${dirId} from directory name: ${entry.name}`);
-                    if (dirId > maxId) {
-                      maxId = dirId;
-                      debugLog(`New max ID from directory name: ${maxId}`);
-                    }
-                  }
-                }
 
-                // Extract ID from filename as secondary source
-                const filenameMatch = planEntry.name.match(/^plan-(\d+)--/);
-                let filenameId = null;
-                if (filenameMatch) {
-                  filenameId = parseInt(filenameMatch[1], 10);
-                  if (!isNaN(filenameId)) {
-                    debugLog(`Extracted ID ${filenameId} from filename: ${planEntry.name}`);
-                    if (filenameId > maxId) {
-                      maxId = filenameId;
-                      debugLog(`New max ID from filename: ${maxId}`);
-                    }
-                  }
-                }
-
-                // Also check frontmatter for most reliable ID
                 try {
                   const content = fs.readFileSync(filePath, 'utf8');
                   const frontmatterId = extractIdFromFrontmatter(content, filePath);
 
-                  if (frontmatterId !== null) {
-                    debugLog(`Extracted ID ${frontmatterId} from frontmatter: ${filePath}`);
-                    if (frontmatterId > maxId) {
-                      maxId = frontmatterId;
-                      debugLog(`New max ID from frontmatter: ${maxId}`);
-                    }
-
-                    // Validate consistency between all sources
-                    if (dirId !== null && dirId !== frontmatterId) {
-                      errorLog(`ID mismatch in ${filePath}: directory has ${dirId}, frontmatter has ${frontmatterId}`);
-                      errorsEncountered++;
-                    }
-                    if (filenameId !== null && filenameId !== frontmatterId) {
-                      errorLog(`ID mismatch in ${filePath}: filename has ${filenameId}, frontmatter has ${frontmatterId}`);
-                      errorsEncountered++;
-                    }
-                  } else {
-                    debugLog(`No ID found in frontmatter: ${filePath}`);
-                    if (dirId === null && filenameId === null) {
-                      errorLog(`No valid ID found in directory, filename, or frontmatter: ${filePath}`);
-                      errorsEncountered++;
-                    }
+                  if (frontmatterId !== null && frontmatterId > maxId) {
+                    maxId = frontmatterId;
                   }
                 } catch (err) {
                   errorLog(`Failed to read file ${filePath}: ${err.message}`);
-                  errorsEncountered++;
                 }
               }
             });
           } catch (err) {
             errorLog(`Failed to read plan directory ${planDirPath}: ${err.message}`);
-            errorsEncountered++;
-          }
-        } else if (entry.isFile() && entry.name.match(/^plan-\d+--.*\.md$/)) {
-          // Legacy: direct plan file in plans/archive directory (fallback for old format)
-          filesScanned++;
-          const filePath = path.join(dir, entry.name);
-          debugLog(`Processing legacy plan file: ${filePath}`);
-
-          // Extract ID from filename as fallback
-          const filenameMatch = entry.name.match(/^plan-(\d+)--/);
-          let filenameId = null;
-          if (filenameMatch) {
-            filenameId = parseInt(filenameMatch[1], 10);
-            if (!isNaN(filenameId)) {
-              debugLog(`Extracted ID ${filenameId} from legacy filename: ${entry.name}`);
-              if (filenameId > maxId) {
-                maxId = filenameId;
-                debugLog(`New max ID from legacy filename: ${maxId}`);
-              }
-            }
           }
-
-          // Also check frontmatter for more reliable ID
-          try {
-            const content = fs.readFileSync(filePath, 'utf8');
-            const frontmatterId = extractIdFromFrontmatter(content, filePath);
-
-            if (frontmatterId !== null) {
-              debugLog(`Extracted ID ${frontmatterId} from legacy frontmatter: ${filePath}`);
-              if (frontmatterId > maxId) {
-                maxId = frontmatterId;
-                debugLog(`New max ID from legacy frontmatter: ${maxId}`);
-              }
-
-              // Validate consistency between filename and frontmatter
-              if (filenameId !== null && filenameId !== frontmatterId) {
-                errorLog(`ID mismatch in legacy ${filePath}: filename has ${filenameId}, frontmatter has ${frontmatterId}`);
-                errorsEncountered++;
-              }
-            } else {
-              debugLog(`No ID found in legacy frontmatter: ${filePath}`);
-              if (filenameId === null) {
-                errorLog(`No valid ID found in legacy filename or frontmatter: ${filePath}`);
-                errorsEncountered++;
-              }
-            }
-          } catch (err) {
-            errorLog(`Failed to read legacy file ${filePath}: ${err.message}`);
-            errorsEncountered++;
-          }
-        } else if (entry.isFile() && entry.name.endsWith('.md')) {
-          debugLog(`Skipping non-plan file: ${entry.name}`);
-        } else if (entry.isDirectory()) {
-          debugLog(`Skipping non-plan directory: ${entry.name}`);
         }
       });
     } catch (err) {
       errorLog(`Failed to read directory ${dir}: ${err.message}`);
-      errorsEncountered++;
     }
   });
 
-  const nextId = maxId + 1;
-  debugLog(`Scan complete. Files scanned: ${filesScanned}, Errors: ${errorsEncountered}, Max ID found: ${maxId}, Next ID: ${nextId}`);
-
-  if (errorsEncountered > 0) {
-    errorLog(`Encountered ${errorsEncountered} errors during scan. Next ID calculation may be inaccurate.`);
-  }
-
-  return nextId;
+  return maxId + 1;
 }
 
 // Output the next plan ID
-console.log(getNextPlanId());
+console.log(getNextPlanId());

package/templates/ai-task-manager/config/scripts/get-next-task-id.cjs

@@ -2,67 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-/**
- * Find the task manager root directory by traversing up from CWD
- * @returns {string|null} Path to task manager root or null if not found
- */
-function findTaskManagerRoot() {
-  let currentPath = process.cwd();
-  const root = path.parse(currentPath).root;
-
-  while (currentPath !== root) {
-    const taskManagerPath = path.join(currentPath, '.ai', 'task-manager', 'plans');
-    if (fs.existsSync(taskManagerPath)) {
-      return path.join(currentPath, '.ai', 'task-manager');
-    }
-    currentPath = path.dirname(currentPath);
-  }
-
-  // Check root directory as well
-  const rootTaskManager = path.join(root, '.ai', 'task-manager', 'plans');
-  if (fs.existsSync(rootTaskManager)) {
-    return path.join(root, '.ai', 'task-manager');
-  }
-
-  return null;
-}
-
-/**
- * Parse YAML frontmatter for ID with resilience to different formats
- * @param {string} content - File content
- * @returns {number|null} Extracted ID or null
- */
-function extractIdFromFrontmatter(content) {
-  const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!frontmatterMatch) return null;
-
-  const frontmatterText = frontmatterMatch[1];
-
-  // Handle various YAML formats for id field using regex:
-  // id: 5
-  // id: "5"
-  // id: '5'
-  // "id": 5
-  // 'id': 5
-  // id : 5 (with spaces)
-  const patterns = [
-    /^\s*["']?id["']?\s*:\s*["']?(\d+)["']?\s*$/m,  // Most flexible pattern
-    /^\s*id\s*:\s*(\d+)\s*$/m,                       // Simple numeric
-    /^\s*id\s*:\s*"(\d+)"\s*$/m,                     // Double quoted
-    /^\s*id\s*:\s*'(\d+)'\s*$/m,                     // Single quoted
-  ];
-
-  for (const pattern of patterns) {
-    const match = frontmatterText.match(pattern);
-    if (match) {
-      const id = parseInt(match[1], 10);
-      if (!isNaN(id)) return id;
-    }
-  }
-
-  return null;
-}
+const { findTaskManagerRoot, extractIdFromFrontmatter } = require('./shared-utils.cjs');
 
 /**
  * Get the next available task ID for a specific plan
@@ -157,4 +97,4 @@ function getNextTaskId(planId) {
 
 // Get plan ID from command line argument
 const planId = process.argv[2];
-console.log(getNextTaskId(planId));
+console.log(getNextTaskId(planId));

package/templates/ai-task-manager/config/scripts/shared-utils.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find the task manager root directory by traversing up from current working directory
+ * @returns {string|null} Path to task manager root or null if not found
+ */
+function findTaskManagerRoot() {
+  let currentPath = process.cwd();
+  const filesystemRoot = path.parse(currentPath).root;
+
+  // Traverse upward through parent directories until we reach the filesystem root
+  while (currentPath !== filesystemRoot) {
+    const taskManagerPlansPath = path.join(currentPath, '.ai', 'task-manager', 'plans');
+
+    try {
+      // Check if this is a valid task manager directory
+      if (fs.existsSync(taskManagerPlansPath)) {
+        // Verify it's a directory, not a file
+        const stats = fs.lstatSync(taskManagerPlansPath);
+        if (stats.isDirectory()) {
+          const taskManagerRoot = path.join(currentPath, '.ai', 'task-manager');
+          return taskManagerRoot;
+        }
+      }
+    } catch (err) {
+      // Handle permission errors or other filesystem issues gracefully
+      // Continue searching in parent directories
+      if (err.code === 'EPERM' || err.code === 'EACCES') {
+        // Silently continue - permission errors are expected in some directories
+      }
+    }
+
+    // Move up to parent directory
+    const parentPath = path.dirname(currentPath);
+
+    // Safety check: if path.dirname returns the same path, we've reached the root
+    if (parentPath === currentPath) {
+      break;
+    }
+
+    currentPath = parentPath;
+  }
+
+  // Check the filesystem root as the final attempt
+  try {
+    const rootTaskManagerPlans = path.join(filesystemRoot, '.ai', 'task-manager', 'plans');
+    if (fs.existsSync(rootTaskManagerPlans)) {
+      const stats = fs.lstatSync(rootTaskManagerPlans);
+      if (stats.isDirectory()) {
+        const taskManagerRoot = path.join(filesystemRoot, '.ai', 'task-manager');
+        return taskManagerRoot;
+      }
+    }
+  } catch (err) {
+    // Silently continue
+  }
+
+  return null;
+}
+
+/**
+ * Parse YAML frontmatter for ID
+ * @param {string} content - File content
+ * @param {string} [filePath] - Optional file path for error context
+ * @returns {number|null} Extracted ID or null
+ */
+function extractIdFromFrontmatter(content, filePath = 'unknown') {
+  // Check for frontmatter block existence
+  const frontmatterMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) {
+    return null;
+  }
+
+  const frontmatterText = frontmatterMatch[1];
+
+  // Enhanced patterns to handle various YAML formats:
+  // - id: 5                    (simple numeric)
+  // - id: "5"                  (double quoted)
+  // - id: '5'                  (single quoted)
+  // - "id": 5                  (quoted key)
+  // - 'id': 5                  (single quoted key)
+  // - id : 5                   (extra spaces)
+  // - id: 05                   (zero-padded)
+  // - id: +5                   (explicit positive)
+  // - Mixed quotes: 'id': "5"  (different quote types)
+  const patterns = [
+    // Most flexible pattern - handles quoted/unquoted keys and values with optional spaces
+    /^\s*["']?id["']?\s*:\s*["']?([+-]?\d+)["']?\s*(?:#.*)?$/mi,
+    // Simple numeric with optional whitespace and comments
+    /^\s*id\s*:\s*([+-]?\d+)\s*(?:#.*)?$/mi,
+    // Double quoted values
+    /^\s*["']?id["']?\s*:\s*"([+-]?\d+)"\s*(?:#.*)?$/mi,
+    // Single quoted values
+    /^\s*["']?id["']?\s*:\s*'([+-]?\d+)'\s*(?:#.*)?$/mi,
+    // Mixed quotes - quoted key, unquoted value
+    /^\s*["']id["']\s*:\s*([+-]?\d+)\s*(?:#.*)?$/mi,
+    // YAML-style with pipe or greater-than indicators (edge case)
+    /^\s*id\s*:\s*[|>]\s*([+-]?\d+)\s*$/mi
+  ];
+
+  // Try each pattern in order
+  for (const regex of patterns) {
+    const match = frontmatterText.match(regex);
+    if (match) {
+      const rawId = match[1];
+      const id = parseInt(rawId, 10);
+
+      // Validate the parsed ID
+      if (isNaN(id)) {
+        console.error(`[ERROR] Invalid ID value "${rawId}" in ${filePath} - not a valid number`);
+        continue;
+      }
+
+      if (id < 0) {
+        console.error(`[ERROR] Invalid ID value ${id} in ${filePath} - ID must be non-negative`);
+        continue;
+      }
+
+      if (id > Number.MAX_SAFE_INTEGER) {
+        console.error(`[ERROR] Invalid ID value ${id} in ${filePath} - ID exceeds maximum safe integer`);
+        continue;
+      }
+
+      return id;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns the frontmatter text as a string (not parsed as YAML)
+ * @param {string} content - The markdown content with frontmatter
+ * @returns {string} Frontmatter text or empty string if not found
+ */
+function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  let inFrontmatter = false;
+  let frontmatterEnd = false;
+  let delimiterCount = 0;
+  const frontmatterLines = [];
+
+  for (const line of lines) {
+    if (line.trim() === '---') {
+      delimiterCount++;
+      if (delimiterCount === 1) {
+        inFrontmatter = true;
+        continue;
+      } else if (delimiterCount === 2) {
+        frontmatterEnd = true;
+        break;
+      }
+    }
+
+    if (inFrontmatter && !frontmatterEnd) {
+      frontmatterLines.push(line);
+    }
+  }
+
+  return frontmatterLines.join('\n');
+}
+
+module.exports = {
+  findTaskManagerRoot,
+  extractIdFromFrontmatter,
+  parseFrontmatter
+};

package/templates/ai-task-manager/config/scripts/validate-plan-blueprint.cjs

@@ -2,20 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-// Enable debug logging via environment variable
-const DEBUG = process.env.DEBUG === 'true';
-
-/**
- * Debug logging utility
- * @param {string} message - Debug message
- * @param {...any} args - Additional arguments to log
- */
-function debugLog(message, ...args) {
-  if (DEBUG) {
-    console.error(`[DEBUG] ${message}`, ...args);
-  }
-}
+const { findTaskManagerRoot } = require('./shared-utils.cjs');
 
 /**
  * Error logging utility
@@ -26,59 +13,6 @@ function errorLog(message, ...args) {
   console.error(`[ERROR] ${message}`, ...args);
 }
 
-/**
- * Find the task manager root directory by traversing up from current working directory
- * @returns {string|null} Path to task manager root or null if not found
- */
-function findTaskManagerRoot() {
-  let currentPath = process.cwd();
-  const filesystemRoot = path.parse(currentPath).root;
-
-  debugLog(`Starting search for task manager root from: ${currentPath}`);
-  debugLog(`Filesystem root: ${filesystemRoot}`);
-
-  while (currentPath !== filesystemRoot) {
-    const taskManagerPlansPath = path.join(currentPath, '.ai', 'task-manager', 'plans');
-    debugLog(`Checking for task manager at: ${taskManagerPlansPath}`);
-
-    try {
-      if (fs.existsSync(taskManagerPlansPath)) {
-        const stats = fs.lstatSync(taskManagerPlansPath);
-        if (stats.isDirectory()) {
-          const taskManagerRoot = path.join(currentPath, '.ai', 'task-manager');
-          debugLog(`Found valid task manager root at: ${taskManagerRoot}`);
-          return taskManagerRoot;
-        } else {
-          debugLog(`Path exists but is not a directory: ${taskManagerPlansPath}`);
-        }
-      } else {
-        debugLog(`Task manager path does not exist: ${taskManagerPlansPath}`);
-      }
-    } catch (err) {
-      if (err.code === 'EPERM' || err.code === 'EACCES') {
-        const warningMsg = `Warning: Permission denied accessing ${taskManagerPlansPath}`;
-        console.warn(warningMsg);
-        debugLog(`Permission error: ${err.message}`);
-      } else {
-        debugLog(`Filesystem error checking ${taskManagerPlansPath}: ${err.message}`);
-      }
-    }
-
-    const parentPath = path.dirname(currentPath);
-
-    if (parentPath === currentPath) {
-      debugLog(`Reached filesystem root, stopping traversal`);
-      break;
-    }
-
-    currentPath = parentPath;
-    debugLog(`Moving up to parent directory: ${currentPath}`);
-  }
-
-  debugLog(`Task manager root not found in any parent directory`);
-  return null;
-}
-
 /**
  * Find plan file and directory for a given plan ID
  * @param {string|number} planId - Plan ID to search for
@@ -92,8 +26,6 @@ function findPlanById(planId) {
     return null;
   }
 
-  debugLog(`Task manager root found: ${taskManagerRoot}`);
-
   // Convert planId to numeric for flexible matching (handles both "2" and "02")
   const numericPlanId = parseInt(planId, 10);
 
@@ -102,23 +34,17 @@ function findPlanById(planId) {
     return null;
   }
 
-  debugLog(`Searching for plan with numeric ID: ${numericPlanId} (input was: ${planId})`);
-
   const plansDir = path.join(taskManagerRoot, 'plans');
   const archiveDir = path.join(taskManagerRoot, 'archive');
 
-  debugLog(`Searching for plan ID ${planId} in: ${plansDir}, ${archiveDir}`);
-
   // Search both plans and archive directories
   for (const dir of [plansDir, archiveDir]) {
     if (!fs.existsSync(dir)) {
-      debugLog(`Directory does not exist: ${dir}`);
       continue;
     }
 
     try {
       const entries = fs.readdirSync(dir, { withFileTypes: true });
-      debugLog(`Found ${entries.length} entries in ${dir}`);
 
       for (const entry of entries) {
         // Match directory pattern: [plan-id]--* (with flexible ID matching)
@@ -127,7 +53,6 @@ function findPlanById(planId) {
           const dirMatch = entry.name.match(/^0*(\d+)--/);
           if (dirMatch && parseInt(dirMatch[1], 10) === numericPlanId) {
             const planDirPath = path.join(dir, entry.name);
-            debugLog(`Found matching plan directory: ${planDirPath} (extracted ID: ${dirMatch[1]} matches input: ${numericPlanId})`);
 
           try {
             const planDirEntries = fs.readdirSync(planDirPath, { withFileTypes: true });
@@ -139,7 +64,6 @@ function findPlanById(planId) {
                 const fileMatch = planEntry.name.match(/^plan-0*(\d+)--.*\.md$/);
                 if (fileMatch && parseInt(fileMatch[1], 10) === numericPlanId) {
                   const planFilePath = path.join(planDirPath, planEntry.name);
-                  debugLog(`Found plan file: ${planFilePath} (extracted ID: ${fileMatch[1]} matches input: ${numericPlanId})`);
 
                   return {
                     planFile: planFilePath,
@@ -148,8 +72,6 @@ function findPlanById(planId) {
                 }
               }
             }
-
-            debugLog(`No plan file found in directory: ${planDirPath}`);
           } catch (err) {
             errorLog(`Failed to read plan directory ${planDirPath}: ${err.message}`);
           }
@@ -161,7 +83,6 @@ function findPlanById(planId) {
     }
   }
 
-  debugLog(`Plan ID ${planId} not found in any directory`);
   return null;
 }
 
@@ -174,19 +95,16 @@ function countTasks(planDir) {
   const tasksDir = path.join(planDir, 'tasks');
 
   if (!fs.existsSync(tasksDir)) {
-    debugLog(`Tasks directory does not exist: ${tasksDir}`);
     return 0;
   }
 
   try {
     const stats = fs.lstatSync(tasksDir);
     if (!stats.isDirectory()) {
-      debugLog(`Tasks path exists but is not a directory: ${tasksDir}`);
       return 0;
     }
 
     const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
-    debugLog(`Found ${files.length} task files in ${tasksDir}`);
     return files.length;
   } catch (err) {
     errorLog(`Failed to read tasks directory ${tasksDir}: ${err.message}`);
@@ -203,7 +121,6 @@ function checkBlueprintExists(planFile) {
   try {
     const planContent = fs.readFileSync(planFile, 'utf8');
     const blueprintExists = /^## Execution Blueprint/m.test(planContent);
-    debugLog(`Blueprint section ${blueprintExists ? 'found' : 'not found'} in ${planFile}`);
     return blueprintExists;
   } catch (err) {
     errorLog(`Failed to read plan file ${planFile}: ${err.message}`);
@@ -270,8 +187,6 @@ function validatePlanBlueprint(planId, fieldName) {
     process.exit(1);
   }
 
-  debugLog(`Validating plan blueprint for ID: ${planId}`);
-
   const planInfo = findPlanById(planId);
 
   if (!planInfo) {
@@ -308,8 +223,6 @@ function validatePlanBlueprint(planId, fieldName) {
     blueprintExists: blueprintExists ? 'yes' : 'no'
   };
 
-  debugLog('Validation complete:', result);
-
   // If field name is provided, output just that field
   if (fieldName) {
     const validFields = ['planFile', 'planDir', 'taskCount', 'blueprintExists'];

package/templates/ai-task-manager/config/templates/PLAN_TEMPLATE.md

@@ -74,6 +74,10 @@ Example:
 2. [Measurable outcome 2]
 3. [Measurable outcome 3]
 
+## Documentation
+
+[Required documentation updates to existing documentation, either human-focused documentation, the project's README.md or assistant-focused documentation like AGENTS.md, .claude/skills/* for the site, etc.]
+
 ## Resource Requirements
 
 ### Development Skills