jumpstart-mode 1.1.12 → 1.1.13

package/bin/lib/risk-register.js

@@ -0,0 +1,211 @@
+/**
+ * risk-register.js — Risk Register Generation & Tracking (Item 29)
+ *
+ * Create, update, and monitor business, delivery, security,
+ * and operational risks.
+ *
+ * Usage:
+ *   node bin/lib/risk-register.js add|update|list|report [options]
+ *
+ * State file: .jumpstart/state/risk-register.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'risk-register.json');
+
+const RISK_CATEGORIES = ['business', 'delivery', 'security', 'operational', 'compliance', 'technical'];
+const RISK_LIKELIHOODS = ['rare', 'unlikely', 'possible', 'likely', 'almost-certain'];
+const RISK_IMPACTS = ['negligible', 'minor', 'moderate', 'major', 'critical'];
+const RISK_STATUSES = ['identified', 'mitigating', 'accepted', 'resolved', 'closed'];
+
+const RISK_SCORE_MATRIX = {
+  'rare': { negligible: 1, minor: 2, moderate: 3, major: 4, critical: 5 },
+  'unlikely': { negligible: 2, minor: 4, moderate: 6, major: 8, critical: 10 },
+  'possible': { negligible: 3, minor: 6, moderate: 9, major: 12, critical: 15 },
+  'likely': { negligible: 4, minor: 8, moderate: 12, major: 16, critical: 20 },
+  'almost-certain': { negligible: 5, minor: 10, moderate: 15, major: 20, critical: 25 }
+};
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    risks: [],
+    mitigations: []
+  };
+}
+
+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');
+}
+
+/**
+ * Add a new risk.
+ *
+ * @param {object} risk - { title, category, description, likelihood, impact, owner?, mitigation? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function addRisk(risk, options = {}) {
+  if (!risk || !risk.title || !risk.description) {
+    return { success: false, error: 'title and description are required' };
+  }
+
+  const category = (risk.category || 'technical').toLowerCase();
+  if (!RISK_CATEGORIES.includes(category)) {
+    return { success: false, error: `Invalid category. Must be one of: ${RISK_CATEGORIES.join(', ')}` };
+  }
+
+  const likelihood = (risk.likelihood || 'possible').toLowerCase();
+  const impact = (risk.impact || 'moderate').toLowerCase();
+
+  if (!RISK_LIKELIHOODS.includes(likelihood)) {
+    return { success: false, error: `Invalid likelihood. Must be one of: ${RISK_LIKELIHOODS.join(', ')}` };
+  }
+  if (!RISK_IMPACTS.includes(impact)) {
+    return { success: false, error: `Invalid impact. Must be one of: ${RISK_IMPACTS.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const score = RISK_SCORE_MATRIX[likelihood][impact];
+
+  const newRisk = {
+    id: `RISK-${(state.risks.length + 1).toString().padStart(3, '0')}`,
+    title: risk.title,
+    description: risk.description,
+    category,
+    likelihood,
+    impact,
+    score,
+    status: 'identified',
+    owner: risk.owner || null,
+    mitigation: risk.mitigation || null,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString()
+  };
+
+  state.risks.push(newRisk);
+  saveState(state, stateFile);
+
+  return { success: true, risk: newRisk };
+}
+
+/**
+ * Update a risk's status or details.
+ *
+ * @param {string} riskId
+ * @param {object} updates
+ * @param {object} [options]
+ * @returns {object}
+ */
+function updateRisk(riskId, updates, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const risk = state.risks.find(r => r.id === riskId);
+  if (!risk) return { success: false, error: `Risk not found: ${riskId}` };
+
+  if (updates.status && RISK_STATUSES.includes(updates.status)) risk.status = updates.status;
+  if (updates.mitigation) risk.mitigation = updates.mitigation;
+  if (updates.owner) risk.owner = updates.owner;
+  if (updates.likelihood && RISK_LIKELIHOODS.includes(updates.likelihood)) {
+    risk.likelihood = updates.likelihood;
+    risk.score = RISK_SCORE_MATRIX[risk.likelihood][risk.impact];
+  }
+  if (updates.impact && RISK_IMPACTS.includes(updates.impact)) {
+    risk.impact = updates.impact;
+    risk.score = RISK_SCORE_MATRIX[risk.likelihood][risk.impact];
+  }
+
+  risk.updated_at = new Date().toISOString();
+  saveState(state, stateFile);
+
+  return { success: true, risk };
+}
+
+/**
+ * List risks with optional filter.
+ *
+ * @param {object} [filter]
+ * @param {object} [options]
+ * @returns {object}
+ */
+function listRisks(filter = {}, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+  let risks = state.risks;
+
+  if (filter.category) risks = risks.filter(r => r.category === filter.category);
+  if (filter.status) risks = risks.filter(r => r.status === filter.status);
+  if (filter.minScore) risks = risks.filter(r => r.score >= filter.minScore);
+
+  return { success: true, risks, total: risks.length };
+}
+
+/**
+ * Generate risk report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const byCategory = {};
+  const byStatus = {};
+  let totalScore = 0;
+
+  for (const risk of state.risks) {
+    byCategory[risk.category] = (byCategory[risk.category] || 0) + 1;
+    byStatus[risk.status] = (byStatus[risk.status] || 0) + 1;
+    totalScore += risk.score;
+  }
+
+  const highRisks = state.risks.filter(r => r.score >= 15);
+  const unmitigated = state.risks.filter(r => !r.mitigation && r.status === 'identified');
+
+  return {
+    success: true,
+    total_risks: state.risks.length,
+    by_category: byCategory,
+    by_status: byStatus,
+    average_score: state.risks.length > 0 ? Math.round(totalScore / state.risks.length) : 0,
+    high_risks: highRisks.length,
+    unmitigated: unmitigated.length,
+    top_risks: state.risks.sort((a, b) => b.score - a.score).slice(0, 5)
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  addRisk,
+  updateRisk,
+  listRisks,
+  generateReport,
+  RISK_CATEGORIES,
+  RISK_LIKELIHOODS,
+  RISK_IMPACTS,
+  RISK_STATUSES,
+  RISK_SCORE_MATRIX
+};

package/bin/lib/role-approval.js

@@ -0,0 +1,249 @@
+/**
+ * role-approval.js — Human Approval Workflows with Roles
+ *
+ * Supports named approvers by role: product, architect, security, legal,
+ * platform owner. Tracks multi-role approval chains for artifacts.
+ *
+ * Usage:
+ *   node bin/lib/role-approval.js assign|approve|status [options]
+ *
+ * State file: .jumpstart/state/role-approvals.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'role-approvals.json');
+
+const APPROVER_ROLES = ['product', 'architect', 'security', 'legal', 'platform', 'qa', 'custom'];
+
+/**
+ * Default role approval store.
+ * @returns {object}
+ */
+function defaultRoleApprovalStore() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    workflows: {}  // artifact_path → workflow
+  };
+}
+
+/**
+ * Load the role approval store from disk.
+ * @param {string} [stateFile]
+ * @returns {object}
+ */
+function loadRoleApprovalStore(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) {
+    return defaultRoleApprovalStore();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return defaultRoleApprovalStore();
+  }
+}
+
+/**
+ * Save the role approval store to disk.
+ * @param {object} store
+ * @param {string} [stateFile]
+ */
+function saveRoleApprovalStore(store, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  store.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(store, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Assign approvers to an artifact.
+ *
+ * @param {string} artifactPath - Relative path to the artifact.
+ * @param {object[]} approvers - Array of { role, name, required? }.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function assignApprovers(artifactPath, approvers, options = {}) {
+  if (!artifactPath) {
+    return { success: false, error: 'artifactPath is required' };
+  }
+  if (!Array.isArray(approvers) || approvers.length === 0) {
+    return { success: false, error: 'approvers array is required and must not be empty' };
+  }
+
+  for (const a of approvers) {
+    const role = (a.role || '').toLowerCase();
+    if (!APPROVER_ROLES.includes(role)) {
+      return { success: false, error: `Invalid role "${a.role}". Must be one of: ${APPROVER_ROLES.join(', ')}` };
+    }
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const store = loadRoleApprovalStore(stateFile);
+
+  const workflow = {
+    artifact: artifactPath,
+    created_at: new Date().toISOString(),
+    last_updated: new Date().toISOString(),
+    status: 'pending',
+    approvers: approvers.map(a => ({
+      role: a.role.toLowerCase(),
+      name: a.name || null,
+      required: a.required !== false,
+      status: 'pending',  // pending | approved | rejected | skipped
+      approved_at: null,
+      comment: null
+    }))
+  };
+
+  store.workflows[artifactPath] = workflow;
+  saveRoleApprovalStore(store, stateFile);
+
+  return {
+    success: true,
+    artifact: artifactPath,
+    approvers: workflow.approvers,
+    total_required: workflow.approvers.filter(a => a.required).length
+  };
+}
+
+/**
+ * Record an approval (or rejection) by a specific role.
+ *
+ * @param {string} artifactPath
+ * @param {string} role
+ * @param {string} action - 'approve' | 'reject'
+ * @param {object} [options] - { approverName?, comment?, stateFile? }
+ * @returns {object}
+ */
+function recordRoleAction(artifactPath, role, action, options = {}) {
+  if (!artifactPath || !role || !action) {
+    return { success: false, error: 'artifactPath, role, and action are required' };
+  }
+
+  if (!['approve', 'reject'].includes(action)) {
+    return { success: false, error: 'action must be "approve" or "reject"' };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const store = loadRoleApprovalStore(stateFile);
+
+  const workflow = store.workflows[artifactPath];
+  if (!workflow) {
+    return { success: false, error: `No approval workflow found for: ${artifactPath}` };
+  }
+
+  const normalizedRole = role.toLowerCase();
+  const approver = workflow.approvers.find(a => a.role === normalizedRole);
+  if (!approver) {
+    return { success: false, error: `Role "${role}" not assigned to this artifact` };
+  }
+
+  approver.status = action === 'approve' ? 'approved' : 'rejected';
+  approver.approved_at = new Date().toISOString();
+  if (options.approverName) approver.name = options.approverName;
+  if (options.comment) approver.comment = options.comment;
+  workflow.last_updated = new Date().toISOString();
+
+  // Update overall workflow status
+  const required = workflow.approvers.filter(a => a.required);
+  const allApproved = required.every(a => a.status === 'approved');
+  const anyRejected = required.some(a => a.status === 'rejected');
+
+  if (anyRejected) {
+    workflow.status = 'rejected';
+  } else if (allApproved) {
+    workflow.status = 'approved';
+  } else {
+    workflow.status = 'pending';
+  }
+
+  saveRoleApprovalStore(store, stateFile);
+
+  return {
+    success: true,
+    artifact: artifactPath,
+    role: normalizedRole,
+    action,
+    workflow_status: workflow.status,
+    pending_roles: workflow.approvers.filter(a => a.required && a.status === 'pending').map(a => a.role)
+  };
+}
+
+/**
+ * Get the approval status of an artifact.
+ *
+ * @param {string} artifactPath
+ * @param {object} [options]
+ * @returns {object}
+ */
+function getApprovalStatus(artifactPath, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const store = loadRoleApprovalStore(stateFile);
+
+  const workflow = store.workflows[artifactPath];
+  if (!workflow) {
+    return {
+      success: true,
+      artifact: artifactPath,
+      has_workflow: false,
+      message: 'No approval workflow assigned'
+    };
+  }
+
+  const pending = workflow.approvers.filter(a => a.required && a.status === 'pending').map(a => a.role);
+  const approved = workflow.approvers.filter(a => a.status === 'approved').map(a => a.role);
+  const rejected = workflow.approvers.filter(a => a.status === 'rejected').map(a => a.role);
+
+  return {
+    success: true,
+    artifact: artifactPath,
+    has_workflow: true,
+    status: workflow.status,
+    pending_roles: pending,
+    approved_roles: approved,
+    rejected_roles: rejected,
+    approvers: workflow.approvers,
+    fully_approved: workflow.status === 'approved'
+  };
+}
+
+/**
+ * List all approval workflows.
+ *
+ * @param {object} [filter] - { status? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function listApprovalWorkflows(filter = {}, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const store = loadRoleApprovalStore(stateFile);
+
+  let workflows = Object.values(store.workflows);
+
+  if (filter.status) {
+    workflows = workflows.filter(w => w.status === filter.status);
+  }
+
+  return { success: true, workflows, total: workflows.length };
+}
+
+module.exports = {
+  APPROVER_ROLES,
+  loadRoleApprovalStore,
+  saveRoleApprovalStore,
+  defaultRoleApprovalStore,
+  assignApprovers,
+  recordRoleAction,
+  getApprovalStatus,
+  listApprovalWorkflows
+};

package/bin/lib/role-views.js

@@ -0,0 +1,142 @@
+/**
+ * role-views.js — Role-Based Project Views (Item 62)
+ *
+ * Same project data, different role-based lenses for
+ * executive, architect, product, and engineer audiences.
+ *
+ * Usage:
+ *   node bin/lib/role-views.js generate|list [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROLES = ['executive', 'architect', 'product', 'engineer'];
+
+const ROLE_FOCUS = {
+  executive: {
+    label: 'Executive View',
+    focus: ['timeline', 'risks', 'budget', 'milestones', 'decisions'],
+    exclude: ['code_details', 'test_coverage', 'api_contracts']
+  },
+  architect: {
+    label: 'Architect View',
+    focus: ['components', 'data_model', 'api_contracts', 'decisions', 'tech_stack', 'nfrs'],
+    exclude: ['budget', 'stakeholder_comms']
+  },
+  product: {
+    label: 'Product View',
+    focus: ['stories', 'acceptance_criteria', 'personas', 'journeys', 'scope', 'priorities'],
+    exclude: ['api_contracts', 'data_model', 'test_coverage']
+  },
+  engineer: {
+    label: 'Engineer View',
+    focus: ['tasks', 'api_contracts', 'data_model', 'test_coverage', 'tech_stack', 'code_details'],
+    exclude: ['budget', 'stakeholder_comms', 'personas']
+  }
+};
+
+/**
+ * Generate a role-specific view of the project.
+ */
+function generateView(root, role, options = {}) {
+  if (!ROLES.includes(role)) {
+    return { success: false, error: `Unknown role: ${role}. Valid roles: ${ROLES.join(', ')}` };
+  }
+
+  const config = ROLE_FOCUS[role];
+  const view = {
+    role,
+    label: config.label,
+    generated_at: new Date().toISOString(),
+    focus_areas: config.focus,
+    excluded_areas: config.exclude,
+    sections: {}
+  };
+
+  // Gather 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);
+    }
+  }
+  view.sections.available_specs = availableSpecs;
+
+  // Phase status
+  const stateFile = path.join(root, '.jumpstart', 'state', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      view.sections.phase_status = {
+        current_phase: state.current_phase || 0,
+        current_agent: state.current_agent || null
+      };
+    } catch { view.sections.phase_status = { current_phase: 0 }; }
+  } else {
+    view.sections.phase_status = { current_phase: 0 };
+  }
+
+  // Risk summary (if relevant to role)
+  if (config.focus.includes('risks')) {
+    const riskFile = path.join(root, '.jumpstart', 'state', 'risk-register.json');
+    if (fs.existsSync(riskFile)) {
+      try {
+        const risks = JSON.parse(fs.readFileSync(riskFile, 'utf8'));
+        view.sections.risks = {
+          total: (risks.risks || []).length,
+          high: (risks.risks || []).filter(r => r.score >= 15).length
+        };
+      } catch { view.sections.risks = { total: 0, high: 0 }; }
+    } else {
+      view.sections.risks = { total: 0, high: 0 };
+    }
+  }
+
+  return { success: true, view };
+}
+
+/**
+ * List all available roles and their focus areas.
+ */
+function listRoles() {
+  return {
+    success: true,
+    roles: ROLES.map(r => ({
+      id: r,
+      label: ROLE_FOCUS[r].label,
+      focus: ROLE_FOCUS[r].focus,
+      exclude: ROLE_FOCUS[r].exclude
+    }))
+  };
+}
+
+/**
+ * Generate summary for a specific role.
+ */
+function generateRoleSummary(root, role) {
+  const viewResult = generateView(root, role);
+  if (!viewResult.success) return viewResult;
+
+  const view = viewResult.view;
+  const summary = {
+    role,
+    label: view.label,
+    current_phase: view.sections.phase_status ? view.sections.phase_status.current_phase : 0,
+    specs_count: view.sections.available_specs ? view.sections.available_specs.length : 0,
+    generated_at: view.generated_at
+  };
+
+  return { success: true, summary };
+}
+
+module.exports = {
+  generateView,
+  listRoles,
+  generateRoleSummary,
+  ROLES,
+  ROLE_FOCUS
+};