Merge pull request #1270 from gsd-build/fix/new-milestone-verification-gate-1269

fix: add verification gate before writing PROJECT.md in new-milestone

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

@@ -43,6 +43,38 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
 
+## 3.5. Verify Milestone Understanding
+
+Before writing any files, present a summary of what was gathered and ask for confirmation.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► MILESTONE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+**Goal:** [One sentence]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+**Key context:** [Any important constraints, decisions, or notes from questioning]
+```
+
+AskUserQuestion:
+- header: "Confirm?"
+- question: "Does this capture what you want to build in this milestone?"
+- options:
+  - "Looks good" — Proceed to write PROJECT.md
+  - "Adjust" — Let me correct or add details
+
+**If "Adjust":** Ask what needs changing (plain text, NOT AskUserQuestion). Incorporate changes, re-present the summary. Loop until "Looks good" is selected.
+
+**If "Looks good":** Proceed to Step 4.
+
 ## 4. Update PROJECT.md
 
 Add/update:

tests/milestone.test.cjs

@@ -703,6 +703,51 @@ describe('requirements mark-complete command', () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// new-milestone workflow verification gate (#1269)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('new-milestone workflow verification gate', () => {
+  test('new-milestone workflow has verification step before writing PROJECT.md', () => {
+    const workflowPath = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'new-milestone.md');
+    const content = fs.readFileSync(workflowPath, 'utf8');
+
+    // Must have a verification step between goal gathering and PROJECT.md writing
+    assert.ok(
+      content.includes('Verify Milestone Understanding'),
+      'workflow must have a "Verify Milestone Understanding" step'
+    );
+
+    // Verification must come before Step 4 (Update PROJECT.md)
+    const verifyIdx = content.indexOf('Verify Milestone Understanding');
+    const updateIdx = content.indexOf('## 4. Update PROJECT.md');
+    assert.ok(verifyIdx > 0, 'verification step must exist');
+    assert.ok(updateIdx > 0, 'Update PROJECT.md step must exist');
+    assert.ok(
+      verifyIdx < updateIdx,
+      'verification step must appear before Update PROJECT.md step'
+    );
+  });
+
+  test('verification step uses AskUserQuestion with adjust loop', () => {
+    const workflowPath = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'new-milestone.md');
+    const content = fs.readFileSync(workflowPath, 'utf8');
+
+    // Extract the section between 3.5 and 4
+    const sectionStart = content.indexOf('## 3.5');
+    const sectionEnd = content.indexOf('## 4.');
+    const section = content.slice(sectionStart, sectionEnd);
+
+    assert.ok(section.includes('AskUserQuestion'), 'verification must use AskUserQuestion');
+    assert.ok(section.includes('Adjust'), 'verification must offer Adjust option');
+    assert.ok(section.includes('Looks good'), 'verification must offer Looks good option');
+    assert.ok(
+      section.includes('Loop until') || section.includes('loop until') || section.includes('re-present'),
+      'verification must loop until user approves'
+    );
+  });
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // validate consistency command
 // ─────────────────────────────────────────────────────────────────────────────