fix(#2118): honor --dry-run in milestone complete with zero-mutation preview (#2155)

* fix(2118): honor --dry-run in milestone complete with zero-mutation preview

milestone complete treated --dry-run as a no-op: the flag was neither
parsed nor rejected, so a caller who expected a preview instead
triggered the full destructive mutation (archive phases → move audit
artifacts → rewrite STATE.md) with no way to back out.

Fix (option 2 from the issue): add dryRun to MilestoneCompleteOptions,
parse --dry-run in the dispatcher, and return a JSON preview plan
(would_archive, would_update) after the read-only stats gathering but
before any mutations. Also gated platformEnsureDir on !dryRun so the
archive directory is not created during preview.

3 regression tests: no-mutation happy path, --no-archive-phases combo,
and --force bypass combo.

* docs(changeset): backfill PR number (#2155)

* chore(#2118): regenerate pi/qwen golden fixtures after next merge

The milestone --dry-run fix changes gsd-core/bin/gsd-tools.cjs; qwen.json
(missed at authoring) and pi.json (added on next, never carried the fix)
were the only two runtime fixtures still holding the pre-fix hash. All
other runtimes already reflect the change. Regenerated via the sanctioned
gen-golden-install-parity script.

* fix(#2118): surface accomplishments in dry-run preview; fix --dry-run --raw

Orthogonal review findings on the --dry-run preview:
- The preview omitted the already-computed accomplishments (the primary
  MILESTONES.md content a real run writes); surface it as a top-level field,
  mirroring the real-run result.
- `--dry-run --raw` discarded the structured payload and printed the literal
  string "dry-run"; drop the raw-value arg so --raw emits the full preview
  JSON, matching the real-run output() call.
Adds tests: --dry-run --raw is parseable JSON, preview includes accomplishments,
and --dry-run --force is proven zero-mutation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-07-13 00:02:52 -04:00
committed by GitHub
parent 0278329c3a
commit 481f00e38a
22 changed files with 197 additions and 21 deletions

View File

@@ -113,6 +113,131 @@ describe('milestone complete command', () => {
assert.ok(milestones.includes('Set up project infrastructure'));
});
test('#2118 — --dry-run does NOT mutate: no archive, no STATE.md rewrite, no phase move', () => {
writeRoadmap(tmpDir, `# Roadmap v1.0 MVP\n\n### Phase 1: Foundation\n**Goal:** Setup\n`);
fs.writeFileSync(
path.join(tmpDir, '.planning', 'REQUIREMENTS.md'),
`# Requirements\n\n- [x] User auth\n`,
);
writeState(tmpDir);
const phasePath = mkPhaseDir(tmpDir, '01-foundation', { oneLiner: 'Set up project infrastructure' });
// Capture pre-state
const stateBefore = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
const result = runGsdTools('milestone complete v1.0 --name Test --dry-run', tmpDir);
assert.ok(result.success, `Command failed: ${result.error}`);
const output = JSON.parse(result.output);
assert.strictEqual(output.dry_run, true, 'dry_run must be true');
assert.strictEqual(output.version, 'v1.0');
assert.ok(output.stats.phases >= 1, 'should count at least 1 phase');
assert.ok(output.would_archive.roadmap, 'should list roadmap archive plan');
assert.ok(output.would_archive.requirements, 'should list requirements archive plan');
assert.ok(
output.would_archive.phases.includes('01-foundation'),
'should list phase dir for archive',
);
assert.ok(
Array.isArray(output.accomplishments) && output.accomplishments.includes('Set up project infrastructure'),
'dry-run preview should surface accomplishments from phase SUMMARY one-liners (#2118)',
);
// CRITICAL: no mutations occurred
assert.ok(
fs.existsSync(path.join(tmpDir, '.planning', 'ROADMAP.md')),
'ROADMAP.md must NOT be archived (dry-run)',
);
assert.ok(
fs.existsSync(path.join(tmpDir, '.planning', 'REQUIREMENTS.md')),
'REQUIREMENTS.md must NOT be archived (dry-run)',
);
assert.ok(
fs.existsSync(phasePath),
'phase directory must NOT be moved (dry-run)',
);
assert.ok(
!fs.existsSync(path.join(tmpDir, '.planning', 'MILESTONES.md')),
'MILESTONES.md must NOT be created (dry-run)',
);
assert.strictEqual(
fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8'),
stateBefore,
'STATE.md must be unchanged (dry-run)',
);
assert.ok(
!fs.existsSync(path.join(tmpDir, '.planning', 'milestones')),
'archive dir must NOT be created (dry-run) — platformEnsureDir must be gated',
);
});
test('#2118 — --dry-run --no-archive-phases omits phase list from preview', () => {
writeRoadmap(tmpDir, `# Roadmap v1.0 MVP\n\n### Phase 1: Foundation\n**Goal:** Setup\n`);
writeState(tmpDir);
mkPhaseDir(tmpDir, '01-foundation');
const result = runGsdTools('milestone complete v1.0 --dry-run --no-archive-phases', tmpDir);
assert.ok(result.success, `Command failed: ${result.error}`);
const output = JSON.parse(result.output);
assert.strictEqual(output.dry_run, true);
assert.deepStrictEqual(output.would_archive.phases, [], 'phases list must be empty with --no-archive-phases');
});
test('#2118 — --dry-run --force bypasses the unstarted-phases guard', () => {
writeRoadmap(tmpDir, `# Roadmap v1.0 MVP\n\n### Phase 1: Foundation\n**Goal:** Setup\n`);
writeState(tmpDir, 'milestone: v1.0\n');
// No phase directory for Phase 1 — guard would block without --force
// Capture pre-state
const stateBefore = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
const result = runGsdTools('milestone complete v1.0 --dry-run --force', tmpDir);
assert.ok(result.success, `Command failed: ${result.error}`);
const output = JSON.parse(result.output);
assert.strictEqual(output.dry_run, true, 'preview should run past the guard with --force');
// CRITICAL: --force must still be a zero-mutation dry-run preview
assert.ok(
!fs.existsSync(path.join(tmpDir, '.planning', 'milestones')),
'archive dir must NOT be created (dry-run --force) — platformEnsureDir must be gated',
);
assert.strictEqual(
fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8'),
stateBefore,
'STATE.md must be unchanged (dry-run --force)',
);
assert.ok(
!fs.existsSync(path.join(tmpDir, '.planning', 'MILESTONES.md')),
'MILESTONES.md must NOT be created (dry-run --force)',
);
});
test('#2118 — --dry-run --raw emits structured preview JSON, not the literal "dry-run" string', () => {
writeRoadmap(tmpDir, `# Roadmap v1.0 MVP\n\n### Phase 1: Foundation\n**Goal:** Setup\n`);
writeState(tmpDir);
mkPhaseDir(tmpDir, '01-foundation', { oneLiner: 'Set up project infrastructure' });
const result = runGsdTools(['milestone', 'complete', 'v1.0', '--name', 'Test', '--dry-run', '--raw'], tmpDir);
assert.ok(result.success, `Command failed: ${result.error}`);
// Before the fix, output(dryRunResult, raw, 'dry-run') meant --raw discarded
// the structured payload and printed only the literal string "dry-run",
// which is not parseable JSON.
let output;
assert.doesNotThrow(
() => { output = JSON.parse(result.output); },
`--dry-run --raw output must be parseable JSON, not the literal "dry-run" string; got ${JSON.stringify(result.output)}`,
);
assert.strictEqual(output.dry_run, true, 'dry_run must be true, not the literal string "dry-run"');
assert.strictEqual(output.version, 'v1.0');
assert.ok(
Array.isArray(output.accomplishments) && output.accomplishments.includes('Set up project infrastructure'),
'structured preview surviving --raw should include accomplishments',
);
});
test('prepends to existing MILESTONES.md (reverse chronological)', () => {
fs.writeFileSync(
path.join(tmpDir, '.planning', 'MILESTONES.md'),