From 802092d8ff2a0e20a02ecf320e1c51ff6f2672cf Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Fri, 20 Mar 2026 22:07:57 -0400
Subject: [PATCH] fix: add verification gate before writing PROJECT.md in
 new-milestone

After gathering milestone goals and determining version, the workflow
now presents a summary and asks for confirmation before writing any
files. Users can adjust until satisfied, preventing the previous
behavior where GSD would immediately write PROJECT.md without verifying
its understanding of the milestone scope.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 get-shit-done/workflows/new-milestone.md | 32 +++++++++++++++++
 tests/milestone.test.cjs                 | 45 ++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/get-shit-done/workflows/new-milestone.md b/get-shit-done/workflows/new-milestone.md
index a2b1e3fd0..c95c7396b 100644
--- a/get-shit-done/workflows/new-milestone.md
+++ b/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:
diff --git a/tests/milestone.test.cjs b/tests/milestone.test.cjs
index c3319d10c..025a05a80 100644
--- a/tests/milestone.test.cjs
+++ b/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
 // ─────────────────────────────────────────────────────────────────────────────