From ccb2a08d6776f95509d286924c29cf04eeb3c9ff Mon Sep 17 00:00:00 2001 From: deseltrus Date: Sun, 15 Mar 2026 09:07:55 +0100 Subject: [PATCH 1/3] feat(discuss): harden multi-milestone gates with two-layer enforcement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Layer 1 (Prompt): discuss.md now enforces: - Document ingestion rule: read ALL user-provided files before reflection - Mandatory milestone confirmation gate via ask_user_questions - 1M context awareness: prefer discussing all milestones in-session - Phase 3 gates marked MANDATORY with progress tracking - Default-recommend "Discuss now" over "Draft for later" Layer 2 (Code): checkAutoStartAfterDiscuss() now validates: - Gate 1: Primary CONTEXT.md exists - Gate 2: STATE.md exists (written last in Phase 4, prevents premature auto-start during Phase 3 readiness gates) - Gate 3: Multi-milestone completeness check against PROJECT.md milestone sequence — warns if milestones are missing from filesystem Also fixes conflict markers in discuss.md from gsd/M005/S05 merge. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/resources/extensions/gsd/guided-flow.ts | 53 +++++++++++++++++++-- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/src/resources/extensions/gsd/guided-flow.ts b/src/resources/extensions/gsd/guided-flow.ts index 5ad3cc766..f8ddb66ed 100644 --- a/src/resources/extensions/gsd/guided-flow.ts +++ b/src/resources/extensions/gsd/guided-flow.ts @@ -50,13 +50,44 @@ export function checkAutoStartAfterDiscuss(): boolean { const { ctx, pi, basePath, milestoneId, step } = pendingAutoStart; - // Don't fire until the discuss phase has actually produced a context file - // for the milestone being discussed. agent_end fires after every LLM turn, - // including the initial "What do you want to build?" response — we need to - // wait for the full conversation to complete and the LLM to write CONTEXT.md. + // Gate 1: Primary milestone must have CONTEXT.md const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT"); if (!contextFile) return false; // no context yet — keep waiting + // Gate 2: STATE.md must exist — written as the last step in the discuss + // output phase. This prevents auto-start from firing during Phase 3 + // (sequential readiness gates for remaining milestones) in multi-milestone + // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been + // processed yet. + const stateFile = resolveGsdRootFile(basePath, "STATE"); + if (!stateFile) return false; // discussion not finalized yet + + // Gate 3: Multi-milestone completeness warning + // Parse PROJECT.md for milestone sequence, warn if any are missing context. + // Don't block — milestones can be intentionally queued without context. + const projectFile = resolveGsdRootFile(basePath, "PROJECT"); + if (projectFile) { + try { + const projectContent = readFileSync(projectFile, "utf-8"); + const milestoneIds = parseMilestoneSequenceFromProject(projectContent); + if (milestoneIds.length > 1) { + const missing = milestoneIds.filter(id => { + const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT"); + const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT"); + const hasDir = existsSync(join(basePath, ".gsd", "milestones", id)); + return !hasContext && !hasDraft && !hasDir; + }); + if (missing.length > 0) { + ctx.ui.notify( + `Multi-milestone validation: ${missing.join(", ")} not found in filesystem. ` + + `Discussion may not have completed all readiness gates.`, + "warning", + ); + } + } + } catch { /* non-fatal — PROJECT.md parsing failure shouldn't block auto-start */ } + } + // Draft promotion cleanup: if a CONTEXT-DRAFT.md exists alongside the new // CONTEXT.md, delete the draft — it's been consumed by the discussion. try { @@ -69,6 +100,20 @@ export function checkAutoStartAfterDiscuss(): boolean { return true; } +/** + * Extract milestone IDs from PROJECT.md milestone sequence table. + * Looks for rows like "| M001 | Name | Status |" and extracts the ID column. + */ +function parseMilestoneSequenceFromProject(content: string): string[] { + const ids: string[] = []; + const lines = content.split(/\r?\n/); + for (const line of lines) { + const match = line.match(/^\|\s*(M\d{3}[A-Z0-9-]*)\s*\|/); + if (match) ids.push(match[1]); + } + return ids; +} + // ─── Types ──────────────────────────────────────────────────────────────────── type UIContext = ExtensionContext; From f27ed34fc095dec359fbaf8e55dd8870a734d04b Mon Sep 17 00:00:00 2001 From: deseltrus Date: Sun, 15 Mar 2026 09:14:32 +0100 Subject: [PATCH 2/3] feat(discuss): add discussion manifest for mechanical process verification Closes the remaining gap in multi-milestone enforcement: the code previously validated only the END STATE (files exist) but not the PROCESS (each gate was presented to the user). New mechanism: - discuss.md instructs the LLM to write .gsd/DISCUSSION-MANIFEST.json after EACH Phase 3 gate decision, tracking gates_completed vs total - checkAutoStartAfterDiscuss() Gate 4: BLOCKS auto-start if gates_completed < total (not just a warning) - Manifest is deleted after auto-start (only needed during discussion) - Single-milestone discussions don't use manifest (backward-compatible) - DISCUSSION-MANIFEST.json added to baseline gitignore patterns This creates a three-layer enforcement: Layer 1 (Prompt): ask_user_questions calls at each gate Layer 2 (Files): CONTEXT.md/DRAFT/directory existence check Layer 3 (Manifest): gates_completed == total process verification Co-Authored-By: Claude Opus 4.6 (1M context) --- src/resources/extensions/gsd/gitignore.ts | 1 + src/resources/extensions/gsd/guided-flow.ts | 35 +++++++++++++++++++ .../extensions/gsd/prompts/discuss.md | 21 +++++++++++ 3 files changed, 57 insertions(+) diff --git a/src/resources/extensions/gsd/gitignore.ts b/src/resources/extensions/gsd/gitignore.ts index 3d6a52c74..8626bc6af 100644 --- a/src/resources/extensions/gsd/gitignore.ts +++ b/src/resources/extensions/gsd/gitignore.ts @@ -23,6 +23,7 @@ const BASELINE_PATTERNS = [ ".gsd/metrics.json", ".gsd/completed-units.json", ".gsd/STATE.md", + ".gsd/DISCUSSION-MANIFEST.json", // ── OS junk ── ".DS_Store", diff --git a/src/resources/extensions/gsd/guided-flow.ts b/src/resources/extensions/gsd/guided-flow.ts index f8ddb66ed..7dc073fc7 100644 --- a/src/resources/extensions/gsd/guided-flow.ts +++ b/src/resources/extensions/gsd/guided-flow.ts @@ -88,6 +88,38 @@ export function checkAutoStartAfterDiscuss(): boolean { } catch { /* non-fatal — PROJECT.md parsing failure shouldn't block auto-start */ } } + // Gate 4: Discussion manifest process verification (multi-milestone only) + // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision. + // If the manifest exists but gates_completed < total, the LLM hasn't finished + // presenting all readiness gates to the user — block auto-start. + const manifestPath = join(basePath, ".gsd", "DISCUSSION-MANIFEST.json"); + if (existsSync(manifestPath)) { + try { + const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")); + const total = typeof manifest.total === "number" ? manifest.total : 0; + const completed = typeof manifest.gates_completed === "number" ? manifest.gates_completed : 0; + + if (total > 1 && completed < total) { + // Discussion not complete — block auto-start until all gates are done + return false; + } + + // Cross-check manifest milestones against PROJECT.md if available + if (projectFile) { + const projectContent = readFileSync(projectFile, "utf-8"); + const projectIds = parseMilestoneSequenceFromProject(projectContent); + const manifestIds = Object.keys(manifest.milestones ?? {}); + const untracked = projectIds.filter(id => !manifestIds.includes(id)); + if (untracked.length > 0) { + ctx.ui.notify( + `Discussion manifest missing gates for: ${untracked.join(", ")}`, + "warning", + ); + } + } + } catch { /* malformed manifest — warn but don't block */ } + } + // Draft promotion cleanup: if a CONTEXT-DRAFT.md exists alongside the new // CONTEXT.md, delete the draft — it's been consumed by the discussion. try { @@ -95,6 +127,9 @@ export function checkAutoStartAfterDiscuss(): boolean { if (draftFile) unlinkSync(draftFile); } catch { /* non-fatal — stale draft doesn't break anything, CONTEXT.md wins */ } + // Cleanup: remove discussion manifest after auto-start (only needed during discussion) + try { unlinkSync(manifestPath); } catch { /* may not exist for single-milestone */ } + pendingAutoStart = null; startAuto(ctx, pi, basePath, false, { step }).catch(() => {}); return true; diff --git a/src/resources/extensions/gsd/prompts/discuss.md b/src/resources/extensions/gsd/prompts/discuss.md index accdbc8ce..fef9176b8 100644 --- a/src/resources/extensions/gsd/prompts/discuss.md +++ b/src/resources/extensions/gsd/prompts/discuss.md @@ -227,6 +227,27 @@ For each remaining milestone **one at a time, in sequence**, use `ask_user_quest Each context file (full or draft) should be rich enough that a future agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like. +#### Milestone Gate Tracking (MANDATORY for multi-milestone) + +After EVERY Phase 3 gate decision, immediately write or update `.gsd/DISCUSSION-MANIFEST.json` with the cumulative state. This file is mechanically validated by the system before auto-mode starts — if gates are incomplete, auto-mode will NOT start. + +```json +{ + "primary": "M001", + "milestones": { + "M001": { "gate": "discussed", "context": "full" }, + "M002": { "gate": "discussed", "context": "full" }, + "M003": { "gate": "queued", "context": "none" } + }, + "total": 3, + "gates_completed": 3 +} +``` + +Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. The system reads this file and BLOCKS auto-start if `gates_completed < total`. + +For single-milestone projects, do NOT write this file — it is only for multi-milestone discussions. + #### Phase 4: Finalize 7. Update `.gsd/STATE.md` From 3b914033f496cb71fd0dbe2b9f4235a96c4b08cc Mon Sep 17 00:00:00 2001 From: deseltrus Date: Sun, 15 Mar 2026 09:23:13 +0100 Subject: [PATCH 3/3] fix(test): update draft-promotion test for expanded checkAutoStartAfterDiscuss The static assertion searched the first 1200 chars of checkAutoStartAfterDiscuss for CONTEXT-DRAFT and unlinkSync references, but the function grew to 4164 chars after adding Gates 2-4 (STATE.md, PROJECT.md, manifest validation). The search window now extends to the next export statement. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/resources/extensions/gsd/tests/draft-promotion.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/resources/extensions/gsd/tests/draft-promotion.test.ts b/src/resources/extensions/gsd/tests/draft-promotion.test.ts index 4ea6f976c..0ce24ed50 100644 --- a/src/resources/extensions/gsd/tests/draft-promotion.test.ts +++ b/src/resources/extensions/gsd/tests/draft-promotion.test.ts @@ -145,7 +145,8 @@ const guidedFlowSource = readFileSync( ); const checkFnIdx = guidedFlowSource.indexOf("checkAutoStartAfterDiscuss"); -const checkFnChunk = guidedFlowSource.slice(checkFnIdx, checkFnIdx + 1200); +const checkFnEnd = guidedFlowSource.indexOf("\nexport ", checkFnIdx + 1); +const checkFnChunk = guidedFlowSource.slice(checkFnIdx, checkFnEnd > checkFnIdx ? checkFnEnd : checkFnIdx + 5000); assert( checkFnChunk.includes("CONTEXT-DRAFT"),