jumpstart-mode 1.1.11 → 1.1.13

package/bin/headless-runner.js

@@ -37,6 +37,10 @@ const { getToolsForPhase } = require('./lib/tool-schemas');
 const { createMockRegistry, createPersonaRegistry } = require('./lib/mock-responses');
 const { SimulationTracer } = require('./lib/simulation-tracer');
 
+// Usage & timeline logging (ESM — loaded dynamically)
+let _usageMod = null;
+const _usageReady = import('./lib/usage.js').then(mod => { _usageMod = mod; }).catch(() => {});
+
 // ─── Configuration ───────────────────────────────────────────────────────────
 
 const ROOT_DIR = path.join(__dirname, '..');
@@ -182,6 +186,9 @@ class HeadlessRunner {
     // Initialize tracer
     this.tracer = new SimulationTracer(this.workspaceDir, options.scenario || 'headless');
     
+    // Usage log path
+    this.usageLogPath = path.join(this.workspaceDir, '.jumpstart', 'usage-log.json');
+    
     // Initialize timeline for event recording
     this.timeline = null;
     try {
@@ -199,6 +206,10 @@ class HeadlessRunner {
           captureSubagents: true,
           captureResearch: true
         });
+        // Connect timeline to usage logger so usage events appear in timeline
+        if (_usageMod && typeof _usageMod.setUsageTimelineHook === 'function') {
+          _usageMod.setUsageTimelineHook(this.timeline);
+        }
       }).catch(() => { /* timeline module not available — ok */ });
     } catch {
       this._timelineReady = Promise.resolve();
@@ -234,8 +245,9 @@ class HeadlessRunner {
   }
   
   async setup() {
-    // Ensure timeline is ready
+    // Ensure timeline and usage modules are ready
     if (this._timelineReady) await this._timelineReady;
+    await _usageReady;
     
     // Create workspace directory structure
     const dirs = [
@@ -518,6 +530,20 @@ Be brief and supportive.`;
     const agentPrompt = this.loadAgentPrompt(agentName);
     const personaPrompt = this.loadPersonaPrompt();
     
+    // Log agent system prompt to timeline
+    if (this.timeline) {
+      this.timeline.recordEvent({
+        event_type: 'prompt_logged',
+        action: `System prompt loaded for ${agentName} (${agentPrompt.length} chars)`,
+        metadata: {
+          prompt_type: 'system',
+          agent: agentName,
+          prompt_length: agentPrompt.length,
+          prompt_preview: agentPrompt.substring(0, 200) + (agentPrompt.length > 200 ? '…' : '')
+        }
+      });
+    }
+    
     // Initialize conversation histories
     this.conversationHistory = [
       { role: 'system', content: agentPrompt }
@@ -534,6 +560,20 @@ Be brief and supportive.`;
     const startMessage = this.getAgentStartMessage(agentName);
     this.conversationHistory.push({ role: 'user', content: startMessage });
     
+    // Log activation prompt to timeline
+    if (this.timeline) {
+      this.timeline.recordEvent({
+        event_type: 'prompt_logged',
+        action: `Activation prompt sent to ${agentName}`,
+        metadata: {
+          prompt_type: 'activation',
+          agent: agentName,
+          prompt_length: startMessage.length,
+          prompt_content: startMessage
+        }
+      });
+    }
+    
     // Main conversation loop
     this.turnCount = 0;
     let sessionActive = true;
@@ -620,10 +660,30 @@ Be brief and supportive.`;
       this.timeline.flush();
     }
     
-    // Log usage
+    // Log usage to usage-log.json and console
     const usage = this.agentProvider.getUsage();
     this.log(`Usage: ${usage.totalTokens} tokens, ${usage.calls} calls`, 'info');
     
+    if (_usageMod && typeof _usageMod.logUsage === 'function') {
+      try {
+        _usageMod.logUsage(this.usageLogPath, {
+          phase: agentName,
+          agent: agentName.charAt(0).toUpperCase() + agentName.slice(1),
+          action: 'generation',
+          estimated_tokens: usage.totalTokens || 0,
+          estimated_cost_usd: (usage.totalTokens || 0) * 0.000002,
+          model: this.options.model || 'unknown',
+          metadata: {
+            turns: this.turnCount,
+            calls: usage.calls || 0,
+            status: finalStatus
+          }
+        });
+      } catch (err) {
+        this.log(`Warning: Failed to write usage log: ${err.message}`, 'warn');
+      }
+    }
+    
     return finalStatus;
   }
   

package/bin/lib/agent-checkpoint.js

@@ -0,0 +1,168 @@
+/**
+ * agent-checkpoint.js — Agent Self-Checkpoint & Resume (Item 57)
+ *
+ * Recover gracefully from interrupted runs or model failures.
+ *
+ * Usage:
+ *   node bin/lib/agent-checkpoint.js save|restore|list|clean [options]
+ *
+ * State file: .jumpstart/state/agent-checkpoints.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'agent-checkpoints.json');
+
+const CHECKPOINT_TYPES = ['phase-start', 'phase-end', 'task-start', 'task-end', 'error-recovery', 'manual'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    checkpoints: [],
+    recovery_log: []
+  };
+}
+
+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');
+}
+
+/**
+ * Save a checkpoint.
+ *
+ * @param {object} checkpoint - { agent, phase?, task?, context, type? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function saveCheckpoint(checkpoint, options = {}) {
+  if (!checkpoint || !checkpoint.agent) {
+    return { success: false, error: 'agent is required' };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const cp = {
+    id: `CP-${Date.now().toString(36).toUpperCase()}`,
+    agent: checkpoint.agent,
+    phase: checkpoint.phase || null,
+    task: checkpoint.task || null,
+    type: checkpoint.type || 'manual',
+    context: checkpoint.context || {},
+    files_snapshot: checkpoint.files_snapshot || [],
+    saved_at: new Date().toISOString()
+  };
+
+  state.checkpoints.push(cp);
+
+  // Keep only last 50 checkpoints
+  if (state.checkpoints.length > 50) {
+    state.checkpoints = state.checkpoints.slice(-50);
+  }
+
+  saveState(state, stateFile);
+
+  return { success: true, checkpoint: cp };
+}
+
+/**
+ * Restore from a checkpoint.
+ *
+ * @param {string} [checkpointId] - If omitted, restores from latest.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function restoreCheckpoint(checkpointId, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  let checkpoint;
+  if (checkpointId) {
+    checkpoint = state.checkpoints.find(c => c.id === checkpointId);
+  } else {
+    checkpoint = state.checkpoints[state.checkpoints.length - 1];
+  }
+
+  if (!checkpoint) {
+    return { success: false, error: checkpointId ? `Checkpoint not found: ${checkpointId}` : 'No checkpoints available' };
+  }
+
+  state.recovery_log.push({
+    checkpoint_id: checkpoint.id,
+    restored_at: new Date().toISOString()
+  });
+  saveState(state, stateFile);
+
+  return {
+    success: true,
+    checkpoint,
+    agent: checkpoint.agent,
+    phase: checkpoint.phase,
+    task: checkpoint.task,
+    context: checkpoint.context
+  };
+}
+
+/**
+ * List available checkpoints.
+ *
+ * @param {object} [filter] - { agent?, phase?, type? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function listCheckpoints(filter = {}, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+  let checkpoints = state.checkpoints;
+
+  if (filter.agent) checkpoints = checkpoints.filter(c => c.agent === filter.agent);
+  if (filter.phase) checkpoints = checkpoints.filter(c => c.phase === filter.phase);
+  if (filter.type) checkpoints = checkpoints.filter(c => c.type === filter.type);
+
+  return { success: true, checkpoints, total: checkpoints.length };
+}
+
+/**
+ * Clean old checkpoints.
+ *
+ * @param {object} [options] - { keep? }
+ * @returns {object}
+ */
+function cleanCheckpoints(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+  const keep = options.keep || 10;
+  const removed = Math.max(0, state.checkpoints.length - keep);
+
+  state.checkpoints = state.checkpoints.slice(-keep);
+  saveState(state, stateFile);
+
+  return { success: true, removed, remaining: state.checkpoints.length };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  saveCheckpoint,
+  restoreCheckpoint,
+  listCheckpoints,
+  cleanCheckpoints,
+  CHECKPOINT_TYPES
+};

package/bin/lib/ai-evaluation.js

@@ -0,0 +1,104 @@
+/**
+ * ai-evaluation.js — Evaluation Framework for AI Systems (Item 90)
+ *
+ * Groundedness, hallucination, safety, latency, cost,
+ * and business KPI eval packs.
+ *
+ * Usage:
+ *   node bin/lib/ai-evaluation.js evaluate|report|configure [options]
+ *
+ * State file: .jumpstart/state/ai-evaluation.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'ai-evaluation.json');
+
+const EVAL_DIMENSIONS = ['groundedness', 'hallucination', 'safety', 'latency', 'cost', 'relevance', 'coherence'];
+
+function defaultState() {
+  return { version: '1.0.0', evaluations: [], benchmarks: [], 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 evaluate(name, scores, options = {}) {
+  if (!name || !scores) return { success: false, error: 'name and scores are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const evaluation = {
+    id: `EVAL-${Date.now()}`,
+    name,
+    scores,
+    overall: Math.round(Object.values(scores).reduce((a, b) => a + b, 0) / Object.keys(scores).length),
+    model: options.model || null,
+    use_case: options.use_case || null,
+    evaluated_at: new Date().toISOString()
+  };
+
+  state.evaluations.push(evaluation);
+  saveState(state, stateFile);
+
+  return { success: true, evaluation };
+}
+
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const avgScores = {};
+  for (const dim of EVAL_DIMENSIONS) {
+    const vals = state.evaluations.filter(e => e.scores[dim] !== undefined).map(e => e.scores[dim]);
+    avgScores[dim] = vals.length > 0 ? Math.round(vals.reduce((a, b) => a + b, 0) / vals.length) : null;
+  }
+
+  return {
+    success: true,
+    total_evaluations: state.evaluations.length,
+    average_scores: avgScores,
+    evaluations: state.evaluations
+  };
+}
+
+function configureBenchmark(name, thresholds, options = {}) {
+  if (!name || !thresholds) return { success: false, error: 'name and thresholds are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const benchmark = {
+    id: `BENCH-${Date.now()}`,
+    name,
+    thresholds,
+    created_at: new Date().toISOString()
+  };
+
+  state.benchmarks.push(benchmark);
+  saveState(state, stateFile);
+
+  return { success: true, benchmark };
+}
+
+module.exports = {
+  evaluate, generateReport, configureBenchmark,
+  loadState, saveState, defaultState,
+  EVAL_DIMENSIONS
+};

package/bin/lib/ai-intake.js

@@ -0,0 +1,152 @@
+/**
+ * ai-intake.js — AI Use Case Intake Templates (Item 34)
+ *
+ * Standardize enterprise intake for business value, data sensitivity,
+ * model risk, and operating model.
+ *
+ * Usage:
+ *   node bin/lib/ai-intake.js create|list|assess [options]
+ *
+ * State file: .jumpstart/state/ai-intake.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'ai-intake.json');
+
+const INTAKE_SECTIONS = ['business-value', 'data-sensitivity', 'model-risk', 'operating-model', 'ethical-review', 'compliance-requirements'];
+
+const RISK_TIERS = [
+  { tier: 1, label: 'Low Risk', description: 'No PII, internal tools, low business impact' },
+  { tier: 2, label: 'Medium Risk', description: 'Some PII, customer-facing, moderate impact' },
+  { tier: 3, label: 'High Risk', description: 'Sensitive data, critical decisions, high impact' },
+  { tier: 4, label: 'Critical Risk', description: 'Regulated domain, autonomous decisions, severe impact' }
+];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    intakes: []
+  };
+}
+
+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');
+}
+
+/**
+ * Create a new AI use case intake.
+ *
+ * @param {object} intake - { name, description, sponsor, business_value, data_types[], model_type? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function createIntake(intake, options = {}) {
+  if (!intake || !intake.name || !intake.description) {
+    return { success: false, error: 'name and description are required' };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  // Auto-assess risk tier
+  const dataTypes = intake.data_types || [];
+  let riskTier = 1;
+  if (dataTypes.some(dt => ['PHI', 'PCI'].includes(dt))) riskTier = 4;
+  else if (dataTypes.some(dt => ['PII', 'credentials'].includes(dt))) riskTier = 3;
+  else if (dataTypes.some(dt => ['business-sensitive', 'internal'].includes(dt))) riskTier = 2;
+
+  const newIntake = {
+    id: `AI-${(state.intakes.length + 1).toString().padStart(3, '0')}`,
+    name: intake.name,
+    description: intake.description,
+    sponsor: intake.sponsor || null,
+    business_value: intake.business_value || '',
+    data_types: dataTypes,
+    model_type: intake.model_type || null,
+    risk_tier: riskTier,
+    risk_label: RISK_TIERS[riskTier - 1].label,
+    status: 'draft',
+    sections_completed: [],
+    created_at: new Date().toISOString()
+  };
+
+  state.intakes.push(newIntake);
+  saveState(state, stateFile);
+
+  return { success: true, intake: newIntake };
+}
+
+/**
+ * List intakes with optional filter.
+ *
+ * @param {object} [filter]
+ * @param {object} [options]
+ * @returns {object}
+ */
+function listIntakes(filter = {}, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+  let intakes = state.intakes;
+
+  if (filter.status) intakes = intakes.filter(i => i.status === filter.status);
+  if (filter.risk_tier) intakes = intakes.filter(i => i.risk_tier === filter.risk_tier);
+
+  return { success: true, intakes, total: intakes.length };
+}
+
+/**
+ * Assess intake completeness.
+ *
+ * @param {string} intakeId
+ * @param {object} [options]
+ * @returns {object}
+ */
+function assessIntake(intakeId, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const intake = state.intakes.find(i => i.id === intakeId);
+  if (!intake) return { success: false, error: `Intake not found: ${intakeId}` };
+
+  const completedSections = intake.sections_completed || [];
+  const missingSections = INTAKE_SECTIONS.filter(s => !completedSections.includes(s));
+  const completeness = Math.round((completedSections.length / INTAKE_SECTIONS.length) * 100);
+
+  return {
+    success: true,
+    intake_id: intakeId,
+    completeness,
+    completed_sections: completedSections,
+    missing_sections: missingSections,
+    risk_tier: intake.risk_tier,
+    ready_for_review: completeness >= 80
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  createIntake,
+  listIntakes,
+  assessIntake,
+  INTAKE_SECTIONS,
+  RISK_TIERS
+};

package/bin/lib/ambiguity-heatmap.js

@@ -0,0 +1,152 @@
+/**
+ * ambiguity-heatmap.js — Requirement Ambiguity Heatmap (Item 71)
+ *
+ * Highlight vague language, missing constraints, undefined terms,
+ * and assumption density.
+ *
+ * Usage:
+ *   node bin/lib/ambiguity-heatmap.js scan|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const VAGUE_TERMS = [
+  'should', 'could', 'might', 'possibly', 'maybe', 'approximately',
+  'reasonable', 'appropriate', 'adequate', 'sufficient', 'as needed',
+  'etc', 'and so on', 'as appropriate', 'in a timely manner',
+  'user-friendly', 'intuitive', 'seamless', 'robust', 'scalable',
+  'performant', 'efficient', 'flexible', 'simple', 'easy'
+];
+
+const MISSING_CONSTRAINT_PATTERNS = [
+  { pattern: /\bfast\b/gi, suggestion: 'Define specific latency target (e.g., <200ms p95)' },
+  { pattern: /\bsecure\b/gi, suggestion: 'Specify security controls (encryption, auth, audit)' },
+  { pattern: /\bhigh availability\b/gi, suggestion: 'Define uptime SLA (e.g., 99.9%)' },
+  { pattern: /\blarge scale\b/gi, suggestion: 'Quantify expected load (users, requests/sec)' },
+  { pattern: /\breal[- ]?time\b/gi, suggestion: 'Define latency requirement (e.g., <1s, <100ms)' }
+];
+
+/**
+ * Scan text for ambiguity indicators.
+ */
+function scanAmbiguity(text, options = {}) {
+  if (!text) return { success: false, error: 'Text content is required' };
+
+  const lines = text.split('\n');
+  const findings = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    // Check vague terms
+    for (const term of VAGUE_TERMS) {
+      const regex = new RegExp(`\\b${term}\\b`, 'gi');
+      const matches = line.match(regex);
+      if (matches) {
+        findings.push({
+          type: 'vague_language',
+          term,
+          line: lineNum,
+          severity: 'medium',
+          context: line.trim().substring(0, 100)
+        });
+      }
+    }
+
+    // Check missing constraints
+    for (const { pattern, suggestion } of MISSING_CONSTRAINT_PATTERNS) {
+      if (pattern.test(line)) {
+        findings.push({
+          type: 'missing_constraint',
+          line: lineNum,
+          severity: 'high',
+          suggestion,
+          context: line.trim().substring(0, 100)
+        });
+        // Reset regex lastIndex
+        pattern.lastIndex = 0;
+      }
+    }
+  }
+
+  // Check for undefined terms (capitalized terms that may be domain concepts)
+  const definedTerms = new Set();
+  const usedTerms = new Set();
+  for (const line of lines) {
+    const defs = line.match(/^#+\s+(.+)/);
+    if (defs) definedTerms.add(defs[1].trim().toLowerCase());
+
+    const caps = line.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g);
+    if (caps) caps.forEach(t => usedTerms.add(t.toLowerCase()));
+  }
+
+  // Assumption density
+  const assumptions = (text.match(/\bassume[ds]?\b|\bassuming\b|\bassumption/gi) || []).length;
+
+  const totalLines = lines.filter(l => l.trim().length > 0).length;
+
+  return {
+    success: true,
+    total_findings: findings.length,
+    findings: findings.slice(0, options.limit || 50),
+    metrics: {
+      vague_terms: findings.filter(f => f.type === 'vague_language').length,
+      missing_constraints: findings.filter(f => f.type === 'missing_constraint').length,
+      assumption_count: assumptions,
+      ambiguity_density: totalLines > 0 ? Math.round((findings.length / totalLines) * 100) : 0
+    }
+  };
+}
+
+/**
+ * Scan a file for ambiguity.
+ */
+function scanFile(filePath, options = {}) {
+  if (!fs.existsSync(filePath)) {
+    return { success: false, error: `File not found: ${filePath}` };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = scanAmbiguity(content, options);
+  result.file = filePath;
+  return result;
+}
+
+/**
+ * Generate ambiguity heatmap report.
+ */
+function generateHeatmap(root, options = {}) {
+  const specsDir = path.join(root, 'specs');
+  const results = [];
+
+  if (fs.existsSync(specsDir)) {
+    for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.md'))) {
+      const fp = path.join(specsDir, f);
+      const result = scanFile(fp, options);
+      if (result.success) {
+        results.push({ file: f, ...result.metrics, total_findings: result.total_findings });
+      }
+    }
+  }
+
+  results.sort((a, b) => b.ambiguity_density - a.ambiguity_density);
+
+  return {
+    success: true,
+    files_scanned: results.length,
+    results,
+    overall: {
+      total_findings: results.reduce((s, r) => s + r.total_findings, 0),
+      highest_density_file: results.length > 0 ? results[0].file : null
+    }
+  };
+}
+
+module.exports = {
+  scanAmbiguity, scanFile, generateHeatmap,
+  VAGUE_TERMS, MISSING_CONSTRAINT_PATTERNS
+};