@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -60,6 +60,21 @@ function v2FixtureWithProject() {
   });
 }
 
+// ─── v2 fixture for multi-project case (existing active + new slug) ──────────
+
+function v2FixtureMultiProject() {
+  // Active project exists and is populated; we are about to create a second, distinct project.
+  return createFixture({
+    'config.json': JSON.stringify({ current_project: 'test-project' }),
+    'PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| test-project | Active |\n',
+    'REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+    'projects/test-project/STATE.md': '# State',
+    'projects/test-project/ROADMAP.md': '# Roadmap',
+    'projects/test-project/REQUIREMENTS.md': '# Requirements',
+    'projects/test-project/PROJECT.md': '# Project',
+  });
+}
+
 // ─── v2 fixture without current_project (for guard tests) ────────────────────
 
 function v2FixtureOneProject() {
@@ -67,6 +82,7 @@ function v2FixtureOneProject() {
     'config.json': JSON.stringify({}),
     'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
     'REPOS.md': '# Repos\n\n| Name | Path |\n',
+    'projects/test-project/PROJECT.md': '# Project\n',
     'projects/test-project/STATE.md': '# State',
   });
 }
@@ -84,7 +100,9 @@ function v2FixtureMultipleProjects() {
     'config.json': JSON.stringify({}),
     'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
     'REPOS.md': '# Repos\n\n| Name | Path |\n',
+    'projects/alpha-project/PROJECT.md': '# Project\n',
     'projects/alpha-project/STATE.md': '# State',
+    'projects/beta-project/PROJECT.md': '# Project\n',
     'projects/beta-project/STATE.md': '# State',
   });
 }
@@ -278,7 +296,8 @@ describe('v1 mode: init todos', () => {
   });
 
   it('returns v1 pending_dir path', () => {
-    assert.equal(result.pending_dir, 'todos/pending');
+    // Flat layout: pending_dir points to todos/ (not todos/pending/)
+    assert.equal(result.pending_dir, 'todos');
   });
 
   it('returns v1 completed_dir path', () => {
@@ -518,7 +537,8 @@ describe('v2 mode with project: init todos', () => {
   });
 
   it('returns product-level pending_dir', () => {
-    assert.equal(result.pending_dir, path.join('todos', 'pending'));
+    // Flat layout: pending_dir points to todos/ (not todos/pending/)
+    assert.equal(result.pending_dir, 'todos');
   });
 
   it('returns product-level completed_dir', () => {
@@ -1661,6 +1681,71 @@ describe('cmdInitQuick quick_dir resolution', () => {
       assert.equal(result.description, 'test task');
     });
   });
+
+  describe('product mode with active quick worktree (parity)', () => {
+    let fixture;
+
+    beforeEach(() => {
+      // Hand-rolled fixture (not v2FixtureWithProject) so we can seed
+      // config.local.json with an active quick worktree whose slug has
+      // already been truncated by worktrees.cjs::_sanitizeSlug to 50 chars.
+      fixture = createFixture({
+        'config.json': JSON.stringify({ current_project: 'test-project' }),
+        'PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| test-project | Active |\n',
+        'REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+        'projects/test-project/PROJECT.md': '# Project',
+        'projects/test-project/STATE.md': '# State',
+        'projects/test-project/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n',
+        'projects/test-project/REQUIREMENTS.md': '# Requirements',
+      });
+      // Seed the active quick worktree AFTER createFixture so we can point
+      // entry.repos at fixture.cwd (which is a real on-disk tmp dir).
+      // Slug is the SHORT (50-char) form that worktrees.cjs would produce.
+      const shortSlug = '260428-k7f-this-is-a-very-long-description-that-w';
+      const localConfig = {
+        execution: { active_context: shortSlug },
+        projects: {
+          'test-project': {
+            worktrees: {
+              [shortSlug]: {
+                type: 'quick',
+                repos: { 'deliver-great-systems': fixture.cwd },
+              },
+            },
+          },
+        },
+      };
+      fs.writeFileSync(path.join(fixture.cwd, 'config.local.json'),
+        JSON.stringify(localConfig), 'utf-8');
+    });
+
+    afterEach(() => {
+      fixture.cleanup();
+    });
+
+    it('task_dir basename matches active worktree slug (parity with getActiveQuick)', () => {
+      // Description deliberately long enough that init.cjs's own 40-char
+      // sanitiser would produce a descSlug differing from the worktree's
+      // 39-char descSlug by exactly one char (pre-fix). Post-fix, init
+      // defers to the worktree slug, so the two align.
+      const result = runInit(fixture.cwd,
+        'quick "this is a very long description that would otherwise"');
+
+      assert.ok(result.task_dir, 'task_dir should be set');
+      assert.equal(
+        path.basename(result.task_dir),
+        '260428-k7f-this-is-a-very-long-description-that-w',
+        'task_dir basename must equal active worktree slug (no second sanitiser pass)'
+      );
+      assert.equal(
+        result.slug,
+        'this-is-a-very-long-description-that-w',
+        'slug must be derived from worktree slug (39 chars), not recomputed from description (40 chars)'
+      );
+      assert.equal(result.quick_id, '260428-k7f',
+        'quick_id should still be extracted from worktree slug prefix (regression guard)');
+    });
+  });
 });
 
 // ─── init progress-all ───────────────────────────────────────────────────────
@@ -1756,7 +1841,9 @@ describe('init progress-all: excludes completed projects', () => {
       'config.json': JSON.stringify({}),
       'PROJECTS.md': '# Projects\n',
       'REPOS.md': '# Repos\n',
+      'projects/active-x/PROJECT.md': '# Project\n',
       'projects/active-x/STATE.md': '# Project State\n\nPhase: 1\nStatus: In progress\nProgress: [#---------] 10%\n',
+      'projects/done-y/PROJECT.md': '# Project\n',
       'projects/done-y/STATE.md': '# Project State\n\nPhase: 5\nStatus: completed\nProgress: [##########] 100%\nCompleted: 2026-01-20\n',
     });
     result = runInit(fixture.cwd, 'progress-all --raw');
@@ -1898,9 +1985,9 @@ describe('init progress-all: counts backlog files', () => {
       'config.json': JSON.stringify({}),
       'PROJECTS.md': '# Projects\n',
       'REPOS.md': '# Repos\n',
-      'todos/pending/todo-1.md': '# todo 1',
-      'todos/pending/todo-2.md': '# todo 2',
-      'ideas/pending/idea-1.md': '# idea 1',
+      'todos/todo-1.md': '---\nstatus: pending\n---\n# todo 1',
+      'todos/todo-2.md': '---\nstatus: pending\n---\n# todo 2',
+      'ideas/idea-1.md': '---\nstatus: pending\n---\n# idea 1',
       'specs/spec-1.md': '# spec 1',
       'specs/spec-2.md': '# spec 2',
       'specs/spec-3.md': '# spec 3',
@@ -1931,3 +2018,123 @@ describe('init progress-all: counts backlog files', () => {
     assert.equal(result.product.backlog.debug_active, 1);
   });
 });
+
+// ─── v2 mode multi-project: init new-project <slug> ──────────────────────────
+
+describe('v2 mode multi-project: init new-project <slug>', () => {
+  it('returns project_exists false for a new, non-existing slug', () => {
+    const fixture = v2FixtureMultiProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(result.project_exists, false);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('returns project_path under the requested slug, not current_project', () => {
+    const fixture = v2FixtureMultiProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(result.project_path, path.join('projects', 'second-project', 'PROJECT.md'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('returns state/roadmap/requirements/research paths under the requested slug', () => {
+    const fixture = v2FixtureMultiProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(result.state_path, path.join('projects', 'second-project', 'STATE.md'));
+      assert.equal(result.roadmap_path, path.join('projects', 'second-project', 'ROADMAP.md'));
+      assert.equal(result.requirements_path, path.join('projects', 'second-project', 'REQUIREMENTS.md'));
+      assert.equal(result.research_dir, path.join('projects', 'second-project', 'research'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('returns project_exists true when the slug DOES already exist', () => {
+    const fixture = v2FixtureWithProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project test-project');
+      assert.equal(result.project_exists, true);
+      assert.equal(result.project_path, path.join('projects', 'test-project', 'PROJECT.md'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('normalizes the slug consistently with generateSlugInternal', () => {
+    // Lock in the contract that the resolver and `projects create` use the same normalizer.
+    const { generateSlugInternal } = require('./core.cjs');
+    assert.equal(generateSlugInternal('Second Project'), 'second-project');
+  });
+
+  it('exposes requested_slug on the result object', () => {
+    const fixture = v2FixtureMultiProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(result.requested_slug, 'second-project');
+      // current_project should still report the active project.
+      assert.equal(result.current_project, 'test-project');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  // Regression: backwards-compatible no-slug behaviour
+  it('v2 with current_project but no slug arg: behaviour unchanged', () => {
+    const fixture = v2FixtureWithProject();
+    try {
+      const result = runInit(fixture.cwd, 'new-project');
+      assert.equal(result.project_path, path.join('projects', 'test-project', 'PROJECT.md'));
+      assert.equal(result.project_exists, true);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('v1 mode with no slug arg: behaviour unchanged', () => {
+    const fixture = v1Fixture();
+    try {
+      const result = runInit(fixture.cwd, 'new-project');
+      assert.equal(result.project_path, 'PROJECT.md');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
+// ─── v2 mode multi-project: end-to-end ───────────────────────────────────────
+
+describe('v2 mode multi-project: end-to-end', () => {
+  it('init new-project <slug> agrees with projects create on the target directory', () => {
+    const fixture = v2FixtureMultiProject();
+    try {
+      // Step 1: init new-project resolves paths under projects/second-project/
+      const initResult = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(initResult.project_exists, false);
+      assert.equal(initResult.project_path, path.join('projects', 'second-project', 'PROJECT.md'));
+      assert.equal(initResult.requested_slug, 'second-project');
+      // current_project is still the active project — workflow uses requested_slug or
+      // project_path, not current_project, when creating.
+      assert.equal(initResult.current_project, 'test-project');
+
+      // Step 2: projects create creates the same folder init pointed at.
+      execSync(`node "${CLI}" projects create "Second Project"`, {
+        cwd: fixture.cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const createdDir = path.join(fixture.cwd, 'projects', 'second-project');
+      assert.ok(fs.existsSync(createdDir), 'projects create should create projects/second-project/');
+      assert.ok(fs.existsSync(path.join(createdDir, 'PROJECT.md')), 'PROJECT.md should exist in created folder');
+
+      // Step 3: re-running init new-project for the same slug now reports it exists.
+      const reinit = runInit(fixture.cwd, 'new-project second-project');
+      assert.equal(reinit.project_exists, true);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -343,6 +343,9 @@ function updateJobStep(filePath, stepIndex, status, options) {
 }
 
 /**
+ * @deprecated Use setJobStatus() for state transitions instead of physical file moves.
+ * Kept for backward compatibility with legacy directory-based job layouts.
+ *
  * Move a job file from its current location to a target directory.
  *
  * @param {string} filePath - Absolute path to the job file
@@ -1461,7 +1464,7 @@ function listJobs(cwd) {
 }
 
 /**
- * Cancel an in-progress job: reset [>] steps to [ ], set Status to pending, move to pending/.
+ * Cancel an in-progress job: reset [>] steps to [ ], set Status to pending.
  *
  * @param {string} cwd - Working directory
  * @param {string} version - Milestone version (e.g., "v6.0")
@@ -1472,7 +1475,7 @@ function cancelJob(cwd, version) {
   if (!found.found) {
     return { cancelled: false, reason: 'not_found' };
   }
-  if (found.directory !== 'in-progress') {
+  if (found.status !== 'in-progress') {
     return { cancelled: false, reason: 'not_in_progress' };
   }
 
@@ -1814,8 +1817,8 @@ function recordStartShas(cwd, jobFilePath) {
         if (name === 'Name' || name.startsWith('-')) continue;
         if (!repoPath || repoPath.startsWith('-')) continue;
 
-        // Resolve absolute path: paths in REPOS.md are relative to planning root's parent
-        const absRepoPath = path.resolve(path.dirname(planningRoot), repoPath);
+        // Resolve absolute path: paths in REPOS.md are relative to the planning root
+        const absRepoPath = path.resolve(planningRoot, repoPath);
         if (!fs.existsSync(absRepoPath)) continue;
 
         try {

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

@@ -4,10 +4,12 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, getMilestonePhaseFilter, getProjectRoot, output, error } = require('./core.cjs');
+const { escapeRegex, getMilestonePhaseFilter, getProjectRoot, output, error, loadConfig } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { writeStateMd } = require('./state.cjs');
+const { getContributors, checkFourEyes } = require('./governance.cjs');
+const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 
 /**
  * Internal helper: marks requirement IDs complete in REQUIREMENTS.md.
@@ -159,6 +161,72 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     }
   } catch {}
 
+  // ── Four-Eyes Gate (GATE-01) ───────────────────────────────────────────────
+  const config = loadConfig(cwd);
+  const rawConfig = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(planRoot, 'config.json'), 'utf-8'));
+    } catch { return {}; }
+  })();
+  const fourEyesMode = (rawConfig.workflow && rawConfig.workflow.four_eyes) || 'off';
+  let governanceNote = null;
+
+  if (fourEyesMode !== 'off') {
+    // Resolve current user identity
+    let currentUserStr = '';
+    try {
+      const identity = requireGitIdentity(cwd);
+      currentUserStr = formatAuthorString(identity);
+    } catch {
+      // Identity gate already ran — this is a safety fallback
+      currentUserStr = '';
+    }
+
+    // Get contributors for this milestone
+    const contribResult = getContributors(cwd);
+    const contributors = contribResult.contributors || [];
+
+    // Run four-eyes check
+    const feResult = checkFourEyes(contributors, currentUserStr, fourEyesMode);
+
+    // Display contributor list (SHR-02 — always when not off)
+    const contribNames = contributors.length > 0
+      ? contributors.join(', ')
+      : '(none detected)';
+
+    if (feResult.passed) {
+      // Four-eyes satisfied — display and continue
+      process.stderr.write('Contributors: ' + contribNames + ' \u2014 \u2714 Four-eyes satisfied\n');
+    } else {
+      // Four-eyes failed — display contributor list first
+      process.stderr.write('Contributors: ' + contribNames + '\n');
+
+      // Extract current user name for display
+      let displayName = currentUserStr;
+      try {
+        const identity = requireGitIdentity(cwd);
+        displayName = identity.name;
+      } catch { /* use full string */ }
+
+      if (fourEyesMode === 'warn') {
+        // GATE-04: warn mode — display warning, proceed, log
+        process.stderr.write('\u26A0 You (' + displayName + ') contributed to this milestone. Completing anyway (warn mode).\n');
+        governanceNote = 'Four-eyes warning: ' + displayName + ' completed while also a contributor. Contributors: ' + contribNames;
+      } else if (fourEyesMode === 'enforce') {
+        if (options.force) {
+          // GATE-06: --force bypasses enforce
+          process.stderr.write('\u26A0 Forced: you (' + displayName + ') are the only contributor. Override logged.\n');
+          governanceNote = 'Four-eyes override: ' + displayName + ' force-completed. Contributors: ' + contribNames;
+        } else {
+          // GATE-05: enforce mode — block completion
+          error('\u2718 Blocked: you (' + displayName + ') are the only contributor. Use --force to override.');
+          return;
+        }
+      }
+    }
+  }
+  // Off mode: no check, no output, no performance impact (GATE-03)
+
   // Archive ROADMAP.md
   if (fs.existsSync(roadmapPath)) {
     const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
@@ -180,7 +248,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
 
   // Create/append MILESTONES.md entry
   const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
-  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+  const governanceLine = governanceNote ? `\n**Governance:** ${governanceNote}\n` : '';
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}${governanceLine}\n\n---\n\n`;
 
   if (fs.existsSync(milestonesPath)) {
     const existing = fs.readFileSync(milestonesPath, 'utf-8');
@@ -214,9 +283,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
       /(\*\*Last Activity:\*\*\s*).*/,
       `$1${today}`
     );
+    const activitySuffix = governanceNote
+      ? ` (four-eyes: ${fourEyesMode === 'warn' ? 'warn' : 'force'} override by ${(() => { try { return requireGitIdentity(cwd).name; } catch { return 'unknown'; } })()})`
+      : '';
     stateContent = stateContent.replace(
       /(\*\*Last Activity Description:\*\*\s*).*/,
-      `$1${version} milestone completed and archived`
+      `$1${version} milestone completed and archived${activitySuffix}`
     );
     writeStateMd(statePath, stateContent, cwd);
   }
@@ -240,6 +312,31 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     } catch {}
   }
 
+  // Archive completed quick task directories
+  let quickArchived = false;
+  const quickDir = path.join(projectRoot, 'quick');
+  if (fs.existsSync(quickDir)) {
+    try {
+      const quickArchiveDir = path.join(archiveDir, `${version}-quick`);
+      const quickEntries = fs.readdirSync(quickDir, { withFileTypes: true });
+      const quickDirNames = quickEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of quickDirNames) {
+        // Check if this quick dir has a SUMMARY file (completed)
+        const dirPath = path.join(quickDir, dir);
+        const dirFiles = fs.readdirSync(dirPath);
+        const hasSummary = dirFiles.some(f => f.endsWith('-SUMMARY.md'));
+        if (!hasSummary) continue;
+        if (!fs.existsSync(quickArchiveDir)) {
+          fs.mkdirSync(quickArchiveDir, { recursive: true });
+        }
+        fs.renameSync(dirPath, path.join(quickArchiveDir, dir));
+        archivedCount++;
+      }
+      quickArchived = archivedCount > 0;
+    } catch {}
+  }
+
   const result = {
     version,
     name: milestoneName,
@@ -253,6 +350,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
       requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
       audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
       phases: phasesArchived,
+      quick: quickArchived,
     },
     milestones_updated: true,
     state_updated: fs.existsSync(statePath),

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

@@ -0,0 +1,203 @@
+/**
+ * Tests for milestone.cjs — quick dir archival in cmdMilestoneComplete
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ * Each test creates an isolated temp directory fixture and cleans up after.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { createFixture, writeFile } = require('./test-helpers.cjs');
+const { cmdMilestoneComplete } = require('./milestone.cjs');
+
+// Helper: capture stdout from cmdMilestoneComplete (which calls output())
+function captureResult(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write;
+  process.stdout.write = function (chunk) {
+    chunks.push(String(chunk));
+  };
+  // Also suppress stderr (governance / state messages)
+  const origStderrWrite = process.stderr.write;
+  process.stderr.write = function () {};
+  // Prevent process.exit from actually exiting during tests
+  const origExit = process.exit;
+  process.exit = function () {};
+  try {
+    fn();
+  } finally {
+    process.stdout.write = origWrite;
+    process.stderr.write = origStderrWrite;
+    process.exit = origExit;
+  }
+  const raw = chunks.join('');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Creates a root-layout fixture suitable for cmdMilestoneComplete.
+ * Root layout: no PROJECTS.md/REPOS.md (avoids v2 detection).
+ * Includes config.local.json with planningRoot, STATE.md, ROADMAP.md, phases/.
+ */
+function createMilestoneFixture(extras) {
+  const base = {
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ planningRoot: '.' }),
+    'STATE.md': '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [----------] 0%\n',
+    'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+    'phases/': null,
+  };
+  if (extras) {
+    Object.assign(base, extras);
+  }
+  return createFixture(base);
+}
+
+// ─── Quick Dir Archival Tests ────────────────────────────────────────────────
+
+describe('cmdMilestoneComplete quick dir archival', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+  });
+
+  it('archives completed quick dirs (with SUMMARY.md) to milestones/v1.0-quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/260101-abc-some-task/260101-abc-PLAN.md': '# Plan',
+      'quick/260101-abc-some-task/260101-abc-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // Quick dir should be moved to milestones/v1.0-quick/
+    const archivedDir = path.join(cwd, 'milestones', 'v1.0-quick', '260101-abc-some-task');
+    assert.ok(fs.existsSync(archivedDir), 'Quick dir should be archived to milestones/v1.0-quick/');
+    assert.ok(!fs.existsSync(path.join(cwd, 'quick', '260101-abc-some-task')), 'Quick dir should be removed from quick/');
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.quick, true, 'archived.quick should be true');
+  });
+
+  it('does not move HISTORY.md from quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/HISTORY.md': '# History\n',
+      'quick/260102-def-other/260102-def-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // HISTORY.md should remain in quick/
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', 'HISTORY.md')), 'HISTORY.md should stay in quick/');
+    // The completed dir should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick', '260102-def-other')), 'Completed dir should be archived');
+  });
+
+  it('skips plain files (non-directories) in quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/some-notes.txt': 'random notes',
+      'quick/260103-ghi-task/260103-ghi-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // File should remain
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', 'some-notes.txt')), 'Plain files should remain in quick/');
+    // Dir should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick', '260103-ghi-task')), 'Completed dir should be archived');
+  });
+
+  it('does NOT move quick dirs without SUMMARY.md (incomplete)', () => {
+    fixture = createMilestoneFixture({
+      'quick/260104-jkl-wip/260104-jkl-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // Should NOT be moved
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', '260104-jkl-wip')), 'Incomplete quick dir should stay in quick/');
+    assert.ok(!fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick')), 'No quick archive dir should be created');
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.quick, false, 'archived.quick should be false when nothing archived');
+  });
+
+  it('gracefully handles when quick/ does not exist', () => {
+    fixture = createMilestoneFixture();
+    const cwd = fixture.cwd;
+
+    // No quick/ directory at all
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.ok(result, 'Should return result JSON without error');
+    assert.equal(result.archived.quick, false, 'archived.quick should be false when no quick/ dir');
+  });
+
+  it('returns quickArchived=false when quick/ has no completed dirs', () => {
+    fixture = createMilestoneFixture({
+      'quick/HISTORY.md': '# History',
+      'quick/260105-mno-wip/260105-mno-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.equal(result.archived.quick, false, 'archived.quick should be false');
+    assert.ok(!fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick')), 'No quick archive dir should be created');
+  });
+
+  it('creates milestones/v{X.Y}-quick/ only when there are dirs to archive', () => {
+    fixture = createMilestoneFixture({
+      'quick/260106-pqr-first/260106-pqr-SUMMARY.md': '# Summary',
+      'quick/260107-stu-second/260107-stu-SUMMARY.md': '# Summary',
+      'quick/260108-vwx-wip/260108-vwx-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v2.0', {}, false);
+    });
+
+    // Both completed dirs should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v2.0-quick', '260106-pqr-first')), 'First completed dir archived');
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v2.0-quick', '260107-stu-second')), 'Second completed dir archived');
+    // Incomplete dir should remain
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', '260108-vwx-wip')), 'Incomplete dir should stay');
+    assert.equal(result.archived.quick, true, 'archived.quick should be true');
+  });
+
+  it('result JSON includes archived.quick field', () => {
+    fixture = createMilestoneFixture();
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.ok(result, 'Should return result');
+    assert.ok('archived' in result, 'Result should have archived object');
+    assert.ok('quick' in result.archived, 'archived should have quick field');
+    assert.equal(typeof result.archived.quick, 'boolean', 'archived.quick should be boolean');
+  });
+});