gsd-pi 2.67.0-dev.1cd1e0f → 2.67.0-dev.2367d7e

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

@@ -7,6 +7,7 @@ import {
   openDatabase,
   closeDatabase,
   isDbAvailable,
+  wasDbOpenAttempted,
   getDbProvider,
   insertDecision,
   getDecisionById,
@@ -346,6 +347,17 @@ describe('gsd-db', () => {
     assert.deepStrictEqual(ar, [], 'getActiveRequirements returns [] when DB closed');
   });
 
+  test('gsd-db: wasDbOpenAttempted tracks openDatabase calls', () => {
+    // wasDbOpenAttempted should return true once openDatabase has been called
+    // (previous tests in this suite already called openDatabase, so the flag is set)
+    assert.ok(wasDbOpenAttempted(), 'wasDbOpenAttempted should be true after openDatabase was called');
+
+    // Verify the flag persists even after closeDatabase
+    closeDatabase();
+    assert.ok(!isDbAvailable(), 'DB should not be available after close');
+    assert.ok(wasDbOpenAttempted(), 'wasDbOpenAttempted should remain true after closeDatabase');
+  });
+
   // ─── Final Report ──────────────────────────────────────────────────────────
 
 });

package/src/resources/extensions/gsd/tests/guided-flow-session-isolation.test.ts

@@ -100,7 +100,7 @@ describe("#2985 Bug 4 — getDiscussionMilestoneId must be keyed by basePath", (
   });
 });
 
-test("checkAutoStartAfterDiscuss fails closed when a multi-milestone manifest is missing", () => {
+test("checkAutoStartAfterDiscuss ignores missing manifest for single-milestone discuss on established project", () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-auto-start-manifest-"));
   try {
     const gsdDir = join(base, ".gsd");
@@ -123,7 +123,7 @@ test("checkAutoStartAfterDiscuss fails closed when a multi-milestone manifest is
     });
 
     const started = checkAutoStartAfterDiscuss();
-    assert.equal(started, false, "auto-start should fail closed without the manifest");
+    assert.equal(started, true, "project history alone should not require a manifest");
   } finally {
     clearPendingAutoStart();
     rmSync(base, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/integration/doctor-fixlevel.test.ts

@@ -15,7 +15,7 @@ import { tmpdir } from "node:os";
 import test from "node:test";
 import assert from "node:assert/strict";
 import { runGSDDoctor } from "../../doctor.ts";
-import { closeDatabase } from "../../gsd-db.ts";
+import { closeDatabase, insertMilestone, insertSlice, openDatabase } from "../../gsd-db.ts";
 
 function makeTmp(name: string): string {
   const dir = join(tmpdir(), `doctor-fixlevel-${name}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
@@ -177,6 +177,57 @@ test("legacy roadmap fallback: future slices are treated as pending, active slic
   );
 });
 
+test("db skipped slices do not report missing directories", async (t) => {
+  const tmp = makeTmp("skipped-slice-dir");
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  const gsd = join(tmp, ".gsd");
+  const m = join(gsd, "milestones", "M001");
+  mkdirSync(m, { recursive: true });
+
+  writeFileSync(join(m, "M001-ROADMAP.md"), `# M001: Test
+
+## Slices
+
+- [ ] **S05: Skipped Slice** \`risk:low\` \`depends:[]\`
+  > Intentionally skipped
+`);
+
+  openDatabase(join(gsd, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S05", milestoneId: "M001", title: "Skipped Slice", status: "skipped", sequence: 5 });
+
+  const report = await runGSDDoctor(tmp, { scope: "M001" });
+  const missingDirIssues = report.issues.filter(
+    i =>
+      (i.code === "missing_slice_dir" || i.code === "missing_tasks_dir") &&
+      i.unitId === "M001/S05",
+  );
+
+  assert.deepStrictEqual(
+    missingDirIssues,
+    [],
+    "skipped slices should not require slice or tasks directories",
+  );
+});
+
+test("doctor source treats skipped DB slices as closed and directory-optional", () => {
+  const doctorSource = readFileSync(join(process.cwd(), "src/resources/extensions/gsd/doctor.ts"), "utf8");
+  assert.match(
+    doctorSource,
+    /done:\s*isClosedStatus\(s\.status\)/,
+    "doctor should normalize skipped DB slices through isClosedStatus()",
+  );
+  assert.match(
+    doctorSource,
+    /if \(slice\.pending \|\| slice\.skipped\) continue;/,
+    "doctor should skip missing-directory checks for skipped slices",
+  );
+});
+
 test("fixLevel:all — delimiter_in_title still fixable", async (t) => {
   const tmp = makeTmp("delimiter-fix");
   t.after(() => rmSync(tmp, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/integration/doctor-git.test.ts

@@ -661,10 +661,9 @@ describe('doctor-git', async () => {
         env: { ...process.env, GIT_COMMITTER_DATE: pastDate },
       });
 
-      // Modify a tracked file and create a new untracked file. The snapshot
-      // must preserve both, not just tracked changes.
+      // Modify an already-tracked file (nativeAddTracked uses git add -u,
+      // which only stages tracked files — new untracked files are not staged)
       writeFileSync(join(dir, "README.md"), "# test\nmodified content\n");
-      writeFileSync(join(dir, "new-untracked.ts"), "export const preserved = true;\n");
 
       const detect = await runGSDDoctor(dir);
       const staleIssues = detect.issues.filter(i => i.code === "stale_uncommitted_changes");
@@ -682,12 +681,6 @@ describe('doctor-git', async () => {
       // Verify the snapshot commit was created with the gsd snapshot tag
       const log = run("git log -1 --oneline", dir);
       assert.ok(log.includes("gsd snapshot"), "commit is tagged with gsd snapshot");
-
-      const files = run("git show --name-only --format= HEAD", dir);
-      assert.ok(files.includes("README.md"), "snapshot keeps tracked modifications");
-      assert.ok(files.includes("new-untracked.ts"), "snapshot also includes new untracked files");
-      const status = run("git status --short", dir);
-      assert.ok(!status.includes("new-untracked.ts"), "snapshot does not leave the new source file untracked");
     });
 
     // ─── Test: stale_uncommitted_changes NOT flagged when recent commit ──

package/src/resources/extensions/gsd/tests/integration/doctor-proactive.test.ts

@@ -219,39 +219,6 @@ describe('doctor-proactive', async () => {
       assert.ok(result.fixesApplied.some((f: string) => f.includes("STATE.md")), "reports STATE.md status as info");
     });
 
-    test('health gate: pre-dispatch snapshot includes new untracked files', async () => {
-      const dir = createRepoWithActiveMilestone();
-      cleanups.push(dir);
-
-      const pastDate = new Date(Date.now() - 45 * 60 * 1000).toISOString();
-      run(`git commit --amend --no-edit --date="${pastDate}"`, dir);
-      execSync(`git commit --amend --no-edit`, {
-        cwd: dir,
-        stdio: ["ignore", "pipe", "pipe"],
-        encoding: "utf-8",
-        env: { ...process.env, GIT_COMMITTER_DATE: pastDate },
-      });
-
-      writeFileSync(join(dir, "README.md"), "# test\nmodified content\n");
-      writeFileSync(join(dir, "new-untracked.ts"), "export const preserved = true;\n");
-
-      const result = await preDispatchHealthGate(dir);
-      assert.ok(result.proceed, "dispatch still proceeds after snapshotting");
-      assert.ok(
-        result.fixesApplied.some((f: string) => f.includes("gsd snapshot")),
-        "pre-dispatch gate creates a snapshot commit",
-      );
-
-      const log = run("git log -1 --oneline", dir);
-      assert.ok(log.includes("gsd snapshot"), "snapshot commit is created");
-
-      const files = run("git show --name-only --format= HEAD", dir);
-      assert.ok(files.includes("README.md"), "snapshot keeps tracked modifications");
-      assert.ok(files.includes("new-untracked.ts"), "snapshot also includes new untracked files");
-      const status = run("git status --short", dir);
-      assert.ok(!status.includes("new-untracked.ts"), "snapshot does not leave the new source file untracked");
-    });
-
     test('health gate: stale crash lock auto-cleared', async () => {
       const dir = realpathSync(mkdtempSync(join(tmpdir(), "doc-proactive-")));
       cleanups.push(dir);

package/src/resources/extensions/gsd/tests/integration/merge-cwd-restore.test.ts

@@ -0,0 +1,169 @@
+/**
+ * GSD-2 — Regression tests for merge cwd restore (#2929)
+ * merge-cwd-restore.test.ts — Regression tests for #2929.
+ *
+ * Verifies:
+ *   1. MergeConflictError restores process.cwd() to the pre-merge directory.
+ *   2. autoCommitDirtyState does not run on the integration branch when cwd
+ *      leaked there from a prior failed merge (parallel mode).
+ *
+ * Bug: PR #2298 added a stash lifecycle around mergeMilestoneToMain but the
+ * MergeConflictError throw path omitted the process.chdir(previousCwd) that
+ * the dirty-working-tree and divergence handlers both include. In parallel
+ * merge sequences, this left cwd on the integration branch, causing the next
+ * merge's autoCommitDirtyState to commit dirty files from OTHER milestones
+ * onto main.
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { mergeMilestoneToMain } from "../../auto-worktree.ts";
+import { MergeConflictError } from "../../git-service.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(
+    mkdtempSync(join(tmpdir(), "merge-cwd-restore-test-")),
+  );
+  run("git init -b main", dir);
+  run("git config user.email test@test.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  writeFileSync(join(dir, ".gitignore"), ".gsd/worktrees/\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  return dir;
+}
+
+function makeRoadmap(mid: string, title: string): string {
+  return [
+    `# ${mid}: Test milestone`,
+    "",
+    "## Slices",
+    "- [x] **S01: Test slice**",
+  ].join("\n");
+}
+
+describe("merge cwd restore (#2929)", () => {
+  let repo: string;
+  let savedCwd: string;
+
+  beforeEach(() => {
+    savedCwd = process.cwd();
+    repo = createTempRepo();
+  });
+
+  afterEach(() => {
+    process.chdir(savedCwd);
+    try { run("git reset --hard HEAD", repo); } catch { /* */ }
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 1: MergeConflictError restores cwd (#2929 bug 2)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  test("MergeConflictError restores cwd to pre-merge directory", () => {
+    // Create milestone branch that modifies README.md
+    run("git checkout -b milestone/M010", repo);
+    writeFileSync(join(repo, "README.md"), "# M010 version\n");
+    run("git add .", repo);
+    run('git commit -m "M010 changes README"', repo);
+    run("git checkout main", repo);
+
+    // Modify README.md on main to create a conflict
+    writeFileSync(join(repo, "README.md"), "# main version (diverged)\n");
+    run("git add .", repo);
+    run('git commit -m "main diverges README"', repo);
+
+    // cwd must be repo root (simulates parallel-merge calling from project root)
+    process.chdir(repo);
+    const cwdBefore = process.cwd();
+
+    let caught: unknown = null;
+    try {
+      mergeMilestoneToMain(repo, "M010", makeRoadmap("M010", "Conflict test"));
+    } catch (err) {
+      caught = err;
+    }
+
+    // Should have thrown a MergeConflictError
+    assert.ok(caught instanceof MergeConflictError, "expected MergeConflictError");
+
+    // Critical: cwd must be restored to where it was before the merge
+    const cwdAfter = process.cwd();
+    assert.equal(
+      cwdAfter,
+      cwdBefore,
+      "cwd should be restored after MergeConflictError — was left on integration branch before fix",
+    );
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 2: autoCommitDirtyState skipped when on integration branch (#2929 bug 1)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  test("autoCommitDirtyState does not commit on integration branch in worktree mode", () => {
+    // Create milestone branch with real work
+    run("git checkout -b milestone/M010", repo);
+    writeFileSync(join(repo, "m010.ts"), "export const m010 = true;\n");
+    run("git add .", repo);
+    run('git commit -m "M010 work"', repo);
+    run("git checkout main", repo);
+
+    // Simulate the parallel-mode state: cwd is on main with dirty files
+    // from another milestone (as if a prior merge's MergeConflictError
+    // left cwd on main and syncStateToProjectRoot wrote these files).
+    writeFileSync(join(repo, "dirty-from-m020.txt"), "should not be committed\n");
+
+    // Set up roadmap so mergeMilestoneToMain can find milestone metadata
+    mkdirSync(join(repo, ".gsd", "milestones", "M010"), { recursive: true });
+    writeFileSync(
+      join(repo, ".gsd", "milestones", "M010", "M010-ROADMAP.md"),
+      makeRoadmap("M010", "First milestone"),
+    );
+
+    process.chdir(repo);
+
+    const result = mergeMilestoneToMain(
+      repo,
+      "M010",
+      makeRoadmap("M010", "First milestone"),
+    );
+
+    assert.ok(result.commitMessage.includes("M010"), "commit should be for M010");
+
+    // Verify the squash merge brought M010's work file
+    const mergeLog = run("git log --oneline --diff-filter=A -- m010.ts", repo);
+    assert.ok(mergeLog.length > 0, "m010.ts should be in a commit on main");
+
+    // The dirty file should NOT appear in the squash merge commit.
+    const squashCommit = run("git log --format=%H --grep='GSD-Milestone: M010' -1", repo);
+    assert.ok(squashCommit.length > 0, "should find the squash merge commit");
+    const filesInSquash = run(`git diff-tree --no-commit-id --name-only -r ${squashCommit}`, repo);
+    assert.ok(
+      !filesInSquash.includes("dirty-from-m020.txt"),
+      "dirty-from-m020.txt should NOT be in the squash merge commit",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/interrupted-session-auto.test.ts

@@ -0,0 +1,146 @@
+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 { assessInterruptedSession } from "../interrupted-session.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-auto-interrupted-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function writeRoadmap(base: string, checked = false): void {
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(join(milestoneDir, "slices", "S01", "tasks"), { recursive: true });
+  writeFileSync(
+    join(milestoneDir, "M001-ROADMAP.md"),
+    [
+      "# M001: Test Milestone",
+      "",
+      "## Vision",
+      "",
+      "Test milestone.",
+      "",
+      "## Success Criteria",
+      "",
+      "- It works.",
+      "",
+      "## Slices",
+      "",
+      `- [${checked ? "x" : " "}] **S01: Test slice** \`risk:low\``,
+      "  After this: Demo",
+      "",
+      "## Boundary Map",
+      "",
+      "- S01 → terminal",
+      "  - Produces: done",
+      "  - Consumes: nothing",
+    ].join("\n"),
+    "utf-8",
+  );
+}
+
+function writeCompleteArtifacts(base: string): void {
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const sliceDir = join(milestoneDir, "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n", "utf-8");
+  writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n", "utf-8");
+  writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\nDone.\n", "utf-8");
+}
+
+function writeLock(base: string, unitType: string, unitId: string): void {
+  writeFileSync(
+    join(base, ".gsd", "auto.lock"),
+    JSON.stringify({
+      pid: 999999999,
+      startedAt: new Date().toISOString(),
+      unitType,
+      unitId,
+      unitStartedAt: new Date().toISOString(),
+    }, null, 2),
+    "utf-8",
+  );
+}
+
+function writePausedSession(base: string, milestoneId = "M001", stepMode = false): void {
+  const runtimeDir = join(base, ".gsd", "runtime");
+  mkdirSync(runtimeDir, { recursive: true });
+  writeFileSync(
+    join(runtimeDir, "paused-session.json"),
+    JSON.stringify({ milestoneId, originalBasePath: base, stepMode }, null, 2),
+    "utf-8",
+  );
+}
+
+test("direct /gsd auto stale complete repo yields stale classification with no recovery payload", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, true);
+    writeCompleteArtifacts(base);
+    writeLock(base, "execute-task", "M001/S01/T01");
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "stale");
+    assert.equal(assessment.recoveryPrompt, null);
+    assert.equal(assessment.hasResumableDiskState, false);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("direct /gsd auto paused-session metadata remains recoverable when work is unfinished", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, false);
+    writePausedSession(base, "M001", false);
+    writeLock(base, "execute-task", "M001/S01/T01");
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "recoverable");
+    assert.equal(assessment.pausedSession?.milestoneId, "M001");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("direct /gsd auto stale paused-session metadata is treated as stale when no resumable work remains", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, true);
+    writeCompleteArtifacts(base);
+    writePausedSession(base, "M999", true);
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "stale");
+    assert.equal(assessment.hasResumableDiskState, false);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("direct /gsd auto source only resumes paused-session metadata for recoverable state with real recovery signals", async () => {
+  const source = await import(`node:fs/promises`).then((fs) =>
+    fs.readFile(new URL("../auto.ts", import.meta.url), "utf-8")
+  );
+  assert.ok(source.includes('const shouldResumePausedSession ='));
+  assert.ok(source.includes('freshStartAssessment.classification === "recoverable"'));
+  assert.ok(source.includes('&& ('));
+  assert.ok(source.includes('freshStartAssessment.hasResumableDiskState'));
+  assert.ok(source.includes('|| !!freshStartAssessment.recoveryPrompt'));
+  assert.ok(source.includes('|| !!freshStartAssessment.lock'));
+});
+
+test("auto module imports successfully after interrupted-session changes", async () => {
+  const mod = await import(`../auto.ts?ts=${Date.now()}-${Math.random()}`);
+  assert.equal(typeof mod.startAuto, "function");
+  assert.equal(typeof mod.pauseAuto, "function");
+});

package/src/resources/extensions/gsd/tests/interrupted-session-ui.test.ts

@@ -0,0 +1,136 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { assessInterruptedSession } from "../interrupted-session.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-smart-entry-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function writeRoadmap(base: string, checked = false): void {
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(join(milestoneDir, "slices", "S01", "tasks"), { recursive: true });
+  writeFileSync(
+    join(milestoneDir, "M001-ROADMAP.md"),
+    [
+      "# M001: Test Milestone",
+      "",
+      "## Vision",
+      "",
+      "Test milestone.",
+      "",
+      "## Success Criteria",
+      "",
+      "- It works.",
+      "",
+      "## Slices",
+      "",
+      `- [${checked ? "x" : " "}] **S01: Test slice** \`risk:low\``,
+      "  After this: Demo",
+      "",
+      "## Boundary Map",
+      "",
+      "- S01 → terminal",
+      "  - Produces: done",
+      "  - Consumes: nothing",
+    ].join("\n"),
+    "utf-8",
+  );
+}
+
+function writeCompleteArtifacts(base: string): void {
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const sliceDir = join(milestoneDir, "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n", "utf-8");
+  writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n", "utf-8");
+  writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\nDone.\n", "utf-8");
+}
+
+function writePausedSession(base: string, milestoneId = "M001", stepMode = false): void {
+  const runtimeDir = join(base, ".gsd", "runtime");
+  mkdirSync(runtimeDir, { recursive: true });
+  writeFileSync(
+    join(runtimeDir, "paused-session.json"),
+    JSON.stringify({ milestoneId, originalBasePath: base, stepMode }, null, 2),
+    "utf-8",
+  );
+}
+
+function writeLock(base: string, unitType: string, unitId: string): void {
+  writeFileSync(
+    join(base, ".gsd", "auto.lock"),
+    JSON.stringify({
+      pid: 999999999,
+      startedAt: new Date().toISOString(),
+      unitType,
+      unitId,
+      unitStartedAt: new Date().toISOString(),
+    }, null, 2),
+    "utf-8",
+  );
+}
+
+test("guided-flow stale complete scenario classifies as stale so the resume prompt can be suppressed", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, true);
+    writeCompleteArtifacts(base);
+    writeLock(base, "execute-task", "M001/S01/T01");
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "stale");
+    assert.equal(assessment.recoveryPrompt, null);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("guided-flow paused-session scenario classifies as recoverable so resume remains available", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, false);
+    writePausedSession(base);
+    writeLock(base, "execute-task", "M001/S01/T01");
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "recoverable");
+    assert.equal(assessment.pausedSession?.milestoneId, "M001");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("guided-flow stale paused-session scenario is suppressed when no resumable work remains", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, true);
+    writeCompleteArtifacts(base);
+    writePausedSession(base, "M999", true);
+
+    const assessment = await assessInterruptedSession(base);
+    assert.equal(assessment.classification, "stale");
+    assert.equal(assessment.hasResumableDiskState, false);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("guided-flow source uses step-aware resume and clears stale paused metadata without changing discuss handoff semantics", () => {
+  const source = readFileSync(join(import.meta.dirname, "..", "guided-flow.ts"), "utf-8");
+  assert.ok(source.includes('const interrupted = await assessInterruptedSession(basePath);'));
+  assert.ok(source.includes('resumeLabel = interrupted.pausedSession?.stepMode'));
+  assert.ok(source.includes('step: interrupted.pausedSession?.stepMode ?? false'));
+  assert.ok(source.includes('unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json"))'));
+  assert.ok(source.includes('pendingAutoStartMap.set(basePath,'));
+});