fix(#2630): reset STATE.md frontmatter atomically on milestone switch (#2666)

The /gsd:new-milestone workflow Step 5 rewrote STATE.md's Current Position
body but never touched the YAML frontmatter, so every downstream reader
(state.json, getMilestoneInfo, progress bars) kept reporting the stale
milestone until the first phase advance forced a resync. Asymmetric with
milestone.complete, which uses readModifyWriteStateMdFull.

Add a new `state milestone-switch` handler (both SDK and CJS) that atomically:
- Stomps frontmatter milestone/milestone_name with caller-supplied values
- Resets status to 'planning' and progress counters to zero
- Rewrites the ## Current Position section to the new-milestone template
- Preserves Accumulated Context (decisions, blockers, todos)

Wire the workflow Step 5 to invoke `state.milestone-switch` instead of the
manual body rewrite. Note the flag is `--milestone` not `--version`:
gsd-tools reserves `--version` as a globally-invalid help flag.

Red vitest in sdk/src/query/state-mutation.test.ts asserts the frontmatter
reset. Regression guard via node:test in tests/bug-2630-*.test.cjs runs
through gsd-tools end-to-end.

Fixes #2630

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-04-24 18:05:10 -04:00
committed by GitHub
parent 8caa7d4c3a
commit e973ff4cb6
7 changed files with 435 additions and 1 deletions

View File

@@ -483,6 +483,12 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
} else if (subcommand === 'prune') {
const { 'keep-recent': keepRecent, 'dry-run': dryRun } = parseNamedArgs(args, ['keep-recent'], ['dry-run']);
state.cmdStatePrune(cwd, { keepRecent: keepRecent || '3', dryRun: !!dryRun }, raw);
} else if (subcommand === 'milestone-switch') {
// Bug #2630: reset STATE.md frontmatter + Current Position for new milestone.
// NB: the flag is `--milestone`, not `--version` — gsd-tools reserves
// `--version` as a globally-invalid help flag (see NEVER_VALID_FLAGS above).
const { milestone, name } = parseNamedArgs(args, ['milestone', 'name']);
state.cmdStateMilestoneSwitch(cwd, milestone, name, raw);
} else {
state.cmdStateLoad(cwd, raw);
}

View File

@@ -1253,6 +1253,70 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
}
/**
* Bug #2630: reset STATE.md for a new milestone cycle.
* Stomps frontmatter milestone/milestone_name/status/progress AND rewrites
* the Current Position body. Preserves Accumulated Context.
* Symmetric with the SDK `stateMilestoneSwitch` handler.
*/
function cmdStateMilestoneSwitch(cwd, version, name, raw) {
if (!version || !String(version).trim()) {
output({ error: 'milestone required (--milestone <vX.Y>)' }, raw);
return;
}
const resolvedName = (name && String(name).trim()) || 'milestone';
const statePath = planningPaths(cwd).state;
const today = new Date().toISOString().split('T')[0];
const lockPath = acquireStateLock(statePath);
try {
const content = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : '';
const existingFm = extractFrontmatter(content);
const body = stripFrontmatter(content);
const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
const resetPositionBody =
`\nPhase: Not started (defining requirements)\n` +
`Plan: —\n` +
`Status: Defining requirements\n` +
`Last activity: ${today} — Milestone ${version} started\n\n`;
let newBody;
if (positionPattern.test(body)) {
newBody = body.replace(positionPattern, (_m, header) => `${header}${resetPositionBody}`);
} else {
const preface = body.trim().length > 0 ? body : '# Project State\n';
newBody = `${preface.trimEnd()}\n\n## Current Position\n${resetPositionBody}`;
}
const fm = {
gsd_state_version: existingFm.gsd_state_version || '1.0',
milestone: version,
milestone_name: resolvedName,
status: 'planning',
last_updated: new Date().toISOString(),
last_activity: today,
progress: {
total_phases: 0,
completed_phases: 0,
total_plans: 0,
completed_plans: 0,
percent: 0,
},
};
const yamlStr = reconstructFrontmatter(fm);
const assembled = `---\n${yamlStr}\n---\n\n${newBody.replace(/^\n+/, '')}`;
atomicWriteFileSync(statePath, normalizeMd(assembled), 'utf-8');
output(
{ switched: true, version, name: resolvedName, status: 'planning' },
raw,
'true',
);
} finally {
releaseStateLock(lockPath);
}
}
/**
* Gate 1: Validate STATE.md against filesystem.
* Returns { valid, warnings, drift } JSON.
@@ -1644,6 +1708,7 @@ module.exports = {
cmdStateValidate,
cmdStateSync,
cmdStatePrune,
cmdStateMilestoneSwitch,
cmdSignalWaiting,
cmdSignalResume,
};

View File

@@ -173,6 +173,19 @@ This document evolves at phase transitions and milestone boundaries.
## 5. Update STATE.md
Reset STATE.md frontmatter AND body atomically via the SDK. This writes the new
milestone version/name into the YAML frontmatter, resets `status` to
`planning`, zeroes `progress.*` counters, and rewrites the `## Current Position`
section to the new-milestone template. Accumulated Context (decisions,
blockers, todos) is preserved across the switch — symmetric with
`milestone.complete`.
```bash
gsd-sdk query state.milestone-switch --milestone "v[X.Y]" --name "[Name]"
```
The resulting Current Position section looks like:
```markdown
## Current Position
@@ -182,7 +195,11 @@ Status: Defining requirements
Last activity: [today] — Milestone v[X.Y] started
```
Keep Accumulated Context section from previous milestone.
Bug #2630: a prior version of this workflow rewrote the Current Position body
manually but left the frontmatter pointing at the previous milestone, so every
downstream reader (`state.json`, `getMilestoneInfo`, progress bars) reported the
stale milestone until the first phase advance forced a resync. Always use the
SDK handler above — do not hand-edit STATE.md here.
## 6. Cleanup and Commit