@devran-ai/kit 4.1.0

package/lib/engineering-manager.js

@@ -0,0 +1,336 @@
+/**
+ * Devran AI Kit — Autonomous Engineering Manager
+ *
+ * Data engine for sprint planning, task auto-assignment,
+ * and velocity metrics. Powers the sprint-orchestrator agent.
+ *
+ * @module lib/engineering-manager
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const taskModel = require('./task-model');
+const agentRegistry = require('./agent-registry');
+const agentReputation = require('./agent-reputation');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const SPRINT_FILE = 'sprint-plans.json';
+
+/** Maximum tasks per sprint suggestion */
+const MAX_SPRINT_SIZE = 20;
+
+/**
+ * @typedef {object} SprintPlan
+ * @property {string} id - Sprint plan ID
+ * @property {string} name - Sprint name
+ * @property {string} createdAt - ISO timestamp
+ * @property {object[]} assignments - Task assignments
+ * @property {string} status - Plan status: 'draft' | 'active' | 'completed'
+ */
+
+/**
+ * @typedef {object} TaskAssignment
+ * @property {string} taskId - Task ID
+ * @property {string} taskTitle - Task title
+ * @property {string} suggestedAgent - Recommended agent
+ * @property {string} reason - Why this agent was chosen
+ * @property {string} priority - Task priority
+ */
+
+/**
+ * Resolves the sprint plans file path.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {string}
+ */
+function resolveSprintPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, SPRINT_FILE);
+}
+
+/**
+ * Loads sprint plans from disk.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ plans: SprintPlan[] }}
+ */
+function loadSprintData(projectRoot) {
+  const filePath = resolveSprintPath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    return { plans: [] };
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return { plans: [] };
+  }
+}
+
+/**
+ * Writes sprint data atomically.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {{ plans: SprintPlan[] }} data
+ * @returns {void}
+ */
+function writeSprintData(projectRoot, data) {
+  const filePath = resolveSprintPath(projectRoot);
+  writeJsonAtomic(filePath, data);
+}
+
+/**
+ * Gets the current workload (in-progress task count) for an agent.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} agentName - Agent name
+ * @returns {number}
+ */
+function getAgentWorkload(projectRoot, agentName) {
+  try {
+    const inProgressTasks = taskModel.listTasks(projectRoot, {
+      status: 'in-progress',
+      assignee: agentName,
+    });
+    return inProgressTasks.length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Finds the best agent for a task based on domain, reputation, and workload.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} taskTitle - Task title for domain matching
+ * @param {string} taskPriority - Task priority
+ * @returns {{ agent: string, reason: string }}
+ */
+function findBestAgent(projectRoot, taskTitle, taskPriority) {
+  let agents = [];
+
+  try {
+    const registry = agentRegistry.loadRegistry(projectRoot);
+    agents = registry.agents;
+  } catch {
+    return { agent: 'unassigned', reason: 'No agent registry available' };
+  }
+
+  if (agents.length === 0) {
+    return { agent: 'unassigned', reason: 'No agents registered' };
+  }
+
+  // Score each agent
+  const scored = agents.map((agent) => {
+    let score = 0;
+    let reasons = [];
+
+    // 1. Domain match (keyword overlap between task title and agent domain)
+    const titleWords = taskTitle.toLowerCase().split(/\W+/);
+    const domainWords = (agent.domain || '').toLowerCase().split(/\W+/);
+    const domainOverlap = titleWords.filter((word) =>
+      word.length > 2 && domainWords.some((dw) => dw.includes(word) || word.includes(dw))
+    ).length;
+
+    if (domainOverlap > 0) {
+      score += domainOverlap * 30;
+      reasons.push(`domain match (${domainOverlap} keywords)`);
+    }
+
+    // 2. Reputation score
+    try {
+      const reputation = agentReputation.getReputation(projectRoot, agent.name);
+      score += reputation.score / 10; // Normalize to ~0-100 range
+      if (reputation.score > 0) {
+        reasons.push(`reputation ${reputation.score}`);
+      }
+    } catch {
+      // No reputation data — neutral
+    }
+
+    // 3. Workload penalty (fewer in-progress tasks = better)
+    const workload = getAgentWorkload(projectRoot, agent.name);
+    score -= workload * 20;
+    if (workload > 0) {
+      reasons.push(`workload ${workload} tasks`);
+    }
+
+    return {
+      agent: agent.name,
+      score,
+      reason: reasons.length > 0 ? reasons.join(', ') : 'general availability',
+    };
+  });
+
+  // Sort by score descending
+  scored.sort((a, b) => b.score - a.score);
+
+  return {
+    agent: scored[0].agent,
+    reason: scored[0].reason,
+  };
+}
+
+/**
+ * Generates a sprint plan from open tasks.
+ * This is an advisory suggestion — never auto-executed.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {object} [options] - Sprint options
+ * @param {string} [options.name] - Sprint name
+ * @param {number} [options.maxTasks] - Max tasks to include
+ * @returns {SprintPlan}
+ */
+function generateSprintPlan(projectRoot, options = {}) {
+  const sprintName = options.name || `Sprint-${new Date().toISOString().slice(0, 10)}`;
+  const maxTasks = options.maxTasks || MAX_SPRINT_SIZE;
+
+  // Get all open/blocked tasks, prioritized
+  let tasks = [];
+  try {
+    const openTasks = taskModel.listTasks(projectRoot, { status: 'open' });
+    const blockedTasks = taskModel.listTasks(projectRoot, { status: 'blocked' });
+    tasks = [...openTasks, ...blockedTasks];
+  } catch {
+    tasks = [];
+  }
+
+  // Priority sort using shared utility
+  const sortedTasks = taskModel.sortByPriority(tasks);
+
+  // Take top N
+  const sprintTasks = sortedTasks.slice(0, maxTasks);
+
+  // Auto-assign each
+  /** @type {TaskAssignment[]} */
+  const assignments = sprintTasks.map((task) => {
+    const best = findBestAgent(projectRoot, task.title, task.priority);
+    return {
+      taskId: task.id,
+      taskTitle: task.title,
+      suggestedAgent: best.agent,
+      reason: best.reason,
+      priority: task.priority,
+    };
+  });
+
+  /** @type {SprintPlan} */
+  const plan = {
+    id: `SPR-${crypto.randomUUID().slice(0, 8).toUpperCase()}`,
+    name: sprintName,
+    createdAt: new Date().toISOString(),
+    assignments,
+    status: 'draft',
+  };
+
+  // Persist
+  const data = loadSprintData(projectRoot);
+  data.plans.push(plan);
+  writeSprintData(projectRoot, data);
+
+  return plan;
+}
+
+/**
+ * Auto-assigns a single task to the best available agent.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} taskId - Task ID
+ * @returns {{ success: boolean, agent?: string, reason?: string, error?: string }}
+ */
+function autoAssignTask(projectRoot, taskId) {
+  const task = taskModel.getTask(projectRoot, taskId);
+  if (!task) {
+    return { success: false, error: `Task not found: ${taskId}` };
+  }
+
+  const best = findBestAgent(projectRoot, task.title, task.priority);
+
+  if (best.agent === 'unassigned') {
+    return { success: false, error: best.reason };
+  }
+
+  const result = taskModel.updateTask(projectRoot, taskId, { assignee: best.agent });
+
+  if (result.success) {
+    return { success: true, agent: best.agent, reason: best.reason };
+  }
+
+  return { success: false, error: 'Failed to update task' };
+}
+
+/**
+ * Suggests the next highest-priority unblocked task.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ task: object | null, reason: string }}
+ */
+function suggestNextTask(projectRoot) {
+  let openTasks = [];
+  try {
+    openTasks = taskModel.listTasks(projectRoot, { status: 'open' });
+  } catch {
+    return { task: null, reason: 'No tasks available' };
+  }
+
+  if (openTasks.length === 0) {
+    return { task: null, reason: 'No open tasks remaining' };
+  }
+
+  // Priority sort using shared utility
+  const sorted = taskModel.sortByPriority(openTasks);
+
+  const topTask = sorted[0];
+  return {
+    task: topTask,
+    reason: `Highest priority open task (${topTask.priority})`,
+  };
+}
+
+/**
+ * Returns sprint velocity and progress metrics.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ totalSprints: number, activeSprint: SprintPlan | null, velocity: number, completionRate: number }}
+ */
+function getSprintMetrics(projectRoot) {
+  const data = loadSprintData(projectRoot);
+  const activeSprint = data.plans.find((p) => p.status === 'active') || null;
+  const completedSprints = data.plans.filter((p) => p.status === 'completed');
+
+  // Velocity: average assignments per completed sprint
+  const velocity = completedSprints.length > 0
+    ? Math.round(
+        completedSprints.reduce((sum, s) => sum + s.assignments.length, 0) / completedSprints.length
+      )
+    : 0;
+
+  // Task metrics
+  let completionRate = 0;
+  try {
+    const metrics = taskModel.getTaskMetrics(projectRoot);
+    completionRate = metrics.completionRate;
+  } catch {
+    completionRate = 0;
+  }
+
+  return {
+    totalSprints: data.plans.length,
+    activeSprint,
+    velocity,
+    completionRate,
+  };
+}
+
+module.exports = {
+  generateSprintPlan,
+  autoAssignTask,
+  suggestNextTask,
+  getSprintMetrics,
+};

package/lib/error-budget.js

@@ -0,0 +1,370 @@
+/**
+ * Devran AI Kit — Error Budget Tracker
+ *
+ * Enables reliability-config.json error budget tracking with
+ * basic metrics collection. Records test, build, and deployment
+ * results and calculates budget health.
+ *
+ * @module lib/error-budget
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('error-budget');
+const RELIABILITY_CONFIG = 'reliability-config.json';
+const METRICS_FILE = 'metrics.json';
+
+/**
+ * @typedef {'HEALTHY' | 'WARNING' | 'EXHAUSTED'} BudgetStatus
+ */
+
+/**
+ * @typedef {object} MetricsData
+ * @property {number} testsPassed - Total tests passed
+ * @property {number} testsFailed - Total tests failed
+ * @property {number} buildsSucceeded - Total successful builds
+ * @property {number} buildsFailed - Total failed builds
+ * @property {number} deploysSucceeded - Total successful deploys
+ * @property {number} deploysRolledBack - Total rolled-back deploys
+ * @property {string} periodStart - ISO timestamp of period start
+ * @property {string} lastUpdated - ISO timestamp of last update
+ */
+
+/**
+ * @typedef {object} BudgetReport
+ * @property {BudgetStatus} status - Overall budget health
+ * @property {object} rates - Current failure rates
+ * @property {number} rates.testFailureRate - Test failure rate (%)
+ * @property {number} rates.buildFailureRate - Build failure rate (%)
+ * @property {number} rates.deployRollbackRate - Deploy rollback rate (%)
+ * @property {object} thresholds - Configured thresholds
+ * @property {number} thresholds.testFailureRatePercent - Max test failure rate
+ * @property {number} thresholds.buildFailureRatePercent - Max build failure rate
+ * @property {number} thresholds.deployRollbackRatePercent - Max deploy rollback rate
+ * @property {string[]} violations - Which metrics exceeded thresholds
+ */
+
+/**
+ * Resolves the path to the metrics file.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to metrics.json
+ */
+function resolveMetricsPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, METRICS_FILE);
+}
+
+/**
+ * Resolves the path to the reliability config.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to reliability-config.json
+ */
+function resolveConfigPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, RELIABILITY_CONFIG);
+}
+
+/**
+ * Loads the reliability configuration.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Parsed reliability config
+ */
+function loadConfig(projectRoot) {
+  const configPath = resolveConfigPath(projectRoot);
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Reliability config not found: ${configPath}`);
+  }
+
+  return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+/**
+ * Loads metrics data from disk, or returns defaults if file doesn't exist.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {MetricsData}
+ */
+function loadMetrics(projectRoot) {
+  const metricsPath = resolveMetricsPath(projectRoot);
+
+  if (!fs.existsSync(metricsPath)) {
+    return createEmptyMetrics();
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+  } catch {
+    return createEmptyMetrics();
+  }
+}
+
+/**
+ * Creates an empty metrics object.
+ *
+ * @returns {MetricsData}
+ */
+function createEmptyMetrics() {
+  return {
+    testsPassed: 0,
+    testsFailed: 0,
+    buildsSucceeded: 0,
+    buildsFailed: 0,
+    deploysSucceeded: 0,
+    deploysRolledBack: 0,
+    periodStart: new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes metrics data to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {MetricsData} metrics - Metrics data to write
+ * @returns {void}
+ */
+function writeMetrics(projectRoot, metrics) {
+  const metricsPath = resolveMetricsPath(projectRoot);
+
+  const updatedMetrics = {
+    ...metrics,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  writeJsonAtomic(metricsPath, updatedMetrics);
+}
+
+/**
+ * Records the result of a test run.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {number} passed - Number of tests passed
+ * @param {number} failed - Number of tests failed
+ * @returns {void}
+ */
+function recordTestResult(projectRoot, passed, failed) {
+  const metrics = loadMetrics(projectRoot);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    testsPassed: metrics.testsPassed + passed,
+    testsFailed: metrics.testsFailed + failed,
+  });
+}
+
+/**
+ * Records the result of a build.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {boolean} success - Whether the build succeeded
+ * @returns {void}
+ */
+function recordBuildResult(projectRoot, success) {
+  const metrics = loadMetrics(projectRoot);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    buildsSucceeded: metrics.buildsSucceeded + (success ? 1 : 0),
+    buildsFailed: metrics.buildsFailed + (success ? 0 : 1),
+  });
+}
+
+/**
+ * Records the result of a deployment.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {boolean} success - Whether deploy succeeded
+ * @param {boolean} [rolledBack=false] - Whether it was rolled back
+ * @returns {void}
+ */
+function recordDeployResult(projectRoot, success, rolledBack = false) {
+  const metrics = loadMetrics(projectRoot);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    deploysSucceeded: metrics.deploysSucceeded + (success && !rolledBack ? 1 : 0),
+    deploysRolledBack: metrics.deploysRolledBack + (rolledBack ? 1 : 0),
+  });
+}
+
+/**
+ * Calculates a failure rate percentage safely.
+ *
+ * @param {number} failed - Number of failures
+ * @param {number} total - Total attempts
+ * @returns {number} Failure rate as percentage (0-100)
+ */
+function calculateRate(failed, total) {
+  if (total === 0) {
+    return 0;
+  }
+  return Number(((failed / total) * 100).toFixed(2));
+}
+
+/**
+ * Generates a budget health report.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {BudgetReport}
+ */
+function getBudgetReport(projectRoot) {
+  const config = loadConfig(projectRoot);
+  const metrics = loadMetrics(projectRoot);
+  const thresholds = config.errorBudget?.thresholds || {};
+
+  const testTotal = metrics.testsPassed + metrics.testsFailed;
+  const buildTotal = metrics.buildsSucceeded + metrics.buildsFailed;
+  const deployTotal = metrics.deploysSucceeded + metrics.deploysRolledBack;
+
+  const rates = {
+    testFailureRate: calculateRate(metrics.testsFailed, testTotal),
+    buildFailureRate: calculateRate(metrics.buildsFailed, buildTotal),
+    deployRollbackRate: calculateRate(metrics.deploysRolledBack, deployTotal),
+  };
+
+  /** @type {string[]} */
+  const violations = [];
+
+  if (rates.testFailureRate > (thresholds.testFailureRatePercent || 5)) {
+    violations.push('testFailureRate');
+  }
+  if (rates.buildFailureRate > (thresholds.buildFailureRatePercent || 2)) {
+    violations.push('buildFailureRate');
+  }
+  if (rates.deployRollbackRate > (thresholds.deployRollbackRatePercent || 10)) {
+    violations.push('deployRollbackRate');
+  }
+
+  /** @type {BudgetStatus} */
+  let status = 'HEALTHY';
+
+  if (violations.length > 0) {
+    status = 'EXHAUSTED';
+  } else {
+    // Warning if any rate is above 80% of threshold
+    const testWarning = rates.testFailureRate > (thresholds.testFailureRatePercent || 5) * 0.8;
+    const buildWarning = rates.buildFailureRate > (thresholds.buildFailureRatePercent || 2) * 0.8;
+    const deployWarning = rates.deployRollbackRate > (thresholds.deployRollbackRatePercent || 10) * 0.8;
+
+    if (testWarning || buildWarning || deployWarning) {
+      status = 'WARNING';
+    }
+  }
+
+  return {
+    status,
+    rates,
+    thresholds: {
+      testFailureRatePercent: thresholds.testFailureRatePercent || 5,
+      buildFailureRatePercent: thresholds.buildFailureRatePercent || 2,
+      deployRollbackRatePercent: thresholds.deployRollbackRatePercent || 10,
+    },
+    violations,
+  };
+}
+
+/**
+ * Archives current metrics before resetting.
+ * Preserves historical data for trend analysis.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ archived: boolean, archivePath: string | null }}
+ */
+function archiveMetrics(projectRoot) {
+  const metrics = loadMetrics(projectRoot);
+  const hasData = metrics.testsPassed + metrics.testsFailed +
+    metrics.buildsSucceeded + metrics.buildsFailed +
+    metrics.deploysSucceeded + metrics.deploysRolledBack > 0;
+
+  if (!hasData) {
+    return { archived: false, archivePath: null };
+  }
+
+  const archiveDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'metrics-archive');
+  if (!fs.existsSync(archiveDir)) {
+    fs.mkdirSync(archiveDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archivePath = path.join(archiveDir, `metrics-${timestamp}.json`);
+
+  const report = getBudgetReport(projectRoot);
+  const archiveEntry = {
+    ...metrics,
+    archivedAt: new Date().toISOString(),
+    budgetStatus: report.status,
+    rates: report.rates,
+  };
+
+  fs.writeFileSync(archivePath, JSON.stringify(archiveEntry, null, 2) + '\n', 'utf-8');
+
+  return { archived: true, archivePath };
+}
+
+/**
+ * Resets metrics for a new tracking period.
+ * Automatically archives previous period's data before resetting.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} [options] - Reset options
+ * @param {boolean} [options.skipArchive=false] - Skip archival
+ * @returns {{ archived: boolean, archivePath: string | null }}
+ */
+function resetMetrics(projectRoot, options = {}) {
+  let archiveResult = { archived: false, archivePath: null };
+
+  if (!options.skipArchive) {
+    archiveResult = archiveMetrics(projectRoot);
+  }
+
+  writeMetrics(projectRoot, createEmptyMetrics());
+  return archiveResult;
+}
+
+/**
+ * Returns historical metrics from the archive.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {number} [limit=10] - Maximum entries to return
+ * @returns {object[]}
+ */
+function getMetricsHistory(projectRoot, limit = 10) {
+  const archiveDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'metrics-archive');
+
+  if (!fs.existsSync(archiveDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(archiveDir)
+    .filter((f) => f.startsWith('metrics-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, limit);
+
+  return files.map((file) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(archiveDir, file), 'utf-8'));
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+module.exports = {
+  loadConfig,
+  loadMetrics,
+  recordTestResult,
+  recordBuildResult,
+  recordDeployResult,
+  getBudgetReport,
+  resetMetrics,
+  archiveMetrics,
+  getMetricsHistory,
+};