fix: clear phases directory when creating new milestone (#1588) (#1594)

* fix: clear phases directory when creating new milestone (#1588)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* ci: re-run CI with Windows pointer lifecycle fix in main

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

get-shit-done/bin/gsd-tools.cjs

@@ -583,8 +583,10 @@ async function runCommand(command, args, cwd, raw) {
           includeArchived: args.includes('--include-archived'),
         };
         phase.cmdPhasesList(cwd, options, raw);
+      } else if (subcommand === 'clear') {
+        milestone.cmdPhasesClear(cwd, raw);
       } else {
-        error('Unknown phases subcommand. Available: list');
+        error('Unknown phases subcommand. Available: list, clear');
       }
       break;
     }

get-shit-done/bin/lib/milestone.cjs

@@ -246,7 +246,28 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   output(result, raw);
 }
 
+function cmdPhasesClear(cwd, raw) {
+  const phasesDir = planningPaths(cwd).phases;
+  let cleared = 0;
+
+  if (fs.existsSync(phasesDir)) {
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        fs.rmSync(path.join(phasesDir, entry.name), { recursive: true, force: true });
+        cleared++;
+      }
+    } catch (e) {
+      error('Failed to clear phases directory: ' + e.message);
+    }
+  }
+
+  output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+
 module.exports = {
   cmdRequirementsMarkComplete,
   cmdMilestoneComplete,
+  cmdPhasesClear,
 };

get-shit-done/workflows/new-milestone.md

@@ -137,6 +137,12 @@ Keep Accumulated Context section from previous milestone.
 
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
+Clear leftover phase directories from the previous milestone:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phases clear
+```
+
 ```bash
 node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```

tests/new-milestone-clear-phases.test.cjs

@@ -0,0 +1,111 @@
+/**
+ * GSD Tools Tests - New Milestone Clear Phases (#1588)
+ *
+ * Verifies that `phases clear` removes all phase subdirectories from
+ * .planning/phases/, leaving the directory itself intact.
+ */
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
+
+describe('phases clear command', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('clears all phase subdirectories from .planning/phases/', () => {
+    const phasesDir = path.join(tmpDir, '.planning', 'phases');
+
+    // Simulate phases left over from a previous milestone
+    const phase1 = path.join(phasesDir, '01-foundation');
+    const phase2 = path.join(phasesDir, '02-api');
+    const phase3 = path.join(phasesDir, '03-ui');
+    fs.mkdirSync(phase1, { recursive: true });
+    fs.mkdirSync(phase2, { recursive: true });
+    fs.mkdirSync(phase3, { recursive: true });
+    fs.writeFileSync(path.join(phase1, '01-01-PLAN.md'), '# Plan');
+    fs.writeFileSync(path.join(phase2, '02-01-SUMMARY.md'), '# Summary');
+
+    const result = runGsdTools('phases clear', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(output.cleared, 3, 'should report 3 directories cleared');
+
+    // phases/ directory itself must still exist
+    assert.ok(fs.existsSync(phasesDir), '.planning/phases/ directory should still exist');
+
+    // all subdirectories must be gone
+    const remaining = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory());
+    assert.strictEqual(remaining.length, 0, 'no phase subdirectories should remain');
+  });
+
+  test('succeeds with cleared=0 when phases directory is already empty', () => {
+    const phasesDir = path.join(tmpDir, '.planning', 'phases');
+    // createTempProject creates the directory but leaves it empty
+
+    const result = runGsdTools('phases clear', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(output.cleared, 0, 'should report 0 cleared when already empty');
+    assert.ok(fs.existsSync(phasesDir), '.planning/phases/ directory should still exist');
+  });
+
+  test('succeeds with cleared=0 when phases directory does not exist', () => {
+    // Remove the phases directory entirely
+    fs.rmSync(path.join(tmpDir, '.planning', 'phases'), { recursive: true, force: true });
+
+    const result = runGsdTools('phases clear', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(output.cleared, 0, 'should report 0 cleared when directory absent');
+  });
+
+  test('does not remove files (only directories) at the phases root', () => {
+    const phasesDir = path.join(tmpDir, '.planning', 'phases');
+
+    // Put a stray file directly in phases/ (edge case)
+    fs.writeFileSync(path.join(phasesDir, 'README.md'), '# Phases');
+
+    const phase1 = path.join(phasesDir, '01-foundation');
+    fs.mkdirSync(phase1, { recursive: true });
+    fs.writeFileSync(path.join(phase1, '01-01-PLAN.md'), '# Plan');
+
+    const result = runGsdTools('phases clear', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(output.cleared, 1, 'should report 1 directory cleared (not the file)');
+
+    // File must survive
+    assert.ok(
+      fs.existsSync(path.join(phasesDir, 'README.md')),
+      'files at phases root should be preserved'
+    );
+  });
+
+  test('clears nested phase content (recursive delete)', () => {
+    const phasesDir = path.join(tmpDir, '.planning', 'phases');
+    const phase1 = path.join(phasesDir, '01-foundation');
+    const nested = path.join(phase1, 'subdir');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.writeFileSync(path.join(nested, 'deep-file.md'), '# Deep');
+
+    const result = runGsdTools('phases clear', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    assert.ok(!fs.existsSync(phase1), 'phase directory including nested content should be removed');
+  });
+});