@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/tests/read-uat-gate-verdict.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Behavioural regression test for the milestone-closeout UAT gate —
+ * `readUatGateVerdict`.
+ *
+ * The gate (ADR-017: DB-authoritative UAT sign-off) reads a slice's UAT
+ * verdict from its ASSESSMENT artifact via the *canonical* expected path
+ * (`resolveSliceFile` + a path-keyed `getAssessment`). When a milestone
+ * artifact-layout migration orphans the ASSESSMENT markdown from that canonical
+ * path (e.g. `phases/…` → `milestones/…`), the gate used to return `null` and
+ * block milestone closure with "missing UAT PASS verdict" — even though the
+ * verdict was correctly recorded in the `assessments` table by
+ * `gsd_uat_result_save`.
+ *
+ * The DB fallback added to `readUatGateVerdict` consults the authoritative
+ * `assessments` table by (milestoneId, sliceId, scope='run-uat') identity,
+ * independent of path. These tests pin that behaviour.
+ */
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertAssessment,
+} from '../gsd-db.ts';
+import { readUatGateVerdict } from '../auto-dispatch.ts';
+
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-uat-gate-'));
+  return path.join(dir, 'test.db');
+}
+
+function cleanupDb(dbPath: string): void {
+  closeDatabase();
+  try { fs.rmSync(path.dirname(dbPath), { recursive: true, force: true }); } catch { /* */ }
+}
+
+const MID = 'M001';
+const SLICE = 'S01';
+
+/** Canonical on-disk ASSESSMENT path produced by `resolveSliceFile`. */
+function canonicalAssessmentPath(basePath: string): string {
+  return path.join(basePath, '.gsd', 'milestones', MID, 'slices', SLICE, `${SLICE}-ASSESSMENT.md`);
+}
+
+/** An ASSESSMENT body that declares a runtime-executable UAT type and a PASS verdict. */
+const RUNTIME_PASS_BODY = [
+  '---',
+  'verdict: pass',
+  '---',
+  '',
+  '# S01 UAT Assessment',
+  '',
+  '## UAT Type',
+  '- UAT mode: runtime-executable',
+  '',
+  '## Result',
+  'All checks passed.',
+].join('\n');
+
+describe('readUatGateVerdict — DB fallback for orphaned ASSESSMENT', () => {
+  let dbPath: string;
+  let basePath: string;
+
+  beforeEach(() => {
+    dbPath = tempDbPath();
+    openDatabase(dbPath);
+    basePath = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-uat-gate-proj-'));
+    insertMilestone({ id: MID });
+    insertSlice({ id: SLICE, milestoneId: MID });
+  });
+
+  afterEach(() => {
+    cleanupDb(dbPath);
+    try { fs.rmSync(basePath, { recursive: true, force: true }); } catch { /* */ }
+  });
+
+  test('returns pass when the ASSESSMENT is keyed by a legacy/orphaned path (the bug)', async () => {
+    // Reproduces milestone 15: `gsd_uat_result_save` wrote S01's assessment row
+    // under a now-migrated path; the canonical file never existed on disk and
+    // the `assessments.path` is not what `resolveSliceFile` computes.
+    insertAssessment({
+      // Deliberately non-canonical — a legacy `phases/…` path.
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result, 'expected the DB fallback to resolve a verdict, got null');
+    assert.equal(result!.verdict, 'pass');
+  });
+
+  test('the DB fallback derives uatType from the assessment body when no file exists', async () => {
+    insertAssessment({
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'pass');
+    assert.equal(result!.uatType, 'runtime-executable');
+  });
+
+  test('canonical ASSESSMENT file on disk still resolves (regression guard)', async () => {
+    // When the file is present at the canonical path, the existing path-keyed
+    // lookup must resolve it without needing the fallback.
+    const file = canonicalAssessmentPath(basePath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, RUNTIME_PASS_BODY);
+    // Also seed the path-keyed assessments row, mirroring a normal save.
+    insertAssessment({
+      path: `.gsd/milestones/${MID}/slices/${SLICE}/${SLICE}-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'pass');
+    assert.equal(result!.uatType, 'runtime-executable');
+  });
+
+  test('a roadmap-scoped assessment does NOT satisfy the UAT gate', async () => {
+    // `reassess-roadmap` writes roadmap-scoped assessments to the same
+    // S##-ASSESSMENT path; those must never be treated as a UAT verdict. The
+    // legacy-path fallback queries scope='run-uat', so a roadmap-only row is
+    // invisible and the gate returns null.
+    insertAssessment({
+      path: `.gsd/milestones/${MID}/slices/${SLICE}/${SLICE}-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'roadmap',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.equal(result, null, 'roadmap-scoped assessments must not satisfy the UAT gate');
+  });
+
+  test('returns null when no assessment and no file exist (fallback does not hallucinate)', async () => {
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+    assert.equal(result, null);
+  });
+
+  test('surfaces a recorded non-pass verdict via the DB fallback', async () => {
+    // A failing verdict stored under a legacy path must surface (not be masked
+    // as "missing") so the gate's non-PASS branch can act on it.
+    insertAssessment({
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'fail',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY.replace('verdict: pass', 'verdict: fail'),
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'fail');
+  });
+});

package/src/resources/extensions/gsd/tests/ready-phrase-no-files-4573.test.ts

@@ -58,7 +58,14 @@ function mkPi(cap: MockCapture, opts: { sendThrows?: boolean } = {}): any {
 
 function mkBase(): string {
   const base = mkdtempSync(join(tmpdir(), "gsd-4573-"));
-  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  const mDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(mDir, { recursive: true });
+  // Seed one content file so the dir is recognised as a content-bearing legacy
+  // milestone by dirIsContentBearingLegacyMilestone. Tests that check for
+  // "no CONTEXT/ROADMAP yet" still work because RESEARCH is not checked by
+  // maybeHandleReadyPhraseWithoutFiles; the stale-cache tests then verify that
+  // a file written to the same dir is NOT found until clearPathCache runs.
+  writeFileSync(join(mDir, "M001-RESEARCH.md"), "# M001 research\n");
   return base;
 }
 
@@ -181,32 +188,32 @@ describe("#4573 maybeHandleReadyPhraseWithoutFiles", () => {
 
   test("stale path cache from a prior listing → fresh writes are detected (regression)", () => {
     // Repro the live binary failure where:
-    //   1. paths.ts cached dir listings were populated when M001/ was empty
-    //      (or the milestone dir didn't yet exist).
+    //   1. paths.ts cached dir listings were populated before M001-CONTEXT.md
+    //      and M001-ROADMAP.md existed (the dir had only M001-RESEARCH.md).
     //   2. The LLM then wrote M001-CONTEXT.md and M001-ROADMAP.md via the
     //      standard Write tool — which has no awareness of paths.ts caches.
     //   3. maybeHandleReadyPhraseWithoutFiles called resolveMilestoneFile,
-    //      which read the stale cache and reported the artifacts missing,
+    //      which read the stale dirListCache and reported the artifacts missing,
     //      firing a false rejection nudge until MAX_READY_REJECTS aborted
     //      the auto-start with `LLM signaled "ready" 3 times without
     //      writing files`.
     //
     // The fix busts the path cache at the top of the validator before
     // re-resolving. This test fails pre-fix (handled === true) because the
-    // cache returns the empty listing it captured in step (a).
+    // dirListCache still holds the stale per-file listing for M001/ from
+    // step (a), so resolveFile cannot see the newly written CONTEXT/ROADMAP.
     const base = mkBase();
     try {
       const mDir = join(base, ".gsd", "milestones", "M001");
 
-      // (a) Prime the cache with a listing that DOES NOT include M001's
-      //     CONTEXT/ROADMAP files. mkBase() has already created the M001
-      //     directory but nothing inside it yet — so this readdir caches an
-      //     empty entry list keyed by the M001 dir path.
+      // (a) Prime the dirListCache for M001/ with only M001-RESEARCH.md.
+      //     mkBase() already created M001-RESEARCH.md; this first resolver
+      //     call caches that listing so CONTEXT/ROADMAP are unknown to it.
       clearPathCache();
       assert.equal(
         resolveMilestoneFile(base, "M001", "CONTEXT"),
         null,
-        "precondition: resolver must report missing before files are written",
+        "precondition: resolver must report CONTEXT missing before files are written",
       );
 
       // (b) Write the artifacts directly to disk (simulates the LLM Write
@@ -215,12 +222,14 @@ describe("#4573 maybeHandleReadyPhraseWithoutFiles", () => {
       writeFileSync(join(mDir, "M001-CONTEXT.md"), "# ctx");
       writeFileSync(join(mDir, "M001-ROADMAP.md"), "# roadmap");
 
-      // (c) Sanity: the cache is still stale. Without the fix, the
-      //     validator would still see the empty cached listing.
+      // (c) Sanity: the dirListCache for M001/ is still stale (only
+      //     M001-RESEARCH.md). dirIsContentBearingLegacyMilestone reads fresh
+      //     so resolveMilestonePath finds the dir, but resolveFile still
+      //     misses CONTEXT because cachedReaddir(M001/) is not yet cleared.
       assert.equal(
         resolveMilestoneFile(base, "M001", "CONTEXT"),
         null,
-        "stale cache still reports missing pre-clearPathCache",
+        "stale dirListCache still reports CONTEXT missing pre-clearPathCache",
       );
 
       // (d) Run the validator. With the fix it busts the cache before

package/src/resources/extensions/gsd/tests/reassess-handler.test.ts

@@ -19,9 +19,9 @@ import { handleReassessRoadmap } from '../tools/reassess-roadmap.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-reassess-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01'), { recursive: true });
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02'), { recursive: true });
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S03'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test', 'slices', 'S03'), { recursive: true });
   return base;
 }
 
@@ -162,7 +162,7 @@ test('handleReassessRoadmap succeeds when modifying only pending slices', async
     assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
 
     // Verify assessments row exists in DB
-    const assessmentPath = join('.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-ASSESSMENT.md');
+    const assessmentPath = join('.gsd', 'phases', '01-test', '01-01-ASSESSMENT.md');
     const assessment = getAssessment(assessmentPath);
     assert.ok(assessment, 'assessment row should exist in DB');
     assert.equal(assessment['milestone_id'], 'M001');
@@ -193,13 +193,14 @@ test('handleReassessRoadmap succeeds when modifying only pending slices', async
     assert.equal(s01?.status, 'complete');
 
     // Verify ROADMAP.md re-rendered on disk
-    const roadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    // Flat-phase renderer writes NN-ROADMAP.md (01-ROADMAP.md for M001)
+    const roadmapPath = join(base, '.gsd', 'phases', '01-test', '01-ROADMAP.md');
     assert.ok(existsSync(roadmapPath), 'ROADMAP.md should be rendered to disk');
     const roadmapContent = readFileSync(roadmapPath, 'utf-8');
     assert.ok(roadmapContent.includes('Updated Slice Two'), 'ROADMAP.md should contain updated S02 title');
 
     // Verify ASSESSMENT.md exists on disk
-    const assessmentDiskPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-ASSESSMENT.md');
+    const assessmentDiskPath = join(base, '.gsd', 'phases', '01-test', '01-01-ASSESSMENT.md');
     assert.ok(existsSync(assessmentDiskPath), 'ASSESSMENT.md should be rendered to disk');
     const assessmentContent = readFileSync(assessmentDiskPath, 'utf-8');
     assert.ok(assessmentContent.includes('confirmed'), 'ASSESSMENT.md should contain verdict');
@@ -340,7 +341,7 @@ test('handleReassessRoadmap invalidates stale milestone-validation when roadmap
     insertSlice({ id: 'S04', milestoneId: 'M001', title: 'Slice Four', status: 'complete', demo: 'Demo' });
 
     // Insert milestone-validation assessment with needs-remediation verdict (stale)
-    const validationPath = join('.gsd', 'milestones', 'M001', 'M001-VALIDATION.md');
+    const validationPath = join('.gsd', 'phases', '01-test', 'M001-VALIDATION.md');
     insertAssessment({
       path: validationPath,
       milestoneId: 'M001',
@@ -404,7 +405,7 @@ test('handleReassessRoadmap does NOT invalidate validation when no roadmap struc
     insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Slice Two', status: 'pending', demo: 'Demo' });
 
     // Insert milestone-validation assessment with pass verdict
-    const validationPath = join('.gsd', 'milestones', 'M001', 'M001-VALIDATION.md');
+    const validationPath = join('.gsd', 'phases', '01-test', 'M001-VALIDATION.md');
     insertAssessment({
       path: validationPath,
       milestoneId: 'M001',

package/src/resources/extensions/gsd/tests/register-hooks-depth-verification.test.ts

@@ -19,6 +19,7 @@ import {
   resetWriteGateState,
   setPendingGate,
   shouldBlockContextArtifactSave,
+  shouldBlockContextWrite,
 } from "../bootstrap/write-gate.ts";
 import { classifyCommand } from "../safety/destructive-guard.ts";
 import { toRoundResultResponse } from "../../remote-questions/manager.ts";
@@ -201,9 +202,82 @@ test("register-hooks unlocks milestone depth verification from question id witho
   );
 });
 
+test("register-hooks canonicalizes lower-case milestone ids in depth-verification question ids", async (t) => {
+  const dir = makeTempDir("lowercase-mid");
+  const originalCwd = process.cwd();
+  process.chdir(dir);
+  resetWriteGateState(dir);
+
+  t.after(() => {
+    try {
+      resetWriteGateState(dir);
+    } finally {
+      process.chdir(originalCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<void> | void>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<void> | void) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  const questionId = "depth_verification_m001_confirm";
+  const questions = [
+    {
+      id: questionId,
+      question: "Do you agree?",
+      options: [
+        { label: "Yes, you got it (Recommended)" },
+        { label: "Needs adjustment" },
+      ],
+    },
+  ];
+
+  await armDepthGate(handlers, "ask_user_questions", questions);
+  assert.equal(getPendingGate(), questionId);
+
+  for (const handler of handlers.get("tool_result") ?? []) {
+    await handler({
+      toolName: "ask_user_questions",
+      input: { questions },
+      details: {
+        response: {
+          answers: {
+            [questionId]: { selected: "Yes, you got it (Recommended)" },
+          },
+        },
+      },
+    });
+  }
+
+  assert.equal(getPendingGate(), null, "confirming lower-case m001 gate should clear pending state");
+  assert.deepEqual(
+    loadWriteGateSnapshot(dir).verifiedDepthMilestones,
+    ["M001"],
+    "verified milestone id should be stored canonically",
+  );
+  assert.equal(
+    shouldBlockContextWrite(
+      "write",
+      ".gsd/milestones/M001/M001-CONTEXT.md",
+      null,
+      false,
+      dir,
+    ).block,
+    false,
+    "lower-case question id should unlock the matching upper-case CONTEXT.md path",
+  );
+});
+
 test("register-hooks persists first structured question round for new milestone re-entry", async (t) => {
   const dir = makeTempDir("question-draft");
-  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
   const originalCwd = process.cwd();
   process.chdir(dir);
   resetWriteGateState(dir);
@@ -274,9 +348,10 @@ test("register-hooks persists first structured question round for new milestone
     }, ctx);
   }
 
-  const milestoneDir = join(dir, ".gsd", "milestones", "M004");
-  const draftPath = join(milestoneDir, "M004-CONTEXT-DRAFT.md");
-  const discussionPath = join(milestoneDir, "M004-DISCUSSION.md");
+  // Flat-phase: ensureMilestoneShell creates phases/04-new-milestone-m004/ for M004
+  const milestoneDir = join(dir, ".gsd", "phases", "04-new-milestone-m004");
+  const draftPath = join(milestoneDir, "04-CONTEXT-DRAFT.md");
+  const discussionPath = join(milestoneDir, "04-DISCUSSION.md");
 
   assert.equal(existsSync(draftPath), true, "first answer round should create a resumable context draft");
   assert.equal(existsSync(discussionPath), true, "first answer round should create a discussion log");
@@ -895,6 +970,93 @@ test("register-hooks agent_end does not re-arm deferred gate after workflow MCP
   });
 });
 
+test("register-hooks message_update uses in-memory write-gate snapshot instead of disk reconcile", async (t) => {
+  const dir = makeTempDir("message-update-memory-snapshot");
+  const originalCwd = process.cwd();
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+  process.chdir(dir);
+  process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+  resetWriteGateState(dir);
+  clearPendingAutoStart(dir);
+
+  const gateId = "depth_verification_M012_confirm";
+  const statePath = join(dir, ".gsd", "runtime", "write-gate-state.json");
+
+  t.after(() => {
+    try {
+      resetWriteGateState(dir);
+      clearPendingAutoStart(dir);
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+      }
+      process.chdir(originalCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+
+  const notices: Array<{ text: string; level: string }> = [];
+  const ctx = {
+    cwd: dir,
+    ui: { notify: (text: string, level: string) => notices.push({ text, level }) },
+  } as any;
+
+  registerHooks(pi, []);
+  setPendingAutoStart(dir, {
+    basePath: dir,
+    milestoneId: "M012",
+    ctx,
+    pi: { sendMessage: () => undefined } as any,
+  });
+
+  mkdirSync(join(dir, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(statePath, JSON.stringify({
+    verifiedDepthMilestones: ["M012"],
+    verifiedApprovalGates: [gateId],
+    activeQueuePhase: false,
+    pendingGateId: null,
+  }, null, 2), "utf-8");
+
+  const approvalMessage = {
+    role: "assistant",
+    content: [
+      { type: "text", text: "Here is the milestone plan.\n\nDid I capture the project correctly?" },
+    ],
+  };
+
+  for (const handler of handlers.get("message_update") ?? []) {
+    await handler({ message: approvalMessage }, ctx);
+  }
+
+  assert.equal(
+    notices.some((n) => /discuss-milestone M012 is waiting for your approval - pausing/.test(n.text)),
+    true,
+    "streaming hook must not suppress the pause from a disk-only verification",
+  );
+  assert.equal(
+    shouldBlockContextArtifactSave("CONTEXT", "M012", null, dir).block,
+    true,
+    "streaming hook must not reconcile disk-only verification into the in-memory snapshot",
+  );
+
+  for (const handler of handlers.get("agent_end") ?? []) {
+    await handler({ messages: [] }, ctx);
+  }
+
+  assert.equal(getPendingGate(dir), null, "agent_end still reconciles disk and suppresses durable re-arm");
+});
+
 // ── External-engine post-hoc gate replay (write-gate two-process sync) ──────
 // On claude-code-cli, pi ingests the SDK turn's tool blocks after the workflow
 // MCP child already executed them. The depth gate can therefore arrive at

package/src/resources/extensions/gsd/tests/register-hooks-loop-guard-auto.test.ts

@@ -0,0 +1,103 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { autoSession } from "../auto-runtime-state.ts";
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { resetToolCallLoopGuard } from "../bootstrap/tool-call-loop-guard.ts";
+
+type Handler = (event: any, ctx?: any) => Promise<any> | any;
+
+function makeHookHarness(): {
+  emitToolCall: (toolName: string, input: Record<string, unknown>) => Promise<any>;
+} {
+  const handlers = new Map<string, Handler[]>();
+  const pi = {
+    on(event: string, handler: Handler) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  };
+  const ctx = {
+    cwd: process.cwd(),
+    ui: { notify: () => undefined },
+  };
+  let callId = 0;
+
+  registerHooks(pi as any, []);
+
+  return {
+    async emitToolCall(toolName: string, input: Record<string, unknown>): Promise<any> {
+      callId += 1;
+      const loopGuardHandler = handlers.get("tool_call")?.[0];
+      assert.ok(loopGuardHandler, "loop-guard tool_call handler should be registered");
+      return loopGuardHandler({ toolCallId: `loop-${callId}`, toolName, input }, ctx);
+    },
+  };
+}
+
+test("register-hooks keeps loop-guard block reason interactive outside auto-mode", async (t) => {
+  autoSession.reset();
+  resetToolCallLoopGuard();
+  t.after(() => {
+    autoSession.reset();
+    resetToolCallLoopGuard();
+  });
+
+  const { emitToolCall } = makeHookHarness();
+
+  for (let i = 0; i < 4; i += 1) {
+    await emitToolCall("web_search", { query: "same query" });
+  }
+  const block = await emitToolCall("web_search", { query: "same query" });
+
+  assert.equal(block?.block, true);
+  assert.match(block.reason, /respond to the user in text/);
+  assert.doesNotMatch(block.reason, /auto-mode recovery\/replan path/);
+});
+
+test("register-hooks rewrites loop-guard block reason for auto-mode identical-args blocks", async (t) => {
+  autoSession.reset();
+  resetToolCallLoopGuard();
+  autoSession.active = true;
+  t.after(() => {
+    autoSession.reset();
+    resetToolCallLoopGuard();
+  });
+
+  const { emitToolCall } = makeHookHarness();
+
+  for (let i = 0; i < 4; i += 1) {
+    await emitToolCall("web_search", { query: "same query" });
+  }
+  const block = await emitToolCall("web_search", { query: "same query" });
+
+  assert.equal(block?.block, true);
+  assert.match(block.reason, /Tool loop detected \(identical args\): web_search/);
+  assert.match(block.reason, /Do not re-issue this blocked tool/);
+  assert.match(block.reason, /auto-mode recovery\/replan path/);
+  assert.doesNotMatch(block.reason, /respond to the user in text/);
+});
+
+test("register-hooks rewrites loop-guard block reason for auto-mode per-tool blocks", async (t) => {
+  autoSession.reset();
+  resetToolCallLoopGuard();
+  autoSession.active = true;
+  t.after(() => {
+    autoSession.reset();
+    resetToolCallLoopGuard();
+  });
+
+  const { emitToolCall } = makeHookHarness();
+
+  for (let i = 0; i < 6; i += 1) {
+    await emitToolCall("gsd_complete_milestone", { milestone: `M${i}` });
+  }
+  const block = await emitToolCall("gsd_complete_milestone", { milestone: "M7" });
+
+  assert.equal(block?.block, true);
+  assert.match(block.reason, /Tool loop detected \(repeated tool\): gsd_complete_milestone/);
+  assert.match(block.reason, /Do not re-issue this blocked tool/);
+  assert.match(block.reason, /auto-mode recovery\/replan path/);
+  assert.doesNotMatch(block.reason, /respond to the user in text/);
+});

package/src/resources/extensions/gsd/tests/replan-handler.test.ts

@@ -21,7 +21,7 @@ import { parsePlan } from '../parsers-legacy.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-replan-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'tasks'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
   return base;
 }
 
@@ -230,11 +230,11 @@ test('handleReplanSlice succeeds when modifying only incomplete tasks', async ()
     assert.equal(t01?.status, 'complete');
 
     // Verify rendered PLAN.md exists on disk
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
     assert.ok(existsSync(planPath), 'PLAN.md should be rendered to disk');
 
     // Verify REPLAN.md exists on disk
-    const replanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-REPLAN.md');
+    const replanPath = join(base, '.gsd', 'phases', '01-test', '01-01-REPLAN.md');
     assert.ok(existsSync(replanPath), 'REPLAN.md should be rendered to disk');
     const replanContent = readFileSync(replanPath, 'utf-8');
     assert.ok(replanContent.includes('Blocker Description'), 'REPLAN.md should contain blocker section');
@@ -272,7 +272,7 @@ test('handleReplanSlice cache invalidation: re-parsing PLAN.md reflects mutation
     assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
 
     // Re-parse PLAN.md from disk to verify cache invalidation worked
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
     const content = readFileSync(planPath, 'utf-8');
     const parsed = parsePlan(content);