agileflow 3.1.0 → 3.2.0

package/scripts/lib/portable-tasks.js

@@ -0,0 +1,479 @@
+/**
+ * portable-tasks.js - File-based task tracking for all IDEs
+ *
+ * Provides a portable, markdown-based task tracking system that works across
+ * all IDEs (Claude Code, Cursor, Windsurf, Codex). Unlike Claude Code's native
+ * TaskCreate/TaskUpdate tools, this system stores tasks in .agileflow/tasks.md
+ * where ANY IDE's AI can read/write.
+ *
+ * File Format (.agileflow/tasks.md):
+ * ```markdown
+ * # AgileFlow Tasks
+ *
+ * > Auto-managed task list. Edit carefully - format matters.
+ * > Last updated: 2026-02-20T15:30:00Z
+ *
+ * ## Active Tasks
+ *
+ * ### T-001: Task title [in_progress]
+ * - **Owner**: AG-API
+ * - **Created**: 2026-02-20
+ * - **Story**: US-0042
+ * - **Description**: Task details here
+ *
+ * ## Completed Tasks
+ *
+ * ### T-002: Completed task [completed]
+ * - **Owner**: AG-CI
+ * - **Created**: 2026-02-20
+ * - **Completed**: 2026-02-21
+ * ```
+ *
+ * Status values: pending, in_progress, completed, blocked
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGILEFLOW_DIR = '.agileflow';
+const TASKS_FILE = 'tasks.md';
+const TASKS_PATH = path.join(AGILEFLOW_DIR, TASKS_FILE);
+
+const STATUS_ACTIVE = ['pending', 'in_progress', 'blocked'];
+const STATUS_COMPLETED = ['completed'];
+const VALID_STATUSES = ['pending', 'in_progress', 'completed', 'blocked'];
+
+/**
+ * Parse the tasks markdown file into structured data
+ * @param {string} content - Raw markdown file content
+ * @returns {Object} { activeTasks: [], completedTasks: [] } where each task is { id, title, status, owner, created, completed, story, blockedBy, description }
+ */
+function parseTasksFile(content) {
+  const activeTasks = [];
+  const completedTasks = [];
+
+  if (!content || content.trim() === '') {
+    return { activeTasks, completedTasks };
+  }
+
+  const lines = content.split('\n');
+  let currentSection = null; // 'active' or 'completed'
+  let currentTask = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect section headers (must be before generic # check)
+    if (line.startsWith('## Active Tasks')) {
+      currentSection = 'active';
+      continue;
+    }
+    if (line.startsWith('## Completed Tasks')) {
+      currentSection = 'completed';
+      continue;
+    }
+
+    // Parse task headers: ### T-001: Title [status] (must be before generic # check)
+    const taskHeaderMatch = line.match(/^### (T-\d+):\s+(.+?)\s+\[(\w+)\]$/);
+    if (taskHeaderMatch) {
+      // Save previous task to appropriate list based on its status
+      if (currentTask) {
+        if (currentTask.status === 'completed') {
+          completedTasks.push(currentTask);
+        } else {
+          // All non-completed statuses go to active (pending, in_progress, blocked)
+          activeTasks.push(currentTask);
+        }
+      }
+
+      // Start new task
+      currentTask = {
+        id: taskHeaderMatch[1],
+        title: taskHeaderMatch[2].trim(),
+        status: taskHeaderMatch[3],
+        owner: null,
+        created: null,
+        completed: null,
+        story: null,
+        blockedBy: null,
+        description: null,
+      };
+      continue;
+    }
+
+    // Skip non-task lines (after checking for task headers and section headers)
+    if (!line.trim() || line.startsWith('>') || line.startsWith('#')) {
+      continue;
+    }
+
+    // Parse task fields: - **Field**: Value or - **Field name**: Value
+    if (currentTask && line.startsWith('- ')) {
+      const fieldMatch = line.match(/^- \*\*([^*]+)\*\*:\s+(.+)$/);
+      if (fieldMatch) {
+        const fieldName = fieldMatch[1].toLowerCase().trim();
+        const fieldValue = fieldMatch[2].trim();
+
+        switch (fieldName) {
+          case 'owner':
+            currentTask.owner = fieldValue;
+            break;
+          case 'created':
+            currentTask.created = fieldValue;
+            break;
+          case 'completed':
+            currentTask.completed = fieldValue;
+            break;
+          case 'story':
+            currentTask.story = fieldValue;
+            break;
+          case 'blockedby':
+          case 'blocked by':
+            currentTask.blockedBy = fieldValue;
+            break;
+          case 'description':
+            currentTask.description = fieldValue;
+            break;
+        }
+      }
+    }
+  }
+
+  // Save last task based on its status
+  if (currentTask) {
+    if (currentTask.status === 'completed') {
+      completedTasks.push(currentTask);
+    } else {
+      activeTasks.push(currentTask);
+    }
+  }
+
+  return { activeTasks, completedTasks };
+}
+
+/**
+ * Convert structured tasks back to markdown format
+ * @param {Array} activeTasks - Active task objects
+ * @param {Array} completedTasks - Completed task objects
+ * @returns {string} Formatted markdown content
+ */
+/**
+ * Sanitize a string value to prevent markdown injection.
+ * Strips newlines and markdown heading markers that could create fake entries.
+ * @param {string} value - Raw string value
+ * @returns {string} Sanitized value safe for single-line markdown fields
+ */
+function sanitizeField(value) {
+  if (!value || typeof value !== 'string') return value;
+  return value
+    .replace(/[\n\r]/g, ' ')
+    .replace(/#{2,}/g, '')
+    .trim();
+}
+
+function formatTasksFile(activeTasks, completedTasks) {
+  const now = new Date().toISOString();
+  let content = `# AgileFlow Tasks
+
+> Auto-managed task list. Edit carefully - format matters.
+> Last updated: ${now}
+
+`;
+
+  // Active tasks section
+  if (activeTasks.length > 0) {
+    content += '## Active Tasks\n\n';
+    for (const task of activeTasks) {
+      content += `### ${task.id}: ${sanitizeField(task.title)} [${task.status}]\n`;
+      if (task.owner) content += `- **Owner**: ${sanitizeField(task.owner)}\n`;
+      if (task.created) content += `- **Created**: ${task.created}\n`;
+      if (task.story) content += `- **Story**: ${sanitizeField(task.story)}\n`;
+      if (task.blockedBy) content += `- **Blocked by**: ${sanitizeField(task.blockedBy)}\n`;
+      if (task.description) content += `- **Description**: ${sanitizeField(task.description)}\n`;
+      content += '\n';
+    }
+  }
+
+  // Completed tasks section
+  if (completedTasks.length > 0) {
+    content += '## Completed Tasks\n\n';
+    for (const task of completedTasks) {
+      content += `### ${task.id}: ${sanitizeField(task.title)} [${task.status}]\n`;
+      if (task.owner) content += `- **Owner**: ${sanitizeField(task.owner)}\n`;
+      if (task.created) content += `- **Created**: ${task.created}\n`;
+      if (task.completed) content += `- **Completed**: ${task.completed}\n`;
+      if (task.story) content += `- **Story**: ${sanitizeField(task.story)}\n`;
+      if (task.description) content += `- **Description**: ${sanitizeField(task.description)}\n`;
+      content += '\n';
+    }
+  }
+
+  return content;
+}
+
+/**
+ * Load and parse tasks from .agileflow/tasks.md
+ * @param {string} projectDir - Project directory (where .agileflow/ is located)
+ * @returns {Object} { activeTasks: [], completedTasks: [] }
+ */
+function loadTasks(projectDir) {
+  const tasksPath = path.join(projectDir, TASKS_PATH);
+
+  try {
+    if (!fs.existsSync(tasksPath)) {
+      return { activeTasks: [], completedTasks: [] };
+    }
+
+    const content = fs.readFileSync(tasksPath, 'utf8');
+    return parseTasksFile(content);
+  } catch (e) {
+    // Return empty if read fails
+    return { activeTasks: [], completedTasks: [] };
+  }
+}
+
+/**
+ * Save tasks back to .agileflow/tasks.md
+ * @param {string} projectDir - Project directory
+ * @param {Object} tasksData - { activeTasks: [], completedTasks: [] }
+ * @returns {boolean} True if successful
+ */
+function saveTasks(projectDir, tasksData) {
+  try {
+    const agileflowDir = path.join(projectDir, AGILEFLOW_DIR);
+    const tasksPath = path.join(projectDir, TASKS_PATH);
+
+    // Ensure .agileflow directory exists
+    if (!fs.existsSync(agileflowDir)) {
+      fs.mkdirSync(agileflowDir, { recursive: true });
+    }
+
+    const content = formatTasksFile(tasksData.activeTasks, tasksData.completedTasks);
+    fs.writeFileSync(tasksPath, content, 'utf8');
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Get the next sequential task ID
+ * @param {Array} allTasks - Array of all tasks (active + completed)
+ * @returns {string} Next ID like T-001, T-002, etc.
+ */
+function getNextId(allTasks) {
+  if (!allTasks || allTasks.length === 0) {
+    return 'T-001';
+  }
+
+  // Extract numeric parts from task IDs
+  const numbers = allTasks.map(t => parseInt(t.id.replace('T-', ''), 10)).filter(n => !isNaN(n));
+
+  if (numbers.length === 0) {
+    return 'T-001';
+  }
+
+  const maxNum = Math.max(...numbers);
+  return `T-${String(maxNum + 1).padStart(3, '0')}`;
+}
+
+/**
+ * Add a new task
+ * @param {string} projectDir - Project directory
+ * @param {Object} task - { subject, description, status, owner, story, blockedBy }
+ * @returns {Object} { ok: boolean, taskId?: string, error?: string }
+ */
+function addTask(projectDir, task) {
+  try {
+    const { activeTasks, completedTasks } = loadTasks(projectDir);
+    const allTasks = [...activeTasks, ...completedTasks];
+
+    const taskId = getNextId(allTasks);
+    const today = new Date().toISOString().split('T')[0];
+
+    const newTask = {
+      id: taskId,
+      title: task.subject || 'Untitled',
+      status: task.status || 'pending',
+      owner: task.owner || null,
+      created: task.created || today,
+      completed: null,
+      story: task.story || null,
+      blockedBy: task.blockedBy || null,
+      description: task.description || null,
+    };
+
+    // Validate status
+    if (!VALID_STATUSES.includes(newTask.status)) {
+      return { ok: false, error: `Invalid status: ${newTask.status}` };
+    }
+
+    // Add to appropriate section
+    const newActiveTasks = newTask.status === 'completed' ? activeTasks : [...activeTasks, newTask];
+    const newCompletedTasks =
+      newTask.status === 'completed' ? [...completedTasks, newTask] : completedTasks;
+
+    if (
+      !saveTasks(projectDir, { activeTasks: newActiveTasks, completedTasks: newCompletedTasks })
+    ) {
+      return { ok: false, error: 'Failed to save tasks file' };
+    }
+
+    return { ok: true, taskId };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Update a task
+ * @param {string} projectDir - Project directory
+ * @param {string} taskId - Task ID like T-001
+ * @param {Object} updates - Fields to update { status, owner, description, etc. }
+ * @returns {Object} { ok: boolean, error?: string }
+ */
+function updateTask(projectDir, taskId, updates) {
+  try {
+    let { activeTasks, completedTasks } = loadTasks(projectDir);
+
+    // Find task in either list
+    let task = activeTasks.find(t => t.id === taskId);
+    let isInActive = !!task;
+
+    if (!task) {
+      task = completedTasks.find(t => t.id === taskId);
+      if (!task) {
+        return { ok: false, error: `Task ${taskId} not found` };
+      }
+    }
+
+    // Update fields
+    if (updates.status) {
+      if (!VALID_STATUSES.includes(updates.status)) {
+        return { ok: false, error: `Invalid status: ${updates.status}` };
+      }
+      task.status = updates.status;
+    }
+    if (updates.owner !== undefined) task.owner = updates.owner;
+    if (updates.description !== undefined) task.description = updates.description;
+    if (updates.title !== undefined) task.title = updates.title;
+    if (updates.story !== undefined) task.story = updates.story;
+    if (updates.blockedBy !== undefined) task.blockedBy = updates.blockedBy;
+    if (updates.completed !== undefined) task.completed = updates.completed;
+
+    // Move between sections if status changed
+    if (updates.status) {
+      const wasCompleted = !isInActive;
+      const isNowCompleted = updates.status === 'completed';
+
+      if (wasCompleted && !isNowCompleted) {
+        // Move from completed to active
+        completedTasks = completedTasks.filter(t => t.id !== taskId);
+        activeTasks.push(task);
+      } else if (!wasCompleted && isNowCompleted) {
+        // Move from active to completed
+        activeTasks = activeTasks.filter(t => t.id !== taskId);
+        // Set completion date if not already set
+        if (!task.completed) {
+          task.completed = new Date().toISOString().split('T')[0];
+        }
+        completedTasks.push(task);
+      }
+    }
+
+    if (!saveTasks(projectDir, { activeTasks, completedTasks })) {
+      return { ok: false, error: 'Failed to save tasks file' };
+    }
+
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Delete a task
+ * @param {string} projectDir - Project directory
+ * @param {string} taskId - Task ID like T-001
+ * @returns {Object} { ok: boolean, error?: string }
+ */
+function deleteTask(projectDir, taskId) {
+  try {
+    let { activeTasks, completedTasks } = loadTasks(projectDir);
+
+    const foundInActive = activeTasks.some(t => t.id === taskId);
+    const foundInCompleted = completedTasks.some(t => t.id === taskId);
+
+    if (!foundInActive && !foundInCompleted) {
+      return { ok: false, error: `Task ${taskId} not found` };
+    }
+
+    activeTasks = activeTasks.filter(t => t.id !== taskId);
+    completedTasks = completedTasks.filter(t => t.id !== taskId);
+
+    if (!saveTasks(projectDir, { activeTasks, completedTasks })) {
+      return { ok: false, error: 'Failed to save tasks file' };
+    }
+
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Get a single task by ID
+ * @param {string} projectDir - Project directory
+ * @param {string} taskId - Task ID like T-001
+ * @returns {Object|null} Task object or null if not found
+ */
+function getTask(projectDir, taskId) {
+  const { activeTasks, completedTasks } = loadTasks(projectDir);
+
+  const task = activeTasks.find(t => t.id === taskId) || completedTasks.find(t => t.id === taskId);
+  return task || null;
+}
+
+/**
+ * List tasks with optional filtering
+ * @param {string} projectDir - Project directory
+ * @param {Object} filters - { status, owner, includeCompleted } - defaults to active only
+ * @returns {Array} Array of task objects
+ */
+function listTasks(projectDir, filters = {}) {
+  const { activeTasks, completedTasks } = loadTasks(projectDir);
+
+  let tasks = [...activeTasks];
+  if (filters.includeCompleted === true) {
+    tasks = [...activeTasks, ...completedTasks];
+  }
+
+  // Filter by status
+  if (filters.status) {
+    const statuses = Array.isArray(filters.status) ? filters.status : [filters.status];
+    tasks = tasks.filter(t => statuses.includes(t.status));
+  } else if (filters.includeCompleted !== true) {
+    // Default: show only active statuses
+    tasks = tasks.filter(t => STATUS_ACTIVE.includes(t.status));
+  }
+
+  // Filter by owner
+  if (filters.owner) {
+    tasks = tasks.filter(t => t.owner === filters.owner);
+  }
+
+  return tasks;
+}
+
+module.exports = {
+  loadTasks,
+  saveTasks,
+  addTask,
+  updateTask,
+  deleteTask,
+  getTask,
+  listTasks,
+  getNextId,
+  parseTasksFile,
+  formatTasksFile,
+  sanitizeField,
+};

package/scripts/lib/signal-detectors.js

@@ -546,7 +546,7 @@ const FEATURE_DETECTORS = {
       priority: 'medium',
       trigger: `${coreFiles} source files modified - logic audit available`,
       action: 'offer',
-      command: '/agileflow:logic:audit',
+      command: '/agileflow:audit:logic',
       phase: 'post-impl',
     });
   },

package/scripts/lib/team-events.js

@@ -80,8 +80,62 @@ const EVENT_TYPES = [
   'gate_passed',
   'gate_failed',
   'model_usage',
+  'cost_warning',
 ];
 
+/**
+ * Model pricing per million tokens (USD).
+ * Includes both shorthand aliases and full model IDs.
+ */
+const MODEL_PRICING = {
+  haiku: { input: 0.8, output: 4.0 },
+  sonnet: { input: 3.0, output: 15.0 },
+  opus: { input: 15.0, output: 75.0 },
+  'claude-haiku-4-5-20251001': { input: 0.8, output: 4.0 },
+  'claude-sonnet-4-6': { input: 3.0, output: 15.0 },
+  'claude-opus-4-6': { input: 15.0, output: 75.0 },
+};
+
+const DEFAULT_COST_THRESHOLD_USD = 5.0;
+
+/**
+ * Compute estimated cost for an agent's token usage.
+ *
+ * @param {number} inputTokens - Number of input tokens
+ * @param {number} outputTokens - Number of output tokens
+ * @param {string} [model='haiku'] - Model name or alias
+ * @returns {number} Estimated cost in USD (6 decimal places)
+ */
+function computeAgentCost(inputTokens, outputTokens, model) {
+  const pricing = MODEL_PRICING[model] || MODEL_PRICING['haiku'];
+  const inputCost = (inputTokens / 1_000_000) * pricing.input;
+  const outputCost = (outputTokens / 1_000_000) * pricing.output;
+  return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+}
+
+/**
+ * Check if team cost exceeds threshold and emit warning event.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {string} traceId - Trace ID for the team run
+ * @param {number} totalCostUsd - Total cost in USD
+ * @param {number} [threshold] - Cost threshold in USD (default: DEFAULT_COST_THRESHOLD_USD)
+ * @returns {boolean} True if threshold was exceeded
+ */
+function checkCostThreshold(rootDir, traceId, totalCostUsd, threshold) {
+  const limit = threshold || DEFAULT_COST_THRESHOLD_USD;
+  if (totalCostUsd > limit) {
+    trackEvent(rootDir, 'cost_warning', {
+      trace_id: traceId,
+      total_cost_usd: totalCostUsd,
+      threshold_usd: limit,
+      message: `Team cost $${totalCostUsd.toFixed(4)} exceeds threshold $${limit.toFixed(2)}`,
+    });
+    return true;
+  }
+  return false;
+}
+
 /**
  * Track an agent teams event.
  *
@@ -232,15 +286,29 @@ function aggregateTeamMetrics(rootDir, traceId) {
   const perAgent = {};
   const ensureAgent = agent => {
     if (!perAgent[agent]) {
-      perAgent[agent] = { total_duration_ms: 0, tasks_completed: 0, errors: 0, timeouts: 0 };
+      perAgent[agent] = {
+        total_duration_ms: 0,
+        tasks_completed: 0,
+        errors: 0,
+        timeouts: 0,
+        input_tokens: 0,
+        output_tokens: 0,
+        cost_usd: 0,
+      };
     }
   };
 
+  // Track model per agent for cost computation
+  const agentModels = {};
+
   for (const e of events) {
     if (e.type === 'task_completed' && e.agent) {
       ensureAgent(e.agent);
       perAgent[e.agent].total_duration_ms += e.duration_ms || 0;
       perAgent[e.agent].tasks_completed++;
+      perAgent[e.agent].input_tokens += e.input_tokens || 0;
+      perAgent[e.agent].output_tokens += e.output_tokens || 0;
+      if (e.model) agentModels[e.agent] = e.model;
     }
     if (e.type === 'agent_error' && e.agent) {
       ensureAgent(e.agent);
@@ -252,6 +320,16 @@ function aggregateTeamMetrics(rootDir, traceId) {
     }
   }
 
+  // Compute per-agent costs
+  for (const [agent, metrics] of Object.entries(perAgent)) {
+    metrics.cost_usd = computeAgentCost(
+      metrics.input_tokens,
+      metrics.output_tokens,
+      agentModels[agent] || 'haiku'
+    );
+  }
+  const totalCostUsd = Object.values(perAgent).reduce((sum, a) => sum + a.cost_usd, 0);
+
   // Per-gate metrics from gate_passed, gate_failed
   const perGate = {};
   for (const e of events) {
@@ -281,6 +359,7 @@ function aggregateTeamMetrics(rootDir, traceId) {
     per_agent: perAgent,
     per_gate: perGate,
     team_completion_ms: teamCompletionMs,
+    total_cost_usd: Math.round(totalCostUsd * 1_000_000) / 1_000_000,
     computed_at: new Date().toISOString(),
   };
 }
@@ -313,6 +392,7 @@ function saveAggregatedMetrics(rootDir, metrics) {
           per_agent: metrics.per_agent,
           per_gate: metrics.per_gate,
           team_completion_ms: metrics.team_completion_ms,
+          total_cost_usd: metrics.total_cost_usd,
           computed_at: metrics.computed_at,
         };
         return state;
@@ -329,6 +409,7 @@ function saveAggregatedMetrics(rootDir, metrics) {
         per_agent: metrics.per_agent,
         per_gate: metrics.per_gate,
         team_completion_ms: metrics.team_completion_ms,
+        total_cost_usd: metrics.total_cost_usd,
         computed_at: metrics.computed_at,
       };
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
@@ -349,9 +430,13 @@ function saveAggregatedMetrics(rootDir, metrics) {
 
 module.exports = {
   EVENT_TYPES,
+  MODEL_PRICING,
+  DEFAULT_COST_THRESHOLD_USD,
   trackEvent,
   getTeamEvents,
   aggregateTeamMetrics,
   saveAggregatedMetrics,
+  computeAgentCost,
+  checkCostThreshold,
   teamMetricsEmitter,
 };

package/scripts/obtain-context.js

@@ -184,20 +184,25 @@ async function main() {
   const metadata = safeReadJSON('docs/00-meta/agileflow-metadata.json');
   const lazyConfig = metadata?.features?.lazyContext;
 
+  // Read context verbosity mode
+  const verbosityMode = metadata?.features?.contextVerbosity?.enabled
+    ? metadata.features.contextVerbosity.mode || 'full'
+    : 'full';
+
   // Determine which sections need full content (US-0093)
   const sectionsToLoad = determineSectionsToLoad(commandName, lazyConfig, isMultiSession);
 
   // Pre-fetch all data in parallel
   const prefetchStart = Date.now();
-  const prefetched = await prefetchAllData({ sectionsToLoad });
+  const prefetched = await prefetchAllData({ sectionsToLoad, verbosityMode });
   const prefetchElapsed = Date.now() - prefetchStart;
   if (prefetchElapsed > 400) {
     process.stderr.write(`Context loaded in ${(prefetchElapsed / 1000).toFixed(1)}s\n`);
   }
 
-  // Run smart detection (contextual feature routing)
+  // Run smart detection (contextual feature routing) - skip in minimal mode
   let smartDetectResults = null;
-  if (smartDetect) {
+  if (smartDetect && verbosityMode !== 'minimal') {
     try {
       smartDetectResults = smartDetect.analyze(prefetched);
       smartDetect.writeRecommendations(smartDetectResults);
@@ -206,8 +211,27 @@ async function main() {
     }
   }
 
+  // Check command prerequisites
+  let prereqResult = null;
+  if (commandName && smartDetect) {
+    try {
+      const { checkCommandPrereqs, loadPrereqConfig } = require('./lib/command-prereqs');
+      const config = loadPrereqConfig();
+      const signals = smartDetect.extractSignals(prefetched);
+      prereqResult = checkCommandPrereqs(commandName, signals, config);
+    } catch {
+      // Fail open - prereq checking is optional
+    }
+  }
+
   // Generate formatted output
-  const formatOptions = { commandName, activeSections, smartDetectResults };
+  const formatOptions = {
+    commandName,
+    activeSections,
+    smartDetectResults,
+    prereqResult,
+    verbosityMode,
+  };
   const summary = generateSummary(prefetched, formatOptions);
   const fullContent = generateFullContent(prefetched, formatOptions);