agileflow 2.99.8 → 3.0.0

package/scripts/lib/story-state-machine.js

@@ -325,7 +325,7 @@ function checkEpicCompletion(statusData, epicId) {
   }
 
   const storyIds = epic.stories || [];
-  const completedStatuses = ['completed', 'done', 'archived'];
+  const completedStatuses = COMPLETED_STATUSES;
   const completed = [];
   const remaining = [];
 

package/scripts/lib/sync-ideation-status.js

@@ -12,6 +12,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { tryOptional } = require('../../lib/errors');
 
 // Paths relative to project root
 const STATUS_PATH = 'docs/09-agents/status.json';
@@ -49,9 +50,7 @@ function saveJSON(filePath, data) {
     fs.renameSync(tempPath, filePath);
     return { ok: true };
   } catch (err) {
-    try {
-      if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
-    } catch {}
+    tryOptional(() => fs.unlinkSync(tempPath), 'cleanup temp');
     return { ok: false, error: `Failed to save ${filePath}: ${err.message}` };
   }
 }

package/scripts/lib/task-registry.js

@@ -332,6 +332,7 @@ class FileLock {
       }
 
       // Try to acquire
+      let fd = null;
       try {
         const dir = path.dirname(this.lockPath);
         if (!fs.existsSync(dir)) {
@@ -339,7 +340,7 @@ class FileLock {
         }
 
         // Use exclusive flag to prevent race
-        const fd = fs.openSync(this.lockPath, 'wx');
+        fd = fs.openSync(this.lockPath, 'wx');
         const lockInfo = {
           pid: process.pid,
           hostname: os.hostname(),
@@ -347,9 +348,14 @@ class FileLock {
         };
         fs.writeSync(fd, JSON.stringify(lockInfo));
         fs.closeSync(fd);
+        fd = null;
         this.held = true;
         return true;
       } catch (e) {
+        // Clean up fd if still open
+        if (fd !== null) {
+          try { fs.closeSync(fd); } catch (_) { /* ignore */ }
+        }
         if (e.code === 'EEXIST') {
           // Another process got the lock
           this._sleep(50);

package/scripts/lib/team-events.js

@@ -0,0 +1,357 @@
+/**
+ * team-events.js - Observability event tracking for Agent Teams
+ *
+ * Captures team lifecycle events and stores them in session-state.json
+ * and the JSONL message bus. Events include:
+ *   - team_created: Team started from template
+ *   - team_stopped: Team shut down
+ *   - task_assigned: Task given to a teammate
+ *   - task_completed: Task finished by a teammate
+ *   - agent_error: Teammate encountered an error
+ *   - agent_timeout: Teammate exceeded time limit
+ *
+ * Usage:
+ *   const { trackEvent, getTeamEvents } = require('./lib/team-events');
+ *
+ *   trackEvent(rootDir, 'task_completed', {
+ *     agent: 'api-builder',
+ *     task_id: 'task_1',
+ *     duration_ms: 5200,
+ *   });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { EventEmitter } = require('events');
+
+/**
+ * Module-level event emitter for cross-module notifications.
+ * Emits 'metrics_saved' after saveAggregatedMetrics() succeeds.
+ */
+const teamMetricsEmitter = new EventEmitter();
+
+// Lazy-load dependencies
+let _fileLock;
+function getFileLock() {
+  if (!_fileLock) {
+    try {
+      _fileLock = require('./file-lock');
+    } catch (e) {
+      _fileLock = null;
+    }
+  }
+  return _fileLock;
+}
+
+let _messagingBridge;
+function getMessagingBridge() {
+  if (!_messagingBridge) {
+    try {
+      _messagingBridge = require('../messaging-bridge');
+    } catch (e) {
+      _messagingBridge = null;
+    }
+  }
+  return _messagingBridge;
+}
+
+let _paths;
+function getPaths() {
+  if (!_paths) {
+    try {
+      _paths = require('../../lib/paths');
+    } catch (e) {
+      _paths = null;
+    }
+  }
+  return _paths;
+}
+
+/**
+ * Valid event types for agent teams
+ */
+const EVENT_TYPES = [
+  'team_created',
+  'team_stopped',
+  'task_assigned',
+  'task_completed',
+  'agent_error',
+  'agent_timeout',
+  'gate_passed',
+  'gate_failed',
+  'model_usage',
+];
+
+/**
+ * Track an agent teams event.
+ *
+ * Writes to both:
+ * 1. session-state.json (hook_metrics.teams section) for real-time status
+ * 2. JSONL bus (via messaging-bridge) for historical audit trail
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {string} eventType - Event type (see EVENT_TYPES)
+ * @param {object} data - Event data (agent, task_id, duration_ms, etc.)
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function trackEvent(rootDir, eventType, data = {}) {
+  const event = {
+    type: eventType,
+    at: new Date().toISOString(),
+    ...data,
+  };
+
+  // 1. Update session-state.json
+  try {
+    const paths = getPaths();
+    const sessionStatePath = paths
+      ? paths.getSessionStatePath(rootDir)
+      : path.join(rootDir, 'docs', '09-agents', 'session-state.json');
+
+    const fileLock = getFileLock();
+
+    if (fileLock && fs.existsSync(sessionStatePath)) {
+      fileLock.atomicReadModifyWrite(sessionStatePath, (state) => {
+        if (!state.hook_metrics) state.hook_metrics = {};
+        if (!state.hook_metrics.teams) state.hook_metrics.teams = { events: [], summary: {} };
+
+        const teams = state.hook_metrics.teams;
+
+        // Append to events (keep last 50)
+        teams.events.push(event);
+        if (teams.events.length > 50) {
+          teams.events = teams.events.slice(-50);
+        }
+
+        // Update summary counters
+        if (!teams.summary[eventType]) teams.summary[eventType] = 0;
+        teams.summary[eventType]++;
+
+        teams.last_updated = event.at;
+
+        return state;
+      });
+    }
+  } catch (e) {
+    // Non-critical - continue to bus logging
+  }
+
+  // 2. Log to JSONL bus
+  try {
+    const bridge = getMessagingBridge();
+    if (bridge) {
+      bridge.sendMessage(rootDir, {
+        from: data.agent || 'team-events',
+        to: 'observability',
+        type: eventType,
+        ...data,
+      });
+    }
+  } catch (e) {
+    // Non-critical
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Get team events from session-state.json.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {object} [filters] - Optional filters { type, agent, trace_id, since, limit }
+ * @returns {{ ok: boolean, events?: Array, summary?: object }}
+ */
+function getTeamEvents(rootDir, filters = {}) {
+  try {
+    const paths = getPaths();
+    const sessionStatePath = paths
+      ? paths.getSessionStatePath(rootDir)
+      : path.join(rootDir, 'docs', '09-agents', 'session-state.json');
+
+    if (!fs.existsSync(sessionStatePath)) {
+      return { ok: true, events: [], summary: {} };
+    }
+
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    const teams = state.hook_metrics && state.hook_metrics.teams;
+    if (!teams) {
+      return { ok: true, events: [], summary: {} };
+    }
+
+    let events = teams.events || [];
+
+    // Apply filters
+    if (filters.type) {
+      events = events.filter(e => e.type === filters.type);
+    }
+    if (filters.agent) {
+      events = events.filter(e => e.agent === filters.agent);
+    }
+    if (filters.trace_id) {
+      events = events.filter(e => e.trace_id === filters.trace_id);
+    }
+    if (filters.since) {
+      const sinceTime = new Date(filters.since).getTime();
+      events = events.filter(e => new Date(e.at).getTime() >= sinceTime);
+    }
+    if (filters.limit && filters.limit > 0) {
+      events = events.slice(-filters.limit);
+    }
+
+    return {
+      ok: true,
+      events,
+      summary: teams.summary || {},
+    };
+  } catch (e) {
+    return { ok: false, error: e.message, events: [] };
+  }
+}
+
+/**
+ * Aggregate team metrics from events filtered by trace_id.
+ *
+ * Computes:
+ * - Per-agent: total duration, tasks completed, errors, timeouts
+ * - Per-gate: passed/failed counts and pass rate
+ * - Team completion time (team_created → team_stopped)
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {string} traceId - Trace ID to aggregate metrics for
+ * @returns {{ ok: boolean, trace_id: string, per_agent: object, per_gate: object, team_completion_ms: number|null, computed_at: string }}
+ */
+function aggregateTeamMetrics(rootDir, traceId) {
+  if (!traceId) {
+    return { ok: false, error: 'trace_id is required' };
+  }
+
+  const result = getTeamEvents(rootDir, { trace_id: traceId });
+  const events = result.events || [];
+
+  // Per-agent metrics from task_completed, agent_error, agent_timeout
+  const perAgent = {};
+  const ensureAgent = (agent) => {
+    if (!perAgent[agent]) {
+      perAgent[agent] = { total_duration_ms: 0, tasks_completed: 0, errors: 0, timeouts: 0 };
+    }
+  };
+
+  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++;
+    }
+    if (e.type === 'agent_error' && e.agent) {
+      ensureAgent(e.agent);
+      perAgent[e.agent].errors++;
+    }
+    if (e.type === 'agent_timeout' && e.agent) {
+      ensureAgent(e.agent);
+      perAgent[e.agent].timeouts++;
+    }
+  }
+
+  // Per-gate metrics from gate_passed, gate_failed
+  const perGate = {};
+  for (const e of events) {
+    if (e.type === 'gate_passed' || e.type === 'gate_failed') {
+      const gateType = e.gate || 'unknown';
+      if (!perGate[gateType]) perGate[gateType] = { passed: 0, failed: 0, pass_rate: 0 };
+      if (e.type === 'gate_passed') perGate[gateType].passed++;
+      else perGate[gateType].failed++;
+    }
+  }
+  for (const gate of Object.keys(perGate)) {
+    const total = perGate[gate].passed + perGate[gate].failed;
+    perGate[gate].pass_rate = total > 0 ? perGate[gate].passed / total : 0;
+  }
+
+  // Team completion time from team_created → team_stopped
+  let teamCompletionMs = null;
+  const created = events.find(e => e.type === 'team_created');
+  const stopped = events.find(e => e.type === 'team_stopped');
+  if (created && stopped) {
+    teamCompletionMs = new Date(stopped.at).getTime() - new Date(created.at).getTime();
+  }
+
+  return {
+    ok: true,
+    trace_id: traceId,
+    per_agent: perAgent,
+    per_gate: perGate,
+    team_completion_ms: teamCompletionMs,
+    computed_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Save aggregated metrics to session-state.json under team_metrics.traces[trace_id].
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {object} metrics - Output from aggregateTeamMetrics()
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function saveAggregatedMetrics(rootDir, metrics) {
+  if (!metrics || !metrics.trace_id) {
+    return { ok: false, error: 'metrics with trace_id required' };
+  }
+
+  try {
+    const paths = getPaths();
+    const sessionStatePath = paths
+      ? paths.getSessionStatePath(rootDir)
+      : path.join(rootDir, 'docs', '09-agents', 'session-state.json');
+
+    const fileLock = getFileLock();
+
+    if (fileLock && fs.existsSync(sessionStatePath)) {
+      fileLock.atomicReadModifyWrite(sessionStatePath, (state) => {
+        if (!state.team_metrics) state.team_metrics = {};
+        if (!state.team_metrics.traces) state.team_metrics.traces = {};
+        state.team_metrics.traces[metrics.trace_id] = {
+          per_agent: metrics.per_agent,
+          per_gate: metrics.per_gate,
+          team_completion_ms: metrics.team_completion_ms,
+          computed_at: metrics.computed_at,
+        };
+        return state;
+      });
+    } else {
+      // Fallback to direct write
+      let state = {};
+      if (fs.existsSync(sessionStatePath)) {
+        state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+      }
+      if (!state.team_metrics) state.team_metrics = {};
+      if (!state.team_metrics.traces) state.team_metrics.traces = {};
+      state.team_metrics.traces[metrics.trace_id] = {
+        per_agent: metrics.per_agent,
+        per_gate: metrics.per_gate,
+        team_completion_ms: metrics.team_completion_ms,
+        computed_at: metrics.computed_at,
+      };
+      fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+    }
+
+    // Notify listeners (e.g., dashboard server) that metrics were saved
+    try {
+      teamMetricsEmitter.emit('metrics_saved', { trace_id: metrics.trace_id });
+    } catch (_) {
+      // Non-critical
+    }
+
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+module.exports = {
+  EVENT_TYPES,
+  trackEvent,
+  getTeamEvents,
+  aggregateTeamMetrics,
+  saveAggregatedMetrics,
+  teamMetricsEmitter,
+};

package/scripts/messaging-bridge.js

@@ -49,6 +49,18 @@ function getFeatureFlags() {
   return _featureFlags;
 }
 
+let _busUtils;
+function getBusUtils() {
+  if (!_busUtils) {
+    try {
+      _busUtils = require('./lib/bus-utils');
+    } catch (e) {
+      return null;
+    }
+  }
+  return _busUtils;
+}
+
 /**
  * Get the bus log path.
  */
@@ -74,28 +86,75 @@ function ensureBusDir(rootDir) {
 /**
  * Send a message to the AgileFlow bus.
  *
+ * When Agent Teams is enabled (native mode), the message is formatted for
+ * both the JSONL bus AND the native SendMessage channel. The JSONL bus
+ * remains the source of truth; native messaging is supplementary.
+ *
+ * Also triggers log rotation when the bus exceeds 1000 lines.
+ *
  * @param {string} rootDir - Project root
  * @param {object} message - Message object { from, to, type, ... }
- * @returns {{ ok: boolean }}
+ * @returns {{ ok: boolean, native?: boolean }}
  */
 function sendMessage(rootDir, message) {
   try {
     ensureBusDir(rootDir);
     const logPath = getBusLogPath(rootDir);
+    const isNative = getFeatureFlags().isAgentTeamsEnabled({ rootDir });
 
     const entry = {
       ...message,
       at: new Date().toISOString(),
-      agent_teams: getFeatureFlags().isAgentTeamsEnabled({ rootDir }),
+      agent_teams: isNative,
     };
 
+    // When native Agent Teams is enabled, also format for native SendMessage
+    if (isNative) {
+      entry.native_format = {
+        tool: 'SendMessage',
+        to: message.to || 'team-lead',
+        content: formatForNative(message),
+      };
+    }
+
+    // Always write to JSONL bus (source of truth)
     fs.appendFileSync(logPath, JSON.stringify(entry) + '\n');
-    return { ok: true };
+
+    // Trigger rotation check (non-blocking, fail-safe)
+    try {
+      const busUtils = getBusUtils();
+      if (busUtils && busUtils.shouldRotate(logPath, 1000)) {
+        busUtils.rotateLog(logPath, { keepRecent: 100 });
+      }
+    } catch (e) {
+      // Rotation failure is non-critical
+    }
+
+    return { ok: true, native: isNative };
   } catch (e) {
     return { ok: false, error: e.message };
   }
 }
 
+/**
+ * Format a message for the native SendMessage tool.
+ * Converts AgileFlow message types into a structured content string.
+ *
+ * @param {object} message - AgileFlow message object
+ * @returns {string} Formatted content for native SendMessage
+ * @private
+ */
+function formatForNative(message) {
+  const parts = [];
+  if (message.type) parts.push(`[${message.type}]`);
+  if (message.from) parts.push(`from:${message.from}`);
+  if (message.task_id) parts.push(`task:${message.task_id}`);
+  if (message.message) parts.push(message.message);
+  if (message.description) parts.push(message.description);
+  if (message.status) parts.push(`status:${message.status}`);
+  return parts.join(' ');
+}
+
 /**
  * Read messages from the AgileFlow bus.
  *
@@ -188,54 +247,37 @@ function getAgentContext(rootDir, agentName) {
 /**
  * Send a task assignment message.
  */
-function sendTaskAssignment(rootDir, from, to, taskId, description) {
-  return sendMessage(rootDir, {
-    from,
-    to,
-    type: 'task_assignment',
-    task_id: taskId,
-    description,
-  });
+function sendTaskAssignment(rootDir, from, to, taskId, description, traceId) {
+  const msg = { from, to, type: 'task_assignment', task_id: taskId, description };
+  if (traceId) msg.trace_id = traceId;
+  return sendMessage(rootDir, msg);
 }
 
 /**
  * Send a plan proposal message.
  */
-function sendPlanProposal(rootDir, from, to, taskId, plan) {
-  return sendMessage(rootDir, {
-    from,
-    to,
-    type: 'plan_proposal',
-    task_id: taskId,
-    plan,
-  });
+function sendPlanProposal(rootDir, from, to, taskId, plan, traceId) {
+  const msg = { from, to, type: 'plan_proposal', task_id: taskId, plan };
+  if (traceId) msg.trace_id = traceId;
+  return sendMessage(rootDir, msg);
 }
 
 /**
  * Send a plan approval/rejection message.
  */
-function sendPlanDecision(rootDir, from, to, taskId, approved, reason) {
-  return sendMessage(rootDir, {
-    from,
-    to,
-    type: approved ? 'plan_approved' : 'plan_rejected',
-    task_id: taskId,
-    reason,
-  });
+function sendPlanDecision(rootDir, from, to, taskId, approved, reason, traceId) {
+  const msg = { from, to, type: approved ? 'plan_approved' : 'plan_rejected', task_id: taskId, reason };
+  if (traceId) msg.trace_id = traceId;
+  return sendMessage(rootDir, msg);
 }
 
 /**
  * Send a validation result message.
  */
-function sendValidationResult(rootDir, from, taskId, status, details) {
-  return sendMessage(rootDir, {
-    from,
-    to: 'team-lead',
-    type: 'validation',
-    task_id: taskId,
-    status, // 'approved' | 'rejected'
-    details,
-  });
+function sendValidationResult(rootDir, from, taskId, status, details, traceId) {
+  const msg = { from, to: 'team-lead', type: 'validation', task_id: taskId, status, details };
+  if (traceId) msg.trace_id = traceId;
+  return sendMessage(rootDir, msg);
 }
 
 // CLI entry point
@@ -297,6 +339,7 @@ module.exports = {
   sendPlanDecision,
   sendValidationResult,
   getBusLogPath,
+  formatForNative,
 };
 
 if (require.main === module) {

package/scripts/migrate-ideation-index.js

@@ -3,7 +3,8 @@
 /**
  * migrate-ideation-index.js - Backfill ideation index from existing reports
  *
- * Parses all existing ideation reports (docs/08-project/ideation-*.md) and
+ * Parses all existing ideation reports (docs/08-project/ideation/ideation-*.md,
+ * with fallback to legacy docs/08-project/ideation-*.md) and
  * populates the ideation index with ideas, detecting duplicates across reports
  * and linking to stories/epics where possible.
  *
@@ -290,19 +291,40 @@ function migrateIdeationReports(rootDir, options = {}) {
 
   const index = loadResult.data;
 
-  // Find all ideation reports
-  const reportsDir = path.join(rootDir, 'docs/08-project');
-  if (!fs.existsSync(reportsDir)) {
-    return { ok: false, error: `Reports directory not found: ${reportsDir}` };
+  // Find all ideation reports (new path first, then legacy fallback)
+  const newReportsDir = path.join(rootDir, 'docs/08-project/ideation');
+  const legacyReportsDir = path.join(rootDir, 'docs/08-project');
+
+  const reportFiles = [];
+
+  // Check new subdirectory first
+  if (fs.existsSync(newReportsDir)) {
+    const newFiles = fs
+      .readdirSync(newReportsDir)
+      .filter(f => f.startsWith('ideation-') && f.endsWith('.md'));
+    for (const f of newFiles) {
+      reportFiles.push({ file: f, dir: newReportsDir });
+    }
+  }
+
+  // Also check legacy location for backward compatibility
+  if (fs.existsSync(legacyReportsDir)) {
+    const legacyFiles = fs
+      .readdirSync(legacyReportsDir)
+      .filter(f => f.startsWith('ideation-') && f.endsWith('.md'));
+    for (const f of legacyFiles) {
+      // Avoid duplicates if same file exists in both locations
+      if (!reportFiles.some(r => r.file === f)) {
+        reportFiles.push({ file: f, dir: legacyReportsDir });
+      }
+    }
   }
 
-  const reportFiles = fs
-    .readdirSync(reportsDir)
-    .filter(f => f.startsWith('ideation-') && f.endsWith('.md'))
-    .sort(); // Sort chronologically
+  // Sort chronologically by filename
+  reportFiles.sort((a, b) => a.file.localeCompare(b.file));
 
   if (reportFiles.length === 0) {
-    console.log('No ideation reports found in docs/08-project/');
+    console.log('No ideation reports found in docs/08-project/ideation/ or docs/08-project/');
     return { ok: true, stats: { reportsProcessed: 0, ideasAdded: 0, duplicates: 0 } };
   }
 
@@ -315,7 +337,7 @@ function migrateIdeationReports(rootDir, options = {}) {
     errors: 0,
   };
 
-  for (const reportFile of reportFiles) {
+  for (const { file: reportFile, dir: reportsDir } of reportFiles) {
     const reportPath = path.join(reportsDir, reportFile);
     console.log(`Processing: ${reportFile}`);
 
@@ -499,9 +521,10 @@ Options:
   --help       Show this help
 
 Description:
-  Parses all ideation reports in docs/08-project/ideation-*.md and populates
-  the ideation index at docs/00-meta/ideation-index.json with ideas, detecting
-  duplicates across reports and linking to epics where possible.
+  Parses all ideation reports in docs/08-project/ideation/ideation-*.md (and
+  legacy docs/08-project/ideation-*.md) and populates the ideation index at
+  docs/00-meta/ideation-index.json with ideas, detecting duplicates across
+  reports and linking to epics where possible.
 `);
     process.exit(0);
   }