jumpstart-mode 1.1.12 → 1.1.13

package/bin/lib/plan-executor.js

@@ -0,0 +1,366 @@
+/**
+ * plan-executor.js — Rich Plan Execution Engine
+ *
+ * Turn implementation-plan tasks into executable, resumable,
+ * verifiable agent jobs.
+ *
+ * State file: .jumpstart/state/plan-execution.json
+ *
+ * Usage:
+ *   node bin/lib/plan-executor.js start|status|resume|verify|reset [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_EXECUTION_FILE = path.join('.jumpstart', 'state', 'plan-execution.json');
+
+const TASK_STATUSES = ['pending', 'in_progress', 'completed', 'failed', 'skipped', 'blocked'];
+
+/**
+ * Default execution state.
+ * @returns {object}
+ */
+function defaultExecutionState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    plan_source: null,
+    jobs: [],
+    execution_log: []
+  };
+}
+
+/**
+ * Load execution state from disk.
+ * @param {string} [stateFile]
+ * @returns {object}
+ */
+function loadExecutionState(stateFile) {
+  const filePath = stateFile || DEFAULT_EXECUTION_FILE;
+  if (!fs.existsSync(filePath)) {
+    return defaultExecutionState();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return defaultExecutionState();
+  }
+}
+
+/**
+ * Save execution state to disk.
+ * @param {object} state
+ * @param {string} [stateFile]
+ */
+function saveExecutionState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_EXECUTION_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Parse implementation plan into executable jobs.
+ *
+ * @param {string} planContent - Implementation plan markdown content.
+ * @returns {object[]}
+ */
+function parsePlanToJobs(planContent) {
+  const jobs = [];
+  const lines = planContent.split('\n');
+  let currentMilestone = null;
+
+  for (const line of lines) {
+    // Detect milestones like "## Milestone 1: ...", "## M01: ..."
+    const milestoneMatch = line.match(/^#{2,3}\s+(?:Milestone\s+)?(\d+|M\d+)[:\s—–-]+\s*(.+)$/i);
+    if (milestoneMatch) {
+      currentMilestone = milestoneMatch[1].startsWith('M') ? milestoneMatch[1] : `M${milestoneMatch[1].padStart(2, '0')}`;
+      continue;
+    }
+
+    // Detect tasks like "- M01-T01: ...", "### M01-T01 — ..."
+    const taskMatch = line.match(/(?:^#{2,4}\s+|^[-*]\s+\*{0,2})(M\d+-T\d+)(?:\*{0,2})[:\s—–-]+\s*(.+)/i);
+    if (taskMatch) {
+      const taskId = taskMatch[1];
+      const title = taskMatch[2].trim().replace(/\*{1,2}/g, '');
+
+      // Extract story refs
+      const storyRefs = line.match(/E\d+-S\d+/g) || [];
+
+      // Extract dependency refs (depends on: M01-T02)
+      const depMatch = line.match(/depends?\s+on[:\s]+([^.]+)/i);
+      const dependencies = depMatch
+        ? (depMatch[1].match(/M\d+-T\d+/g) || [])
+        : [];
+
+      jobs.push({
+        id: taskId,
+        title,
+        milestone: currentMilestone || taskId.split('-')[0],
+        status: 'pending',
+        story_refs: [...new Set(storyRefs)],
+        dependencies,
+        started_at: null,
+        completed_at: null,
+        verification: null,
+        output_files: [],
+        error: null
+      });
+    }
+  }
+
+  return jobs;
+}
+
+/**
+ * Initialize execution from implementation plan.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function initializeExecution(root, options = {}) {
+  const planPath = options.planPath || path.join(root, 'specs', 'implementation-plan.md');
+  const stateFile = options.stateFile || path.join(root, DEFAULT_EXECUTION_FILE);
+
+  if (!fs.existsSync(planPath)) {
+    return { success: false, error: `Implementation plan not found: ${planPath}` };
+  }
+
+  const planContent = fs.readFileSync(planPath, 'utf8');
+  const jobs = parsePlanToJobs(planContent);
+
+  if (jobs.length === 0) {
+    return { success: false, error: 'No tasks found in implementation plan' };
+  }
+
+  const state = defaultExecutionState();
+  state.plan_source = path.relative(root, planPath);
+  state.jobs = jobs;
+  state.execution_log.push({
+    event: 'initialized',
+    timestamp: new Date().toISOString(),
+    total_jobs: jobs.length
+  });
+
+  saveExecutionState(state, stateFile);
+
+  return {
+    success: true,
+    total_jobs: jobs.length,
+    milestones: [...new Set(jobs.map(j => j.milestone))],
+    jobs: jobs.map(j => ({ id: j.id, title: j.title, milestone: j.milestone, dependencies: j.dependencies }))
+  };
+}
+
+/**
+ * Get execution status.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function getExecutionStatus(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_EXECUTION_FILE;
+  const state = loadExecutionState(stateFile);
+
+  if (state.jobs.length === 0) {
+    return { success: true, initialized: false, message: 'No execution plan loaded' };
+  }
+
+  const statusCounts = {};
+  for (const status of TASK_STATUSES) {
+    statusCounts[status] = state.jobs.filter(j => j.status === status).length;
+  }
+
+  const completedPct = state.jobs.length > 0
+    ? Math.round((statusCounts.completed / state.jobs.length) * 100)
+    : 0;
+
+  // Find next actionable tasks (pending with all dependencies completed)
+  const completedIds = new Set(state.jobs.filter(j => j.status === 'completed').map(j => j.id));
+  const nextTasks = state.jobs.filter(j =>
+    j.status === 'pending' &&
+    j.dependencies.every(dep => completedIds.has(dep))
+  );
+
+  return {
+    success: true,
+    initialized: true,
+    plan_source: state.plan_source,
+    total_jobs: state.jobs.length,
+    progress: completedPct,
+    status_counts: statusCounts,
+    next_tasks: nextTasks.map(j => ({ id: j.id, title: j.title, milestone: j.milestone })),
+    jobs: state.jobs.map(j => ({
+      id: j.id,
+      title: j.title,
+      status: j.status,
+      milestone: j.milestone
+    }))
+  };
+}
+
+/**
+ * Update a job's status.
+ *
+ * @param {string} jobId - Task ID (e.g., M01-T01).
+ * @param {string} status - New status.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function updateJobStatus(jobId, status, options = {}) {
+  if (!TASK_STATUSES.includes(status)) {
+    return { success: false, error: `Invalid status: ${status}. Must be one of: ${TASK_STATUSES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_EXECUTION_FILE;
+  const state = loadExecutionState(stateFile);
+  const job = state.jobs.find(j => j.id === jobId);
+
+  if (!job) {
+    return { success: false, error: `Job not found: ${jobId}` };
+  }
+
+  const previousStatus = job.status;
+  job.status = status;
+
+  if (status === 'in_progress' && !job.started_at) {
+    job.started_at = new Date().toISOString();
+  }
+  if (status === 'completed') {
+    job.completed_at = new Date().toISOString();
+  }
+  if (status === 'failed' && options.error) {
+    job.error = options.error;
+  }
+  if (options.output_files) {
+    job.output_files = options.output_files;
+  }
+
+  state.execution_log.push({
+    event: 'status_change',
+    job_id: jobId,
+    from: previousStatus,
+    to: status,
+    timestamp: new Date().toISOString()
+  });
+
+  saveExecutionState(state, stateFile);
+
+  return {
+    success: true,
+    job_id: jobId,
+    previous_status: previousStatus,
+    new_status: status,
+    started_at: job.started_at,
+    completed_at: job.completed_at
+  };
+}
+
+/**
+ * Verify a completed job.
+ *
+ * @param {string} jobId - Task ID.
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function verifyJob(jobId, root, options = {}) {
+  const stateFile = options.stateFile || path.join(root, DEFAULT_EXECUTION_FILE);
+  const state = loadExecutionState(stateFile);
+  const job = state.jobs.find(j => j.id === jobId);
+
+  if (!job) {
+    return { success: false, error: `Job not found: ${jobId}` };
+  }
+
+  const checks = [];
+
+  // Check if job has output files
+  if (job.output_files && job.output_files.length > 0) {
+    for (const file of job.output_files) {
+      const exists = fs.existsSync(path.join(root, file));
+      checks.push({ check: `file_exists: ${file}`, passed: exists });
+    }
+  }
+
+  // Check status
+  checks.push({ check: 'status_completed', passed: job.status === 'completed' });
+  checks.push({ check: 'has_completion_time', passed: !!job.completed_at });
+  checks.push({ check: 'no_errors', passed: !job.error });
+
+  const allPassed = checks.every(c => c.passed);
+
+  job.verification = {
+    verified_at: new Date().toISOString(),
+    passed: allPassed,
+    checks
+  };
+
+  saveExecutionState(state, stateFile);
+
+  return {
+    success: true,
+    job_id: jobId,
+    verified: allPassed,
+    checks,
+    summary: {
+      total_checks: checks.length,
+      passed: checks.filter(c => c.passed).length,
+      failed: checks.filter(c => !c.passed).length
+    }
+  };
+}
+
+/**
+ * Reset execution state.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function resetExecution(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_EXECUTION_FILE;
+  const state = loadExecutionState(stateFile);
+  const previousCount = state.jobs.length;
+
+  for (const job of state.jobs) {
+    job.status = 'pending';
+    job.started_at = null;
+    job.completed_at = null;
+    job.verification = null;
+    job.error = null;
+  }
+
+  state.execution_log.push({
+    event: 'reset',
+    timestamp: new Date().toISOString(),
+    jobs_reset: previousCount
+  });
+
+  saveExecutionState(state, stateFile);
+
+  return {
+    success: true,
+    jobs_reset: previousCount
+  };
+}
+
+module.exports = {
+  defaultExecutionState,
+  loadExecutionState,
+  saveExecutionState,
+  parsePlanToJobs,
+  initializeExecution,
+  getExecutionStatus,
+  updateJobStatus,
+  verifyJob,
+  resetExecution,
+  TASK_STATUSES
+};

package/bin/lib/platform-engineering.js

@@ -0,0 +1,119 @@
+/**
+ * platform-engineering.js — Platform Engineering Integration (Item 86)
+ *
+ * Connect to golden paths, service templates, IDP portals,
+ * and paved-road tooling.
+ *
+ * Usage:
+ *   node bin/lib/platform-engineering.js register|list|instantiate|report [options]
+ *
+ * State file: .jumpstart/state/platform-engineering.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'platform-engineering.json');
+
+const TEMPLATE_TYPES = ['service', 'library', 'worker', 'api-gateway', 'frontend'];
+const GOLDEN_PATH_STAGES = ['scaffold', 'ci-cd', 'observability', 'security', 'deployment'];
+
+function defaultState() {
+  return { version: '1.0.0', templates: [], golden_paths: [], instances: [], last_updated: null };
+}
+
+function loadState(stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(fp)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(fp);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(fp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function registerTemplate(name, type, options = {}) {
+  if (!name || !type) return { success: false, error: 'name and type are required' };
+  if (!TEMPLATE_TYPES.includes(type)) {
+    return { success: false, error: `Unknown type: ${type}. Valid: ${TEMPLATE_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const template = {
+    id: `PLAT-${Date.now()}`,
+    name,
+    type,
+    tech_stack: options.tech_stack || [],
+    golden_path_stages: options.stages || GOLDEN_PATH_STAGES,
+    version: options.version || '1.0.0',
+    created_at: new Date().toISOString()
+  };
+
+  state.templates.push(template);
+  saveState(state, stateFile);
+
+  return { success: true, template };
+}
+
+function listTemplates(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  let templates = state.templates;
+  if (options.type) templates = templates.filter(t => t.type === options.type);
+
+  return { success: true, total: templates.length, templates };
+}
+
+function instantiateTemplate(templateId, projectName, options = {}) {
+  if (!templateId || !projectName) return { success: false, error: 'templateId and projectName are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const template = state.templates.find(t => t.id === templateId);
+  if (!template) return { success: false, error: `Template ${templateId} not found` };
+
+  const instance = {
+    id: `INST-${Date.now()}`,
+    template_id: templateId,
+    template_name: template.name,
+    project_name: projectName,
+    status: 'created',
+    created_at: new Date().toISOString()
+  };
+
+  state.instances.push(instance);
+  saveState(state, stateFile);
+
+  return { success: true, instance };
+}
+
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_templates: state.templates.length,
+    total_instances: state.instances.length,
+    by_type: state.templates.reduce((acc, t) => { acc[t.type] = (acc[t.type] || 0) + 1; return acc; }, {}),
+    templates: state.templates,
+    instances: state.instances
+  };
+}
+
+module.exports = {
+  registerTemplate, listTemplates, instantiateTemplate, generateReport,
+  loadState, saveState, defaultState,
+  TEMPLATE_TYPES, GOLDEN_PATH_STAGES
+};

package/bin/lib/playback-summaries.js

@@ -0,0 +1,126 @@
+/**
+ * playback-summaries.js — Stakeholder Playback Summaries (Item 68)
+ *
+ * Translate technical outputs into business-language summaries
+ * for each audience.
+ *
+ * Usage:
+ *   node bin/lib/playback-summaries.js generate|list [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AUDIENCES = ['executive', 'technical', 'product', 'operations', 'compliance'];
+
+const AUDIENCE_CONFIG = {
+  executive: {
+    label: 'Executive Summary',
+    focus: ['business_value', 'timeline', 'budget', 'risks', 'decisions'],
+    tone: 'strategic',
+    max_length: 500
+  },
+  technical: {
+    label: 'Technical Summary',
+    focus: ['architecture', 'tech_stack', 'api_design', 'data_model', 'nfrs'],
+    tone: 'technical',
+    max_length: 1000
+  },
+  product: {
+    label: 'Product Summary',
+    focus: ['user_stories', 'acceptance_criteria', 'personas', 'scope', 'prioritization'],
+    tone: 'user-centric',
+    max_length: 800
+  },
+  operations: {
+    label: 'Operations Summary',
+    focus: ['deployment', 'monitoring', 'runbooks', 'sla_slo', 'incident_response'],
+    tone: 'operational',
+    max_length: 700
+  },
+  compliance: {
+    label: 'Compliance Summary',
+    focus: ['regulations', 'controls', 'evidence', 'audit_trail', 'data_classification'],
+    tone: 'regulatory',
+    max_length: 600
+  }
+};
+
+/**
+ * Generate a playback summary for a target audience.
+ */
+function generateSummary(root, audience, options = {}) {
+  if (!AUDIENCES.includes(audience)) {
+    return { success: false, error: `Unknown audience: ${audience}. Valid: ${AUDIENCES.join(', ')}` };
+  }
+
+  const config = AUDIENCE_CONFIG[audience];
+  const summary = {
+    audience,
+    label: config.label,
+    tone: config.tone,
+    focus_areas: config.focus,
+    generated_at: new Date().toISOString(),
+    sections: {}
+  };
+
+  // Gather data from available specs
+  const specsDir = path.join(root, 'specs');
+  const availableSpecs = [];
+  if (fs.existsSync(specsDir)) {
+    for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.md'))) {
+      availableSpecs.push(f);
+      try {
+        const content = fs.readFileSync(path.join(specsDir, f), 'utf8');
+        summary.sections[f] = {
+          available: true,
+          size: content.length,
+          has_approval: content.includes('Phase Gate Approval')
+        };
+      } catch { summary.sections[f] = { available: true, size: 0 }; }
+    }
+  }
+
+  // Phase status
+  const stateFile = path.join(root, '.jumpstart', 'state', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      summary.project_status = {
+        current_phase: state.current_phase || 0,
+        last_agent: state.current_agent || null
+      };
+    } catch { summary.project_status = { current_phase: 0 }; }
+  } else {
+    summary.project_status = { current_phase: 0 };
+  }
+
+  summary.specs_available = availableSpecs;
+  summary.max_length = config.max_length;
+
+  return { success: true, summary };
+}
+
+/**
+ * List available audience types.
+ */
+function listAudiences() {
+  return {
+    success: true,
+    audiences: AUDIENCES.map(a => ({
+      id: a,
+      label: AUDIENCE_CONFIG[a].label,
+      tone: AUDIENCE_CONFIG[a].tone,
+      focus: AUDIENCE_CONFIG[a].focus
+    }))
+  };
+}
+
+module.exports = {
+  generateSummary,
+  listAudiences,
+  AUDIENCES,
+  AUDIENCE_CONFIG
+};