@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/jobs.cjs

@@ -0,0 +1,2015 @@
+/**
+ * Jobs — Job file parse, step update, file move, find, header update,
+ * step insertion, gap-fix sections, milestone job creation, and visibility/polish
+ *
+ * Provides the programmatic foundation for all job lifecycle operations.
+ * Parses markdown job files into structured JSON, updates individual step
+ * statuses, moves files between lifecycle directories, locates job files
+ * by version, updates header fields in-place, inserts new steps dynamically,
+ * manages gap-fix cycle sections (both milestone-level and phase-level),
+ * generates milestone job files from roadmap phase analysis, lists jobs,
+ * cancels jobs, runs health checks, previews dry runs, and generates
+ * job summaries.
+ *
+ * Exports: parseJobFile, updateJobStep, moveJobFile, findJobFile,
+ *          updateJobHeader, insertJobSteps, buildGapFixSteps,
+ *          buildPhaseGapFixSteps, insertGapFixSection,
+ *          insertPhaseGapFixSection, updatePhaseFixCycleHeader,
+ *          generateMilestoneSteps, buildJobFileContent, listJobs,
+ *          cancelJob, recordStartShas, rollbackJob,
+ *          healthCheck, dryRunPreview, generateJobSummary,
+ *          cmdJobsParse, cmdJobsUpdateStep, cmdJobsMove,
+ *          cmdJobsFindJob, cmdJobsUpdateHeader, cmdJobsInsertSteps,
+ *          cmdJobsInsertGapFixSection, cmdJobsInsertPhaseGapFix,
+ *          cmdJobsCreateMilestone, cmdJobsMilestonePreview,
+ *          cmdJobsListJobs, cmdJobsCancelJob,
+ *          cmdJobsRecordStartShas, cmdJobsRollback,
+ *          cmdJobsHealthCheck, cmdJobsDryRun, cmdJobsGenerateSummary
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { output, error, getProjectRoot } = require('./core.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Known DGS command patterns for step validation */
+const KNOWN_COMMANDS = new Set([
+  'plan-phase',
+  'execute-phase',
+  'verify-work',
+  'map-codebase',
+  'audit-milestone',
+  'audit-phase',
+  'complete-milestone',
+  'plan-milestone-gaps',
+  'discuss-phase',
+  'research-phase',
+  'verify-phase',
+]);
+
+/** Required header fields */
+const REQUIRED_FIELDS = ['Version', 'Created', 'Status', 'Check'];
+
+/** Maximum error message length on step lines */
+const MAX_ERROR_LENGTH = 120;
+
+// ─── v2-aware Path Resolution ────────────────────────────────────────────────
+
+/**
+ * Resolve the project root directory for milestone/roadmap operations.
+ * Uses getProjectRoot (v2-aware) with a fallback to getPlanningRoot (v1).
+ * Returns an absolute path in all cases.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Absolute path to project root
+ */
+function resolveProjectRoot(cwd) {
+  try {
+    const projRoot = getProjectRoot(cwd);
+    return path.isAbsolute(projRoot) ? projRoot : path.join(cwd, projRoot);
+  } catch {
+    return getPlanningRoot(cwd);
+  }
+}
+
+/** Checkbox marker to status mapping */
+const MARKER_TO_STATUS = {
+  'x': 'completed',
+  '>': 'in-progress',
+  '!': 'failed',
+  ' ': 'pending',
+};
+
+/** Status to checkbox marker mapping */
+const STATUS_TO_MARKER = {
+  'completed': 'x',
+  'in-progress': '>',
+  'failed': '!',
+  'pending': ' ',
+};
+
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+
+/**
+ * Parse header fields from job file content.
+ * @param {string} content - Raw file content
+ * @returns {Object} Parsed header fields { version, created, status, check }
+ * @throws {Error} If a required field is missing
+ */
+function parseHeader(content) {
+  const fields = {};
+
+  const versionMatch = content.match(/^\*\*Version:\*\*\s*(.+)$/m);
+  if (versionMatch) fields.version = versionMatch[1].trim();
+
+  const createdMatch = content.match(/^\*\*Created:\*\*\s*(.+)$/m);
+  if (createdMatch) fields.created = createdMatch[1].trim();
+
+  const statusMatch = content.match(/^\*\*Status:\*\*\s*(.+)$/m);
+  if (statusMatch) fields.status = statusMatch[1].trim();
+
+  const checkMatch = content.match(/^\*\*Check:\*\*\s*(.+)$/m);
+  if (checkMatch) {
+    const val = checkMatch[1].trim().toLowerCase();
+    fields.check = val === 'true';
+  }
+
+  // Optional: Created_by field (not required for backward compat)
+  const createdByMatch = content.match(/^\*\*Created_by:\*\*\s*(.+)$/m);
+  if (createdByMatch) fields.created_by = createdByMatch[1].trim();
+
+  // Validate required fields
+  for (const field of REQUIRED_FIELDS) {
+    const key = field.toLowerCase();
+    if (fields[key] === undefined) {
+      throw new Error(`Missing required field: ${field}`);
+    }
+  }
+
+  return fields;
+}
+
+/**
+ * Parse a single step line into structured data.
+ * @param {string} line - The step line (e.g., `- [x] \`/dgs:plan-phase 41\` -- completed ...`)
+ * @param {number} index - Zero-based step index
+ * @returns {Object|null} Parsed step object or null if line is not a step
+ */
+function parseStepLine(line, index) {
+  // Match: - [marker] `/dgs:command args` [— annotation]
+  const stepRegex = /^-\s*\[([x >!])\]\s*`\/dgs:([^\s`]+)(?:\s+([^`]*))?`(?:\s*\u2014\s*(.+))?$/;
+  const match = line.match(stepRegex);
+  if (!match) return null;
+
+  const marker = match[1];
+  const command = match[2];
+  const args = (match[3] || '').trim();
+  const annotation = match[4] || null;
+  const raw = `/dgs:${command}${args ? ' ' + args : ''}`;
+
+  const status = MARKER_TO_STATUS[marker] || 'pending';
+
+  let timestamp = null;
+  let stepError = null;
+
+  if (annotation) {
+    // Parse annotation: "completed|failed|started <ISO timestamp>[: error message]"
+    const annoRegex = /^(?:completed|failed|started)\s+(\d{4}-\d{2}-\d{2}T[\d:.]+Z)(?::\s*(.+))?$/;
+    const annoMatch = annotation.match(annoRegex);
+    if (annoMatch) {
+      timestamp = annoMatch[1];
+      stepError = annoMatch[2] || null;
+    }
+  }
+
+  const step = {
+    index,
+    status,
+    command,
+    args,
+    raw,
+    timestamp,
+    error: stepError,
+  };
+
+  // Add warning for unrecognized commands
+  if (!KNOWN_COMMANDS.has(command)) {
+    step.warning = `Unrecognized command: ${command}`;
+  }
+
+  return step;
+}
+
+/**
+ * Build a step line from structured data.
+ * @param {Object} step - Step object with command, args
+ * @param {string} status - New status
+ * @param {Object} [options] - { timestamp, error }
+ * @returns {string} Formatted step line
+ */
+function buildStepLine(step, status, options) {
+  const opts = options || {};
+  const marker = STATUS_TO_MARKER[status] || ' ';
+  let line = `- [${marker}] \`/dgs:${step.command}${step.args ? ' ' + step.args : ''}\``;
+
+  if (status === 'completed' && opts.timestamp) {
+    line += ` \u2014 completed ${opts.timestamp}`;
+  } else if (status === 'in-progress' && opts.timestamp) {
+    line += ` \u2014 started ${opts.timestamp}`;
+  } else if (status === 'failed' && opts.timestamp) {
+    let errorMsg = opts.error || '';
+    if (errorMsg.length > MAX_ERROR_LENGTH) {
+      errorMsg = errorMsg.substring(0, MAX_ERROR_LENGTH) + '...';
+    }
+    line += ` \u2014 failed ${opts.timestamp}`;
+    if (errorMsg) {
+      line += `: ${errorMsg}`;
+    }
+  }
+
+  return line;
+}
+
+// ─── Exported Functions ─────────────────────────────────────────────────────
+
+/**
+ * Parse a job markdown file into structured JSON.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @returns {Object} Structured job data with steps and computed fields
+ * @throws {Error} On missing file, missing required fields, or malformed content
+ */
+function parseJobFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Job file not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const header = parseHeader(content);
+
+  // Parse optional StartShas header (defaults to null for backwards compat)
+  const startShasMatch = content.match(/^\*\*StartShas:\*\*\s*(.+)$/m);
+  let startShas = null;
+  if (startShasMatch) {
+    try {
+      startShas = JSON.parse(startShasMatch[1].trim());
+    } catch {
+      // Malformed JSON — treat as absent
+    }
+  }
+
+  // Parse optional GapFixCycle header (defaults to 0 for backwards compat)
+  const gapFixMatch = content.match(/^\*\*GapFixCycle:\*\*\s*(\d+)$/m);
+  const gapFixCycle = gapFixMatch ? parseInt(gapFixMatch[1], 10) : 0;
+
+  // Parse optional PhaseFixCycle header (format: "N:phase_number")
+  const phaseFixMatch = content.match(/^\*\*PhaseFixCycle:\*\*\s*(\d+):(\S+)$/m);
+  const phaseFixCycle = phaseFixMatch ? parseInt(phaseFixMatch[1], 10) : 0;
+  const phaseFixCyclePhase = phaseFixMatch ? phaseFixMatch[2] : null;
+
+  // Parse steps from lines
+  const lines = content.split('\n');
+  const steps = [];
+  let stepIndex = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepIndex);
+      if (step) {
+        steps.push(step);
+        stepIndex++;
+      }
+    }
+  }
+
+  // Compute aggregate fields
+  const stepCount = steps.length;
+  const completedCount = steps.filter(s => s.status === 'completed').length;
+  const failedCount = steps.filter(s => s.status === 'failed').length;
+  const inProgressCount = steps.filter(s => s.status === 'in-progress').length;
+
+  // nextStepIndex: first pending step, or null if all done/empty
+  const nextPending = steps.find(s => s.status === 'pending');
+  const nextStepIndex = nextPending ? nextPending.index : null;
+
+  // Progress: percentage of completed steps (100 if no steps)
+  const progress = stepCount === 0 ? 100 : Math.round((completedCount / stepCount) * 100);
+
+  return {
+    version: header.version,
+    created: header.created,
+    created_by: header.created_by || null,
+    status: header.status,
+    check: header.check,
+    startShas,
+    gapFixCycle,
+    phaseFixCycle,
+    phaseFixCyclePhase,
+    steps,
+    stepCount,
+    completedCount,
+    failedCount,
+    inProgressCount,
+    nextStepIndex,
+    progress,
+  };
+}
+
+/**
+ * Update a single step's status in-place in the job file.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {number} stepIndex - Zero-based index of the step to update
+ * @param {string} status - New status: 'completed', 'failed', 'in-progress', 'pending'
+ * @param {Object} [options] - { timestamp: string, error: string }
+ * @throws {Error} On out-of-range step index
+ */
+function updateJobStep(filePath, stepIndex, status, options) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  // Find all step lines and their line indices
+  const stepLines = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepLines.length);
+      if (step) {
+        stepLines.push({ lineIndex: i, step });
+      }
+    }
+  }
+
+  const stepCount = stepLines.length;
+
+  if (stepIndex < 0 || stepIndex >= stepCount) {
+    throw new Error(`Step index ${stepIndex} out of range (0-${stepCount - 1})`);
+  }
+
+  const target = stepLines[stepIndex];
+  const newLine = buildStepLine(target.step, status, options);
+  lines[target.lineIndex] = newLine;
+
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+}
+
+/**
+ * Move a job file from its current location to a target directory.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {string} targetDir - Absolute path to the target directory
+ * @returns {{ moved: boolean, from: string, to: string, warning?: string }}
+ */
+function moveJobFile(filePath, targetDir) {
+  const fileName = path.basename(filePath);
+  const currentDir = path.dirname(filePath);
+  const destPath = path.join(targetDir, fileName);
+
+  // Check if file is already in the target directory
+  if (path.resolve(currentDir) === path.resolve(targetDir)) {
+    return {
+      moved: false,
+      from: filePath,
+      to: destPath,
+      warning: `File already in target directory: ${targetDir}`,
+    };
+  }
+
+  // Auto-create target directory
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // Move file
+  fs.renameSync(filePath, destPath);
+
+  return {
+    moved: true,
+    from: filePath,
+    to: destPath,
+  };
+}
+
+/**
+ * Locate a job file by milestone version, checking directories in priority order.
+ *
+ * Search order: in-progress/ (resume case), pending/ (new job), completed/ (inspection).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version (e.g., "v6.0" or "6.0")
+ * @returns {{ found: boolean, path?: string, directory?: string }}
+ */
+function findJobFile(cwd, version) {
+  // Normalize version: ensure 'v' prefix
+  const normalized = version.startsWith('v') ? version : 'v' + version;
+  const fileName = `milestone-${normalized}.md`;
+  const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
+
+  // Search order: in-progress first (resume case), then pending, then completed (inspection)
+  for (const dir of ['in-progress', 'pending', 'completed']) {
+    const filePath = path.join(jobsDir, dir, fileName);
+    if (fs.existsSync(filePath)) {
+      return { found: true, path: filePath, directory: dir };
+    }
+  }
+
+  // Search project subdirectories: .planning/projects/*/jobs/
+  const projectsDir = path.join(getPlanningRoot(cwd), 'projects');
+  if (fs.existsSync(projectsDir)) {
+    const projects = fs.readdirSync(projectsDir).filter(d =>
+      fs.statSync(path.join(projectsDir, d)).isDirectory()
+    );
+    for (const project of projects) {
+      for (const dir of ['in-progress', 'pending', 'completed']) {
+        const filePath = path.join(projectsDir, project, 'jobs', dir, fileName);
+        if (fs.existsSync(filePath)) {
+          return { found: true, path: filePath, directory: dir };
+        }
+      }
+    }
+  }
+
+  return { found: false };
+}
+
+/**
+ * Update a header field value in-place in a job file.
+ *
+ * Finds the line matching `**{Field}:** ...` and replaces the value portion.
+ * Does NOT alter any step lines.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {string} field - Header field name (e.g., "Status")
+ * @param {string} value - New value for the field
+ * @throws {Error} If the field is not found in the file
+ */
+function updateJobHeader(filePath, field, value) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  const fieldPattern = new RegExp(`^\\*\\*${field}:\\*\\*\\s+.*$`);
+  let found = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (fieldPattern.test(lines[i])) {
+      lines[i] = `**${field}:** ${value}`;
+      found = true;
+      break;
+    }
+  }
+
+  if (!found) {
+    throw new Error(`Field not found in job file: ${field}`);
+  }
+
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+}
+
+/**
+ * Insert new step lines at a specific position in the job file.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {number} afterStepIndex - Insert after this step index (-1 = insert before all steps)
+ * @param {Array<{ command: string, args: string }>} newSteps - Steps to insert
+ * @returns {{ inserted: boolean, count: number, startIndex: number }}
+ */
+function insertJobSteps(filePath, afterStepIndex, newSteps) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  // Find all step lines and their line indices
+  const stepLines = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepLines.length);
+      if (step) {
+        stepLines.push({ lineIndex: i, step });
+      }
+    }
+  }
+
+  // Build the new step lines using buildStepLine
+  const newLines = newSteps.map(s => buildStepLine(s, 'pending'));
+
+  // Determine insertion line index
+  let insertAtLine;
+  if (afterStepIndex === -1) {
+    // Insert before the first step
+    if (stepLines.length > 0) {
+      insertAtLine = stepLines[0].lineIndex;
+    } else {
+      // No steps exist; insert at end of file
+      insertAtLine = lines.length;
+    }
+  } else {
+    // Insert after the specified step's line
+    insertAtLine = stepLines[afterStepIndex].lineIndex + 1;
+  }
+
+  // Splice in the new lines
+  lines.splice(insertAtLine, 0, ...newLines);
+
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+
+  return {
+    inserted: true,
+    count: newSteps.length,
+    startIndex: afterStepIndex + 1,
+  };
+}
+
+/**
+ * Build the step sequence for a gap-fix cycle.
+ *
+ * For each phase: plan-phase + execute-phase (no discuss-phase, no verify-work).
+ * Ends with audit-milestone for re-audit.
+ *
+ * @param {Array<{ number: string, name: string }>} newPhases - Gap-fix phases
+ * @param {string} version - Milestone version for re-audit step
+ * @returns {Array<{ command: string, args: string }>} Step sequence
+ */
+function buildGapFixSteps(newPhases, version) {
+  const steps = [];
+  for (const phase of newPhases) {
+    steps.push({ command: 'plan-phase', args: `${phase.number} --non-interactive` });
+    steps.push({ command: 'execute-phase', args: `${phase.number} --non-interactive` });
+  }
+  steps.push({ command: 'audit-milestone', args: version });
+  return steps;
+}
+
+/**
+ * Build the step sequence for a phase-level gap-fix cycle.
+ *
+ * Simpler than buildGapFixSteps (milestone-level): no plan-phase, no
+ * audit-milestone. Just execute existing fix plans and re-verify.
+ *
+ * @param {string} phaseNumber - Phase number (e.g., "41")
+ * @returns {Array<{ command: string, args: string }>} Step sequence (2 steps)
+ */
+function buildPhaseGapFixSteps(phaseNumber) {
+  return [
+    { command: 'execute-phase', args: `${phaseNumber} --gaps-only` },
+    { command: 'audit-phase', args: `${phaseNumber} --rerun-failed` },
+  ];
+}
+
+/**
+ * Insert a gap-fix section into a job file.
+ *
+ * Inserts a section marker line followed by gap-fix step lines after the
+ * specified step index. Updates the GapFixCycle header field.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {number} afterStepIndex - Insert after this step index (typically the audit step)
+ * @param {number} cycleNumber - Gap-fix cycle number (1, 2, 3, ...)
+ * @param {Array<{ number: string, name: string }>} newPhases - Gap-fix phases
+ * @param {string} version - Milestone version for re-audit step
+ * @returns {{ inserted: boolean, count: number, cycleNumber: number, sectionMarker: string }}
+ */
+function insertGapFixSection(filePath, afterStepIndex, cycleNumber, newPhases, version) {
+  // Build the section marker
+  const gapCount = newPhases.length;
+  let phaseNames = newPhases.map(p => p.name).join(', ');
+  if (phaseNames.length > 80) {
+    phaseNames = phaseNames.substring(0, 77) + '...';
+  }
+  const sectionMarker = `\n--- Gap-Fix Cycle ${cycleNumber} (${gapCount} gaps: ${phaseNames}) ---`;
+
+  // Build gap-fix steps
+  const gapSteps = buildGapFixSteps(newPhases, version);
+
+  // Insert the step lines using existing insertJobSteps
+  insertJobSteps(filePath, afterStepIndex, gapSteps);
+
+  // Now read the file again and insert the section marker line
+  // The section marker goes immediately before the first newly-inserted step line
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  // Find all step lines and their positions
+  const stepPositions = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepPositions.length);
+      if (step) {
+        stepPositions.push({ lineIndex: i, step });
+      }
+    }
+  }
+
+  // The first inserted step is at step index afterStepIndex + 1
+  const firstInsertedStepIdx = afterStepIndex + 1;
+  if (firstInsertedStepIdx < stepPositions.length) {
+    const insertLineIdx = stepPositions[firstInsertedStepIdx].lineIndex;
+    lines.splice(insertLineIdx, 0, sectionMarker);
+  }
+
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+
+  // Update the GapFixCycle header field
+  const updatedContent = fs.readFileSync(filePath, 'utf-8');
+  const hasGapFixField = /^\*\*GapFixCycle:\*\*\s+.*$/m.test(updatedContent);
+
+  if (hasGapFixField) {
+    updateJobHeader(filePath, 'GapFixCycle', String(cycleNumber));
+  } else {
+    // Insert GapFixCycle line after the Check header line
+    const fileLines = fs.readFileSync(filePath, 'utf-8').split('\n');
+    const checkLineIdx = fileLines.findIndex(l => /^\*\*Check:\*\*\s+/.test(l));
+    if (checkLineIdx !== -1) {
+      fileLines.splice(checkLineIdx + 1, 0, `**GapFixCycle:** ${cycleNumber}`);
+      fs.writeFileSync(filePath, fileLines.join('\n'), 'utf-8');
+    }
+  }
+
+  return {
+    inserted: true,
+    count: gapSteps.length,
+    cycleNumber,
+    sectionMarker,
+  };
+}
+
+/**
+ * CLI wrapper for insertGapFixSection.
+ * Usage: dgs-tools.cjs jobs insert-gap-fix-section <file> <after-index> <cycle> <version> <phases-json>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} afterIndexStr - Step index to insert after (string, parsed to int)
+ * @param {string} cycleStr - Cycle number (string, parsed to int)
+ * @param {string} version - Milestone version
+ * @param {string} phasesJson - JSON string of phases array [{number, name}]
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsInsertGapFixSection(cwd, file, afterIndexStr, cycleStr, version, phasesJson, raw) {
+  if (!file || afterIndexStr === undefined || cycleStr === undefined || !version || !phasesJson) {
+    error('Usage: jobs insert-gap-fix-section <file> <after-index> <cycle> <version> <phases-json>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  const afterIndex = parseInt(afterIndexStr, 10);
+  if (isNaN(afterIndex)) {
+    error(`Invalid step index: ${afterIndexStr}`);
+  }
+  const cycle = parseInt(cycleStr, 10);
+  if (isNaN(cycle)) {
+    error(`Invalid cycle number: ${cycleStr}`);
+  }
+  let phases;
+  try {
+    phases = JSON.parse(phasesJson);
+  } catch (parseErr) {
+    error(`Invalid JSON for phases: ${parseErr.message}`);
+  }
+  try {
+    const result = insertGapFixSection(filePath, afterIndex, cycle, phases, version);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * Update the PhaseFixCycle header in a job file.
+ *
+ * If the header exists, updates it in-place. If not, inserts it after
+ * the GapFixCycle header (if present) or after the Check header.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {number} cycleNumber - Phase fix cycle number
+ * @param {string} phaseNumber - Phase number (e.g., "41")
+ */
+function updatePhaseFixCycleHeader(filePath, cycleNumber, phaseNumber) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const headerPattern = /^\*\*PhaseFixCycle:\*\*\s+.*$/m;
+
+  if (headerPattern.test(content)) {
+    const updated = content.replace(headerPattern, `**PhaseFixCycle:** ${cycleNumber}:${phaseNumber}`);
+    fs.writeFileSync(filePath, updated, 'utf-8');
+  } else {
+    // Insert after GapFixCycle if it exists, else after Check line
+    const lines = content.split('\n');
+    const checkLineIdx = lines.findIndex(l => /^\*\*Check:\*\*\s+/.test(l));
+    if (checkLineIdx !== -1) {
+      const gapFixIdx = lines.findIndex(l => /^\*\*GapFixCycle:\*\*\s+/.test(l));
+      const insertIdx = gapFixIdx !== -1 ? gapFixIdx + 1 : checkLineIdx + 1;
+      lines.splice(insertIdx, 0, `**PhaseFixCycle:** ${cycleNumber}:${phaseNumber}`);
+      fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+    }
+  }
+}
+
+/**
+ * Insert a phase-level gap-fix section into a job file.
+ *
+ * Inserts a section marker line followed by phase gap-fix step lines
+ * (execute-phase --gaps-only + audit-phase --rerun-failed) after the
+ * specified step index. Updates the PhaseFixCycle header field.
+ *
+ * @param {string} filePath - Absolute path to the job file
+ * @param {number} afterStepIndex - Insert after this step index (typically the audit-phase step)
+ * @param {number} cycleNumber - Phase fix cycle number (1, 2)
+ * @param {string} phaseNumber - Phase number (e.g., "41")
+ * @returns {{ inserted: boolean, count: number, cycleNumber: number, phaseNumber: string, sectionMarker: string }}
+ */
+function insertPhaseGapFixSection(filePath, afterStepIndex, cycleNumber, phaseNumber) {
+  const sectionMarker = `\n--- Phase ${phaseNumber} Gap-Fix Cycle ${cycleNumber}/2 ---`;
+  const gapSteps = buildPhaseGapFixSteps(phaseNumber);
+
+  // Insert steps using existing infrastructure
+  insertJobSteps(filePath, afterStepIndex, gapSteps);
+
+  // Insert section marker before the first inserted step (same technique as insertGapFixSection)
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const stepPositions = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepPositions.length);
+      if (step) stepPositions.push({ lineIndex: i, step });
+    }
+  }
+  const firstInsertedStepIdx = afterStepIndex + 1;
+  if (firstInsertedStepIdx < stepPositions.length) {
+    const insertLineIdx = stepPositions[firstInsertedStepIdx].lineIndex;
+    lines.splice(insertLineIdx, 0, sectionMarker);
+  }
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+
+  // Update PhaseFixCycle header
+  updatePhaseFixCycleHeader(filePath, cycleNumber, phaseNumber);
+
+  return {
+    inserted: true,
+    count: gapSteps.length,
+    cycleNumber,
+    phaseNumber,
+    sectionMarker,
+  };
+}
+
+/**
+ * CLI wrapper for insertPhaseGapFixSection.
+ * Usage: dgs-tools.cjs jobs insert-phase-gap-fix <file> <after-index> <cycle> <phase-number>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} afterIndexStr - Step index to insert after (string, parsed to int)
+ * @param {string} cycleStr - Cycle number (string, parsed to int)
+ * @param {string} phaseNumber - Phase number (e.g., "41")
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsInsertPhaseGapFix(cwd, file, afterIndexStr, cycleStr, phaseNumber, raw) {
+  if (!file || afterIndexStr === undefined || cycleStr === undefined || !phaseNumber) {
+    error('Usage: jobs insert-phase-gap-fix <file> <after-index> <cycle> <phase-number>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  const afterIndex = parseInt(afterIndexStr, 10);
+  if (isNaN(afterIndex)) error(`Invalid step index: ${afterIndexStr}`);
+  const cycle = parseInt(cycleStr, 10);
+  if (isNaN(cycle)) error(`Invalid cycle number: ${cycleStr}`);
+  try {
+    const result = insertPhaseGapFixSection(filePath, afterIndex, cycle, phaseNumber);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+// ─── CLI Wrapper Functions ──────────────────────────────────────────────────
+
+/**
+ * CLI wrapper for parseJobFile.
+ * Usage: dgs-tools.cjs jobs parse <file>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file (relative to cwd or absolute)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsParse(cwd, file, raw) {
+  if (!file) {
+    error('file path required. Usage: jobs parse <file>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  try {
+    const result = parseJobFile(filePath);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for updateJobStep.
+ * Usage: dgs-tools.cjs jobs update-step <file> <step-index> <status> [--timestamp T] [--error E]
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} stepIndexStr - Step index as string
+ * @param {string} status - New status
+ * @param {Object} opts - { timestamp, error }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsUpdateStep(cwd, file, stepIndexStr, status, opts, raw) {
+  if (!file || stepIndexStr === undefined || !status) {
+    error('Usage: jobs update-step <file> <step-index> <status> [--timestamp T] [--error E]');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  const stepIndex = parseInt(stepIndexStr, 10);
+  if (isNaN(stepIndex)) {
+    error(`Invalid step index: ${stepIndexStr}`);
+  }
+  try {
+    updateJobStep(filePath, stepIndex, status, opts);
+    output({ updated: true, step: stepIndex, status }, raw, `Step ${stepIndex} updated to ${status}`);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for moveJobFile.
+ * Usage: dgs-tools.cjs jobs move <file> <target-dir>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} targetDir - Target directory path
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsMove(cwd, file, targetDir, raw) {
+  if (!file || !targetDir) {
+    error('Usage: jobs move <file> <target-dir>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  const target = path.isAbsolute(targetDir) ? targetDir : path.join(cwd, targetDir);
+  try {
+    const result = moveJobFile(filePath, target);
+    const fileName = path.basename(filePath);
+    const dirName = path.basename(target);
+    output(result, raw, result.moved ? `${fileName} moved to ${dirName}` : result.warning);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for findJobFile.
+ * Usage: dgs-tools.cjs jobs find-job <version>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version (e.g., "v6.0" or "6.0")
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsFindJob(cwd, version, raw) {
+  if (!version) {
+    error('version required. Usage: jobs find-job <version>');
+  }
+  const result = findJobFile(cwd, version);
+  output(result, raw);
+}
+
+/**
+ * CLI wrapper for updateJobHeader.
+ * Usage: dgs-tools.cjs jobs update-header <file> <field> <value>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} field - Header field name
+ * @param {string} value - New value
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsUpdateHeader(cwd, file, field, value, raw) {
+  if (!file || !field || !value) {
+    error('Usage: jobs update-header <file> <field> <value>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  try {
+    updateJobHeader(filePath, field, value);
+    output({ updated: true, field, value }, raw, `${field} updated to ${value}`);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for insertJobSteps.
+ * Usage: dgs-tools.cjs jobs insert-steps <file> <after-index> <steps-json>
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} file - Path to job file
+ * @param {string} afterIndexStr - Step index to insert after (string, parsed to int)
+ * @param {string} stepsJson - JSON string of steps array
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdJobsInsertSteps(cwd, file, afterIndexStr, stepsJson, raw) {
+  if (!file || afterIndexStr === undefined || !stepsJson) {
+    error('Usage: jobs insert-steps <file> <after-index> <steps-json>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  const afterIndex = parseInt(afterIndexStr, 10);
+  if (isNaN(afterIndex)) {
+    error(`Invalid step index: ${afterIndexStr}`);
+  }
+  let steps;
+  try {
+    steps = JSON.parse(stepsJson);
+  } catch (parseErr) {
+    error(`Invalid JSON for steps: ${parseErr.message}`);
+  }
+  try {
+    const result = insertJobSteps(filePath, afterIndex, steps);
+    output(result, raw, `${result.count} steps inserted at index ${result.startIndex}`);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+// ─── Milestone Step Generation ──────────────────────────────────────────────
+
+/** Disk statuses that require map-codebase + plan-phase + execute-phase + audit-phase */
+const NEEDS_PLANNING = new Set(['no_directory', 'empty', 'discussed', 'researched']);
+
+/** Disk statuses that require execute-phase + audit-phase (already planned) */
+const NEEDS_EXECUTION = new Set(['planned', 'partial']);
+
+/**
+ * Compare phase numbers numerically (handles decimals like 50.1).
+ * @param {string} a - Phase number
+ * @param {string} b - Phase number
+ * @returns {number} Comparison result
+ */
+function comparePhaseNumbers(a, b) {
+  return parseFloat(a) - parseFloat(b);
+}
+
+/**
+ * Generate the step sequence for a milestone job based on phase states.
+ *
+ * @param {Array} phases - Array of phase objects from roadmap analysis
+ * @param {Object} options - { check: boolean, version: string }
+ * @returns {Array<{ command: string, args: string }>} Ordered step sequence
+ */
+function generateMilestoneSteps(phases, options) {
+  const { check, version } = options;
+
+  // Sort phases by number (numeric, handles decimals)
+  const sorted = [...phases].sort((a, b) => comparePhaseNumbers(a.number, b.number));
+
+  const steps = [];
+
+  for (const phase of sorted) {
+    // Skip completed phases
+    if (phase.disk_status === 'complete' || phase.roadmap_complete === true) {
+      continue;
+    }
+
+    const num = phase.number;
+
+    if (NEEDS_PLANNING.has(phase.disk_status)) {
+      steps.push({ command: 'map-codebase', args: `${num} --auto` });
+      steps.push({ command: 'plan-phase', args: `${num} --non-interactive` });
+      steps.push({ command: 'execute-phase', args: `${num} --non-interactive` });
+      steps.push({ command: 'audit-phase', args: `${num}` });
+    } else if (NEEDS_EXECUTION.has(phase.disk_status)) {
+      steps.push({ command: 'execute-phase', args: `${num} --non-interactive` });
+      steps.push({ command: 'audit-phase', args: `${num}` });
+    }
+  }
+
+  // Append audit + complete steps if check is enabled
+  if (check) {
+    steps.push({ command: 'audit-milestone', args: version });
+    steps.push({ command: 'complete-milestone', args: version });
+  }
+
+  return steps;
+}
+
+/**
+ * Build the markdown content for a milestone job file.
+ *
+ * @param {string} version - Milestone version (e.g., "v6.0")
+ * @param {boolean} check - Whether audit/complete steps are included
+ * @param {Array<{ command: string, args: string }>} steps - Step sequence
+ * @param {string|null} [createdBy=null] - Author string (e.g., "Name <email>"). Omits Created_by line when null/undefined.
+ * @returns {string} Complete markdown file content
+ */
+function buildJobFileContent(version, check, steps, createdBy) {
+  const created = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  let content = `# Milestone Job: ${version}\n\n`;
+  content += `**Version:** ${version}\n`;
+  content += `**Created:** ${created}\n`;
+  if (createdBy) {
+    content += `**Created_by:** ${createdBy}\n`;
+  }
+  content += `**Status:** pending\n`;
+  content += `**Check:** ${check}\n`;
+  content += `\n## Steps\n\n`;
+
+  for (const step of steps) {
+    content += `- [ ] \`/dgs:${step.command} ${step.args}\`\n`;
+  }
+
+  return content;
+}
+
+// ─── Milestone Phase Analysis ───────────────────────────────────────────────
+
+/**
+ * Analyze phases belonging to a specific milestone from ROADMAP.md.
+ * Replicates the disk_status detection from roadmap.cjs but scoped to a
+ * single milestone's phases, avoiding circular dependency with output().
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version to analyze (e.g., "v6.0")
+ * @returns {Array} Phase objects with { number, name, disk_status, roadmap_complete }
+ * @throws {Error} If ROADMAP.md not found or version not found
+ */
+function analyzeMilestonePhases(cwd, version) {
+  const projectRoot = resolveProjectRoot(cwd);
+  const roadmapPath = path.join(projectRoot, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    throw new Error('ROADMAP.md not found at ' + roadmapPath);
+  }
+
+  const content = fs.readFileSync(roadmapPath, 'utf-8');
+  const phasesDir = path.join(projectRoot, 'phases');
+
+  // Find the milestone section: look for heading containing the version + "In Progress" or "SHIPPED"
+  // Also match the milestone in the summary list to find its phase range
+  const escapedVersion = version.replace(/\./g, '\\.');
+
+  // Fast path: explicit "Phases N-M" in milestone summary line
+  const milestoneRangePattern = new RegExp(
+    `${escapedVersion}\\s+[^\\n]*Phases\\s+(\\d+)\\s*-\\s*(\\d+)`,
+    'i'
+  );
+  const rangeMatch = content.match(milestoneRangePattern);
+
+  let phaseStart, phaseEnd;
+
+  if (rangeMatch) {
+    phaseStart = parseInt(rangeMatch[1], 10);
+    phaseEnd = parseInt(rangeMatch[2], 10);
+  } else {
+    // Fallback: find milestone section heading containing the version, then
+    // scan for Phase N: headers within that section to determine the range.
+    const sectionHeadingPattern = new RegExp(
+      `^(#{2,4})\\s+.*${escapedVersion}[^\\n]*$`,
+      'im'
+    );
+    const sectionMatch = content.match(sectionHeadingPattern);
+    if (!sectionMatch) {
+      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+    }
+
+    const headingLevel = sectionMatch[1].length;
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+
+    // Find the end of this section (next heading at same or higher level)
+    const endPattern = new RegExp(
+      `^#{2,${headingLevel}}\\s+`,
+      'im'
+    );
+    const restContent = content.slice(sectionStart);
+    const endMatch = restContent.match(endPattern);
+    const sectionContent = endMatch
+      ? restContent.slice(0, endMatch.index)
+      : restContent;
+
+    // Collect Phase N: headers within this section
+    const phaseHeaderPattern = /Phase\s+(\d+)\s*:/gi;
+    const phaseNumbers = [];
+    let phMatch;
+    while ((phMatch = phaseHeaderPattern.exec(sectionContent)) !== null) {
+      phaseNumbers.push(parseInt(phMatch[1], 10));
+    }
+
+    // If section-based search found nothing (common when ROADMAP has peer-level
+    // ## headings like ## v1.0, ## Overview, ## Phase Details), search the entire
+    // ROADMAP for Phase N: headings. For single-milestone ROADMAPs all phases
+    // belong to the milestone.
+    if (phaseNumbers.length === 0) {
+      const fullPhasePattern = new RegExp(
+        `Phase\\s+(\\d+)`,
+        'gi'
+      );
+      let fpMatch;
+      while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
+        phaseNumbers.push(parseInt(fpMatch[1], 10));
+      }
+    }
+
+    if (phaseNumbers.length === 0) {
+      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+    }
+
+    phaseStart = Math.min(...phaseNumbers);
+    phaseEnd = Math.max(...phaseNumbers);
+  }
+
+  // Extract all phase detail sections: ### Phase N: Name
+  const phasePattern = /#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*:\s*([^\n]+)/gi;
+  const phases = [];
+  let match;
+
+  while ((match = phasePattern.exec(content)) !== null) {
+    const phaseNum = match[1];
+    const phaseFloat = parseFloat(phaseNum);
+
+    // Only include phases in this milestone's range
+    if (phaseFloat < phaseStart || phaseFloat > phaseEnd) continue;
+
+    const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim();
+
+    // Determine disk status by examining the phases directory
+    const padded = phaseNum.replace(/^(\d+)/, (m) => m.padStart(2, '0'));
+    let diskStatus = 'no_directory';
+
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+      const dirMatch = dirs.find(d => d.startsWith(padded + '-') || d === padded);
+
+      if (dirMatch) {
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
+        const planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+        const summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+        const hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
+        const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md');
+
+        if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete';
+        else if (summaryCount > 0) diskStatus = 'partial';
+        else if (planCount > 0) diskStatus = 'planned';
+        else if (hasResearch) diskStatus = 'researched';
+        else if (hasContext) diskStatus = 'discussed';
+        else diskStatus = 'empty';
+      }
+    } catch {}
+
+    // Check ROADMAP checkbox status
+    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseNum.replace('.', '\\.')}`, 'i');
+    const checkboxMatch = content.match(checkboxPattern);
+    const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
+
+    phases.push({
+      number: phaseNum,
+      name: phaseName,
+      disk_status: diskStatus,
+      roadmap_complete: roadmapComplete,
+    });
+  }
+
+  return phases;
+}
+
+/**
+ * Detect the active milestone version from ROADMAP.md.
+ *
+ * @param {string} content - ROADMAP.md content
+ * @returns {string|null} Version string (e.g., "v6.0") or null if not found
+ */
+function detectActiveMilestone(content) {
+  // Primary: heading with (In Progress)
+  const match = content.match(/##\s+.*?(v\d+\.\d+).*?\((?:In|in)\s+[Pp]rogress\)/i);
+  if (match) return match[1];
+  // Fallback: milestone list item with (in progress)
+  const listMatch = content.match(/-\s+.*?(v\d+\.\d+).*?\((?:in\s+progress)\)/i);
+  return listMatch ? listMatch[1] : null;
+}
+
+// ─── Milestone Job CLI Wrappers ─────────────────────────────────────────────
+
+/**
+ * Create a milestone job file from roadmap analysis.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string|null} version - Milestone version (null = auto-detect)
+ * @param {boolean} check - Include audit/complete steps
+ * @param {boolean} raw - Raw output mode
+ * @returns {Object} Result JSON (when called directly, not via CLI)
+ */
+function cmdJobsCreateMilestone(cwd, version, check, raw) {
+  const roadmapPath = path.join(resolveProjectRoot(cwd), 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    throw new Error('ROADMAP.md not found at ' + roadmapPath);
+  }
+
+  const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+
+  // Resolve version
+  let resolvedVersion = version;
+  if (!resolvedVersion) {
+    resolvedVersion = detectActiveMilestone(roadmapContent);
+    if (!resolvedVersion) {
+      throw new Error('No active milestone found in ROADMAP.md');
+    }
+  } else {
+    // Validate the version exists in ROADMAP
+    const escapedV = resolvedVersion.replace(/\./g, '\\.');
+    const versionPattern = new RegExp(escapedV + '\\s+', 'i');
+    if (!versionPattern.test(roadmapContent)) {
+      throw new Error(`Milestone ${resolvedVersion} not found in ROADMAP.md`);
+    }
+  }
+
+  // Analyze phases for this milestone
+  const phases = analyzeMilestonePhases(cwd, resolvedVersion);
+
+  // Generate steps
+  const steps = generateMilestoneSteps(phases, { check, version: resolvedVersion });
+
+  // Resolve git identity for Created_by (best-effort; don't block creation)
+  let createdBy = null;
+  try {
+    const identity = requireGitIdentity(cwd);
+    createdBy = formatAuthorString(identity);
+  } catch {
+    // Identity resolution is best-effort for jobs; don't block creation
+  }
+
+  // Build file content
+  const content = buildJobFileContent(resolvedVersion, check, steps, createdBy);
+
+  // Write to pending directory
+  const pendingDir = path.join(getPlanningRoot(cwd), 'jobs', 'pending');
+  fs.mkdirSync(pendingDir, { recursive: true });
+  const fileName = `milestone-${resolvedVersion}.md`;
+  const filePath = path.join(pendingDir, fileName);
+  fs.writeFileSync(filePath, content, 'utf-8');
+
+  // Count phases that contribute at least one step
+  const phasesWithSteps = phases.filter(p =>
+    p.disk_status !== 'complete' && p.roadmap_complete !== true
+  );
+
+  const result = {
+    created: true,
+    version: resolvedVersion,
+    file: path.join(path.relative(cwd, getPlanningRoot(cwd)) || '.', 'jobs', 'pending', fileName),
+    step_count: steps.length,
+    check,
+    phase_count: phasesWithSteps.length,
+    steps_preview: steps.map(s => `/dgs:${s.command} ${s.args}`),
+  };
+
+  return result;
+}
+
+/**
+ * Preview a milestone job without writing any file.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string|null} version - Milestone version (null = auto-detect)
+ * @param {boolean} check - Include audit/complete steps
+ * @param {boolean} raw - Raw output mode
+ * @returns {Object} Preview JSON
+ */
+function cmdJobsMilestonePreview(cwd, version, check, raw) {
+  const roadmapPath = path.join(resolveProjectRoot(cwd), 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    throw new Error('ROADMAP.md not found at ' + roadmapPath);
+  }
+
+  const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+
+  // Resolve version
+  let resolvedVersion = version;
+  if (!resolvedVersion) {
+    resolvedVersion = detectActiveMilestone(roadmapContent);
+    if (!resolvedVersion) {
+      throw new Error('No active milestone found in ROADMAP.md');
+    }
+  } else {
+    const escapedV = resolvedVersion.replace(/\./g, '\\.');
+    const versionPattern = new RegExp(escapedV + '\\s+', 'i');
+    if (!versionPattern.test(roadmapContent)) {
+      throw new Error(`Milestone ${resolvedVersion} not found in ROADMAP.md`);
+    }
+  }
+
+  // Analyze phases
+  const phases = analyzeMilestonePhases(cwd, resolvedVersion);
+
+  // Generate steps
+  const steps = generateMilestoneSteps(phases, { check, version: resolvedVersion });
+
+  // Build content (but do NOT write)
+  const content = buildJobFileContent(resolvedVersion, check, steps);
+
+  // Count phases with steps
+  const phasesWithSteps = phases.filter(p =>
+    p.disk_status !== 'complete' && p.roadmap_complete !== true
+  );
+
+  return {
+    preview: true,
+    version: resolvedVersion,
+    check,
+    step_count: steps.length,
+    phase_count: phasesWithSteps.length,
+    steps_preview: steps.map(s => `/dgs:${s.command} ${s.args}`),
+    content,
+  };
+}
+
+// ─── Visibility & Polish Functions ──────────────────────────────────────────
+
+/**
+ * List all job files across pending/in-progress/completed, grouped by status.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ in_progress: Array, pending: Array, completed: Array }}
+ */
+function listJobs(cwd) {
+  const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
+  const groups = { in_progress: [], pending: [], completed: [] };
+  const dirMap = { 'in-progress': 'in_progress', 'pending': 'pending', 'completed': 'completed' };
+
+  for (const [dirName, groupKey] of Object.entries(dirMap)) {
+    const dirPath = path.join(jobsDir, dirName);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+
+    let files;
+    try {
+      files = fs.readdirSync(dirPath).filter(f => f.startsWith('milestone-') && f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+
+    // Sort by modification time, most recent first
+    const fileStats = files.map(f => {
+      const fullPath = path.join(dirPath, f);
+      let mtime = 0;
+      try { mtime = fs.statSync(fullPath).mtimeMs; } catch {}
+      return { file: f, fullPath, mtime };
+    });
+    fileStats.sort((a, b) => b.mtime - a.mtime);
+
+    for (const { file, fullPath } of fileStats) {
+      try {
+        const parsed = parseJobFile(fullPath);
+        groups[groupKey].push({
+          version: parsed.version,
+          status: parsed.status,
+          check: parsed.check,
+          created_by: parsed.created_by,
+          progress: `${parsed.completedCount}/${parsed.stepCount}`,
+          file: fullPath,
+        });
+      } catch {
+        // Skip unparseable files
+      }
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Cancel an in-progress job: reset [>] steps to [ ], set Status to pending, move to pending/.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version (e.g., "v6.0")
+ * @returns {{ cancelled: boolean, version?: string, path?: string, steps_reset?: number, reason?: string }}
+ */
+function cancelJob(cwd, version) {
+  const found = findJobFile(cwd, version);
+  if (!found.found) {
+    return { cancelled: false, reason: 'not_found' };
+  }
+  if (found.directory !== 'in-progress') {
+    return { cancelled: false, reason: 'not_in_progress' };
+  }
+
+  const filePath = found.path;
+
+  // Read and find all in-progress steps
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const stepLines = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('- [')) {
+      const step = parseStepLine(trimmed, stepLines.length);
+      if (step) {
+        stepLines.push({ lineIndex: i, step });
+      }
+    }
+  }
+
+  // Reset in-progress steps to pending
+  let stepsReset = 0;
+  for (const { step } of stepLines) {
+    if (step.status === 'in-progress') {
+      updateJobStep(filePath, step.index, 'pending');
+      stepsReset++;
+    }
+  }
+
+  // Update Status header to pending
+  updateJobHeader(filePath, 'Status', 'pending');
+
+  // Move to pending/
+  const pendingDir = path.join(getPlanningRoot(cwd), 'jobs', 'pending');
+  const moveResult = moveJobFile(filePath, pendingDir);
+
+  return {
+    cancelled: true,
+    version: version.startsWith('v') ? version : 'v' + version,
+    path: moveResult.to,
+    steps_reset: stepsReset,
+  };
+}
+
+/**
+ * Validate jobs directory structure. Auto-create missing directories.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ healthy: boolean, directories: Array, job_count: number, issues?: Array }}
+ */
+function healthCheck(cwd) {
+  const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
+  const requiredDirs = ['pending', 'in-progress', 'completed'];
+  const directories = [];
+  const issues = [];
+  let jobCount = 0;
+
+  for (const dirName of requiredDirs) {
+    const dirPath = path.join(jobsDir, dirName);
+    const exists = fs.existsSync(dirPath);
+    let created = false;
+
+    if (!exists) {
+      fs.mkdirSync(dirPath, { recursive: true });
+      created = true;
+      issues.push(`Missing directory auto-created: ${dirName}/`);
+    }
+
+    directories.push({ name: dirName, exists: exists || created, created });
+
+    // Scan for job files
+    try {
+      const files = fs.readdirSync(dirPath).filter(f => f.startsWith('milestone-') && f.endsWith('.md'));
+      jobCount += files.length;
+
+      // Validate each file
+      for (const file of files) {
+        const filePath = path.join(dirPath, file);
+        try {
+          parseJobFile(filePath);
+        } catch (err) {
+          issues.push(`Parse failure in ${dirName}/${file}: ${err.message}`);
+        }
+      }
+    } catch {
+      // Directory just created, no files
+    }
+  }
+
+  return {
+    healthy: issues.length === 0,
+    directories,
+    job_count: jobCount,
+    issues,
+  };
+}
+
+/**
+ * Preview a job's steps with status annotations and precondition warnings.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version
+ * @returns {{ found: boolean, version?: string, status?: string, steps?: Array, resume_from?: number, warnings?: Array }}
+ */
+function dryRunPreview(cwd, version) {
+  const found = findJobFile(cwd, version);
+  if (!found.found) {
+    return { found: false };
+  }
+
+  const parsed = parseJobFile(found.path);
+  const steps = parsed.steps.map(step => {
+    let marker;
+    if (step.status === 'completed') marker = '[x]';
+    else if (step.status === 'in-progress') marker = '[>]';
+    else if (step.status === 'failed') marker = '[!]';
+    else marker = '[ ]';
+
+    return {
+      index: step.index,
+      command: step.command,
+      args: step.args,
+      status: step.status,
+      display: `${marker} /dgs:${step.command}${step.args ? ' ' + step.args : ''}`,
+    };
+  });
+
+  // Resume from first non-completed step
+  const firstNonCompleted = parsed.steps.find(s => s.status !== 'completed');
+  const resumeFrom = firstNonCompleted ? firstNonCompleted.index : null;
+
+  // Precondition warnings
+  const planRoot = getPlanningRoot(cwd);
+  const projectRootForHealth = resolveProjectRoot(cwd);
+  const warnings = [];
+  if (!fs.existsSync(planRoot)) {
+    warnings.push('Planning root directory missing');
+  }
+  if (!fs.existsSync(path.join(projectRootForHealth, 'ROADMAP.md'))) {
+    warnings.push('ROADMAP.md missing');
+  }
+  if (!fs.existsSync(path.join(projectRootForHealth, 'STATE.md'))) {
+    warnings.push('STATE.md missing');
+  }
+
+  return {
+    found: true,
+    version: parsed.version,
+    status: parsed.status,
+    steps,
+    resume_from: resumeFrom,
+    warnings,
+  };
+}
+
+/**
+ * Generate a markdown summary report for a job.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version
+ * @returns {{ found: boolean, version?: string, content?: string }}
+ */
+function generateJobSummary(cwd, version) {
+  const found = findJobFile(cwd, version);
+  if (!found.found) {
+    return { found: false };
+  }
+
+  const parsed = parseJobFile(found.path);
+  const normalizedVersion = parsed.version;
+
+  let md = `# Job Summary: milestone-${normalizedVersion}\n\n`;
+  md += `## Overview\n\n`;
+  md += `- **Version:** ${normalizedVersion}\n`;
+  md += `- **Status:** ${parsed.status}\n`;
+  if (parsed.created_by) {
+    md += `- **Created_by:** ${parsed.created_by}\n`;
+  }
+  md += `- **Created:** ${parsed.created}\n`;
+  md += `- **Total Steps:** ${parsed.stepCount}\n`;
+  md += `- **Completed Steps:** ${parsed.completedCount}\n`;
+  md += `- **Failed Steps:** ${parsed.failedCount}\n\n`;
+
+  // Per-step timing table
+  md += `## Step Details\n\n`;
+  md += `| # | Command | Started | Duration | Status |\n`;
+  md += `|---|---------|---------|----------|--------|\n`;
+
+  for (let i = 0; i < parsed.steps.length; i++) {
+    const step = parsed.steps[i];
+    const cmd = `/dgs:${step.command}${step.args ? ' ' + step.args : ''}`;
+    const started = step.timestamp || '-';
+
+    // Calculate duration from consecutive timestamps
+    let duration = '-';
+    if (step.timestamp && i + 1 < parsed.steps.length && parsed.steps[i + 1].timestamp) {
+      const startMs = new Date(step.timestamp).getTime();
+      const endMs = new Date(parsed.steps[i + 1].timestamp).getTime();
+      if (!isNaN(startMs) && !isNaN(endMs) && endMs > startMs) {
+        const diffSec = Math.round((endMs - startMs) / 1000);
+        if (diffSec < 60) duration = `${diffSec}s`;
+        else duration = `${Math.round(diffSec / 60)}m`;
+      }
+    }
+
+    md += `| ${i} | ${cmd} | ${started} | ${duration} | ${step.status} |\n`;
+  }
+  md += `\n`;
+
+  // Errors section
+  const failedSteps = parsed.steps.filter(s => s.status === 'failed');
+  if (failedSteps.length > 0) {
+    md += `## Errors\n\n`;
+    for (const step of failedSteps) {
+      const cmd = `/dgs:${step.command}${step.args ? ' ' + step.args : ''}`;
+      md += `- **Step ${step.index}** (${cmd}): ${step.error || 'No error message recorded'}\n`;
+    }
+    md += `\n`;
+  }
+
+  // Auto-resolve audit section
+  const autoSteps = parsed.steps.filter(s => s.args && (s.args.includes('--auto') || s.args.includes('--non-interactive')));
+  if (autoSteps.length > 0) {
+    md += `## Auto-Resolved Steps\n\n`;
+    for (const step of autoSteps) {
+      const cmd = `/dgs:${step.command}${step.args ? ' ' + step.args : ''}`;
+      md += `- Step ${step.index}: ${cmd} (auto-resolved)\n`;
+    }
+    md += `\n`;
+  }
+
+  // Human verification scanning — find UAT files with human_needed entries
+  let humanVerifications = [];
+  try {
+    const milestonePhases = analyzeMilestonePhases(cwd, normalizedVersion);
+    const projectRoot = resolveProjectRoot(cwd);
+    const phasesDir = path.join(projectRoot, 'phases');
+
+    for (const phase of milestonePhases) {
+      const phaseNum = phase.number;
+      const padded = String(phaseNum).replace(/^(\d+)/, (m) => m.padStart(2, '0'));
+
+      // Find the phase directory on disk
+      let phaseDir = null;
+      try {
+        const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+        phaseDir = dirs.find(d => d.startsWith(padded + '-') || d === padded);
+      } catch {}
+
+      if (!phaseDir) continue;
+
+      // Look for UAT file
+      const uatPath = path.join(phasesDir, phaseDir, `${padded}-UAT.md`);
+      let uatContent = null;
+      try {
+        uatContent = fs.readFileSync(uatPath, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      // Check for mode: auto-test in frontmatter (first ~10 lines)
+      const headerLines = uatContent.split('\n').slice(0, 15).join('\n');
+      if (!/mode:\s*auto-test/i.test(headerLines)) continue;
+
+      // Parse test blocks for human_needed entries
+      const blocks = uatContent.split(/(?=^### \d+\.)/m);
+      for (const block of blocks) {
+        const headingMatch = block.match(/^### \d+\.\s+(.+)/);
+        if (!headingMatch) continue;
+
+        if (!/^result:\s*human_needed\s*$/m.test(block)) continue;
+
+        const description = headingMatch[1].trim();
+        const sourceMatch = block.match(/^source:\s*(.+)\s*$/m);
+        const source = sourceMatch ? sourceMatch[1].trim() : '-';
+
+        humanVerifications.push({
+          phase: phaseNum,
+          description,
+          source,
+        });
+      }
+    }
+  } catch {
+    // If milestone phase analysis fails (e.g., no ROADMAP.md), skip silently
+  }
+
+  if (humanVerifications.length > 0) {
+    md += `## Outstanding Human Verifications\n\n`;
+    md += `The following tests require manual verification:\n\n`;
+    md += `| Phase | Test | Source |\n`;
+    md += `|-------|------|--------|\n`;
+    for (const hv of humanVerifications) {
+      md += `| ${hv.phase} | ${hv.description} | ${hv.source} |\n`;
+    }
+    md += `\nTotal: ${humanVerifications.length} human verification(s) remaining.\n\n`;
+  }
+
+  return {
+    found: true,
+    version: normalizedVersion,
+    content: md,
+    human_verification_count: humanVerifications.length,
+  };
+}
+
+// ─── SHA Recording & Rollback ───────────────────────────────────────────────
+
+/**
+ * Record starting commit SHAs for all registered code repos and the planning repo.
+ * Writes a **StartShas:** header line into the job file.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} jobFilePath - Absolute path to the job file
+ * @returns {{ recorded: boolean, shas?: Object, reason?: string }}
+ */
+function recordStartShas(cwd, jobFilePath) {
+  try {
+    const planningRoot = getPlanningRoot(cwd);
+    const shas = {};
+
+    // Record planning repo SHA
+    try {
+      const planningSha = execSync('git rev-parse HEAD', { cwd: planningRoot, stdio: 'pipe' }).toString().trim();
+      shas['_planning'] = planningSha;
+    } catch (gitErr) {
+      return { recorded: false, reason: `Failed to get planning repo SHA: ${gitErr.message}` };
+    }
+
+    // Check for REPOS.md (v2 multi-repo setup)
+    const reposPath = path.join(planningRoot, 'REPOS.md');
+    if (fs.existsSync(reposPath)) {
+      const reposContent = fs.readFileSync(reposPath, 'utf-8');
+      // Parse the markdown table: | Name | Path | ...
+      const lines = reposContent.split('\n');
+      for (const line of lines) {
+        const match = line.match(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/);
+        if (!match) continue;
+        const name = match[1].trim();
+        const repoPath = match[2].trim();
+        // Skip header row and separator
+        if (name === 'Name' || name.startsWith('-')) continue;
+        if (!repoPath || repoPath.startsWith('-')) continue;
+
+        // Resolve absolute path: paths in REPOS.md are relative to planning root's parent
+        const absRepoPath = path.resolve(path.dirname(planningRoot), repoPath);
+        if (!fs.existsSync(absRepoPath)) continue;
+
+        try {
+          const sha = execSync('git rev-parse HEAD', { cwd: absRepoPath, stdio: 'pipe' }).toString().trim();
+          shas[name] = sha;
+        } catch {
+          // Skip repos that aren't git repos or have issues
+        }
+      }
+    }
+
+    // Write StartShas into the job file (after header block, before ## Steps)
+    const content = fs.readFileSync(jobFilePath, 'utf-8');
+
+    // Check if StartShas already exists
+    if (/^\*\*StartShas:\*\*\s+/m.test(content)) {
+      return { recorded: true, shas, already_existed: true };
+    }
+
+    const shaJson = JSON.stringify(shas);
+    const lines = content.split('\n');
+
+    // Find the ## Steps line and insert before it
+    const stepsIdx = lines.findIndex(l => /^## Steps/.test(l));
+    if (stepsIdx !== -1) {
+      lines.splice(stepsIdx, 0, `**StartShas:** ${shaJson}`, '');
+    } else {
+      // Fallback: insert after Check header line
+      const checkIdx = lines.findIndex(l => /^\*\*Check:\*\*\s+/.test(l));
+      if (checkIdx !== -1) {
+        lines.splice(checkIdx + 1, 0, `**StartShas:** ${shaJson}`);
+      }
+    }
+
+    fs.writeFileSync(jobFilePath, lines.join('\n'), 'utf-8');
+    return { recorded: true, shas };
+  } catch (err) {
+    return { recorded: false, reason: err.message };
+  }
+}
+
+/**
+ * Roll back all code repo changes made by a milestone job.
+ * Reads StartShas from the job file, resets CODE repos (not planning),
+ * deletes SUMMARY.md files for executed phases, and marks job as rolled_back.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} version - Milestone version (e.g., "v6.0")
+ * @returns {{ rolledBack: boolean, version?: string, repos_reset?: Array, summaries_deleted?: Array, path?: string, reason?: string }}
+ */
+function rollbackJob(cwd, version) {
+  const found = findJobFile(cwd, version);
+  if (!found.found) {
+    return { rolledBack: false, reason: 'not_found' };
+  }
+
+  const filePath = found.path;
+  const parsed = parseJobFile(filePath);
+
+  if (!parsed.startShas) {
+    return { rolledBack: false, reason: 'no_start_shas' };
+  }
+
+  const planningRoot = getPlanningRoot(cwd);
+  const reposReset = [];
+  const summariesDeleted = [];
+
+  // Reset code repos (all keys except _planning)
+  for (const [repoName, sha] of Object.entries(parsed.startShas)) {
+    if (repoName === '_planning') continue;
+
+    // Resolve repo path: check REPOS.md for the path
+    let absRepoPath = null;
+    const reposPath = path.join(planningRoot, 'REPOS.md');
+    if (fs.existsSync(reposPath)) {
+      const reposContent = fs.readFileSync(reposPath, 'utf-8');
+      const repoLines = reposContent.split('\n');
+      for (const line of repoLines) {
+        const match = line.match(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/);
+        if (!match) continue;
+        const name = match[1].trim();
+        const repoPathStr = match[2].trim();
+        if (name === repoName && repoPathStr && !repoPathStr.startsWith('-')) {
+          absRepoPath = path.resolve(path.dirname(planningRoot), repoPathStr);
+          break;
+        }
+      }
+    }
+
+    if (!absRepoPath || !fs.existsSync(absRepoPath)) continue;
+
+    try {
+      execSync(`git reset --hard ${sha}`, { cwd: absRepoPath, stdio: 'pipe' });
+      reposReset.push({ name: repoName, sha, path: absRepoPath });
+    } catch (gitErr) {
+      // Log but continue with other repos
+      reposReset.push({ name: repoName, sha, error: gitErr.message });
+    }
+  }
+
+  // Identify executed phases from completed steps
+  const projectRoot = resolveProjectRoot(cwd);
+  const phasesDir = path.join(projectRoot, 'phases');
+
+  for (const step of parsed.steps) {
+    if (step.status === 'completed' && step.command === 'execute-phase') {
+      // Extract phase number from args (first token)
+      const phaseNum = step.args.split(/\s+/)[0];
+      if (!phaseNum) continue;
+
+      const padded = phaseNum.replace(/^(\d+)/, (m) => m.padStart(2, '0'));
+
+      try {
+        const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+        const dirMatch = dirs.find(d => d.startsWith(padded + '-') || d === padded);
+
+        if (dirMatch) {
+          const phaseDir = path.join(phasesDir, dirMatch);
+          const phaseFiles = fs.readdirSync(phaseDir);
+          const summaryFiles = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+
+          for (const sf of summaryFiles) {
+            const sfPath = path.join(phaseDir, sf);
+            try {
+              fs.unlinkSync(sfPath);
+              summariesDeleted.push(sfPath);
+            } catch {
+              // Skip files that can't be deleted
+            }
+          }
+        }
+      } catch {
+        // Phase directory doesn't exist, skip
+      }
+    }
+  }
+
+  // Update job status to rolled_back
+  updateJobHeader(filePath, 'Status', 'rolled_back');
+
+  return {
+    rolledBack: true,
+    version: version.startsWith('v') ? version : 'v' + version,
+    repos_reset: reposReset,
+    summaries_deleted: summariesDeleted,
+    path: filePath,
+  };
+}
+
+/**
+ * CLI wrapper for recordStartShas.
+ * Usage: dgs-tools.cjs jobs record-start-shas <file>
+ */
+function cmdJobsRecordStartShas(cwd, file, raw) {
+  if (!file) {
+    error('file path required. Usage: jobs record-start-shas <file>');
+  }
+  const filePath = path.isAbsolute(file) ? file : path.join(cwd, file);
+  try {
+    const result = recordStartShas(cwd, filePath);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for rollbackJob.
+ * Usage: dgs-tools.cjs jobs rollback <version>
+ */
+function cmdJobsRollback(cwd, version, raw) {
+  if (!version) {
+    error('version required. Usage: jobs rollback <version>');
+  }
+  try {
+    const result = rollbackJob(cwd, version);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+// ─── Visibility & Polish CLI Wrappers ───────────────────────────────────────
+
+/**
+ * CLI wrapper for listJobs.
+ * Usage: dgs-tools.cjs jobs list-jobs
+ */
+function cmdJobsListJobs(cwd, raw) {
+  try {
+    const result = listJobs(cwd);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for cancelJob.
+ * Usage: dgs-tools.cjs jobs cancel-job <version>
+ */
+function cmdJobsCancelJob(cwd, version, raw) {
+  if (!version) {
+    error('version required. Usage: jobs cancel-job <version>');
+  }
+  try {
+    const result = cancelJob(cwd, version);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for healthCheck.
+ * Usage: dgs-tools.cjs jobs health
+ */
+function cmdJobsHealthCheck(cwd, raw) {
+  try {
+    const result = healthCheck(cwd);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for dryRunPreview.
+ * Usage: dgs-tools.cjs jobs dry-run <version>
+ */
+function cmdJobsDryRun(cwd, version, raw) {
+  if (!version) {
+    error('version required. Usage: jobs dry-run <version>');
+  }
+  try {
+    const result = dryRunPreview(cwd, version);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+/**
+ * CLI wrapper for generateJobSummary.
+ * Usage: dgs-tools.cjs jobs generate-summary <version>
+ */
+function cmdJobsGenerateSummary(cwd, version, raw) {
+  if (!version) {
+    error('version required. Usage: jobs generate-summary <version>');
+  }
+  try {
+    const result = generateJobSummary(cwd, version);
+    output(result, raw);
+  } catch (err) {
+    error(err.message);
+  }
+}
+
+module.exports = {
+  parseJobFile,
+  updateJobStep,
+  moveJobFile,
+  findJobFile,
+  updateJobHeader,
+  insertJobSteps,
+  buildGapFixSteps,
+  buildPhaseGapFixSteps,
+  insertGapFixSection,
+  insertPhaseGapFixSection,
+  updatePhaseFixCycleHeader,
+  generateMilestoneSteps,
+  buildJobFileContent,
+  listJobs,
+  cancelJob,
+  recordStartShas,
+  rollbackJob,
+  healthCheck,
+  dryRunPreview,
+  generateJobSummary,
+  cmdJobsParse,
+  cmdJobsUpdateStep,
+  cmdJobsMove,
+  cmdJobsFindJob,
+  cmdJobsUpdateHeader,
+  cmdJobsInsertSteps,
+  cmdJobsInsertGapFixSection,
+  cmdJobsInsertPhaseGapFix,
+  cmdJobsCreateMilestone,
+  cmdJobsMilestonePreview,
+  cmdJobsListJobs,
+  cmdJobsCancelJob,
+  cmdJobsRecordStartShas,
+  cmdJobsRollback,
+  cmdJobsHealthCheck,
+  cmdJobsDryRun,
+  cmdJobsGenerateSummary,
+};