@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,2619 @@
+/**
+ * Tests for jobs.cjs — Job file parse, update-step, move, find, header update,
+ * step insertion, and gap-fix operations
+ *
+ * Covers parseJobFile, updateJobStep, moveJobFile, findJobFile, updateJobHeader,
+ * insertJobSteps, buildGapFixSteps, insertGapFixSection, and cmd* CLI wrappers.
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { createFixture, createTempProject } = require('./test-helpers.cjs');
+const { resetPaths } = require('./paths.cjs');
+
+const {
+  parseJobFile, updateJobStep, moveJobFile,
+  generateMilestoneSteps, buildJobFileContent,
+  cmdJobsCreateMilestone, cmdJobsMilestonePreview,
+  findJobFile, updateJobHeader, insertJobSteps,
+  buildGapFixSteps, insertGapFixSection,
+  listJobs, cancelJob, recordStartShas, rollbackJob,
+  healthCheck, dryRunPreview, generateJobSummary,
+} = require('./jobs.cjs');
+
+// ─── Sample Job File Content ────────────────────────────────────────────────
+
+const WELL_FORMED_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-02T14:30:00Z
+- [>] \`/dgs:plan-phase 42\` \u2014 started 2026-03-02T14:00:00Z
+- [ ] \`/dgs:execute-phase 41\`
+- [!] \`/dgs:plan-phase 43\` \u2014 failed 2026-03-02T15:00:00Z: Planning inconclusive after retry
+`;
+
+const ALL_COMPLETED_JOB = `# Milestone Job: v5.0
+
+**Version:** v5.0
+**Created:** 2026-03-01T08:00:00Z
+**Status:** completed
+**Check:** false
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-01T09:00:00Z
+- [x] \`/dgs:execute-phase 41\` \u2014 completed 2026-03-01T10:00:00Z
+`;
+
+const EMPTY_STEPS_JOB = `# Milestone Job: v7.0
+
+**Version:** v7.0
+**Created:** 2026-04-01T12:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+`;
+
+const MISSING_VERSION_JOB = `# Milestone Job: v8.0
+
+**Created:** 2026-04-01T12:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 50\`
+`;
+
+const MISSING_CREATED_JOB = `# Milestone Job: v8.0
+
+**Version:** v8.0
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 50\`
+`;
+
+const MISSING_STATUS_JOB = `# Milestone Job: v8.0
+
+**Version:** v8.0
+**Created:** 2026-04-01T12:00:00Z
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 50\`
+`;
+
+const MISSING_CHECK_JOB = `# Milestone Job: v8.0
+
+**Version:** v8.0
+**Created:** 2026-04-01T12:00:00Z
+**Status:** pending
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 50\`
+`;
+
+const UNRECOGNIZED_COMMAND_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 41\`
+- [ ] \`/dgs:unknown-cmd 42\`
+- [ ] \`/dgs:execute-phase 41\`
+`;
+
+const AUDIT_AND_COMPLETE_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:audit-milestone v6\`
+- [ ] \`/dgs:complete-milestone v6\`
+- [ ] \`/dgs:plan-milestone-gaps\`
+- [ ] \`/dgs:discuss-phase 41\`
+- [ ] \`/dgs:research-phase 42\`
+- [ ] \`/dgs:verify-phase 43\`
+`;
+
+const UAT_WITH_HUMAN_NEEDED = `---
+mode: auto-test
+ai_verified: true
+---
+
+# UAT: Phase 50
+
+## Tests
+
+### 1. Build compiles successfully
+expected: Build exits with code 0
+result: pass
+command: npm run build
+
+### 2. Dashboard renders correctly
+expected: Dashboard shows 3 cards in grid layout
+result: human_needed
+source: 50-01-PLAN.md
+
+### 3. Login form accessible
+expected: Screen reader announces form fields
+result: human_needed
+source: VALIDATION.md
+
+## Summary
+total: 3
+passed: 1
+issues: 0
+human_needed: 2
+pending: 0
+skipped: 0
+`;
+
+const UAT_ALL_PASSED = `---
+mode: auto-test
+ai_verified: true
+---
+
+# UAT: Phase 50
+
+## Tests
+
+### 1. Build compiles successfully
+expected: Build exits with code 0
+result: pass
+command: npm run build
+
+### 2. Dashboard renders correctly
+expected: Dashboard shows 3 cards in grid layout
+result: pass
+command: node -e "console.log('ok')"
+
+## Summary
+total: 2
+passed: 2
+issues: 0
+human_needed: 0
+pending: 0
+skipped: 0
+`;
+
+const UAT_MANUAL_WITH_HUMAN_NEEDED = `---
+ai_verified: false
+---
+
+# UAT: Phase 50
+
+## Tests
+
+### 1. Visual check
+expected: Looks correct
+result: human_needed
+source: manual-check
+
+## Summary
+total: 1
+passed: 0
+issues: 0
+human_needed: 1
+pending: 0
+skipped: 0
+`;
+
+const ROADMAP_WITH_PHASE_50 = `# Roadmap
+
+## v6.0 Auto-Verify (In Progress)
+
+Phases 50-50
+
+### Phase 50: Test Phase
+
+- [ ] **Phase 50: Test Phase** - Testing
+`;
+
+const COMPLETED_JOB_V6 = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** completed
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 50\` \u2014 completed 2026-03-02T14:30:00Z
+- [x] \`/dgs:execute-phase 50\` \u2014 completed 2026-03-02T15:00:00Z
+`;
+
+const WELL_FORMED_JOB_WITH_CREATED_BY = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Created_by:** Adrian <adrian@example.com>
+**Status:** in-progress
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-02T14:30:00Z
+- [ ] \`/dgs:execute-phase 41\`
+`;
+
+// ─── parseJobFile Tests ─────────────────────────────────────────────────────
+
+describe('jobs', () => {
+
+  describe('parseJobFile', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('parses well-formed file with mixed statuses', () => {
+      fixture = createFixture({
+        'job-v6.md': WELL_FORMED_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-v6.md'));
+
+      assert.equal(result.version, 'v6.0');
+      assert.equal(result.created, '2026-03-02T10:00:00Z');
+      assert.equal(result.status, 'in-progress');
+      assert.equal(result.check, true);
+      assert.equal(result.stepCount, 4);
+      assert.equal(result.completedCount, 1);
+      assert.equal(result.failedCount, 1);
+      assert.equal(result.inProgressCount, 1);
+      assert.equal(result.nextStepIndex, 2);
+      assert.equal(result.progress, 25);
+
+      // Step 0: completed
+      assert.equal(result.steps[0].index, 0);
+      assert.equal(result.steps[0].status, 'completed');
+      assert.equal(result.steps[0].command, 'plan-phase');
+      assert.equal(result.steps[0].args, '41');
+      assert.equal(result.steps[0].raw, '/dgs:plan-phase 41');
+      assert.equal(result.steps[0].timestamp, '2026-03-02T14:30:00Z');
+      assert.equal(result.steps[0].error, null);
+
+      // Step 1: in-progress
+      assert.equal(result.steps[1].index, 1);
+      assert.equal(result.steps[1].status, 'in-progress');
+      assert.equal(result.steps[1].command, 'plan-phase');
+      assert.equal(result.steps[1].args, '42');
+      assert.equal(result.steps[1].timestamp, '2026-03-02T14:00:00Z');
+
+      // Step 2: pending
+      assert.equal(result.steps[2].index, 2);
+      assert.equal(result.steps[2].status, 'pending');
+      assert.equal(result.steps[2].command, 'execute-phase');
+      assert.equal(result.steps[2].args, '41');
+      assert.equal(result.steps[2].timestamp, null);
+
+      // Step 3: failed with error
+      assert.equal(result.steps[3].index, 3);
+      assert.equal(result.steps[3].status, 'failed');
+      assert.equal(result.steps[3].command, 'plan-phase');
+      assert.equal(result.steps[3].args, '43');
+      assert.equal(result.steps[3].timestamp, '2026-03-02T15:00:00Z');
+      assert.equal(result.steps[3].error, 'Planning inconclusive after retry');
+    });
+
+    it('returns nextStepIndex null and progress 100 when all steps completed', () => {
+      fixture = createFixture({
+        'job-v5.md': ALL_COMPLETED_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-v5.md'));
+
+      assert.equal(result.version, 'v5.0');
+      assert.equal(result.status, 'completed');
+      assert.equal(result.check, false);
+      assert.equal(result.stepCount, 2);
+      assert.equal(result.completedCount, 2);
+      assert.equal(result.failedCount, 0);
+      assert.equal(result.inProgressCount, 0);
+      assert.equal(result.nextStepIndex, null);
+      assert.equal(result.progress, 100);
+    });
+
+    it('handles empty steps section', () => {
+      fixture = createFixture({
+        'job-v7.md': EMPTY_STEPS_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-v7.md'));
+
+      assert.equal(result.stepCount, 0);
+      assert.equal(result.nextStepIndex, null);
+      assert.equal(result.progress, 100);
+      assert.deepEqual(result.steps, []);
+    });
+
+    it('hard-fails on missing Version field', () => {
+      fixture = createFixture({
+        'job-bad.md': MISSING_VERSION_JOB,
+      });
+      assert.throws(
+        () => parseJobFile(path.join(fixture.cwd, 'job-bad.md')),
+        (err) => err.message.includes('Version')
+      );
+    });
+
+    it('hard-fails on missing Created field', () => {
+      fixture = createFixture({
+        'job-bad.md': MISSING_CREATED_JOB,
+      });
+      assert.throws(
+        () => parseJobFile(path.join(fixture.cwd, 'job-bad.md')),
+        (err) => err.message.includes('Created')
+      );
+    });
+
+    it('hard-fails on missing Status field', () => {
+      fixture = createFixture({
+        'job-bad.md': MISSING_STATUS_JOB,
+      });
+      assert.throws(
+        () => parseJobFile(path.join(fixture.cwd, 'job-bad.md')),
+        (err) => err.message.includes('Status')
+      );
+    });
+
+    it('hard-fails on missing Check field', () => {
+      fixture = createFixture({
+        'job-bad.md': MISSING_CHECK_JOB,
+      });
+      assert.throws(
+        () => parseJobFile(path.join(fixture.cwd, 'job-bad.md')),
+        (err) => err.message.includes('Check')
+      );
+    });
+
+    it('warns on unrecognized step commands without hard error', () => {
+      fixture = createFixture({
+        'job-warn.md': UNRECOGNIZED_COMMAND_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-warn.md'));
+
+      assert.equal(result.stepCount, 3);
+      // Step 0: recognized command, no warning
+      assert.equal(result.steps[0].command, 'plan-phase');
+      assert.equal(result.steps[0].warning, undefined);
+      // Step 1: unrecognized command, should have warning
+      assert.equal(result.steps[1].command, 'unknown-cmd');
+      assert.ok(result.steps[1].warning, 'Unrecognized command should have a warning');
+      // Step 2: recognized command, no warning
+      assert.equal(result.steps[2].command, 'execute-phase');
+      assert.equal(result.steps[2].warning, undefined);
+    });
+
+    it('parses version from header field, not filename', () => {
+      fixture = createFixture({
+        'job-wrong-name.md': WELL_FORMED_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-wrong-name.md'));
+      assert.equal(result.version, 'v6.0');
+    });
+
+    it('parses all known DGS commands correctly', () => {
+      fixture = createFixture({
+        'job-cmds.md': AUDIT_AND_COMPLETE_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job-cmds.md'));
+
+      assert.equal(result.steps[0].command, 'audit-milestone');
+      assert.equal(result.steps[0].args, 'v6');
+      assert.equal(result.steps[1].command, 'complete-milestone');
+      assert.equal(result.steps[1].args, 'v6');
+      assert.equal(result.steps[2].command, 'plan-milestone-gaps');
+      assert.equal(result.steps[2].args, '');
+      assert.equal(result.steps[3].command, 'discuss-phase');
+      assert.equal(result.steps[3].args, '41');
+      assert.equal(result.steps[4].command, 'research-phase');
+      assert.equal(result.steps[4].args, '42');
+      assert.equal(result.steps[5].command, 'verify-phase');
+      assert.equal(result.steps[5].args, '43');
+
+      // All known commands should NOT have warnings
+      for (const step of result.steps) {
+        assert.equal(step.warning, undefined, `${step.command} should be recognized`);
+      }
+    });
+
+    it('hard-fails on non-existent file', () => {
+      assert.throws(
+        () => parseJobFile('/tmp/nonexistent-job-file-xyz.md'),
+        (err) => err.message.includes('not found') || err.message.includes('ENOENT')
+      );
+    });
+  });
+
+  // ─── updateJobStep Tests ──────────────────────────────────────────────────
+
+  describe('updateJobStep', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('marks step as completed with timestamp', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      updateJobStep(filePath, 2, 'completed', { timestamp: '2026-03-02T16:00:00Z' });
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('- [x] `/dgs:execute-phase 41` \u2014 completed 2026-03-02T16:00:00Z'));
+    });
+
+    it('marks step as failed with error message', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      updateJobStep(filePath, 2, 'failed', {
+        timestamp: '2026-03-02T16:00:00Z',
+        error: 'Some error occurred',
+      });
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('- [!] `/dgs:execute-phase 41` \u2014 failed 2026-03-02T16:00:00Z: Some error occurred'));
+    });
+
+    it('marks step as in-progress with timestamp', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      updateJobStep(filePath, 2, 'in-progress', { timestamp: '2026-03-02T16:00:00Z' });
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('- [>] `/dgs:execute-phase 41` \u2014 started 2026-03-02T16:00:00Z'));
+    });
+
+    it('truncates error messages longer than 120 characters', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      const longError = 'A'.repeat(200);
+      updateJobStep(filePath, 2, 'failed', {
+        timestamp: '2026-03-02T16:00:00Z',
+        error: longError,
+      });
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      // Error should be truncated to ~120 chars + "..."
+      const stepLine = content.split('\n').find(l => l.includes('execute-phase 41'));
+      assert.ok(stepLine, 'Step line should exist');
+      const errorPart = stepLine.split(': ').slice(1).join(': ');
+      // The error on the line should be truncated
+      assert.ok(errorPart.length <= 130, `Error should be truncated, got length ${errorPart.length}`);
+      assert.ok(errorPart.endsWith('...'), 'Truncated error should end with ...');
+    });
+
+    it('hard-errors on negative step index', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      assert.throws(
+        () => updateJobStep(filePath, -1, 'completed', { timestamp: '2026-03-02T16:00:00Z' }),
+        (err) => err.message.includes('out of range')
+      );
+    });
+
+    it('hard-errors on step index >= stepCount', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      assert.throws(
+        () => updateJobStep(filePath, 10, 'completed', { timestamp: '2026-03-02T16:00:00Z' }),
+        (err) => err.message.includes('out of range')
+      );
+    });
+
+    it('preserves all other content (header, other steps) exactly', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      const before = fs.readFileSync(filePath, 'utf-8');
+
+      updateJobStep(filePath, 2, 'completed', { timestamp: '2026-03-02T16:00:00Z' });
+
+      const after = fs.readFileSync(filePath, 'utf-8');
+
+      // Header should be preserved
+      assert.ok(after.includes('# Milestone Job: v6.0'));
+      assert.ok(after.includes('**Version:** v6.0'));
+      assert.ok(after.includes('**Created:** 2026-03-02T10:00:00Z'));
+      assert.ok(after.includes('**Status:** in-progress'));
+      assert.ok(after.includes('**Check:** true'));
+
+      // Other steps should be preserved exactly
+      assert.ok(after.includes('- [x] `/dgs:plan-phase 41` \u2014 completed 2026-03-02T14:30:00Z'));
+      assert.ok(after.includes('- [>] `/dgs:plan-phase 42` \u2014 started 2026-03-02T14:00:00Z'));
+      assert.ok(after.includes('- [!] `/dgs:plan-phase 43` \u2014 failed 2026-03-02T15:00:00Z: Planning inconclusive after retry'));
+    });
+
+    it('resets a previously completed step to pending', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const filePath = path.join(fixture.cwd, 'job.md');
+      updateJobStep(filePath, 0, 'pending');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('- [ ] `/dgs:plan-phase 41`'));
+      // Should not have any annotation after backtick close
+      const stepLine = content.split('\n').find(l => l.includes('plan-phase 41') && l.startsWith('- [ ]'));
+      assert.ok(stepLine, 'Pending step line should exist');
+      assert.ok(!stepLine.includes('\u2014'), 'Pending step should have no annotation');
+    });
+  });
+
+  // ─── moveJobFile Tests ────────────────────────────────────────────────────
+
+  describe('moveJobFile', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('moves file from source to target directory', () => {
+      fixture = createFixture({
+        'pending/job-v6.md': WELL_FORMED_JOB,
+        'in-progress/': null,
+      });
+      const src = path.join(fixture.cwd, 'pending', 'job-v6.md');
+      const targetDir = path.join(fixture.cwd, 'in-progress');
+
+      const result = moveJobFile(src, targetDir);
+
+      assert.equal(result.moved, true);
+      assert.ok(!fs.existsSync(src), 'Source file should be removed');
+      assert.ok(fs.existsSync(path.join(targetDir, 'job-v6.md')), 'File should exist in target');
+    });
+
+    it('auto-creates target directory if it does not exist', () => {
+      fixture = createFixture({
+        'pending/job-v6.md': WELL_FORMED_JOB,
+      });
+      const src = path.join(fixture.cwd, 'pending', 'job-v6.md');
+      const targetDir = path.join(fixture.cwd, 'completed');
+
+      const result = moveJobFile(src, targetDir);
+
+      assert.equal(result.moved, true);
+      assert.ok(fs.existsSync(targetDir), 'Target directory should have been created');
+      assert.ok(fs.existsSync(path.join(targetDir, 'job-v6.md')), 'File should exist in target');
+      assert.ok(!fs.existsSync(src), 'Source file should be removed');
+    });
+
+    it('returns no-op with warning when file already in target directory', () => {
+      fixture = createFixture({
+        'in-progress/job-v6.md': WELL_FORMED_JOB,
+      });
+      const src = path.join(fixture.cwd, 'in-progress', 'job-v6.md');
+      const targetDir = path.join(fixture.cwd, 'in-progress');
+
+      const result = moveJobFile(src, targetDir);
+
+      assert.equal(result.moved, false);
+      assert.ok(result.warning, 'Should return a warning for no-op');
+      assert.ok(fs.existsSync(src), 'File should still exist');
+    });
+
+    it('returns from and to paths in result', () => {
+      fixture = createFixture({
+        'pending/job-v6.md': WELL_FORMED_JOB,
+        'completed/': null,
+      });
+      const src = path.join(fixture.cwd, 'pending', 'job-v6.md');
+      const targetDir = path.join(fixture.cwd, 'completed');
+
+      const result = moveJobFile(src, targetDir);
+
+      assert.equal(result.moved, true);
+      assert.equal(result.from, src);
+      assert.equal(result.to, path.join(targetDir, 'job-v6.md'));
+    });
+
+    it('handles deeply nested target directory creation', () => {
+      fixture = createFixture({
+        'job-v6.md': WELL_FORMED_JOB,
+      });
+      const src = path.join(fixture.cwd, 'job-v6.md');
+      const targetDir = path.join(fixture.cwd, 'a', 'b', 'c', 'completed');
+
+      const result = moveJobFile(src, targetDir);
+
+      assert.equal(result.moved, true);
+      assert.ok(fs.existsSync(path.join(targetDir, 'job-v6.md')));
+    });
+  });
+
+  // ─── generateMilestoneSteps Tests ──────────────────────────────────────────
+
+  describe('generateMilestoneSteps', () => {
+
+    it('produces 4 steps for unplanned phase (no_directory)', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'no_directory', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 4);
+      assert.equal(steps[0].command, 'map-codebase');
+      assert.equal(steps[0].args, '50 --auto');
+      assert.equal(steps[1].command, 'plan-phase');
+      assert.equal(steps[1].args, '50 --non-interactive');
+      assert.equal(steps[2].command, 'execute-phase');
+      assert.equal(steps[2].args, '50 --non-interactive');
+      assert.equal(steps[3].command, 'verify-work');
+      assert.equal(steps[3].args, '50 --auto-test');
+    });
+
+    it('produces 4 steps for unplanned phase (empty)', () => {
+      const phases = [
+        { number: '51', name: 'Job Execution', disk_status: 'empty', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 4);
+      assert.equal(steps[0].command, 'map-codebase');
+      assert.equal(steps[1].command, 'plan-phase');
+      assert.equal(steps[2].command, 'execute-phase');
+      assert.equal(steps[3].command, 'verify-work');
+    });
+
+    it('produces 4 steps for discussed phase (context but no plan)', () => {
+      const phases = [
+        { number: '52', name: 'Silent Mode', disk_status: 'discussed', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 4);
+      assert.equal(steps[0].command, 'map-codebase');
+      assert.equal(steps[1].command, 'plan-phase');
+      assert.equal(steps[2].command, 'execute-phase');
+      assert.equal(steps[3].command, 'verify-work');
+    });
+
+    it('produces 4 steps for researched phase', () => {
+      const phases = [
+        { number: '53', name: 'Audit Integration', disk_status: 'researched', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 4);
+      assert.equal(steps[0].command, 'map-codebase');
+      assert.equal(steps[1].command, 'plan-phase');
+      assert.equal(steps[2].command, 'execute-phase');
+      assert.equal(steps[3].command, 'verify-work');
+    });
+
+    it('produces 2 steps for planned phase', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 2);
+      assert.equal(steps[0].command, 'execute-phase');
+      assert.equal(steps[0].args, '50 --non-interactive');
+      assert.equal(steps[1].command, 'verify-work');
+      assert.equal(steps[1].args, '50 --auto-test');
+    });
+
+    it('produces 2 steps for partially executed phase', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'partial', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 2);
+      assert.equal(steps[0].command, 'execute-phase');
+      assert.equal(steps[1].command, 'verify-work');
+      assert.equal(steps[1].args, '50 --auto-test');
+    });
+
+    it('produces 0 steps for completed phase (disk_status complete)', () => {
+      const phases = [
+        { number: '49', name: 'Job File Format', disk_status: 'complete', roadmap_complete: true },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 0);
+    });
+
+    it('produces 0 steps for roadmap_complete phase even if disk_status is not complete', () => {
+      const phases = [
+        { number: '49', name: 'Job File Format', disk_status: 'planned', roadmap_complete: true },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 0);
+    });
+
+    it('handles mixed phases correctly (complete + unplanned + planned)', () => {
+      const phases = [
+        { number: '49', name: 'Job File Format', disk_status: 'complete', roadmap_complete: true },
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+        { number: '51', name: 'Job Execution', disk_status: 'no_directory', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      // Phase 49: 0 steps (complete)
+      // Phase 50: 2 steps (planned -> execute + verify)
+      // Phase 51: 4 steps (unplanned -> map + plan + execute + verify)
+      assert.equal(steps.length, 6);
+      assert.equal(steps[0].command, 'execute-phase');
+      assert.equal(steps[0].args, '50 --non-interactive');
+      assert.equal(steps[1].command, 'verify-work');
+      assert.equal(steps[1].args, '50 --auto-test');
+      assert.equal(steps[2].command, 'map-codebase');
+      assert.equal(steps[2].args, '51 --auto');
+      assert.equal(steps[3].command, 'plan-phase');
+      assert.equal(steps[3].args, '51 --non-interactive');
+      assert.equal(steps[4].command, 'execute-phase');
+      assert.equal(steps[4].args, '51 --non-interactive');
+      assert.equal(steps[5].command, 'verify-work');
+      assert.equal(steps[5].args, '51 --auto-test');
+    });
+
+    it('appends audit and complete steps when check=true', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: true, version: 'v6.0' });
+
+      // 2 phase steps + 2 check steps = 4
+      assert.equal(steps.length, 4);
+      assert.equal(steps[2].command, 'audit-milestone');
+      assert.equal(steps[2].args, 'v6.0');
+      assert.equal(steps[3].command, 'complete-milestone');
+      assert.equal(steps[3].args, 'v6.0');
+    });
+
+    it('does NOT append audit/complete steps when check=false', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 2);
+      // No audit/complete steps
+      assert.ok(!steps.some(s => s.command === 'audit-milestone'));
+      assert.ok(!steps.some(s => s.command === 'complete-milestone'));
+    });
+
+    it('returns only audit+complete when all phases complete and check=true', () => {
+      const phases = [
+        { number: '49', name: 'Job File Format', disk_status: 'complete', roadmap_complete: true },
+        { number: '50', name: 'Job Creation', disk_status: 'complete', roadmap_complete: true },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: true, version: 'v6.0' });
+
+      assert.equal(steps.length, 2);
+      assert.equal(steps[0].command, 'audit-milestone');
+      assert.equal(steps[1].command, 'complete-milestone');
+    });
+
+    it('returns empty array when all phases complete and check=false', () => {
+      const phases = [
+        { number: '49', name: 'Job File Format', disk_status: 'complete', roadmap_complete: true },
+        { number: '50', name: 'Job Creation', disk_status: 'complete', roadmap_complete: true },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      assert.equal(steps.length, 0);
+    });
+
+    it('handles decimal phase numbers in correct sequence order', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+        { number: '50.1', name: 'Hotfix', disk_status: 'no_directory', roadmap_complete: false },
+        { number: '51', name: 'Job Execution', disk_status: 'planned', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      // Phase 50: 2 steps (execute + verify), Phase 50.1: 4 steps (map + plan + execute + verify), Phase 51: 2 steps (execute + verify) = 8 total
+      assert.equal(steps.length, 8);
+      // First phase should be 50 (execute-phase)
+      assert.equal(steps[0].args, '50 --non-interactive');
+      // Then 50.1 (map-codebase at index 2)
+      assert.equal(steps[2].command, 'map-codebase');
+      assert.equal(steps[2].args, '50.1 --auto');
+      // Then 51 (execute-phase at index 6)
+      assert.equal(steps[6].args, '51 --non-interactive');
+    });
+
+    it('includes correct flags on plan-phase (--non-interactive), execute-phase (--non-interactive), and map-codebase (--auto) steps', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'no_directory', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      const mapStep = steps.find(s => s.command === 'map-codebase');
+      const planStep = steps.find(s => s.command === 'plan-phase');
+      const executeStep = steps.find(s => s.command === 'execute-phase');
+      const verifyStep = steps.find(s => s.command === 'verify-work');
+
+      assert.ok(mapStep.args.includes('--auto'), 'map-codebase should have --auto');
+      assert.ok(planStep.args.includes('--non-interactive'), 'plan-phase should have --non-interactive');
+      assert.ok(executeStep.args.includes('--non-interactive'), 'execute-phase should have --non-interactive');
+      assert.ok(verifyStep.args.includes('--auto-test'), 'verify-work should have --auto-test');
+    });
+
+    it('sorts phases by number numerically, not lexicographically', () => {
+      const phases = [
+        { number: '51', name: 'Job Execution', disk_status: 'planned', roadmap_complete: false },
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+        { number: '49', name: 'Job File Format', disk_status: 'complete', roadmap_complete: true },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      // Phase 49 complete (0 steps), Phase 50 planned (2 steps), Phase 51 planned (2 steps) = 4
+      assert.equal(steps.length, 4);
+      assert.equal(steps[0].args, '50 --non-interactive');
+      assert.equal(steps[1].args, '50 --auto-test');
+      assert.equal(steps[2].args, '51 --non-interactive');
+      assert.equal(steps[3].args, '51 --auto-test');
+    });
+
+    it('returns steps as objects with command and args properties', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      for (const step of steps) {
+        assert.ok(typeof step.command === 'string', 'step should have command string');
+        assert.ok(typeof step.args === 'string', 'step should have args string');
+      }
+    });
+
+    it('map-codebase step has --auto flag', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'no_directory', roadmap_complete: false },
+        { number: '51', name: 'Job Execution', disk_status: 'empty', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      const mapSteps = steps.filter(s => s.command === 'map-codebase');
+      assert.ok(mapSteps.length > 0, 'Should have map-codebase steps');
+      for (const step of mapSteps) {
+        assert.ok(step.args.includes('--auto'), `map-codebase step for ${step.args} should have --auto`);
+      }
+    });
+
+    it('verify-work steps include --auto-test flag', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+        { number: '51', name: 'Job Execution', disk_status: 'no_directory', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      const verifySteps = steps.filter(s => s.command === 'verify-work');
+      assert.ok(verifySteps.length > 0, 'Should have verify-work steps');
+      for (const step of verifySteps) {
+        assert.ok(step.args.includes('--auto-test'), `verify-work step for ${step.args} should have --auto-test`);
+      }
+    });
+
+    it('no map-codebase for NEEDS_EXECUTION phases', () => {
+      const phases = [
+        { number: '50', name: 'Job Creation', disk_status: 'planned', roadmap_complete: false },
+        { number: '51', name: 'Job Execution', disk_status: 'partial', roadmap_complete: false },
+      ];
+      const steps = generateMilestoneSteps(phases, { check: false, version: 'v6.0' });
+
+      const mapSteps = steps.filter(s => s.command === 'map-codebase');
+      assert.equal(mapSteps.length, 0, 'Planned and partial phases should NOT have map-codebase steps');
+    });
+  });
+
+  // ─── buildJobFileContent Tests ─────────────────────────────────────────────
+
+  describe('buildJobFileContent', () => {
+
+    it('produces valid markdown with header fields', () => {
+      const steps = [
+        { command: 'plan-phase', args: '50 --non-interactive' },
+        { command: 'execute-phase', args: '50 --non-interactive' },
+        { command: 'verify-work', args: '50' },
+      ];
+      const content = buildJobFileContent('v6.0', true, steps);
+
+      assert.ok(content.includes('# Milestone Job: v6.0'), 'Should have title');
+      assert.ok(content.includes('**Version:** v6.0'), 'Should have version');
+      assert.ok(content.includes('**Status:** pending'), 'Should have status');
+      assert.ok(content.includes('**Check:** true'), 'Should have check=true');
+    });
+
+    it('has Created field with ISO timestamp', () => {
+      const content = buildJobFileContent('v6.0', true, []);
+      const createdMatch = content.match(/\*\*Created:\*\*\s*(\S+)/);
+      assert.ok(createdMatch, 'Should have Created field');
+      // Verify ISO format: YYYY-MM-DDTHH:MM:SSZ
+      assert.ok(createdMatch[1].match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/), 'Created should be ISO timestamp');
+    });
+
+    it('produces checkbox lines for each step', () => {
+      const steps = [
+        { command: 'plan-phase', args: '50 --non-interactive' },
+        { command: 'execute-phase', args: '50 --non-interactive' },
+        { command: 'verify-work', args: '50' },
+      ];
+      const content = buildJobFileContent('v6.0', true, steps);
+
+      assert.ok(content.includes('- [ ] `/dgs:plan-phase 50 --non-interactive`'), 'plan-phase step');
+      assert.ok(content.includes('- [ ] `/dgs:execute-phase 50 --non-interactive`'), 'execute-phase step');
+      assert.ok(content.includes('- [ ] `/dgs:verify-work 50`'), 'verify-work step');
+    });
+
+    it('includes ## Steps section heading', () => {
+      const content = buildJobFileContent('v6.0', true, []);
+      assert.ok(content.includes('## Steps'), 'Should have Steps heading');
+    });
+
+    it('sets Check to false when check param is false', () => {
+      const content = buildJobFileContent('v6.0', false, []);
+      assert.ok(content.includes('**Check:** false'), 'Should have check=false');
+    });
+
+    it('round-trips through parseJobFile without errors', () => {
+      const steps = [
+        { command: 'plan-phase', args: '50 --non-interactive' },
+        { command: 'execute-phase', args: '50 --non-interactive' },
+        { command: 'verify-work', args: '50' },
+        { command: 'audit-milestone', args: 'v6.0' },
+        { command: 'complete-milestone', args: 'v6.0' },
+      ];
+      const content = buildJobFileContent('v6.0', true, steps);
+
+      // Write to temp file, parse it back
+      const fixture = createFixture({
+        'job-roundtrip.md': content,
+      });
+
+      try {
+        const parsed = parseJobFile(path.join(fixture.cwd, 'job-roundtrip.md'));
+        assert.equal(parsed.version, 'v6.0');
+        assert.equal(parsed.check, true);
+        assert.equal(parsed.status, 'pending');
+        assert.equal(parsed.stepCount, 5);
+        assert.equal(parsed.steps[0].command, 'plan-phase');
+        assert.equal(parsed.steps[0].args, '50 --non-interactive');
+        assert.equal(parsed.steps[4].command, 'complete-milestone');
+        assert.equal(parsed.steps[4].args, 'v6.0');
+      } finally {
+        fixture.cleanup();
+      }
+    });
+
+    it('ends with trailing newline', () => {
+      const content = buildJobFileContent('v6.0', true, []);
+      assert.ok(content.endsWith('\n'), 'Should end with newline');
+    });
+  });
+
+  // ─── cmdJobsCreateMilestone Tests ──────────────────────────────────────────
+
+  describe('cmdJobsCreateMilestone', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const FIXTURE_ROADMAP = `# Roadmap
+
+## Milestones
+
+- v6.0 Job Orchestration -- Phases 49-55 (in progress)
+
+## Phases
+
+### v6.0 Job Orchestration (In Progress)
+
+- [x] **Phase 49: Job File Format & Infrastructure** (completed 2026-03-03)
+- [ ] **Phase 50: Job Creation**
+- [ ] **Phase 51: Job Execution Core**
+
+### Phase 49: Job File Format & Infrastructure
+**Goal**: Job files can be created, parsed, updated, and moved
+**Depends on**: Nothing
+**Plans:** 2/2 plans complete
+Plans:
+- [x] 49-01-PLAN.md
+- [x] 49-02-PLAN.md
+
+### Phase 50: Job Creation
+**Goal**: Users can generate a milestone build job
+**Depends on**: Phase 49
+Plans:
+- [ ] 50-01-PLAN.md
+- [ ] 50-02-PLAN.md
+
+### Phase 51: Job Execution Core
+**Goal**: Users can execute a milestone job
+**Depends on**: Phase 50
+`;
+
+    it('auto-detects active milestone version from ROADMAP.md', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsCreateMilestone(fixture.cwd, null, true, false);
+      assert.equal(result.version, 'v6.0');
+      assert.equal(result.created, true);
+    });
+
+    it('writes job file to .planning/jobs/pending/', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsCreateMilestone(fixture.cwd, 'v6.0', true, false);
+      assert.ok(result.file.includes('pending'));
+      assert.ok(result.file.includes('milestone-v6.0.md'));
+
+      const jobFilePath = path.join(fixture.cwd, result.file);
+      assert.ok(fs.existsSync(jobFilePath), 'Job file should exist on disk');
+    });
+
+    it('auto-creates .planning/jobs/pending/ directory', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      // Ensure pending dir does not exist yet
+      const pendingDir = path.join(fixture.cwd, '.planning', 'jobs', 'pending');
+      assert.ok(!fs.existsSync(pendingDir), 'pending dir should not exist before call');
+
+      cmdJobsCreateMilestone(fixture.cwd, 'v6.0', true, false);
+      assert.ok(fs.existsSync(pendingDir), 'pending dir should be auto-created');
+    });
+
+    it('returns JSON with expected fields', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsCreateMilestone(fixture.cwd, 'v6.0', true, false);
+      assert.equal(result.created, true);
+      assert.equal(result.version, 'v6.0');
+      assert.ok(typeof result.file === 'string');
+      assert.ok(typeof result.step_count === 'number');
+      assert.ok(typeof result.phase_count === 'number');
+      assert.ok(Array.isArray(result.steps_preview));
+      assert.ok(result.step_count > 0);
+    });
+
+    it('throws error when no ROADMAP.md exists', () => {
+      fixture = createFixture({
+        '.planning/phases/': null,
+      });
+
+      assert.throws(
+        () => cmdJobsCreateMilestone(fixture.cwd, null, true, false),
+        (err) => err.message.includes('ROADMAP.md')
+      );
+    });
+
+    it('throws error when specified version not found in ROADMAP', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/': null,
+      });
+
+      assert.throws(
+        () => cmdJobsCreateMilestone(fixture.cwd, 'v99.0', true, false),
+        (err) => err.message.includes('v99.0') || err.message.includes('not found')
+      );
+    });
+  });
+
+  // ─── cmdJobsMilestonePreview Tests ─────────────────────────────────────────
+
+  describe('cmdJobsMilestonePreview', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const FIXTURE_ROADMAP = `# Roadmap
+
+## Milestones
+
+- v6.0 Job Orchestration -- Phases 49-55 (in progress)
+
+## Phases
+
+### v6.0 Job Orchestration (In Progress)
+
+- [x] **Phase 49: Job File Format & Infrastructure** (completed 2026-03-03)
+- [ ] **Phase 50: Job Creation**
+- [ ] **Phase 51: Job Execution Core**
+
+### Phase 49: Job File Format & Infrastructure
+**Goal**: Job files can be created, parsed, updated, and moved
+**Depends on**: Nothing
+**Plans:** 2/2 plans complete
+Plans:
+- [x] 49-01-PLAN.md
+- [x] 49-02-PLAN.md
+
+### Phase 50: Job Creation
+**Goal**: Users can generate a milestone build job
+**Depends on**: Phase 49
+Plans:
+- [ ] 50-01-PLAN.md
+- [ ] 50-02-PLAN.md
+
+### Phase 51: Job Execution Core
+**Goal**: Users can execute a milestone job
+**Depends on**: Phase 50
+`;
+
+    it('returns preview JSON with expected fields', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+      assert.equal(result.preview, true);
+      assert.equal(result.version, 'v6.0');
+      assert.equal(result.check, true);
+      assert.ok(typeof result.step_count === 'number');
+      assert.ok(typeof result.phase_count === 'number');
+      assert.ok(Array.isArray(result.steps_preview));
+      assert.ok(typeof result.content === 'string');
+    });
+
+    it('does NOT write any file to disk', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+
+      const pendingDir = path.join(fixture.cwd, '.planning', 'jobs', 'pending');
+      assert.ok(!fs.existsSync(pendingDir), 'No jobs directory should be created for preview');
+    });
+
+    it('steps_preview is array of step command strings', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+      for (const preview of result.steps_preview) {
+        assert.ok(typeof preview === 'string', 'Each preview should be a string');
+        assert.ok(preview.startsWith('/dgs:'), 'Each preview should start with /dgs:');
+      }
+    });
+
+    it('content is the full markdown that would be written', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+      assert.ok(result.content.includes('# Milestone Job: v6.0'));
+      assert.ok(result.content.includes('## Steps'));
+    });
+
+    it('phase_count counts distinct phases with steps', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+      // Phase 49 complete (0 steps), Phase 50 planned (2 steps), Phase 51 no_directory (3 steps) = 2 phases
+      assert.equal(result.phase_count, 2);
+    });
+
+    it('combines correctly with --no-check (omits audit/complete from preview)', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const withCheck = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', true, false);
+      const withoutCheck = cmdJobsMilestonePreview(fixture.cwd, 'v6.0', false, false);
+
+      assert.equal(withCheck.check, true);
+      assert.equal(withoutCheck.check, false);
+      assert.ok(withCheck.step_count > withoutCheck.step_count, 'check=true should have more steps');
+      assert.ok(withCheck.steps_preview.some(s => s.includes('audit-milestone')), 'check=true should have audit');
+      assert.ok(!withoutCheck.steps_preview.some(s => s.includes('audit-milestone')), 'check=false should NOT have audit');
+    });
+
+    it('auto-detects milestone version same as create', () => {
+      fixture = createFixture({
+        '.planning/ROADMAP.md': FIXTURE_ROADMAP,
+        '.planning/phases/49-job-file-format/49-01-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-02-PLAN.md': '',
+        '.planning/phases/49-job-file-format/49-01-SUMMARY.md': '',
+        '.planning/phases/49-job-file-format/49-02-SUMMARY.md': '',
+        '.planning/phases/50-job-creation/50-01-PLAN.md': '',
+        '.planning/phases/50-job-creation/50-02-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, null, true, false);
+      assert.equal(result.version, 'v6.0');
+    });
+
+    it('throws error when no ROADMAP.md exists', () => {
+      fixture = createFixture({
+        '.planning/phases/': null,
+      });
+
+      assert.throws(
+        () => cmdJobsMilestonePreview(fixture.cwd, null, true, false),
+        (err) => err.message.includes('ROADMAP.md')
+      );
+    });
+  });
+
+  // ─── findJobFile Tests ──────────────────────────────────────────────────
+
+  describe('findJobFile', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('finds job in in-progress/ when file exists there', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'in-progress');
+      assert.ok(result.path.includes('in-progress'));
+      assert.ok(result.path.includes('milestone-v6.0.md'));
+    });
+
+    it('finds job in pending/ when not in in-progress/', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'pending');
+      assert.ok(result.path.includes('pending'));
+    });
+
+    it('prefers in-progress/ over pending/ when file exists in both', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'in-progress');
+    });
+
+    it('returns found:false when file exists in neither directory', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, false);
+    });
+
+    it('checks completed/ as fallback for inspection', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'completed');
+      assert.ok(result.path.includes('completed'));
+    });
+
+    it('handles version without v prefix (e.g., "6.0" -> milestone-v6.0.md)', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, '6.0');
+      assert.equal(result.found, true);
+      assert.ok(result.path.includes('milestone-v6.0.md'));
+    });
+
+    it('handles version with v prefix correctly', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.ok(result.path.includes('milestone-v6.0.md'));
+    });
+
+    it('finds job in project subdirectory completed/', () => {
+      fixture = createFixture({
+        '.planning/projects/test-project/jobs/completed/milestone-v6.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'completed');
+      assert.ok(result.path.includes('projects'));
+      assert.ok(result.path.includes('test-project'));
+      assert.ok(result.path.includes('milestone-v6.0.md'));
+    });
+
+    it('prefers top-level jobs/ over project subdirectory', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/projects/test-project/jobs/completed/milestone-v6.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'in-progress');
+      assert.ok(!result.path.includes('projects'), 'Should find top-level job first');
+    });
+
+    it('finds job in project subdirectory in-progress/', () => {
+      fixture = createFixture({
+        '.planning/projects/my-app/jobs/in-progress/milestone-v7.0.md': WELL_FORMED_JOB,
+      });
+      const result = findJobFile(fixture.cwd, 'v7.0');
+      assert.equal(result.found, true);
+      assert.equal(result.directory, 'in-progress');
+      assert.ok(result.path.includes('my-app'));
+    });
+
+    it('returns found:false when not in top-level or project subdirectories', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/projects/test-project/jobs/pending/': null,
+      });
+      const result = findJobFile(fixture.cwd, 'v99.0');
+      assert.equal(result.found, false);
+    });
+  });
+
+  // ─── updateJobHeader Tests ──────────────────────────────────────────────
+
+  describe('updateJobHeader', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('updates Status field from pending to in-progress', () => {
+      const pendingJob = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 41\`
+- [ ] \`/dgs:execute-phase 41\`
+`;
+      fixture = createFixture({ 'job.md': pendingJob });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      updateJobHeader(filePath, 'Status', 'in-progress');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('**Status:** in-progress'), 'Status should be updated');
+      // Other header fields preserved
+      assert.ok(content.includes('**Version:** v6.0'));
+      assert.ok(content.includes('**Created:** 2026-03-02T10:00:00Z'));
+      assert.ok(content.includes('**Check:** true'));
+    });
+
+    it('updates Status field from in-progress to completed preserving all other headers', () => {
+      fixture = createFixture({ 'job.md': WELL_FORMED_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      updateJobHeader(filePath, 'Status', 'completed');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('**Status:** completed'), 'Status should be updated to completed');
+      assert.ok(content.includes('**Version:** v6.0'), 'Version preserved');
+      assert.ok(content.includes('**Created:** 2026-03-02T10:00:00Z'), 'Created preserved');
+      assert.ok(content.includes('**Check:** true'), 'Check preserved');
+    });
+
+    it('updates Status field from in-progress to failed', () => {
+      fixture = createFixture({ 'job.md': WELL_FORMED_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      updateJobHeader(filePath, 'Status', 'failed');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('**Status:** failed'), 'Status should be updated to failed');
+    });
+
+    it('throws Error if the field is not found in the file', () => {
+      fixture = createFixture({ 'job.md': WELL_FORMED_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      assert.throws(
+        () => updateJobHeader(filePath, 'NonExistent', 'value'),
+        (err) => err.message.includes('NonExistent') || err.message.includes('not found')
+      );
+    });
+
+    it('preserves exact step line content (round-trip identical steps)', () => {
+      fixture = createFixture({ 'job.md': WELL_FORMED_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      // Parse steps before
+      const beforeParsed = parseJobFile(filePath);
+
+      // Update a header field
+      updateJobHeader(filePath, 'Status', 'completed');
+
+      // Parse steps after
+      const afterParsed = parseJobFile(filePath);
+
+      // Steps should be identical
+      assert.equal(afterParsed.steps.length, beforeParsed.steps.length);
+      for (let i = 0; i < beforeParsed.steps.length; i++) {
+        assert.equal(afterParsed.steps[i].command, beforeParsed.steps[i].command);
+        assert.equal(afterParsed.steps[i].args, beforeParsed.steps[i].args);
+        assert.equal(afterParsed.steps[i].status, beforeParsed.steps[i].status);
+        assert.equal(afterParsed.steps[i].timestamp, beforeParsed.steps[i].timestamp);
+        assert.equal(afterParsed.steps[i].error, beforeParsed.steps[i].error);
+      }
+    });
+  });
+
+  // ─── insertJobSteps Tests ──────────────────────────────────────────────
+
+  describe('insertJobSteps', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const SIX_STEP_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 50\` \u2014 completed 2026-03-02T11:00:00Z
+- [x] \`/dgs:execute-phase 50 --auto\` \u2014 completed 2026-03-02T12:00:00Z
+- [x] \`/dgs:verify-work 50\` \u2014 completed 2026-03-02T13:00:00Z
+- [x] \`/dgs:plan-phase 51\` \u2014 completed 2026-03-02T14:00:00Z
+- [x] \`/dgs:execute-phase 51 --auto\` \u2014 completed 2026-03-02T15:00:00Z
+- [ ] \`/dgs:verify-work 51\`
+`;
+
+    it('inserts steps after a specific completed step', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newSteps = [
+        { command: 'plan-phase', args: '51.1 --non-interactive' },
+        { command: 'execute-phase', args: '51.1 --non-interactive' },
+        { command: 'verify-work', args: '51.1' },
+        { command: 'plan-phase', args: '51.2 --non-interactive' },
+      ];
+
+      const result = insertJobSteps(filePath, 4, newSteps);
+
+      assert.equal(result.inserted, true);
+      assert.equal(result.count, 4);
+      assert.equal(result.startIndex, 5);
+
+      // Verify the file content
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const stepLines = content.split('\n').filter(l => l.trim().startsWith('- ['));
+      assert.equal(stepLines.length, 10, 'Should have 6 original + 4 new = 10 steps');
+
+      // The new steps should be pending with correct commands
+      assert.ok(stepLines[5].includes('plan-phase 51.1 --non-interactive'), 'First inserted step');
+      assert.ok(stepLines[6].includes('execute-phase 51.1 --non-interactive'), 'Second inserted step');
+      assert.ok(stepLines[7].includes('verify-work 51.1'), 'Third inserted step');
+      assert.ok(stepLines[8].includes('plan-phase 51.2 --non-interactive'), 'Fourth inserted step');
+    });
+
+    it('each new step is formatted as pending checkbox with /dgs: prefix', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newSteps = [
+        { command: 'plan-phase', args: '52 --non-interactive' },
+      ];
+
+      insertJobSteps(filePath, 0, newSteps);
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const stepLines = content.split('\n').filter(l => l.trim().startsWith('- ['));
+      // Inserted step at index 1 (after step 0)
+      assert.ok(stepLines[1].includes('- [ ] `/dgs:plan-phase 52 --non-interactive`'), 'Step should be formatted correctly');
+    });
+
+    it('inserting after the last step appends at the end of steps section', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newSteps = [
+        { command: 'audit-milestone', args: 'v6.0' },
+      ];
+
+      const result = insertJobSteps(filePath, 5, newSteps);
+
+      assert.equal(result.inserted, true);
+      assert.equal(result.count, 1);
+      assert.equal(result.startIndex, 6);
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const stepLines = content.split('\n').filter(l => l.trim().startsWith('- ['));
+      assert.equal(stepLines.length, 7, 'Should have 6 + 1 = 7 steps');
+      assert.ok(stepLines[6].includes('audit-milestone v6.0'), 'Last step should be the new one');
+    });
+
+    it('inserting with afterStepIndex -1 inserts before all existing steps', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newSteps = [
+        { command: 'plan-phase', args: '49 --non-interactive' },
+      ];
+
+      const result = insertJobSteps(filePath, -1, newSteps);
+
+      assert.equal(result.inserted, true);
+      assert.equal(result.count, 1);
+      assert.equal(result.startIndex, 0);
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const stepLines = content.split('\n').filter(l => l.trim().startsWith('- ['));
+      assert.equal(stepLines.length, 7, 'Should have 6 + 1 = 7 steps');
+      assert.ok(stepLines[0].includes('plan-phase 49 --non-interactive'), 'First step should be the new one');
+      // Original first step should now be second
+      assert.ok(stepLines[1].includes('plan-phase 50'), 'Original first step should be second');
+    });
+
+    it('preserves all existing steps and header content exactly', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      // Parse before
+      const beforeParsed = parseJobFile(filePath);
+
+      const newSteps = [
+        { command: 'plan-phase', args: '52 --non-interactive' },
+      ];
+
+      insertJobSteps(filePath, 2, newSteps);
+
+      // Parse after
+      const afterParsed = parseJobFile(filePath);
+
+      // Header should be preserved
+      assert.equal(afterParsed.version, beforeParsed.version);
+      assert.equal(afterParsed.status, beforeParsed.status);
+      assert.equal(afterParsed.check, beforeParsed.check);
+
+      // Original steps should still be there (just shifted)
+      assert.equal(afterParsed.stepCount, beforeParsed.stepCount + 1);
+
+      // Steps 0-2 should be identical to before
+      for (let i = 0; i <= 2; i++) {
+        assert.equal(afterParsed.steps[i].command, beforeParsed.steps[i].command);
+        assert.equal(afterParsed.steps[i].args, beforeParsed.steps[i].args);
+        assert.equal(afterParsed.steps[i].status, beforeParsed.steps[i].status);
+      }
+
+      // Steps 4-6 after insert should correspond to original 3-5
+      for (let i = 3; i < beforeParsed.steps.length; i++) {
+        assert.equal(afterParsed.steps[i + 1].command, beforeParsed.steps[i].command);
+        assert.equal(afterParsed.steps[i + 1].args, beforeParsed.steps[i].args);
+        assert.equal(afterParsed.steps[i + 1].status, beforeParsed.steps[i].status);
+      }
+    });
+
+    it('returns { inserted: true, count: N, startIndex: M }', () => {
+      fixture = createFixture({ 'job.md': SIX_STEP_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newSteps = [
+        { command: 'plan-phase', args: '52 --non-interactive' },
+        { command: 'execute-phase', args: '52 --non-interactive' },
+      ];
+
+      const result = insertJobSteps(filePath, 3, newSteps);
+
+      assert.equal(result.inserted, true);
+      assert.equal(result.count, 2);
+      assert.equal(result.startIndex, 4);
+    });
+  });
+
+  // ─── parseJobFile GapFixCycle Tests ───────────────────────────────────
+
+  describe('parseJobFile GapFixCycle header', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('returns gapFixCycle: 0 when no GapFixCycle header field exists', () => {
+      fixture = createFixture({ 'job.md': WELL_FORMED_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const result = parseJobFile(filePath);
+      assert.equal(result.gapFixCycle, 0, 'Should default to 0 when GapFixCycle header absent');
+    });
+
+    it('returns gapFixCycle: 2 when **GapFixCycle:** 2 header line exists', () => {
+      const jobWithGapFix = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+**GapFixCycle:** 2
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-02T14:30:00Z
+- [ ] \`/dgs:execute-phase 41\`
+`;
+      fixture = createFixture({ 'job.md': jobWithGapFix });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const result = parseJobFile(filePath);
+      assert.equal(result.gapFixCycle, 2, 'Should parse GapFixCycle as 2');
+    });
+  });
+
+  // ─── buildGapFixSteps Tests ───────────────────────────────────────────
+
+  describe('buildGapFixSteps', () => {
+    it('generates plan-phase + execute-phase per phase, ending with audit-milestone', () => {
+      const newPhases = [
+        { number: '53.1', name: 'Fix auth gaps' },
+        { number: '53.2', name: 'Fix data gaps' },
+      ];
+
+      const steps = buildGapFixSteps(newPhases, 'v6.0');
+
+      assert.equal(steps.length, 5, 'Should have 5 steps (2 phases x 2 + 1 audit)');
+
+      assert.equal(steps[0].command, 'plan-phase');
+      assert.equal(steps[0].args, '53.1 --non-interactive');
+
+      assert.equal(steps[1].command, 'execute-phase');
+      assert.equal(steps[1].args, '53.1 --non-interactive');
+
+      assert.equal(steps[2].command, 'plan-phase');
+      assert.equal(steps[2].args, '53.2 --non-interactive');
+
+      assert.equal(steps[3].command, 'execute-phase');
+      assert.equal(steps[3].args, '53.2 --non-interactive');
+
+      assert.equal(steps[4].command, 'audit-milestone');
+      assert.equal(steps[4].args, 'v6.0');
+    });
+
+    it('does not include discuss-phase or verify-work steps', () => {
+      const newPhases = [
+        { number: '53.1', name: 'Fix auth gaps' },
+      ];
+
+      const steps = buildGapFixSteps(newPhases, 'v6.0');
+
+      const commands = steps.map(s => s.command);
+      assert.ok(!commands.includes('discuss-phase'), 'Should not include discuss-phase');
+      assert.ok(!commands.includes('verify-work'), 'Should not include verify-work');
+    });
+  });
+
+  // ─── insertGapFixSection Tests ────────────────────────────────────────
+
+  describe('insertGapFixSection', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const AUDIT_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 50\` \u2014 completed 2026-03-02T11:00:00Z
+- [x] \`/dgs:execute-phase 50 --auto\` \u2014 completed 2026-03-02T12:00:00Z
+- [x] \`/dgs:verify-work 50\` \u2014 completed 2026-03-02T13:00:00Z
+- [x] \`/dgs:audit-milestone v6.0\` \u2014 completed 2026-03-02T14:00:00Z
+- [ ] \`/dgs:complete-milestone v6.0\`
+`;
+
+    it('inserts section marker and gap-fix steps after the triggering audit step', () => {
+      fixture = createFixture({ 'job.md': AUDIT_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newPhases = [
+        { number: '50.1', name: 'Fix auth' },
+        { number: '50.2', name: 'Fix data' },
+      ];
+
+      const result = insertGapFixSection(filePath, 3, 1, newPhases, 'v6.0');
+
+      assert.equal(result.inserted, true);
+      assert.equal(result.count, 5, 'Should have 5 steps (2x plan+execute + 1 audit)');
+      assert.equal(result.cycleNumber, 1);
+      assert.ok(result.sectionMarker.includes('Gap-Fix Cycle 1'), 'Marker should include cycle number');
+      assert.ok(result.sectionMarker.includes('2 gaps'), 'Marker should include gap count');
+
+      // Check file content
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('--- Gap-Fix Cycle 1'), 'File should contain section marker');
+      assert.ok(content.includes('Fix auth'), 'Marker should include phase name');
+      assert.ok(content.includes('Fix data'), 'Marker should include phase name');
+
+      // Section marker should appear between the audit step and the gap-fix steps
+      const lines = content.split('\n');
+      const auditLine = lines.findIndex(l => l.includes('audit-milestone v6.0') && l.includes('[x]'));
+      const markerLine = lines.findIndex(l => l.includes('--- Gap-Fix Cycle 1'));
+      assert.ok(markerLine > auditLine, 'Section marker should be after the audit step');
+    });
+
+    it('writes the GapFixCycle header field', () => {
+      fixture = createFixture({ 'job.md': AUDIT_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newPhases = [
+        { number: '50.1', name: 'Fix auth' },
+      ];
+
+      insertGapFixSection(filePath, 3, 1, newPhases, 'v6.0');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('**GapFixCycle:** 1'), 'Should add GapFixCycle header');
+    });
+
+    it('places section marker + steps between audit step and subsequent steps', () => {
+      fixture = createFixture({ 'job.md': AUDIT_JOB });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newPhases = [
+        { number: '50.1', name: 'Fix auth' },
+      ];
+
+      insertGapFixSection(filePath, 3, 1, newPhases, 'v6.0');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+      const stepLines = lines.filter(l => l.trim().startsWith('- ['));
+
+      // Original: 5 steps (plan, exec, verify, audit, complete)
+      // Inserted: 3 steps (plan, exec, audit-milestone re-audit)
+      // Total: 8 step lines
+      assert.equal(stepLines.length, 8, 'Should have 5 original + 3 inserted = 8 steps');
+
+      // The complete-milestone step should still be the last step
+      assert.ok(stepLines[stepLines.length - 1].includes('complete-milestone'), 'complete-milestone should remain last');
+    });
+
+    it('updates existing GapFixCycle header using updateJobHeader when field already present', () => {
+      const jobWithExistingCycle = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+**GapFixCycle:** 1
+
+## Steps
+
+- [x] \`/dgs:plan-phase 50\` \u2014 completed 2026-03-02T11:00:00Z
+- [x] \`/dgs:audit-milestone v6.0\` \u2014 completed 2026-03-02T14:00:00Z
+- [ ] \`/dgs:complete-milestone v6.0\`
+`;
+      fixture = createFixture({ 'job.md': jobWithExistingCycle });
+      const filePath = path.join(fixture.cwd, 'job.md');
+
+      const newPhases = [
+        { number: '50.2', name: 'Fix more gaps' },
+      ];
+
+      insertGapFixSection(filePath, 1, 2, newPhases, 'v6.0');
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      assert.ok(content.includes('**GapFixCycle:** 2'), 'GapFixCycle should be updated to 2');
+      assert.ok(!content.includes('**GapFixCycle:** 1'), 'Old GapFixCycle value should be replaced');
+    });
+  });
+
+  // ─── listJobs Tests ───────────────────────────────────────────────────
+
+  describe('listJobs', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('returns empty groups when no job files exist in any directory', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = listJobs(fixture.cwd);
+
+      assert.deepEqual(result.pending, []);
+      assert.deepEqual(result.in_progress, []);
+      assert.deepEqual(result.completed, []);
+    });
+
+    it('returns jobs grouped by status with correct fields', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = listJobs(fixture.cwd);
+
+      assert.equal(result.in_progress.length, 1);
+      assert.equal(result.completed.length, 1);
+      assert.equal(result.pending.length, 0);
+
+      const inProg = result.in_progress[0];
+      assert.equal(inProg.version, 'v6.0');
+      assert.equal(inProg.status, 'in-progress');
+      assert.equal(inProg.check, true);
+      assert.equal(inProg.progress, '1/4');
+      assert.ok(inProg.file.includes('milestone-v6.0.md'));
+
+      const comp = result.completed[0];
+      assert.equal(comp.version, 'v5.0');
+      assert.equal(comp.status, 'completed');
+      assert.equal(comp.check, false);
+      assert.equal(comp.progress, '2/2');
+    });
+
+    it('shows check flag false when --no-check was used', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = listJobs(fixture.cwd);
+
+      const comp = result.completed[0];
+      assert.equal(comp.check, false);
+    });
+
+    it('handles missing directories gracefully with empty groups', () => {
+      fixture = createFixture({
+        '.planning/': null,
+      });
+      const result = listJobs(fixture.cwd);
+
+      assert.deepEqual(result.pending, []);
+      assert.deepEqual(result.in_progress, []);
+      assert.deepEqual(result.completed, []);
+    });
+
+    it('each entry includes progress as fraction string like "4/12"', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = listJobs(fixture.cwd);
+      const entry = result.in_progress[0];
+      assert.match(entry.progress, /^\d+\/\d+$/, 'Progress should be fraction string');
+    });
+  });
+
+  // ─── cancelJob Tests ──────────────────────────────────────────────────
+
+  describe('cancelJob', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('cancels in-progress job: resets [>] steps to [ ], updates Status, moves to pending/', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/jobs/pending/': null,
+      });
+      const result = cancelJob(fixture.cwd, 'v6.0');
+
+      assert.equal(result.cancelled, true);
+      assert.equal(result.version, 'v6.0');
+      assert.ok(result.path);
+      assert.equal(result.steps_reset, 1); // one [>] step
+
+      // Verify file moved to pending
+      assert.ok(fs.existsSync(path.join(fixture.cwd, '.planning', 'jobs', 'pending', 'milestone-v6.0.md')));
+      assert.ok(!fs.existsSync(path.join(fixture.cwd, '.planning', 'jobs', 'in-progress', 'milestone-v6.0.md')));
+
+      // Verify content: [>] reset to [ ], [x] preserved
+      const content = fs.readFileSync(path.join(fixture.cwd, '.planning', 'jobs', 'pending', 'milestone-v6.0.md'), 'utf-8');
+      assert.ok(content.includes('**Status:** pending'), 'Status should be pending');
+      assert.ok(!content.includes('[>]'), 'No in-progress markers should remain');
+      // completed steps preserved
+      assert.ok(content.includes('[x]'), 'Completed steps should be preserved');
+    });
+
+    it('returns steps_reset count of reset steps', () => {
+      const twoInProgress = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** in-progress
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-02T14:30:00Z
+- [>] \`/dgs:execute-phase 41\` \u2014 started 2026-03-02T15:00:00Z
+- [>] \`/dgs:plan-phase 42\` \u2014 started 2026-03-02T15:30:00Z
+- [ ] \`/dgs:execute-phase 42\`
+`;
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': twoInProgress,
+        '.planning/jobs/pending/': null,
+      });
+      const result = cancelJob(fixture.cwd, 'v6.0');
+
+      assert.equal(result.cancelled, true);
+      assert.equal(result.steps_reset, 2);
+    });
+
+    it('keeps completed [x] steps marked done', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/jobs/pending/': null,
+      });
+      cancelJob(fixture.cwd, 'v6.0');
+
+      const content = fs.readFileSync(path.join(fixture.cwd, '.planning', 'jobs', 'pending', 'milestone-v6.0.md'), 'utf-8');
+      const stepLines = content.split('\n').filter(l => l.trim().startsWith('- ['));
+      const completedSteps = stepLines.filter(l => l.includes('[x]'));
+      assert.ok(completedSteps.length > 0, 'Completed steps should be preserved');
+    });
+
+    it('returns not_found when no job exists for version', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = cancelJob(fixture.cwd, 'v99.0');
+
+      assert.equal(result.cancelled, false);
+      assert.equal(result.reason, 'not_found');
+    });
+
+    it('returns not_in_progress when job is in pending/', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = cancelJob(fixture.cwd, 'v6.0');
+
+      assert.equal(result.cancelled, false);
+      assert.equal(result.reason, 'not_in_progress');
+    });
+
+    it('returns not_in_progress when job is in completed/', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = cancelJob(fixture.cwd, 'v5.0');
+
+      assert.equal(result.cancelled, false);
+      assert.equal(result.reason, 'not_in_progress');
+    });
+  });
+
+  // ─── healthCheck Tests ────────────────────────────────────────────────
+
+  describe('healthCheck', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('returns healthy: true with valid directory structure', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.healthy, true);
+      assert.ok(Array.isArray(result.directories));
+      assert.equal(result.job_count, 0);
+    });
+
+    it('returns healthy: false listing issues for missing directories, then auto-creates them', () => {
+      fixture = createFixture({
+        '.planning/': null,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      // Should report missing directories but auto-create them
+      assert.ok(Array.isArray(result.directories));
+      // After auto-create, directories should exist
+      assert.ok(fs.existsSync(path.join(fixture.cwd, '.planning', 'jobs', 'pending')));
+      assert.ok(fs.existsSync(path.join(fixture.cwd, '.planning', 'jobs', 'in-progress')));
+      assert.ok(fs.existsSync(path.join(fixture.cwd, '.planning', 'jobs', 'completed')));
+    });
+
+    it('validates each job file parses successfully; reports parse failures as issues', () => {
+      const malformedJob = `# Bad Job
+
+No version or anything
+
+- [ ] random line
+`;
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v99.0.md': malformedJob,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.healthy, false);
+      assert.ok(result.issues.length > 0, 'Should report parse failure');
+      assert.ok(result.issues.some(i => i.includes('milestone-v99.0.md') || i.includes('parse')), 'Issue should reference the file');
+    });
+
+    it('counts total job files across all directories', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/milestone-v7.0.md': EMPTY_STEPS_JOB,
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.job_count, 3);
+    });
+  });
+
+  // ─── dryRunPreview Tests ──────────────────────────────────────────────
+
+  describe('dryRunPreview', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('returns step list with status annotations', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/ROADMAP.md': '# Roadmap',
+      });
+      const result = dryRunPreview(fixture.cwd, 'v6.0');
+
+      assert.equal(result.found, true);
+      assert.equal(result.version, 'v6.0');
+      assert.ok(Array.isArray(result.steps));
+      assert.equal(result.steps.length, 4);
+    });
+
+    it('each step includes index, command, args, status, display', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/ROADMAP.md': '# Roadmap',
+      });
+      const result = dryRunPreview(fixture.cwd, 'v6.0');
+
+      for (const step of result.steps) {
+        assert.ok(typeof step.index === 'number', 'step should have index');
+        assert.ok(typeof step.command === 'string', 'step should have command');
+        assert.ok(typeof step.args === 'string', 'step should have args');
+        assert.ok(typeof step.status === 'string', 'step should have status');
+        assert.ok(typeof step.display === 'string', 'step should have display');
+      }
+    });
+
+    it('shows resume_from as first non-completed step', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        '.planning/ROADMAP.md': '# Roadmap',
+      });
+      const result = dryRunPreview(fixture.cwd, 'v6.0');
+
+      // Step 0 completed, step 1 in-progress, step 2 pending
+      // Resume from first non-completed = step 1
+      assert.equal(result.resume_from, 1);
+    });
+
+    it('returns found: false when job does not exist', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = dryRunPreview(fixture.cwd, 'v99.0');
+
+      assert.equal(result.found, false);
+    });
+
+    it('validates preconditions: warns if .planning/ missing or ROADMAP.md missing', () => {
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      // No ROADMAP.md
+      const result = dryRunPreview(fixture.cwd, 'v6.0');
+
+      assert.ok(result.found, true);
+      assert.ok(Array.isArray(result.warnings));
+      assert.ok(result.warnings.some(w => w.includes('ROADMAP.md')), 'Should warn about missing ROADMAP.md');
+    });
+  });
+
+  // ─── generateJobSummary Tests ─────────────────────────────────────────
+
+  describe('generateJobSummary', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('produces markdown string with correct header', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v5.0');
+
+      assert.equal(result.found, true);
+      assert.equal(result.version, 'v5.0');
+      assert.ok(typeof result.content === 'string');
+      assert.ok(result.content.includes('# Job Summary: milestone-v5.0'));
+    });
+
+    it('includes per-step timing table', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v5.0');
+
+      assert.ok(result.content.includes('| #'));
+      assert.ok(result.content.includes('Command'));
+      assert.ok(result.content.includes('Status'));
+    });
+
+    it('includes error section for failed steps', () => {
+      const failedJob = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** failed
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41\` \u2014 completed 2026-03-02T14:30:00Z
+- [!] \`/dgs:execute-phase 41\` \u2014 failed 2026-03-02T15:00:00Z: Tests failed in auth module
+- [ ] \`/dgs:verify-work 41\`
+`;
+      fixture = createFixture({
+        '.planning/jobs/in-progress/milestone-v6.0.md': failedJob,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.ok(result.content.includes('Error'), 'Should include error section');
+      assert.ok(result.content.includes('Tests failed in auth module'), 'Should include specific error message');
+    });
+
+    it('includes auto-resolve audit section listing auto-resolved steps', () => {
+      const autoJob = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** completed
+**Check:** true
+
+## Steps
+
+- [x] \`/dgs:plan-phase 41 --auto\` \u2014 completed 2026-03-02T14:30:00Z
+- [x] \`/dgs:execute-phase 41 --auto\` \u2014 completed 2026-03-02T15:00:00Z
+- [x] \`/dgs:verify-work 41\` \u2014 completed 2026-03-02T15:30:00Z
+`;
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': autoJob,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.ok(result.content.includes('Auto'), 'Should include auto-resolve audit section');
+    });
+
+    it('handles completed, failed, and cancelled jobs', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v5.0');
+      assert.equal(result.found, true);
+      assert.ok(result.content.includes('completed'));
+    });
+
+    it('returns found: false when job does not exist', () => {
+      fixture = createFixture({
+        '.planning/jobs/pending/': null,
+        '.planning/jobs/in-progress/': null,
+        '.planning/jobs/completed/': null,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v99.0');
+
+      assert.equal(result.found, false);
+    });
+
+    it('includes human verifications section when UAT has human_needed entries', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': COMPLETED_JOB_V6,
+        '.planning/ROADMAP.md': ROADMAP_WITH_PHASE_50,
+        '.planning/phases/50-test-phase/50-UAT.md': UAT_WITH_HUMAN_NEEDED,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.equal(result.found, true);
+      assert.ok(result.content.includes('Outstanding Human Verifications'), 'Should include human verifications section');
+      assert.ok(result.content.includes('Dashboard renders correctly'), 'Should include dashboard test');
+      assert.ok(result.content.includes('Login form accessible'), 'Should include login form test');
+      assert.equal(result.human_verification_count, 2);
+    });
+
+    it('omits human verifications section when no human_needed entries', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': COMPLETED_JOB_V6,
+        '.planning/ROADMAP.md': ROADMAP_WITH_PHASE_50,
+        '.planning/phases/50-test-phase/50-UAT.md': UAT_ALL_PASSED,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.equal(result.found, true);
+      assert.ok(!result.content.includes('Outstanding Human Verifications'), 'Should not include human verifications section');
+      assert.equal(result.human_verification_count, 0);
+    });
+
+    it('omits human verifications when no UAT files exist', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': COMPLETED_JOB_V6,
+        '.planning/ROADMAP.md': ROADMAP_WITH_PHASE_50,
+        '.planning/phases/50-test-phase/': null,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.equal(result.found, true);
+      assert.ok(!result.content.includes('Outstanding Human Verifications'), 'Should not include human verifications section');
+      assert.equal(result.human_verification_count, 0);
+    });
+
+    it('skips UAT files without mode: auto-test', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': COMPLETED_JOB_V6,
+        '.planning/ROADMAP.md': ROADMAP_WITH_PHASE_50,
+        '.planning/phases/50-test-phase/50-UAT.md': UAT_MANUAL_WITH_HUMAN_NEEDED,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+
+      assert.equal(result.found, true);
+      assert.ok(!result.content.includes('Outstanding Human Verifications'), 'Should not include human verifications for manual UAT');
+      assert.equal(result.human_verification_count, 0);
+    });
+  });
+
+  // ─── Created_by field Tests ─────────────────────────────────────────────
+
+  describe('Created_by field', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    it('parseJobFile returns created_by when present', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB_WITH_CREATED_BY,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job.md'));
+      assert.equal(result.created_by, 'Adrian <adrian@example.com>');
+    });
+
+    it('parseJobFile returns null created_by when absent', () => {
+      fixture = createFixture({
+        'job.md': WELL_FORMED_JOB,
+      });
+      const result = parseJobFile(path.join(fixture.cwd, 'job.md'));
+      assert.equal(result.created_by, null);
+    });
+
+    it('buildJobFileContent includes Created_by when provided', () => {
+      const content = buildJobFileContent('v99.0', true, [{command:'plan-phase', args:'99'}], 'Test <test@t.com>');
+      assert.ok(content.includes('**Created_by:** Test <test@t.com>'));
+    });
+
+    it('buildJobFileContent omits Created_by when not provided', () => {
+      const content = buildJobFileContent('v99.0', true, [{command:'plan-phase', args:'99'}]);
+      assert.ok(!content.includes('Created_by'));
+    });
+
+    it('buildJobFileContent Created_by appears between Created and Status', () => {
+      const content = buildJobFileContent('v99.0', true, [{command:'plan-phase', args:'99'}], 'Test <test@t.com>');
+      const lines = content.split('\n');
+      const createdIdx = lines.findIndex(l => l.startsWith('**Created:**'));
+      const createdByIdx = lines.findIndex(l => l.startsWith('**Created_by:**'));
+      const statusIdx = lines.findIndex(l => l.startsWith('**Status:**'));
+      assert.ok(createdByIdx > createdIdx, 'Created_by should come after Created');
+      assert.ok(createdByIdx < statusIdx, 'Created_by should come before Status');
+    });
+
+    it('generateJobSummary includes Created_by in overview when present', () => {
+      const jobWithCreatedBy = WELL_FORMED_JOB_WITH_CREATED_BY.replace('in-progress', 'completed');
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v6.0.md': jobWithCreatedBy,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v6.0');
+      assert.equal(result.found, true);
+      assert.ok(result.content.includes('**Created_by:** Adrian <adrian@example.com>'));
+    });
+
+    it('generateJobSummary omits Created_by in overview when absent', () => {
+      fixture = createFixture({
+        '.planning/jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = generateJobSummary(fixture.cwd, 'v5.0');
+      assert.equal(result.found, true);
+      assert.ok(!result.content.includes('Created_by'));
+    });
+  });
+});
+
+// ─── Root Layout Tests ───────────────────────────────────────────────────────
+
+describe('jobs root-layout', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+    fixture = null;
+    resetPaths();
+  });
+
+  it('findJobFile resolves jobs dir at root layout', () => {
+    fixture = createTempProject({ layout: 'root' });
+    // Create a job file at root/jobs/pending/ (not .planning/jobs/pending/)
+    const jobsDir = path.join(fixture.cwd, 'jobs', 'pending');
+    fs.mkdirSync(jobsDir, { recursive: true });
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** pending\n**Check:** true\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+    fs.writeFileSync(path.join(jobsDir, 'milestone-v1.0.md'), jobContent);
+
+    const result = findJobFile(fixture.cwd, 'v1.0');
+    assert.equal(result.found, true);
+    assert.equal(result.directory, 'pending');
+    // Should NOT be at .planning/jobs/
+    assert.ok(result.path.includes(path.join(fixture.cwd, 'jobs')));
+    assert.ok(!result.path.includes('.planning'));
+  });
+
+  it('healthCheck creates jobs dirs at root layout', () => {
+    fixture = createTempProject({ layout: 'root' });
+    const result = healthCheck(fixture.cwd);
+    assert.ok(result.directories.length >= 3);
+    // Verify dirs were created at root, not at .planning/
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')));
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')));
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')));
+  });
+
+  it('listJobs works in root layout', () => {
+    fixture = createTempProject({ layout: 'root' });
+    // Create jobs directory structure at root
+    const pendingDir = path.join(fixture.cwd, 'jobs', 'pending');
+    fs.mkdirSync(pendingDir, { recursive: true });
+    fs.mkdirSync(path.join(fixture.cwd, 'jobs', 'in-progress'), { recursive: true });
+    fs.mkdirSync(path.join(fixture.cwd, 'jobs', 'completed'), { recursive: true });
+
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** pending\n**Check:** true\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+    fs.writeFileSync(path.join(pendingDir, 'milestone-v1.0.md'), jobContent);
+
+    const result = listJobs(fixture.cwd);
+    assert.equal(result.pending.length, 1);
+    assert.equal(result.pending[0].version, 'v1.0');
+  });
+});
+
+// ─── SHA Recording & Rollback Tests ─────────────────────────────────────────
+
+describe('recordStartShas', () => {
+  let fixture;
+  afterEach(() => { if (fixture) fixture.cleanup(); });
+
+  it('records planning repo SHA when no REPOS.md exists', () => {
+    fixture = createTempProject({ withGit: true });
+    const pendingDir = path.join(fixture.planningDir, 'jobs', 'pending');
+    fs.mkdirSync(pendingDir, { recursive: true });
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** in-progress\n**Check:** true\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+    const jobPath = path.join(pendingDir, 'milestone-v1.0.md');
+    fs.writeFileSync(jobPath, jobContent);
+
+    const result = recordStartShas(fixture.cwd, jobPath);
+    assert.equal(result.recorded, true);
+    assert.ok(result.shas._planning, 'Should have _planning SHA');
+    assert.ok(result.shas._planning.length >= 7, 'SHA should be at least 7 chars');
+
+    // Verify it was written into the file
+    const updatedContent = fs.readFileSync(jobPath, 'utf-8');
+    assert.ok(updatedContent.includes('**StartShas:**'), 'Job file should contain StartShas header');
+  });
+
+  it('skips recording if StartShas already exists', () => {
+    fixture = createTempProject({ withGit: true });
+    const pendingDir = path.join(fixture.planningDir, 'jobs', 'pending');
+    fs.mkdirSync(pendingDir, { recursive: true });
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** in-progress\n**Check:** true\n**StartShas:** {"_planning":"abc123"}\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+    const jobPath = path.join(pendingDir, 'milestone-v1.0.md');
+    fs.writeFileSync(jobPath, jobContent);
+
+    const result = recordStartShas(fixture.cwd, jobPath);
+    assert.equal(result.recorded, true);
+    assert.equal(result.already_existed, true);
+  });
+});
+
+describe('parseJobFile with StartShas', () => {
+  let fixture;
+  afterEach(() => { if (fixture) fixture.cleanup(); });
+
+  it('returns startShas as parsed JSON when present', () => {
+    const shaObj = { _planning: 'abc123', myrepo: 'def456' };
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** in-progress\n**Check:** true\n**StartShas:** ${JSON.stringify(shaObj)}\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+
+    fixture = createFixture({
+      '.planning/config.json': '{}',
+      '.planning/job.md': jobContent,
+    });
+
+    const parsed = parseJobFile(path.join(fixture.cwd, '.planning', 'job.md'));
+    assert.deepEqual(parsed.startShas, shaObj);
+  });
+
+  it('returns startShas as null when absent', () => {
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** pending\n**Check:** true\n\n## Steps\n\n- [ ] \`/dgs:plan-phase 1\`\n`;
+
+    fixture = createFixture({
+      '.planning/config.json': '{}',
+      '.planning/job.md': jobContent,
+    });
+
+    const parsed = parseJobFile(path.join(fixture.cwd, '.planning', 'job.md'));
+    assert.equal(parsed.startShas, null);
+  });
+});
+
+describe('rollbackJob', () => {
+  let fixture;
+  afterEach(() => { if (fixture) fixture.cleanup(); });
+
+  it('returns not_found for missing job', () => {
+    fixture = createTempProject({ withGit: true });
+    const result = rollbackJob(fixture.cwd, 'v99.0');
+    assert.equal(result.rolledBack, false);
+    assert.equal(result.reason, 'not_found');
+  });
+
+  it('returns no_start_shas for job without SHAs', () => {
+    fixture = createTempProject({ withGit: true });
+    const pendingDir = path.join(fixture.planningDir, 'jobs', 'pending');
+    fs.mkdirSync(pendingDir, { recursive: true });
+    const jobContent = `# Milestone Job: v1.0\n\n**Version:** v1.0\n**Created:** 2026-01-01T00:00:00Z\n**Status:** completed\n**Check:** true\n\n## Steps\n\n- [x] \`/dgs:plan-phase 1\` \u2014 completed 2026-01-01T01:00:00Z\n`;
+    fs.writeFileSync(path.join(pendingDir, 'milestone-v1.0.md'), jobContent);
+
+    const result = rollbackJob(fixture.cwd, 'v1.0');
+    assert.equal(result.rolledBack, false);
+    assert.equal(result.reason, 'no_start_shas');
+  });
+});