jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/guided-handoff.js

@@ -0,0 +1,120 @@
+/**
+ * guided-handoff.js — Guided Handoff Packages by Team (Item 73)
+ *
+ * Product to engineering, engineering to QA, engineering to ops,
+ * ops to support handoff package generation.
+ *
+ * Usage:
+ *   node bin/lib/guided-handoff.js generate|list|validate [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const HANDOFF_TYPES = [
+  'product-to-engineering',
+  'engineering-to-qa',
+  'engineering-to-ops',
+  'ops-to-support'
+];
+
+const HANDOFF_CHECKLISTS = {
+  'product-to-engineering': {
+    label: 'Product → Engineering',
+    required: ['user_stories', 'acceptance_criteria', 'wireframes', 'priorities', 'scope_boundaries'],
+    optional: ['competitive_analysis', 'analytics_requirements', 'feature_flags']
+  },
+  'engineering-to-qa': {
+    label: 'Engineering → QA',
+    required: ['test_plan', 'api_contracts', 'environment_setup', 'known_limitations', 'test_data'],
+    optional: ['performance_baselines', 'security_considerations', 'rollback_procedures']
+  },
+  'engineering-to-ops': {
+    label: 'Engineering → Ops',
+    required: ['deployment_guide', 'runbooks', 'monitoring_config', 'rollback_procedures', 'dependencies'],
+    optional: ['load_test_results', 'capacity_planning', 'dr_procedures']
+  },
+  'ops-to-support': {
+    label: 'Ops → Support',
+    required: ['known_issues', 'troubleshooting_guide', 'escalation_paths', 'sla_details', 'faq'],
+    optional: ['common_errors', 'workarounds', 'release_notes']
+  }
+};
+
+/**
+ * Generate a handoff package.
+ */
+function generateHandoff(type, root, options = {}) {
+  if (!HANDOFF_TYPES.includes(type)) {
+    return { success: false, error: `Unknown handoff type: ${type}. Valid: ${HANDOFF_TYPES.join(', ')}` };
+  }
+
+  const checklist = HANDOFF_CHECKLISTS[type];
+  const items = [];
+
+  for (const req of checklist.required) {
+    items.push({ name: req, required: true, status: options[req] ? 'provided' : 'missing' });
+  }
+  for (const opt of checklist.optional) {
+    items.push({ name: opt, required: false, status: options[opt] ? 'provided' : 'not_provided' });
+  }
+
+  const missing = items.filter(i => i.required && i.status === 'missing');
+
+  return {
+    success: true,
+    type,
+    label: checklist.label,
+    items,
+    complete: missing.length === 0,
+    missing_required: missing.map(i => i.name),
+    generated_at: new Date().toISOString()
+  };
+}
+
+/**
+ * List available handoff types.
+ */
+function listHandoffTypes() {
+  return {
+    success: true,
+    types: HANDOFF_TYPES.map(t => ({
+      id: t,
+      label: HANDOFF_CHECKLISTS[t].label,
+      required_count: HANDOFF_CHECKLISTS[t].required.length,
+      optional_count: HANDOFF_CHECKLISTS[t].optional.length
+    }))
+  };
+}
+
+/**
+ * Validate a handoff package completeness.
+ */
+function validateHandoff(type, provided, options = {}) {
+  if (!HANDOFF_TYPES.includes(type)) {
+    return { success: false, error: `Unknown handoff type: ${type}` };
+  }
+
+  const checklist = HANDOFF_CHECKLISTS[type];
+  const providedSet = new Set(provided || []);
+  const missing = checklist.required.filter(r => !providedSet.has(r));
+  const coverage = checklist.required.length > 0
+    ? Math.round(((checklist.required.length - missing.length) / checklist.required.length) * 100)
+    : 100;
+
+  return {
+    success: true,
+    type,
+    complete: missing.length === 0,
+    coverage_pct: coverage,
+    missing,
+    provided: [...providedSet]
+  };
+}
+
+module.exports = {
+  generateHandoff, listHandoffTypes, validateHandoff,
+  HANDOFF_TYPES, HANDOFF_CHECKLISTS
+};

package/bin/lib/impact-analysis.js

@@ -0,0 +1,190 @@
+/**
+ * impact-analysis.js — Agentic Change Impact Analysis
+ *
+ * Before editing, maps what requirements, tests, services, APIs, and
+ * consumers will be affected by a given change.
+ *
+ * Usage:
+ *   node bin/lib/impact-analysis.js analyze|report [--file <path>] [--symbol <name>]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Analyse the impact of changing a given file or symbol.
+ *
+ * @param {string} root - Project root.
+ * @param {object} target - { file?, symbol?, specId? } — what is being changed.
+ * @param {object} [options]
+ * @returns {object} Impact analysis result.
+ */
+function analyzeImpact(root, target, options = {}) {
+  if (!target || (!target.file && !target.symbol && !target.specId)) {
+    return { success: false, error: 'target.file, target.symbol, or target.specId is required' };
+  }
+
+  const result = {
+    target,
+    affected_requirements: [],
+    affected_tests: [],
+    affected_services: [],
+    affected_apis: [],
+    affected_consumers: [],
+    risk_level: 'low',
+    summary: {}
+  };
+
+  const specsDir = path.join(root, 'specs');
+  const testsDir = path.join(root, options.testsDir || 'tests');
+  const srcDir = path.join(root, options.srcDir || 'src');
+
+  // Determine the key to search for (filename stem, symbol name, or spec ID)
+  const searchTerms = [];
+  if (target.file) {
+    searchTerms.push(path.basename(target.file, path.extname(target.file)));
+    searchTerms.push(path.basename(target.file));
+  }
+  if (target.symbol) {
+    searchTerms.push(target.symbol);
+  }
+  if (target.specId) {
+    searchTerms.push(target.specId);
+  }
+
+  function grepDir(dir, label) {
+    if (!fs.existsSync(dir)) return [];
+    const hits = [];
+    const walk = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (entry.isFile()) {
+          try {
+            const content = fs.readFileSync(full, 'utf8');
+            const rel = path.relative(root, full).replace(/\\/g, '/');
+            for (const term of searchTerms) {
+              if (content.includes(term)) {
+                hits.push({ file: rel, label, matched_term: term });
+                break;
+              }
+            }
+          } catch {
+            // skip unreadable files
+          }
+        }
+      }
+    };
+    walk(dir);
+    return hits;
+  }
+
+  // Find affected spec requirements
+  const specHits = grepDir(specsDir, 'requirement');
+  for (const h of specHits) {
+    if (!result.affected_requirements.some(r => r.file === h.file)) {
+      result.affected_requirements.push(h);
+    }
+  }
+
+  // Find affected tests
+  const testHits = grepDir(testsDir, 'test');
+  for (const h of testHits) {
+    if (!result.affected_tests.some(r => r.file === h.file)) {
+      result.affected_tests.push(h);
+    }
+  }
+
+  // Find affected services and API consumers within src
+  const srcHits = grepDir(srcDir, 'source');
+  for (const h of srcHits) {
+    // Rough heuristic: files with "service", "api", "controller", "route" in name are services/APIs
+    const lower = h.file.toLowerCase();
+    if (lower.includes('service') || lower.includes('controller') || lower.includes('route')) {
+      result.affected_services.push(h);
+    } else if (lower.includes('api') || lower.includes('endpoint') || lower.includes('handler')) {
+      result.affected_apis.push(h);
+    } else {
+      result.affected_consumers.push(h);
+    }
+  }
+
+  // Compute risk level
+  const totalAffected =
+    result.affected_requirements.length +
+    result.affected_tests.length +
+    result.affected_services.length +
+    result.affected_apis.length +
+    result.affected_consumers.length;
+
+  if (totalAffected > 20) {
+    result.risk_level = 'critical';
+  } else if (totalAffected > 10) {
+    result.risk_level = 'high';
+  } else if (totalAffected > 4) {
+    result.risk_level = 'medium';
+  } else {
+    result.risk_level = 'low';
+  }
+
+  result.summary = {
+    total_affected: totalAffected,
+    requirements: result.affected_requirements.length,
+    tests: result.affected_tests.length,
+    services: result.affected_services.length,
+    apis: result.affected_apis.length,
+    consumers: result.affected_consumers.length,
+    risk_level: result.risk_level
+  };
+
+  return { success: true, ...result };
+}
+
+/**
+ * Render a human-readable impact report.
+ *
+ * @param {object} analysis - Result from analyzeImpact().
+ * @returns {string}
+ */
+function renderImpactReport(analysis) {
+  if (!analysis.success) {
+    return `❌ Impact analysis failed: ${analysis.error}`;
+  }
+
+  const lines = [];
+  const riskEmoji = { low: '🟢', medium: '🟡', high: '🟠', critical: '🔴' };
+  const emoji = riskEmoji[analysis.risk_level] || '⚪';
+
+  lines.push(`\n${emoji} Impact Analysis — Risk: ${analysis.risk_level.toUpperCase()}`);
+  lines.push(`\nTarget: ${JSON.stringify(analysis.target)}`);
+  lines.push(`Total affected: ${analysis.summary.total_affected}`);
+  lines.push('');
+
+  const sections = [
+    ['Requirements', analysis.affected_requirements],
+    ['Tests', analysis.affected_tests],
+    ['Services', analysis.affected_services],
+    ['APIs', analysis.affected_apis],
+    ['Consumers', analysis.affected_consumers]
+  ];
+
+  for (const [label, items] of sections) {
+    if (items.length > 0) {
+      lines.push(`${label} (${items.length}):`);
+      for (const item of items) {
+        lines.push(`  • ${item.file}`);
+      }
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  analyzeImpact,
+  renderImpactReport
+};

package/bin/lib/incident-feedback.js

@@ -0,0 +1,157 @@
+/**
+ * incident-feedback.js — Incident-to-Spec Feedback Loop (Item 52)
+ *
+ * Convert production incidents into requirements, NFR updates,
+ * and architecture improvements.
+ *
+ * Usage:
+ *   node bin/lib/incident-feedback.js log|analyze|report [options]
+ *
+ * State file: .jumpstart/state/incidents.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'incidents.json');
+
+const INCIDENT_SEVERITIES = ['sev1', 'sev2', 'sev3', 'sev4'];
+const INCIDENT_CATEGORIES = ['availability', 'performance', 'security', 'data-loss', 'functionality', 'ux'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    incidents: [],
+    spec_updates: []
+  };
+}
+
+function loadState(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_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');
+}
+
+/**
+ * Log a production incident.
+ *
+ * @param {object} incident - { title, severity, category, description, root_cause?, impact? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function logIncident(incident, options = {}) {
+  if (!incident || !incident.title || !incident.severity) {
+    return { success: false, error: 'title and severity are required' };
+  }
+
+  if (!INCIDENT_SEVERITIES.includes(incident.severity)) {
+    return { success: false, error: `Invalid severity. Must be one of: ${INCIDENT_SEVERITIES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const inc = {
+    id: `INC-${(state.incidents.length + 1).toString().padStart(4, '0')}`,
+    title: incident.title,
+    severity: incident.severity,
+    category: incident.category || 'functionality',
+    description: incident.description || '',
+    root_cause: incident.root_cause || null,
+    impact: incident.impact || null,
+    spec_updates_generated: false,
+    logged_at: new Date().toISOString()
+  };
+
+  state.incidents.push(inc);
+  saveState(state, stateFile);
+
+  return { success: true, incident: inc };
+}
+
+/**
+ * Analyze incident and generate spec update recommendations.
+ *
+ * @param {string} incidentId
+ * @param {object} [options]
+ * @returns {object}
+ */
+function analyzeIncident(incidentId, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const incident = state.incidents.find(i => i.id === incidentId);
+  if (!incident) return { success: false, error: `Incident not found: ${incidentId}` };
+
+  const recommendations = [];
+
+  if (incident.category === 'availability') {
+    recommendations.push({ type: 'nfr', spec: 'architecture.md', update: 'Add/update availability SLO', priority: 'high' });
+    recommendations.push({ type: 'requirement', spec: 'prd.md', update: 'Add monitoring requirement', priority: 'medium' });
+  }
+  if (incident.category === 'performance') {
+    recommendations.push({ type: 'nfr', spec: 'architecture.md', update: 'Add/update latency SLO', priority: 'high' });
+  }
+  if (incident.category === 'security') {
+    recommendations.push({ type: 'requirement', spec: 'prd.md', update: 'Add security hardening requirement', priority: 'critical' });
+    recommendations.push({ type: 'architecture', spec: 'architecture.md', update: 'Review security architecture', priority: 'high' });
+  }
+  if (incident.severity === 'sev1') {
+    recommendations.push({ type: 'architecture', spec: 'architecture.md', update: 'Add circuit breaker or failover', priority: 'critical' });
+  }
+
+  incident.spec_updates_generated = true;
+  state.spec_updates.push({
+    incident_id: incidentId,
+    recommendations,
+    generated_at: new Date().toISOString()
+  });
+  saveState(state, stateFile);
+
+  return { success: true, incident_id: incidentId, recommendations, total: recommendations.length };
+}
+
+/**
+ * Generate incident feedback report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_incidents: state.incidents.length,
+    by_severity: state.incidents.reduce((acc, i) => { acc[i.severity] = (acc[i.severity] || 0) + 1; return acc; }, {}),
+    by_category: state.incidents.reduce((acc, i) => { acc[i.category] = (acc[i.category] || 0) + 1; return acc; }, {}),
+    spec_updates_pending: state.incidents.filter(i => !i.spec_updates_generated).length,
+    total_spec_updates: state.spec_updates.length,
+    incidents: state.incidents
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  logIncident,
+  analyzeIncident,
+  generateReport,
+  INCIDENT_SEVERITIES,
+  INCIDENT_CATEGORIES
+};

package/bin/lib/integrate.js

@@ -88,7 +88,7 @@ function parseSkillFrontmatter(content) {
     result.triggers = triggerMatch[1]
       .split('\n')
       .map((l) => l.replace(/^[-*]\s*/, '').trim())
-      .filter((l) => l.length > 0 && !l.startsWith('Use when'));
+      .filter((l) => l.length > 0);
   }
 
   return result;

package/bin/lib/knowledge-graph.js

@@ -0,0 +1,122 @@
+/**
+ * knowledge-graph.js — Knowledge Graph Across Initiatives (Item 81)
+ *
+ * Reuse patterns, controls, decisions, skills, and modules
+ * across the enterprise.
+ *
+ * Usage:
+ *   node bin/lib/knowledge-graph.js add|query|report [options]
+ *
+ * State file: .jumpstart/state/knowledge-graph.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'knowledge-graph.json');
+
+const NODE_TYPES = ['pattern', 'decision', 'control', 'component', 'skill', 'module'];
+const EDGE_TYPES = ['uses', 'implements', 'depends-on', 'related-to', 'supersedes'];
+
+function defaultState() {
+  return { version: '1.0.0', nodes: [], edges: [], 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 addNode(name, type, options = {}) {
+  if (!name || !type) return { success: false, error: 'name and type are required' };
+  if (!NODE_TYPES.includes(type)) {
+    return { success: false, error: `Unknown type: ${type}. Valid: ${NODE_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const node = {
+    id: `KG-${Date.now()}`,
+    name,
+    type,
+    tags: options.tags || [],
+    metadata: options.metadata || {},
+    created_at: new Date().toISOString()
+  };
+
+  state.nodes.push(node);
+  saveState(state, stateFile);
+
+  return { success: true, node };
+}
+
+function addEdge(fromId, toId, edgeType, options = {}) {
+  if (!fromId || !toId || !edgeType) return { success: false, error: 'fromId, toId, and edgeType are required' };
+  if (!EDGE_TYPES.includes(edgeType)) {
+    return { success: false, error: `Unknown edge type: ${edgeType}. Valid: ${EDGE_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const edge = { from: fromId, to: toId, type: edgeType, created_at: new Date().toISOString() };
+  state.edges.push(edge);
+  saveState(state, stateFile);
+
+  return { success: true, edge };
+}
+
+function queryGraph(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  let nodes = state.nodes;
+  if (options.type) nodes = nodes.filter(n => n.type === options.type);
+  if (options.tag) nodes = nodes.filter(n => n.tags.includes(options.tag));
+  if (options.search) {
+    const q = options.search.toLowerCase();
+    nodes = nodes.filter(n => n.name.toLowerCase().includes(q));
+  }
+
+  return {
+    success: true,
+    nodes: nodes.length,
+    edges: state.edges.length,
+    results: nodes,
+    related_edges: state.edges.filter(e => nodes.some(n => n.id === e.from || n.id === e.to))
+  };
+}
+
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const byType = {};
+  for (const n of state.nodes) { byType[n.type] = (byType[n.type] || 0) + 1; }
+
+  return {
+    success: true,
+    total_nodes: state.nodes.length,
+    total_edges: state.edges.length,
+    by_type: byType
+  };
+}
+
+module.exports = {
+  addNode, addEdge, queryGraph, generateReport,
+  loadState, saveState, defaultState,
+  NODE_TYPES, EDGE_TYPES
+};