@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/gsd/tests/flat-phase-validation-path.test.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { relMilestoneFile, resolveMilestoneFile } from "../paths.ts";
+import { normalizeRealPath, relMilestoneFile, relSliceFile, resolveMilestoneFile, targetMilestoneFile } from "../paths.ts";
 
 function makeFlatPhaseFixture(): { basePath: string; cleanup: () => void } {
   const basePath = mkdtempSync(join(tmpdir(), "flat-phase-validation-"));
@@ -33,42 +33,82 @@ function makeFlatPhaseFixture(): { basePath: string; cleanup: () => void } {
   return { basePath, cleanup: () => rmSync(basePath, { recursive: true, force: true }) };
 }
 
-test("flat-phase: relMilestoneFile resolves to the layout-aware path", () => {
+test("flat-phase: relMilestoneFile resolves to the layout-aware path", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    const rel = relMilestoneFile(basePath, "M001", "VALIDATION");
-    assert.equal(rel, ".gsd/phases/01-foo/01-VALIDATION.md");
-    const abs = join(basePath, rel);
-    assert.equal(existsSync(abs), true);
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  const rel = relMilestoneFile(basePath, "M001", "VALIDATION");
+  assert.equal(rel, ".gsd/phases/01-foo/01-VALIDATION.md");
+  const abs = join(basePath, rel);
+  assert.equal(existsSync(abs), true);
+});
+
+test("flat-phase: relMilestoneFile fallback uses the milestone title when no directory exists", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-missing-dir-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+
+  const rel = relMilestoneFile(basePath, "M001", "ROADMAP", "Milestone");
+  assert.equal(rel, ".gsd/phases/01-milestone/01-ROADMAP.md");
 });
 
-test("flat-phase: resolveMilestoneFile finds the on-disk file", () => {
+test("legacy layout: relMilestoneFile fallback stays in milestones when the target dir is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "legacy-missing-dir-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const existingLegacyDir = join(basePath, ".gsd", "milestones", "M002");
+  mkdirSync(existingLegacyDir, { recursive: true });
+  writeFileSync(join(existingLegacyDir, "M002-ROADMAP.md"), "# existing legacy roadmap\n");
+
+  const rel = relMilestoneFile(basePath, "M001", "ROADMAP", "Milestone");
+
+  assert.equal(rel, ".gsd/milestones/M001/M001-ROADMAP.md");
+});
+
+test("legacy layout: relSliceFile fallback uses slices directory when target milestone is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "legacy-missing-slice-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const existingLegacyDir = join(basePath, ".gsd", "milestones", "M002");
+  mkdirSync(existingLegacyDir, { recursive: true });
+  writeFileSync(join(existingLegacyDir, "M002-ROADMAP.md"), "# existing legacy roadmap\n");
+
+  const rel = relSliceFile(basePath, "M001", "S01", "PLAN", "Milestone");
+
+  assert.equal(rel, ".gsd/milestones/M001/slices/S01/S01-PLAN.md");
+});
+
+test("flat-phase: targetMilestoneFile ignores legacy-named compatibility files when writing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-legacy-named-file-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const phaseDir = join(basePath, ".gsd", "phases", "01-foo");
+  mkdirSync(phaseDir, { recursive: true });
+  writeFileSync(join(phaseDir, "M001-ROADMAP.md"), "# legacy named roadmap\n");
+
+  assert.equal(
+    targetMilestoneFile(basePath, "M001", "ROADMAP", "Foo"),
+    join(normalizeRealPath(phaseDir), "01-ROADMAP.md"),
+  );
+  assert.equal(relMilestoneFile(basePath, "M001", "ROADMAP", "Foo"), ".gsd/phases/01-foo/M001-ROADMAP.md");
+});
+
+test("flat-phase: resolveMilestoneFile finds the on-disk file", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    const abs = resolveMilestoneFile(basePath, "M001", "VALIDATION");
-    assert.ok(abs, "resolveMilestoneFile must return a path for the flat-phase fixture");
-    assert.equal(abs!.endsWith("/.gsd/phases/01-foo/01-VALIDATION.md"), true);
-    assert.equal(existsSync(abs!), true);
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  const abs = resolveMilestoneFile(basePath, "M001", "VALIDATION");
+  assert.ok(abs, "resolveMilestoneFile must return a path for the flat-phase fixture");
+  assert.equal(abs!.endsWith("/.gsd/phases/01-foo/01-VALIDATION.md"), true);
+  assert.equal(existsSync(abs!), true);
 });
 
-test("flat-phase: the legacy hardcoded path does NOT resolve (regression for #876)", () => {
+test("flat-phase: the legacy hardcoded path does NOT resolve (regression for #876)", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    // This is the path that auto-verification.ts:264-270 used to construct.
-    // It must NOT exist on a flat-phase project — that's the whole bug.
-    const legacyHardcoded = join(basePath, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
-    assert.equal(
-      existsSync(legacyHardcoded),
-      false,
-      "legacy hardcoded path must not exist in flat-phase fixture — if it does, the test fixture is wrong",
-    );
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  // This is the path that auto-verification.ts:264-270 used to construct.
+  // It must NOT exist on a flat-phase project — that's the whole bug.
+  const legacyHardcoded = join(basePath, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+  assert.equal(
+    existsSync(legacyHardcoded),
+    false,
+    "legacy hardcoded path must not exist in flat-phase fixture — if it does, the test fixture is wrong",
+  );
 });

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

@@ -33,6 +33,10 @@ import {
   getMilestoneSliceSummaries,
   getClosedSliceIds,
   getActiveMilestoneFromDb,
+  getActiveSliceFromDb,
+  getActiveTaskFromDb,
+  getActiveTaskIdFromDb,
+  getSliceTaskCounts,
   deleteMilestone,
   clearEngineHierarchy,
   recordMilestoneCommitAttribution,
@@ -240,6 +244,42 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  test("gsd-db: active readers use the shared closed-status vocabulary", () => {
+    openDatabase(":memory:");
+
+    try {
+      insertMilestone({ id: "M001", title: "Status vocabulary", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Closed dep", status: "closed", sequence: 1 });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Runnable", status: "pending", depends: ["S01"], sequence: 2 });
+      insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", title: "Skipped", status: "skipped", sequence: 1 });
+      insertTask({ id: "T02", sliceId: "S02", milestoneId: "M001", title: "Closed", status: "closed", sequence: 2 });
+      insertTask({ id: "T03", sliceId: "S02", milestoneId: "M001", title: "Pending", status: "pending", sequence: 3 });
+
+      assert.equal(
+        getActiveSliceFromDb("M001")?.id,
+        "S02",
+        "closed dependency slices must satisfy dependencies and be excluded from active slice selection",
+      );
+      assert.equal(
+        getActiveTaskFromDb("M001", "S02")?.id,
+        "T03",
+        "skipped/closed tasks must be excluded from active task selection",
+      );
+      assert.equal(
+        getActiveTaskIdFromDb("M001", "S02")?.id,
+        "T03",
+        "lightweight active task selection must use the same closed-status vocabulary",
+      );
+      assert.deepEqual(
+        getSliceTaskCounts("M001", "S02"),
+        { total: 3, done: 2, pending: 1 },
+        "slice task counts must derive done/pending from the shared closed-status vocabulary",
+      );
+    } finally {
+      closeDatabase();
+    }
+  });
+
   test('gsd-db: active_decisions view excludes superseded', () => {
     openDatabase(':memory:');
 

package/src/resources/extensions/gsd/tests/import-completion-lost-update.test.ts

@@ -0,0 +1,196 @@
+// Project/App: gsd-pi
+// File Purpose: Regression for #1222 — a re-import must not silently downgrade
+// a completed flat-phase task back to pending when its SUMMARY.md attests the
+// completion. gsd_task_complete succeeds and writes TID-SUMMARY.md, but a stale
+// plan checkbox re-imported into the DB would revert the task to pending,
+// hard-stopping auto-mode on its "state did not advance" guard.
+
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, rmSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import { openDatabase, closeDatabase, getAllMilestones, getMilestoneSlices, getSliceTasks, repairTaskCompletionFromSummary } from "../gsd-db.ts";
+import { migrateHierarchyToDb } from "../md-importer.ts";
+import { invalidateStateCache } from "../state.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = join(__dirname, "__fixtures__", "flat-phase");
+// The flat-phase fixture parses to M001/S01/T01 (phase 01, plan 01, task T01).
+const PHASE_DIR = join(".gsd", "phases", "01-foundation");
+const SUMMARY_REL = join(PHASE_DIR, "T01-SUMMARY.md");
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function copyFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-lostupdate-${randomUUID()}`));
+  cpSync(FIXTURE_ROOT, base, { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+function taskStatus(base: string): string | undefined {
+  return t01Row()?.status;
+}
+
+function t01Row() {
+  const ms = getAllMilestones();
+  if (ms.length === 0) return undefined;
+  const slices = getMilestoneSlices(ms[0]!.id);
+  if (slices.length === 0) return undefined;
+  const tasks = getSliceTasks(ms[0]!.id, slices[0]!.id);
+  return tasks.find((t) => t.id === "T01");
+}
+
+function t01Ids() {
+  const ms = getAllMilestones();
+  const slices = getMilestoneSlices(ms[0]!.id);
+  return { milestoneId: ms[0]!.id, sliceId: slices[0]!.id };
+}
+
+test("re-import keeps a flat-phase task complete when its SUMMARY.md is present (#1222)", () => {
+  const base = copyFixture();
+  // The fixture plan leaves T01 unchecked ([ ]). Simulate a completed task: the
+  // durable SUMMARY.md exists even though the plan checkbox is stale-unchecked.
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "complete",
+    "task with SUMMARY.md on disk must import as complete, not revert to pending",
+  );
+});
+
+test("re-import leaves an unchecked flat-phase task pending when no SUMMARY.md exists (#1222)", () => {
+  const base = copyFixture();
+  // No SUMMARY.md — the unchecked checkbox is the authoritative signal.
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "pending",
+    "unchecked task without a SUMMARY.md must stay pending",
+  );
+});
+
+test("re-import keeps a flat-phase task complete even when an auxiliary tasks/ subdir exists (#1222)", () => {
+  const base = copyFixture();
+  // Flat-phase may keep a tasks/ subdir for gate artifacts (e.g. T01-VERIFY.json)
+  // while gsd_task_complete still writes TID-SUMMARY.md at the phase root. The
+  // tasks/ subdir must NOT shadow that real summary and downgrade the task.
+  mkdirSync(join(base, PHASE_DIR, "tasks"), { recursive: true });
+  writeFileSync(join(base, PHASE_DIR, "tasks", "T01-VERIFY.json"), "{}\n");
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "complete",
+    "a phase-root SUMMARY.md must win even when a tasks/ subdir exists (no shadowing)",
+  );
+});
+
+test("re-import preserves execution metadata and completed_at of an attested-complete task (#1222)", () => {
+  const base = copyFixture();
+  // T01 is completed on disk (SUMMARY present) but its plan checkbox is stale-unchecked.
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  // Simulate the row gsd_task_complete leaves behind: real execution prose plus
+  // a completion timestamp from when the task actually finished.
+  const OLD_COMPLETED_AT = "2026-07-01T00:00:00.000Z";
+  const REAL_ONE_LINER = "Implemented the widget frobnicator end-to-end";
+  const REAL_SUMMARY = "# T01 full summary\n\nEverything about how T01 was done.";
+  const REAL_VERIFICATION = "all 12 checks passed";
+  const { milestoneId, sliceId } = t01Ids();
+  repairTaskCompletionFromSummary({
+    milestoneId,
+    sliceId,
+    taskId: "T01",
+    oneLiner: REAL_ONE_LINER,
+    verificationResult: REAL_VERIFICATION,
+    completedAt: OLD_COMPLETED_AT,
+    fullSummaryMd: REAL_SUMMARY,
+  });
+  invalidateStateCache();
+
+  const before = t01Row()!;
+  assert.equal(before.status, "complete", "precondition: T01 is complete");
+  assert.equal(before.one_liner, REAL_ONE_LINER, "precondition: one_liner set");
+  assert.equal(before.completed_at, OLD_COMPLETED_AT, "precondition: completed_at set");
+
+  // The pre-dispatch reconcile re-imports the whole tree (plan checkbox still [ ]).
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  const after = t01Row()!;
+  assert.equal(after.status, "complete", "status must survive re-import");
+  assert.equal(after.one_liner, REAL_ONE_LINER, "one_liner must survive re-import");
+  assert.equal(after.full_summary_md, REAL_SUMMARY, "full_summary_md must survive re-import");
+  assert.equal(after.verification_result, REAL_VERIFICATION, "verification_result must survive re-import");
+  assert.equal(after.completed_at, OLD_COMPLETED_AT, "completed_at must not be refreshed by re-import");
+});
+
+test("removing the SUMMARY.md (reopen) lets a re-import return the task to pending and clears completion metadata (#1222)", () => {
+  const base = copyFixture();
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  assert.equal(taskStatus(base), "complete", "precondition: task imports complete with SUMMARY present");
+
+  // Simulate the durable completion row gsd_task_complete leaves behind.
+  const { milestoneId, sliceId } = t01Ids();
+  repairTaskCompletionFromSummary({
+    milestoneId,
+    sliceId,
+    taskId: "T01",
+    oneLiner: "Implemented the widget frobnicator end-to-end",
+    verificationResult: "all 12 checks passed",
+    completedAt: "2026-07-01T00:00:00.000Z",
+    fullSummaryMd: "# T01 full summary\n\nEverything about how T01 was done.",
+  });
+  invalidateStateCache();
+  const before = t01Row()!;
+  assert.equal(before.status, "complete", "precondition: T01 is complete");
+  assert.equal(before.completed_at, "2026-07-01T00:00:00.000Z", "precondition: completed_at set");
+
+  // reopen-task deletes the flat-phase SUMMARY; the next re-import must respect it.
+  unlinkSync(join(base, SUMMARY_REL));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  const after = t01Row()!;
+  assert.equal(
+    after.status,
+    "pending",
+    "after the SUMMARY is removed, a re-import must return the unchecked task to pending",
+  );
+  // A pending re-import must not preserve stale completion metadata (#1228 thread):
+  // preserveCompletionMetadata only applies to complete/done imports.
+  assert.ok(!after.completed_at, "completed_at must be cleared when the task reverts to pending");
+  assert.ok(!after.one_liner, "one_liner must be cleared when the task reverts to pending");
+  assert.ok(!after.full_summary_md, "full_summary_md must be cleared when the task reverts to pending");
+  assert.ok(!after.verification_result, "verification_result must be cleared when the task reverts to pending");
+});

package/src/resources/extensions/gsd/tests/integration/all-milestones-complete-merge.test.ts

@@ -25,12 +25,10 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import {
-  createAutoWorktree,
-  isInAutoWorktree,
-  getAutoWorktreeOriginalBase,
-  mergeMilestoneToMain,
-} from "../../auto-worktree.ts";
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { isInAutoWorktree } from "../../auto-worktree-entry.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
+import { getAutoWorktreeOriginalBase } from "../../auto-worktree-session-registry.ts";
 
 function run(command: string, cwd: string): string {
   return execSync(command, {

package/src/resources/extensions/gsd/tests/integration/auto-stash-merge.test.ts

@@ -12,7 +12,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import { createAutoWorktree, mergeMilestoneToMain } from "../../auto-worktree.ts";
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
 import { nativeMergeSquash } from "../../native-git-bridge.ts";
 
 function run(cmd: string, cwd: string): string {

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -19,12 +19,12 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
 import {
-  createAutoWorktree,
   mergeMilestoneToMain,
-  getAutoWorktreeOriginalBase,
   _setRestoreEntryFnForTests,
-} from "../../auto-worktree.ts";
+} from "../../auto-worktree-merge.ts";
+import { getAutoWorktreeOriginalBase } from "../../auto-worktree-session-registry.ts";
 import { getSliceBranchName } from "../../worktree.ts";
 import { nativeMergeSquash } from "../../native-git-bridge.ts";
 import { drainLogs, setStderrLoggingEnabled } from "../../workflow-logger.ts";

package/src/resources/extensions/gsd/tests/integration/auto-worktree.test.ts

@@ -17,17 +17,16 @@ import {
   writeGsdMilestoneContext,
 } from "./gsd-integration-fixture.ts";
 
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { enterAutoWorktree, isInAutoWorktree } from "../../auto-worktree-entry.ts";
+import { getAutoWorktreePath } from "../../auto-worktree-path-resolution.ts";
 import {
-  createAutoWorktree,
-  teardownAutoWorktree,
-  isInAutoWorktree,
-  getAutoWorktreePath,
-  enterAutoWorktree,
-  getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
-  syncGsdStateToWorktree,
+  getAutoWorktreeOriginalBase,
   _resetAutoWorktreeOriginalBaseForTests,
-} from "../../auto-worktree.ts";
+} from "../../auto-worktree-session-registry.ts";
+import { syncGsdStateToWorktree } from "../../auto-worktree-sync.ts";
+import { teardownAutoWorktree } from "../../auto-worktree-teardown.ts";
 
 // Note: execSync is used intentionally in tests for git operations with
 // controlled, hardcoded inputs (no user input). This is safe and matches

package/src/resources/extensions/gsd/tests/integration/feature-branch-lifecycle-integration.test.ts

@@ -22,11 +22,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import {
-  createAutoWorktree,
-  mergeMilestoneToMain,
-  autoWorktreeBranch,
-} from "../../auto-worktree.ts";
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
 import { captureIntegrationBranch, getSliceBranchName } from "../../worktree.ts";
 import { writeIntegrationBranch, readIntegrationBranch } from "../../git-service.ts";
 import { nextMilestoneId, generateMilestoneSuffix } from "../../guided-flow.ts";

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

@@ -15,6 +15,7 @@ import {
   RUNTIME_EXCLUSION_PATHS,
   VALID_BRANCH_NAME,
   runGit,
+  taskBranchArgs,
   readIntegrationBranch,
   resolveMilestoneIntegrationBranch,
   writeIntegrationBranch,
@@ -1119,6 +1120,81 @@ process.exit(result.status ?? 0);
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ─── taskBranchArgs ───────────────────────────────────────────────────
+
+  test('taskBranchArgs starts new workflow branches from the base branch, not from HEAD', () => {
+    const repo = initBranchTestRepo();
+
+    assert.deepStrictEqual(
+      taskBranchArgs(repo, "gsd/spike/first", "main", "main"),
+      ["checkout", "-b", "gsd/spike/first"],
+      "branching while on the base branch itself needs no explicit start point",
+    );
+
+    // Simulate a finished workflow left checked out with its own commit.
+    run("git checkout -b gsd/spike/first", repo);
+    createFile(repo, "first.txt", "first workflow output");
+    runGit(repo, ["add", "-A"]);
+    runGit(repo, ["commit", "-m", "first workflow work"]);
+    _resetHasChangesCache();
+
+    const args = taskBranchArgs(repo, "gsd/spike/second", "gsd/spike/first", "main");
+    assert.deepStrictEqual(
+      args,
+      ["checkout", "-b", "gsd/spike/second", "main"],
+      "next workflow branch starts from the base so workflows do not stack",
+    );
+
+    runGit(repo, args);
+    assert.deepStrictEqual(
+      run("git rev-parse HEAD", repo),
+      run("git rev-parse main", repo),
+      "second workflow branch points at the base, without the first workflow's commit",
+    );
+
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  test('taskBranchArgs keeps branch-from-HEAD on user branches and unsafe states', () => {
+    const repo = initBranchTestRepo();
+
+    // Manual feature branch: the user chose to stand here — new workflow
+    // branches base on it, never silently jump to main.
+    run("git checkout -b feature/login", repo);
+    createFile(repo, "feature.txt", "feature work");
+    runGit(repo, ["add", "-A"]);
+    runGit(repo, ["commit", "-m", "feature work"]);
+    _resetHasChangesCache();
+    assert.deepStrictEqual(
+      taskBranchArgs(repo, "gsd/spike/from-feature", "feature/login", "main"),
+      ["checkout", "-b", "gsd/spike/from-feature"],
+      "a manual feature branch is a deliberate base — no redirect to main",
+    );
+
+    // Base branch without a local ref (e.g. origin/HEAD names a branch that
+    // was never checked out locally): fall back to HEAD instead of failing.
+    run("git checkout -b gsd/spike/stale", repo);
+    _resetHasChangesCache();
+    assert.deepStrictEqual(
+      taskBranchArgs(repo, "gsd/spike/next", "gsd/spike/stale", "no-such-branch"),
+      ["checkout", "-b", "gsd/spike/next"],
+      "missing local base ref falls back to branch-from-HEAD",
+    );
+
+    // Dirty tree on a task branch: a tree-changing start point would abort
+    // the checkout or strand the changes — fall back to HEAD.
+    createFile(repo, "dirty.txt", "uncommitted");
+    runGit(repo, ["add", "-A"]);
+    _resetHasChangesCache();
+    assert.deepStrictEqual(
+      taskBranchArgs(repo, "gsd/spike/next", "gsd/spike/stale", "main"),
+      ["checkout", "-b", "gsd/spike/next"],
+      "dirty working tree falls back to branch-from-HEAD",
+    );
+
+    rmSync(repo, { recursive: true, force: true });
+  });
+
   // ═══════════════════════════════════════════════════════════════════════
   // S05: Enhanced features — snapshots, pre-merge checks
   // ═══════════════════════════════════════════════════════════════════════

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

@@ -28,7 +28,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import { mergeMilestoneToMain } from "../../auto-worktree.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
 import { MergeConflictError } from "../../git-service.ts";
 
 function run(cmd: string, cwd: string): string {

package/src/resources/extensions/gsd/tests/integration/merge-preserve-worktree-on-preteardown-error.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { GSDError } from "../../errors.js";
-import { mergeMilestoneToMain } from "../../auto-worktree.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
 
 function run(cmd: string, cwd: string): string {
   return execSync(cmd, {

package/src/resources/extensions/gsd/tests/integration/merge-strategy-regular.test.ts

@@ -29,7 +29,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import { createAutoWorktree, mergeMilestoneToMain } from "../../auto-worktree.ts";
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
 import { closeDatabase } from "../../gsd-db.ts";
 import { getSliceBranchName } from "../../worktree.ts";
 

package/src/resources/extensions/gsd/tests/integration/milestone-transition-worktree.test.ts

@@ -16,13 +16,11 @@ import { execSync } from "node:child_process";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import {
-  createAutoWorktree,
-  teardownAutoWorktree,
-  isInAutoWorktree,
-  getAutoWorktreeOriginalBase,
-  mergeMilestoneToMain,
-} from "../../auto-worktree.ts";
+import { createAutoWorktree } from "../../auto-worktree-creation.ts";
+import { isInAutoWorktree } from "../../auto-worktree-entry.ts";
+import { mergeMilestoneToMain } from "../../auto-worktree-merge.ts";
+import { getAutoWorktreeOriginalBase } from "../../auto-worktree-session-registry.ts";
+import { teardownAutoWorktree } from "../../auto-worktree-teardown.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));