gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/cmux.test.ts

@@ -14,7 +14,7 @@ import {
   shouldPromptToEnableCmux,
 } from "../../cmux/index.ts";
 import { autoEnableCmuxPreferences } from "../commands-cmux.ts";
-import type { GSDState } from "../types.ts";
+import type { CmuxStateInput } from "../../shared/cmux-events.ts";
 
 test("detectCmuxEnvironment requires workspace, surface, and socket", () => {
   const detected = detectCmuxEnvironment(
@@ -146,15 +146,11 @@ describe("autoEnableCmuxPreferences", () => {
 });
 
 test("buildCmuxStatusLabel and progress prefer deepest active unit", () => {
-  const state: GSDState = {
-    activeMilestone: { id: "M001", title: "Milestone" },
-    activeSlice: { id: "S02", title: "Slice" },
-    activeTask: { id: "T03", title: "Task" },
+  const state: CmuxStateInput = {
+    activeMilestone: { id: "M001" },
+    activeSlice: { id: "S02" },
+    activeTask: { id: "T03" },
     phase: "executing",
-    recentDecisions: [],
-    blockers: [],
-    nextAction: "Keep going",
-    registry: [],
     progress: {
       milestones: { done: 0, total: 1 },
       slices: { done: 1, total: 3 },

package/src/resources/extensions/gsd/tests/commands-extract-learnings.test.ts

@@ -245,7 +245,7 @@ describe("buildExtractLearningsPrompt", () => {
     assert.ok(result.includes("M001-VERIFICATION.md"));
   });
 
-  it("does NOT reference phantom capture_thought tool (regression for #4429)", () => {
+  it("references capture_thought as the memory-store mirror write (Option A' dual-write)", () => {
     const result = buildExtractLearningsPrompt({
       milestoneId: "M001",
       milestoneName: "Test Milestone",
@@ -260,8 +260,8 @@ describe("buildExtractLearningsPrompt", () => {
     });
 
     assert.ok(
-      !result.includes("capture_thought"),
-      "prompt must not advertise the non-existent capture_thought tool",
+      result.includes("capture_thought"),
+      "prompt must instruct the LLM to mirror durable insights into the memory store via capture_thought",
     );
   });
 
@@ -452,84 +452,84 @@ describe("buildExtractionStepsBlock", () => {
     assert.ok(block.includes("M042-ROADMAP.md"));
   });
 
-  it("points the LLM at .gsd/KNOWLEDGE.md for append", () => {
+  // ─── Removed by ADR-013 step 6 cutover ────────────────────────────────────
+  //
+  // The following nine tests asserted structural properties of the legacy
+  // KNOWLEDGE.md table scaffolding (Rules/Patterns/Lessons headers, P###/L###
+  // row templates, em-dash placeholders, append-only semantics, "missing file"
+  // template) and the gsd_save_decision call-out (parameter list, "never edit
+  // DECISIONS.md" prohibition). The cutover replaced both surfaces with
+  // capture_thought calls into the memories table; the extraction steps no
+  // longer reference KNOWLEDGE.md tables or gsd_save_decision at all, so each
+  // assertion is now structurally false.
+  //
+  // The replacement assertions ("removes the legacy KNOWLEDGE.md table append
+  // step", "removes the gsd_save_decision call", "requires structuredFields
+  // payload on architecture-category memories") below cover the inverse
+  // contract.
+  //
+  // Per ADR-013 cutover criterion: "No regression test in tests/ is silenced
+  // or removed without an explicit rationale comment in the diff." That
+  // criterion is satisfied by this comment block.
+
+  it("keeps Surprises milestone-local (not persisted to memory store, no MCP call)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes(".gsd/KNOWLEDGE.md"));
-  });
-
-  it("covers the missing-file case with the canonical KNOWLEDGE.md template", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("If the file does not exist yet, create it first"));
-    // Canonical column headers must be inlined so the LLM does not have to guess.
-    assert.ok(block.includes("| # | Scope | Rule | Why | Added |"));
-    assert.ok(block.includes("| # | Pattern | Where | Notes |"));
-    assert.ok(block.includes("| # | What Happened | Root Cause | Fix | Scope |"));
-  });
-
-  it("specifies the exact Patterns row format with milestone scope", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("| P<NNN>"));
-    assert.ok(block.includes(`| ${ctx.milestoneId} |`));
-  });
-
-  it("specifies the exact Lessons row format with milestone scope", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("| L<NNN>"));
-  });
-
-  it("enforces zero-padded three-digit IDs", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/zero[- ]pad/i.test(block));
-    assert.ok(block.includes("three digits") || block.includes("3 digits"));
-  });
-
-  it("instructs append-only behaviour (no edits to existing rows)", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("Append-only"));
-  });
-
-  it("uses em-dash as the placeholder for unknown column values", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("—"));
-    assert.ok(!block.includes("N/A"));
-  });
-
-  it("forbids modifications to the Rules table", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/do not.*rules/i.test(block.toLowerCase()) || block.includes("Do NOT modify"));
-    assert.ok(block.includes("## Rules"));
+    assert.ok(block.includes("Surprises stay only in LEARNINGS.md"));
   });
 
-  it("routes Decisions through the gsd_save_decision MCP tool", () => {
+  it("enforces a deduplication rule across all persistence steps", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("gsd_save_decision"));
-    assert.ok(block.includes("`scope`"));
-    assert.ok(block.includes("`decision`"));
-    assert.ok(block.includes("`choice`"));
-    assert.ok(block.includes("`rationale`"));
-    assert.ok(block.includes("`made_by`"));
+    assert.ok(/deduplication/i.test(block) || /dedup/i.test(block));
+    assert.ok(/semantically equivalent/i.test(block));
+    assert.ok(/skip/i.test(block));
   });
 
-  it("forbids direct edits to DECISIONS.md (DB-authoritative)", () => {
+  it("instructs capture_thought as the sole persistence path for Patterns, Lessons, and Decisions (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/never edit.+decisions\.md/i.test(block));
+    // Each of the three persistence steps must call capture_thought.
+    const captureThoughtMatches = block.match(/capture_thought/g) ?? [];
+    assert.ok(
+      captureThoughtMatches.length >= 3,
+      `expected at least 3 capture_thought references (Patterns + Lessons + Decisions); got ${captureThoughtMatches.length}`,
+    );
+    // Required category vocabulary for the three captures.
+    assert.ok(/category:\s*"pattern"/.test(block), "Patterns must use category: \"pattern\"");
+    assert.ok(/category:\s*"gotcha"/.test(block), "Lessons must reference category: \"gotcha\"");
+    assert.ok(/category:\s*"architecture"/.test(block), "Decisions must use category: \"architecture\"");
+    // Milestone scope must be threaded through.
+    assert.ok(block.includes(`scope: "${ctx.milestoneId}"`), "capture_thought calls must scope to the milestone ID");
   });
 
-  it("keeps Surprises milestone-local (not in KNOWLEDGE.md, no tool call)", () => {
+  it("removes the legacy KNOWLEDGE.md table append step (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("Surprises stay only in LEARNINGS.md"));
+    // ADR-013 Cutover: memories table is the single source of truth.
+    // KNOWLEDGE.md is no longer written by the extraction flow.
+    assert.ok(!block.includes("| # | Scope | Rule | Why | Added |"), "Rules table scaffolding must be removed");
+    assert.ok(!block.includes("| # | Pattern | Where | Notes |"), "Patterns table scaffolding must be removed");
+    assert.ok(!block.includes("| # | What Happened | Root Cause | Fix | Scope |"), "Lessons table scaffolding must be removed");
+    assert.ok(!/\| P<NNN>/.test(block), "Pattern row template must be removed");
+    assert.ok(!/\| L<NNN>/.test(block), "Lesson row template must be removed");
+    assert.ok(!block.includes(".gsd/KNOWLEDGE.md"), "extraction flow must not reference KNOWLEDGE.md as a write target");
   });
 
-  it("enforces a deduplication rule across all persistence steps", () => {
+  it("removes the gsd_save_decision call (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/deduplication/i.test(block) || /dedup/i.test(block));
-    assert.ok(/semantically equivalent/i.test(block));
-    assert.ok(/skip/i.test(block));
+    // ADR-013 Cutover: decisions are now persisted via capture_thought with
+    // category=architecture and a structuredFields payload that preserves the
+    // gsd_save_decision schema. The legacy MCP tool is no longer called from
+    // the extraction flow.
+    assert.ok(!block.includes("gsd_save_decision"), "gsd_save_decision must no longer appear in extraction steps");
   });
 
-  it("does NOT reference the non-existent capture_thought tool (#4429 regression)", () => {
+  it("requires structuredFields payload on architecture-category memories (ADR-013 lossless projection)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(!block.includes("capture_thought"));
+    // ADR-013 Cutover: architecture-category memories must carry structured
+    // fields so projection back to a human-visible decisions register stays
+    // lossless. The Decisions persistence step must instruct the LLM to set
+    // structuredFields with the original gsd_save_decision schema fields.
+    assert.ok(/structuredFields/.test(block), "Decisions persistence step must instruct structuredFields use");
+    assert.ok(/scope/i.test(block) && /decision/i.test(block) && /choice/i.test(block) && /rationale/i.test(block),
+      "structuredFields must enumerate the preserved decision fields");
   });
 
   it("does NOT reference the non-existent gsd_graph tool (#4429 regression)", () => {
@@ -614,7 +614,9 @@ describe("complete-milestone loadPrompt round-trip (#4429)", () => {
     // Placeholder must be gone — real content must be in.
     assert.ok(!rendered.includes("{{extractLearningsSteps}}"));
     assert.ok(rendered.includes("Structured Learnings Extraction"));
-    assert.ok(rendered.includes("gsd_save_decision"));
+    // ADR-013 cutover: gsd_save_decision is no longer in the rendered block;
+    // the new persistence path is capture_thought with structuredFields.
+    assert.ok(rendered.includes("capture_thought"));
     assert.ok(rendered.includes("M123"));
   });
 });

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -0,0 +1,123 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  buildSnapshot,
+  readCompactionSnapshot,
+  writeCompactionSnapshot,
+  DEFAULT_SNAPSHOT_BYTES,
+} from '../compaction-snapshot.ts';
+import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { createMemory } from '../memory-store.ts';
+import { executeResume } from '../tools/resume-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-snap-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+test('buildSnapshot: renders memories, exec history, and active context', () => {
+  const snap = buildSnapshot({
+    generatedAt: new Date('2026-04-20T12:00:00.000Z'),
+    activeContext: 'M001 / S01 / T01 — wire gsd_exec',
+    memories: [
+      { id: 'MEM001', category: 'gotcha', content: 'FTS5 needs Porter tokenizer', confidence: 0.9,
+        source_unit_type: null, source_unit_id: null, created_at: '', updated_at: '',
+        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null },
+    ],
+    execHistory: [
+      {
+        id: 'abc',
+        runtime: 'bash',
+        purpose: 'count TODOs',
+        started_at: '', finished_at: '', duration_ms: 10,
+        exit_code: 0, signal: null, timed_out: false,
+        stdout_bytes: 1, stderr_bytes: 0, stdout_truncated: false, stderr_truncated: false,
+        stdout_path: '/tmp/abc.stdout', stderr_path: '/tmp/abc.stderr', meta_path: '/tmp/abc.meta.json',
+      },
+    ],
+  });
+  assert.match(snap, /Active context/);
+  assert.match(snap, /M001 \/ S01 \/ T01/);
+  assert.match(snap, /FTS5 needs Porter tokenizer/);
+  assert.match(snap, /\[abc\] bash exit:0 — count TODOs/);
+});
+
+test('buildSnapshot: enforces the byte cap with a truncation marker', () => {
+  const longMemories = Array.from({ length: 50 }, (_v, i) => ({
+    id: `MEM${String(i).padStart(3, '0')}`,
+    category: 'gotcha',
+    content: 'x'.repeat(200),
+    confidence: 0.8,
+    source_unit_type: null,
+    source_unit_id: null,
+    created_at: '',
+    updated_at: '',
+    superseded_by: null,
+    hit_count: 0,
+    scope: 'project',
+    seq: i,
+    tags: [] as string[],
+    structured_fields: null,
+  }));
+  const snap = buildSnapshot(
+    { generatedAt: new Date(), memories: longMemories, execHistory: [] },
+    { maxBytes: 512, maxMemories: 50 },
+  );
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= 512, 'should respect cap');
+  assert.match(snap, /\[truncated\]/, 'should include truncation marker');
+});
+
+test('buildSnapshot: handles empty state with an explanatory placeholder', () => {
+  const snap = buildSnapshot({ generatedAt: new Date(), memories: [], execHistory: [] });
+  assert.match(snap, /_No durable memories/);
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= DEFAULT_SNAPSHOT_BYTES);
+});
+
+test('writeCompactionSnapshot + readCompactionSnapshot + executeResume: end-to-end', () => {
+  const base = freshBase();
+  try {
+    openDatabase(':memory:');
+    createMemory({ category: 'architecture', content: 'Single-writer DB through gsd-db.ts', confidence: 0.95 });
+    createMemory({ category: 'convention', content: 'Prefer typed helpers over raw SQL', confidence: 0.9 });
+
+    const out = writeCompactionSnapshot(base, { activeContext: 'M099 resume check' });
+    assert.ok(out.path.endsWith('last-snapshot.md'));
+    assert.ok(out.bytes > 0);
+    assert.equal(out.memories, 2);
+
+    const contents = readCompactionSnapshot(base);
+    assert.ok(contents);
+    assert.match(contents!, /Single-writer DB through gsd-db\.ts/);
+    assert.match(contents!, /M099 resume check/);
+
+    const tool = executeResume({}, { baseDir: base });
+    assert.ok(!tool.isError);
+    assert.equal(tool.details.found, true);
+    assert.match(tool.content[0].text, /Single-writer DB through gsd-db\.ts/);
+
+    // also verify the file content matches (without trailing newline)
+    const raw = readFileSync(out.path, 'utf-8');
+    assert.ok(raw.endsWith('\n'));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test('executeResume: reports friendly empty state when no snapshot exists', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base });
+    assert.equal(result.details.found, false);
+    assert.match(result.content[0].text, /No snapshot found/);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/complete-milestone-false-merge.test.ts

@@ -105,6 +105,21 @@ test("#4175: postUnitPreVerification pauses complete-milestone after retries exh
   );
 });
 
+test("#4658: postUnitPreVerification waits briefly for DB-close on complete-milestone before retrying", () => {
+  assert.ok(
+    /async function waitForMilestoneDbClose/.test(postUnitSrc),
+    "auto-post-unit should define a DB settle helper for complete-milestone",
+  );
+  assert.ok(
+    /setTimeout\(resolve,\s*COMPLETE_MILESTONE_DB_SETTLE_POLL_MS\)/.test(postUnitSrc),
+    "DB settle helper should poll with a bounded timeout window",
+  );
+  assert.ok(
+    /s\.currentUnit\.type\s*===\s*"complete-milestone"[\s\S]*waitForMilestoneDbClose/.test(postUnitSrc),
+    "complete-milestone path should invoke DB settle check before retry flow",
+  );
+});
+
 test("#4175: recoverTimedOutUnit pauses complete-milestone instead of writing a blocker placeholder", () => {
   // The complete-milestone pause branch must sit immediately above the
   // "retries exhausted" writeBlockerPlaceholder call so a failed

package/src/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -1,11 +1,14 @@
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { invalidateAllCaches } from '../cache.ts';
 import { parseUnitId } from "../unit-id.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { clearPathCache } from "../paths.ts";
+import { clearParseCache } from "../files.ts";
 
 // loadPrompt reads from ~/.gsd/agent/extensions/gsd/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
@@ -404,6 +407,63 @@ describe("complete-milestone", () => {
     }
   });
 
+  test("handleCompleteMilestone does not overwrite existing SUMMARY.md on re-dispatch (#4598)", async () => {
+    // This test verifies that when SUMMARY.md already exists (from a prior completion),
+    // re-calling handleCompleteMilestone does not overwrite it.
+    // Before the fix this test FAILS because the handler unconditionally writes SUMMARY.md.
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    const mid = "M001";
+    const dbPath = join(base, ".gsd", "gsd.db");
+    try {
+      // Set up DB with milestone and a complete slice + task
+      openDatabase(dbPath);
+      insertMilestone({ id: mid, title: "Test Milestone", status: "active" });
+      insertSlice({ id: "S01", milestoneId: mid, title: "Slice One", status: "complete" });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: mid, title: "Task One", status: "complete" });
+
+      // Pre-write an existing SUMMARY.md to simulate a prior completion
+      const milestoneDir = join(base, ".gsd", "milestones", mid);
+      mkdirSync(milestoneDir, { recursive: true });
+      const summaryPath = join(milestoneDir, `${mid}-SUMMARY.md`);
+      const originalContent = "original content — must not be overwritten";
+      writeFileSync(summaryPath, originalContent, "utf-8");
+
+      // Call handleCompleteMilestone — this is the re-dispatch scenario
+      const params = {
+        milestoneId: mid,
+        title: "Test Milestone",
+        oneLiner: "Re-dispatched",
+        narrative: "This is a re-dispatch",
+        successCriteriaResults: "Met",
+        definitionOfDoneResults: "Done",
+        requirementOutcomes: "Covered",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        verificationPassed: true,
+      };
+
+      const result = await handleCompleteMilestone(params, base);
+
+      // The call may return an error (milestone already complete) or success
+      // but in either case the SUMMARY.md must NOT be overwritten.
+      const actualContent = readFileSync(summaryPath, "utf-8");
+      assert.strictEqual(
+        actualContent,
+        originalContent,
+        "existing SUMMARY.md must not be overwritten on re-dispatch (#4598)",
+      );
+    } finally {
+      try { closeDatabase(); } catch { /* */ }
+      clearPathCache();
+      clearParseCache();
+      cleanup(base);
+    }
+  });
+
   test("deriveState completing-milestone integration", async () => {
     const { deriveState, isMilestoneComplete } = await import("../state.ts");
     const { invalidateAllCaches: invalidateAllCachesDynamic } = await import("../cache.ts");

package/src/resources/extensions/gsd/tests/complete-slice.test.ts

@@ -125,9 +125,9 @@ console.log('\n=== complete-slice: schema v6 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v20 — memory system Phase 4 relations)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 20, 'schema version should be 20');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify slices table has full_summary_md and full_uat_md columns
   const cols = adapter.prepare("PRAGMA table_info(slices)").all();

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -109,9 +109,9 @@ console.log('\n=== complete-task: schema v5 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v20 — memory system Phase 4 relations)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 20, 'schema version should be 20');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify all 4 new tables exist
   const tables = adapter.prepare(

package/src/resources/extensions/gsd/tests/complexity-classifier.test.ts

@@ -21,9 +21,9 @@ test("tierOrdinal returns correct ordering", () => {
 
 // ─── Unit Type Classification ────────────────────────────────────────────────
 
-test("complete-slice classifies as light", () => {
+test("complete-slice classifies as standard", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake");
-  assert.equal(result.tier, "light");
+  assert.equal(result.tier, "standard");
 });
 
 test("run-uat classifies as light", () => {
@@ -145,7 +145,7 @@ test("budget pressure at 90% downgrades standard to light", () => {
   assert.equal(result.downgraded, true);
 });
 
-test("budget pressure at 90% downgrades light stays light", () => {
+test("budget pressure at 90% downgrades complete-slice standard to light", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake", 0.95);
   assert.equal(result.tier, "light");
 });

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -179,6 +179,8 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
+    preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
+    postflightPopStash: () => {},
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,
@@ -479,6 +481,165 @@ describe("Custom engine loop integration", () => {
     );
   });
 
+  it("stops custom workflow after repeated verification retries", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([makeStep({ id: "retry-step" })], "retry-exhaustion");
+    writeGraph(runDir, graph);
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify({
+      version: 1,
+      name: "retry-exhaustion",
+      steps: [{
+        id: "retry-step",
+        name: "retry-step",
+        prompt: "Do retry-step",
+        produces: "retry-step/output.md",
+        verify: { policy: "shell-command", command: "exit 1" },
+      }],
+    }));
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+    });
+
+    const resolver = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+    }, 25);
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx, pi, s, deps),
+        new Promise((_, reject) =>
+          timeout = setTimeout(() => {
+            s.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `autoLoop did not stop after verification retry exhaustion; calls=${pi.calls.length}; log=${deps.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver);
+      if (timeout) clearTimeout(timeout);
+    }
+
+    assert.equal(pi.calls.length, 4, "verification retry should be capped after four dispatched attempts");
+    const stopEntry = deps.callLog.find((e: string) => e.startsWith("stopAuto:"));
+    assert.match(stopEntry ?? "", /requested retry 4 times without passing/);
+    const finalGraph = readGraph(runDir);
+    assert.equal(finalGraph.steps[0]?.status, "active", "failed verification must not reconcile the step complete");
+  });
+
+  it("persists custom verification retry budget across a session restart", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([makeStep({ id: "retry-step" })], "retry-restart");
+    writeGraph(runDir, graph);
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify({
+      version: 1,
+      name: "retry-restart",
+      steps: [{
+        id: "retry-step",
+        name: "retry-step",
+        prompt: "Do retry-step",
+        produces: "retry-step/output.md",
+        verify: { policy: "shell-command", command: "exit 1" },
+      }],
+    }));
+
+    const ctx1 = makeMockCtx();
+    const pi1 = makeMockPi();
+    const s1 = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps1 = makeMockDeps();
+    const resolver1 = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+      if (pi1.calls.length >= 2) {
+        s1.active = false;
+      }
+    }, 25);
+    let timeout1: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx1, pi1, s1, deps1),
+        new Promise((_, reject) =>
+          timeout1 = setTimeout(() => {
+            s1.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `first autoLoop did not pause after two retry attempts; calls=${pi1.calls.length}; log=${deps1.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver1);
+      if (timeout1) clearTimeout(timeout1);
+    }
+    assert.equal(pi1.calls.length, 2, "first session should consume two retry attempts");
+    assert.equal(
+      deps1.callLog.some((e: string) => e.startsWith("stopAuto:")),
+      false,
+      "first session should stop because the session deactivated, not because retry budget exhausted",
+    );
+
+    _resetPendingResolve();
+    const ctx2 = makeMockCtx();
+    const pi2 = makeMockPi();
+    const s2 = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps2 = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps2.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s2.active = false;
+      },
+    });
+    const resolver2 = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+    }, 25);
+    let timeout2: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx2, pi2, s2, deps2),
+        new Promise((_, reject) =>
+          timeout2 = setTimeout(() => {
+            s2.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `second autoLoop did not stop after persisted retry exhaustion; calls=${pi2.calls.length}; log=${deps2.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver2);
+      if (timeout2) clearTimeout(timeout2);
+    }
+
+    assert.equal(pi2.calls.length, 2, "second session should exhaust after attempts 3 and 4");
+    const stopEntry = deps2.callLog.find((e: string) => e.startsWith("stopAuto:"));
+    assert.match(stopEntry ?? "", /requested retry 4 times without passing/);
+  });
+
   it("GRAPH.yaml step stays pending when session deactivates before reconcile", async () => {
     _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/db-access-guardrails.test.ts

@@ -50,6 +50,7 @@ test("doctor-heal.md contains DB access guardrail naming gsd_milestone_status",
   const prompt = readPrompt("doctor-heal");
   assert.match(prompt, /gsd_milestone_status/, "doctor-heal.md must name gsd_milestone_status as the DB inspection tool");
   assert.match(prompt, /Do NOT query.*\.gsd\/gsd\.db/i, "doctor-heal.md must prohibit direct DB queries");
+  assert.doesNotMatch(prompt, /\{\{milestoneId\}\}/, "doctor-heal.md must not declare unprovided milestoneId template variables");
 });
 
 test("forensics.md contains DB inspection guardrail", () => {