gsd-pi 2.79.0-dev.579e14e9b → 2.79.0-dev.8f814f3af

package/src/resources/extensions/gsd/tests/deep-planning-mode-dispatch.test.ts

@@ -14,6 +14,7 @@ import {
   DISPATCH_RULES,
   getDeepStageGate,
   hasPendingDeepStage,
+  resolveDispatch,
   setResearchProjectPromptBuilderForTest,
   type DispatchContext,
 } from "../auto-dispatch.ts";
@@ -248,6 +249,11 @@ function writeCapturedDeepPrefs(base: string): void {
   );
 }
 
+function writeSkippedProjectResearchDecision(base: string): void {
+  mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "runtime", "research-decision.json"), JSON.stringify({ decision: "skip" }));
+}
+
 function makeCtx(
   basePath: string,
   prefs: GSDPreferences | undefined,
@@ -785,6 +791,42 @@ test("Deep mode: research-project DOES dispatch when only 3 of 4 research files
   assert.ok(result && result.action === "dispatch", "any missing dimension must trigger re-run");
 });
 
+test("Deep mode: queued milestone without CONTEXT.md routes to milestone research after project setup", async (t) => {
+  const base = makeIsolatedBaseWithCleanup(t);
+
+  writeCapturedDeepPrefs(base);
+  writeValidProject(base);
+  writeValidRequirements(base);
+  writeSkippedProjectResearchDecision(base);
+
+  const prefs = { planning_depth: "deep" } as GSDPreferences;
+  const result = await resolveDispatch(makeCtx(base, prefs));
+
+  assert.equal(result.action, "dispatch");
+  if (result.action === "dispatch") {
+    assert.equal(result.unitType, "research-milestone");
+    assert.equal(result.unitId, "M001");
+  }
+});
+
+test("Deep mode: queued milestone without CONTEXT.md can route directly to milestone planning", async (t) => {
+  const base = makeIsolatedBaseWithCleanup(t);
+
+  writeCapturedDeepPrefs(base);
+  writeValidProject(base);
+  writeValidRequirements(base);
+  writeSkippedProjectResearchDecision(base);
+
+  const prefs = { planning_depth: "deep", phases: { skip_research: true } } as GSDPreferences;
+  const result = await resolveDispatch(makeCtx(base, prefs));
+
+  assert.equal(result.action, "dispatch");
+  if (result.action === "dispatch") {
+    assert.equal(result.unitType, "plan-milestone");
+    assert.equal(result.unitId, "M001");
+  }
+});
+
 // ─── centralized deep-stage gate ─────────────────────────────────────────
 
 test("Deep mode gate reports the earliest missing section", (t) => {

package/src/resources/extensions/gsd/tests/deep-project-auto-loop.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -23,6 +23,11 @@ import {
   showSmartEntry,
   startDeepProjectSetupForeground,
 } from "../guided-flow.ts";
+import {
+  closeDatabase,
+  insertMilestone,
+  openDatabase,
+} from "../gsd-db.ts";
 import type { GSDPreferences } from "../preferences.ts";
 import type { GSDState } from "../types.ts";
 
@@ -342,6 +347,62 @@ test("deep project setup: pre-dispatch can run before the first milestone exists
   }
 });
 
+test("deep project setup: bootstrap continues queued M002 without milestone context", async () => {
+  const base = makeRepo();
+  try {
+    writeCapturedDeepPrefs(base);
+    writeValidProjectAndRequirements(base);
+    mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "runtime", "research-decision.json"), '{"decision":"skip"}\n');
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "First milestone", status: "complete" });
+    insertMilestone({ id: "M002", title: "Second milestone", status: "queued" });
+    closeDatabase();
+
+    const messages: unknown[] = [];
+    const pi = {
+      ...makePi(messages),
+      getThinkingLevel: () => "medium",
+    };
+    const s = new AutoSession();
+    const ready = await bootstrapAutoSession(
+      s,
+      makeCtx(`queued-${randomUUID()}`) as any,
+      pi as any,
+      base,
+      false,
+      false,
+      {
+        shouldUseWorktreeIsolation: () => false,
+        registerSigtermHandler: () => {},
+        lockBase: () => base,
+        buildResolver: () => ({}) as any,
+      },
+      {
+        classification: "none",
+        lock: null,
+        pausedSession: null,
+        state: null,
+        recovery: null,
+        recoveryPrompt: null,
+        recoveryToolCallCount: 0,
+        artifactSatisfied: false,
+        hasResumableDiskState: false,
+        isBootstrapCrash: false,
+      },
+    );
+
+    assert.equal(ready, true);
+    assert.equal(s.active, true);
+    assert.equal(s.currentMilestoneId, "M002");
+    assert.equal(messages.length, 0, "queued deep milestone must not re-enter smart new-milestone discussion");
+  } finally {
+    try { closeDatabase(); } catch {}
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("deep project setup: pre-dispatch takes precedence over an existing draft milestone", async () => {
   const base = makeBase();
   try {
@@ -1020,7 +1081,7 @@ test("deep project setup: research-project blocker placeholder is a file, not th
   const base = makeBase();
   try {
     const expectedPath = resolveExpectedArtifactPath("research-project", "PROJECT-RESEARCH", base);
-    assert.equal(expectedPath, join(base, ".gsd", "research", "PROJECT-RESEARCH-BLOCKER.md"));
+    assert.equal(expectedPath, join(realpathSync(base), ".gsd", "research", "PROJECT-RESEARCH-BLOCKER.md"));
 
     mkdirSync(join(base, ".gsd", "research"), { recursive: true });
     const diagnosis = writeBlockerPlaceholder(

package/src/resources/extensions/gsd/tests/execute-summary-save-empty-project.test.ts

@@ -0,0 +1,109 @@
+// gsd-2 / execute-summary-save PROJECT registration hard-fail tests
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { openDatabase, closeDatabase, getAllMilestones } from "../gsd-db.ts";
+import { markApprovalGateVerified, clearDiscussionFlowState } from "../bootstrap/write-gate.ts";
+import { executeSummarySave } from "../tools/workflow-tool-executors.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-summary-save-empty-project-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* swallow */ }
+}
+
+function openTestDb(base: string): void {
+  openDatabase(join(base, ".gsd", "gsd.db"));
+}
+
+async function inProjectDir<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const originalCwd = process.cwd();
+  try {
+    process.chdir(dir);
+    return await fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+function setupBase(t: { after: (fn: () => void) => void }): string {
+  const base = makeTmpBase();
+  // Force deep planning so the root-artifact guard requires a verified approval gate,
+  // matching the production flow that surfaces the regression.
+  writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\nplanning_depth: deep\n---\n");
+  openTestDb(base);
+  markApprovalGateVerified("depth_verification_project_confirm", base);
+  t.after(() => {
+    clearDiscussionFlowState(base);
+    closeDatabase();
+    cleanup(base);
+  });
+  return base;
+}
+
+test("executeSummarySave returns isError when PROJECT.md content has zero parseable milestone lines", async (t) => {
+  const base = setupBase(t);
+
+  const content = [
+    "# Project",
+    "",
+    "## What This Is",
+    "",
+    "Bad-separator regression fixture.",
+    "",
+    "## Milestone Sequence",
+    "",
+    // Wrong separator: " : " instead of em-dash / -- / -  → MILESTONE_LINE_RE matches zero lines.
+    "- [ ] M001: Foundation : Establish the first runnable slice.",
+    "",
+    "## Next Section",
+    "",
+    "Trailing prose with no list bullets so MILESTONE_LINE_RE cannot bridge across lines.",
+    "",
+  ].join("\n");
+
+  const result = await inProjectDir(base, () => executeSummarySave({
+    artifact_type: "PROJECT",
+    content,
+  }, base));
+
+  assert.equal(result.isError, true);
+  assert.equal(result.details.error, "milestone_registration_empty_parse");
+  assert.match(result.content[0].text, /zero parseable milestone lines/);
+  assert.equal(getAllMilestones().length, 0);
+});
+
+test("executeSummarySave registers milestones when PROJECT.md uses canonical em-dash format", async (t) => {
+  const base = setupBase(t);
+
+  const content = [
+    "# Project",
+    "",
+    "## What This Is",
+    "",
+    "Canonical milestone-sequence fixture.",
+    "",
+    "## Milestone Sequence",
+    "",
+    "- [ ] M001: Foo — bar",
+    "- [ ] M002: Baz — qux",
+    "",
+  ].join("\n");
+
+  const result = await inProjectDir(base, () => executeSummarySave({
+    artifact_type: "PROJECT",
+    content,
+  }, base));
+
+  assert.notEqual(result.isError, true);
+  assert.deepEqual(result.details.registeredMilestones, ["M001", "M002"]);
+  assert.equal(getAllMilestones().length, 2);
+});

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -1,5 +1,10 @@
+// GSD2 UOK Contract Versioning and DB Authority Tests
+
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import type {
   AuditEventEnvelope,
@@ -11,8 +16,17 @@ import type {
   WriteRecord,
   WriterToken,
 } from "../uok/contracts.ts";
-import { buildAuditEnvelope } from "../uok/audit.ts";
+import {
+  CURRENT_UOK_CONTRACT_VERSION,
+  normalizeAuditEvent,
+  validateAuditEvent,
+  validateDispatchEnvelope,
+  validateTurnResult,
+} from "../uok/contracts.ts";
+import { buildAuditEnvelope, emitUokAuditEvent } from "../uok/audit.ts";
 import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
+import { buildTurnTimeline } from "../uok/timeline.ts";
+import { _getAdapter, closeDatabase, openDatabase } from "../gsd-db.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -37,6 +51,7 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
   };
 
   const result: TurnResult = {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     traceId: contract.traceId,
     turnId: contract.turnId,
     iteration: contract.iteration,
@@ -56,8 +71,10 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
 
   const roundTrip = JSON.parse(JSON.stringify(result)) as TurnResult;
   assert.equal(roundTrip.turnId, "turn-1");
+  assert.equal(roundTrip.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(roundTrip.gateResults?.[0]?.gateId, "Q3");
   assert.equal(roundTrip.phaseResults.length, 3);
+  assert.equal(validateTurnResult(roundTrip).ok, true);
 });
 
 test("uok contracts include required DAG node kinds", () => {
@@ -84,9 +101,11 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   });
 
   assert.equal(event.traceId, "trace-xyz");
+  assert.equal(event.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(event.turnId, "turn-xyz");
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
+  assert.equal(validateAuditEvent(event).ok, true);
 });
 
 test("uok dispatch envelope carries scheduler reason and constraints", () => {
@@ -107,9 +126,98 @@ test("uok dispatch envelope carries scheduler reason and constraints", () => {
   });
 
   assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(envelope.reason.reasonCode, "dependency");
   assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
   assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+  assert.equal(validateDispatchEnvelope(envelope).ok, true);
+});
+
+test("uok contracts normalize legacy records without losing payload fields", () => {
+  const legacy = {
+    eventId: "event-legacy",
+    traceId: "trace-legacy",
+    category: "orchestration",
+    type: "turn-result",
+    ts: new Date().toISOString(),
+    payload: { status: "completed", extra: "preserved" },
+  } as AuditEventEnvelope;
+
+  const normalized = normalizeAuditEvent(legacy);
+  assert.equal(normalized.version, "0");
+  assert.equal(normalized.payload.extra, "preserved");
+  assert.equal(validateAuditEvent(legacy).ok, true);
+});
+
+test("uok audit emission writes DB as authoritative before jsonl projection", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-db-audit-"));
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-db",
+      turnId: "turn-db",
+      category: "orchestration",
+      type: "turn-start",
+      payload: { unitType: "execute-task" },
+    }),
+  );
+
+  const row = _getAdapter()!.prepare(
+    "SELECT payload_json FROM audit_events WHERE trace_id = 'trace-db' AND turn_id = 'turn-db'",
+  ).get() as { payload_json: string } | undefined;
+  assert.ok(row, "DB audit row should be written");
+  assert.equal(JSON.parse(row.payload_json).contractVersion, CURRENT_UOK_CONTRACT_VERSION);
+
+  const projection = readFileSync(join(basePath, ".gsd", "audit", "events.jsonl"), "utf-8");
+  assert.ok(projection.includes("trace-db"), "jsonl projection should still be written");
+});
+
+test("uok timeline prefers DB records over jsonl projection when DB is available", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-timeline-"));
+  const auditDir = join(basePath, ".gsd", "audit");
+  mkdirSync(auditDir, { recursive: true });
+  writeFileSync(
+    join(auditDir, "events.jsonl"),
+    `${JSON.stringify({
+      version: CURRENT_UOK_CONTRACT_VERSION,
+      eventId: "jsonl-only",
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "jsonl-projection",
+      ts: "2026-01-01T00:00:00.000Z",
+      payload: {},
+    })}\n`,
+  );
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "db-authoritative",
+      payload: {},
+    }),
+  );
+
+  const timeline = buildTurnTimeline(basePath, { traceId: "trace-timeline", turnId: "turn-timeline" });
+  assert.equal(timeline.authoritative, "db");
+  assert.equal(timeline.degraded, false);
+  assert.ok(timeline.entries.some((entry) => entry.type === "db-authoritative"));
+  assert.equal(timeline.entries.some((entry) => entry.type === "jsonl-projection"), false);
 });
 
 test("uok writer records serialize sequence metadata", () => {

package/src/resources/extensions/gsd/tests/uok-loop-adapter-writer.test.ts

@@ -63,3 +63,101 @@ test("uok turn observer adds writer sequence metadata to audit events", (t) => {
   assert.equal(payloads[1]?.writeSequence, 2);
   assert.equal(typeof payloads[0]?.writerTokenId, "string");
 });
+
+test("uok turn observer releases writer token when validation throws", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-throw-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-throw",
+    turnId: "turn-throw",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), true);
+
+  // Invalid payload (missing required fields like status/finishedAt) should
+  // trigger validateTurnResult to fail and throw.
+  assert.throws(() => {
+    observer.onTurnResult({
+      traceId: "trace-throw",
+      turnId: "turn-throw",
+      // @ts-expect-error intentionally invalid for test
+      iteration: "not-a-number",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      phaseResults: [],
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  }, /Invalid UOK turn result/);
+
+  // Cleanup must run in finally — token released, no leaked state.
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), false);
+});
+
+test("uok turn observer falls back to cached phaseResults when result.phaseResults is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-missing-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-missing",
+    turnId: "turn-missing",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+
+  // Without the Array.isArray guard, accessing result.phaseResults.length on a
+  // payload where phaseResults is undefined would throw TypeError before
+  // validateTurnResult could surface a structured error. The guard must defer
+  // to the cached phaseResults fallback so the turn completes cleanly.
+  assert.doesNotThrow(() => {
+    observer.onTurnResult({
+      traceId: "trace-missing",
+      turnId: "turn-missing",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      // @ts-expect-error intentionally missing for test
+      phaseResults: undefined,
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  });
+
+  assert.equal(hasActiveWriterToken(basePath, "turn-missing"), false);
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -692,7 +692,18 @@ test("executeSummarySave supports root-level deep planning artifacts", async ()
 
     const project = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "A root project artifact.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n"),
     }, base));
     assert.equal(project.isError, undefined);
     assert.equal(project.details.path, "PROJECT.md");
@@ -794,7 +805,7 @@ test("executeSummarySave registers PROJECT milestone sequence for the next run",
   }
 });
 
-test("executeSummarySave keeps PROJECT artifact save successful if milestone registration fails", async () => {
+test("executeSummarySave hard-fails when milestone registration throws so silent No-Active-Milestone is impossible", async () => {
   const base = makeTmpBase();
   try {
     openTestDb(base);
@@ -824,10 +835,15 @@ test("executeSummarySave keeps PROJECT artifact save successful if milestone reg
       ].join("\n"),
     }, base));
 
-    assert.equal(result.isError, undefined);
+    // The artifact is persisted before registration runs, but registration must
+    // surface as isError so the LLM retries (INSERT OR IGNORE makes it idempotent)
+    // instead of announcing "ready" while the DB has zero milestone rows.
+    assert.equal(result.isError, true);
     assert.equal(result.details.path, "PROJECT.md");
-    assert.equal(result.details.registeredMilestones, undefined);
-    assert.match(String(result.details.warning), /milestone registration failed/);
+    assert.equal(result.details.error, "milestone_registration_threw");
+    assert.match(String(result.details.registration_error), /simulated milestone registration failure/);
+    assert.match(result.content[0].text, /milestone registration failed/);
+    assert.match(result.content[0].text, /idempotent/);
     assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
     const artifact = originalPrepare("SELECT path FROM artifacts WHERE path = ?").get("PROJECT.md");
     assert.equal(artifact?.path, "PROJECT.md");
@@ -872,9 +888,22 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
     writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\nplanning_depth: deep\n---\n");
     openTestDb(base);
 
+    const projectFixture = [
+      "# Project",
+      "",
+      "## What This Is",
+      "",
+      "A root project artifact.",
+      "",
+      "## Milestone Sequence",
+      "",
+      "- [ ] M001: Foundation - Establish the first runnable slice.",
+      "",
+    ].join("\n");
+
     const blocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(blocked.isError, true);
@@ -886,7 +915,7 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
 
     const unblocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(unblocked.isError, undefined);

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -190,19 +190,63 @@ export async function executeSummarySave(
     );
 
     let registeredMilestones: string[] = [];
-    let registrationWarning: string | undefined;
     if (params.artifact_type === "PROJECT") {
       try {
         registeredMilestones = registerProjectMilestoneSequence(contentToSave);
         if (registeredMilestones.length > 0) invalidateStateCache();
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        registrationWarning = `PROJECT artifact saved, but milestone registration failed: ${msg}`;
-        logWarning("tool", registrationWarning, {
+        logError("tool", `gsd_summary_save: PROJECT artifact persisted but milestone registration threw: ${msg}`, {
           tool: "gsd_summary_save",
           error: String(err),
           stack: err instanceof Error ? err.stack ?? "" : "",
         });
+        // PROJECT.md was persisted by saveArtifactToDb above; the artifacts row
+        // changed even though no milestones registered. Invalidate so subsequent
+        // /gsd reads see the persisted artifact instead of the pre-save cache.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but milestone registration failed: ${msg}. ` +
+              `The DB has no milestone rows for this project, so /gsd will report "No Active Milestone". ` +
+              `Re-call gsd_summary_save(PROJECT) once the underlying error is resolved — INSERT OR IGNORE makes registration idempotent.`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_threw",
+            registration_error: msg,
+          },
+          isError: true,
+        };
+      }
+      if (registeredMilestones.length === 0) {
+        logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+          tool: "gsd_summary_save",
+        });
+        // PROJECT.md was persisted; invalidate so subsequent reads see the new
+        // artifacts row even though no milestones registered.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+              `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+              `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+              `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_empty_parse",
+          },
+          isError: true,
+        };
       }
     }
 
@@ -225,7 +269,6 @@ export async function executeSummarySave(
         artifact_type: params.artifact_type,
         content_source: contentSource,
         ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
-        ...(registrationWarning ? { warning: registrationWarning } : {}),
       },
     };
   } catch (err) {