@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

package/src/resources/extensions/gsd/tests/gate-1b-orphan-discrimination.test.ts

@@ -14,6 +14,7 @@ import { tmpdir } from "node:os";
 
 import {
   checkAutoStartAfterDiscuss,
+  _getPendingAutoStart,
   setPendingAutoStart,
   clearPendingAutoStart,
 } from "../guided-flow.ts";
@@ -21,6 +22,7 @@ import { drainLogs } from "../workflow-logger.ts";
 import {
   openDatabase,
   closeDatabase,
+  getMilestone,
   insertMilestone,
 } from "../gsd-db.ts";
 
@@ -59,6 +61,12 @@ function mkBase(): string {
   return base;
 }
 
+function mkFlatBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-gate1b-flat-"));
+  mkdirSync(join(base, ".gsd", "phases", "01-m001"), { recursive: true });
+  return base;
+}
+
 function writeContext(base: string): void {
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
@@ -66,6 +74,13 @@ function writeContext(base: string): void {
   );
 }
 
+function writeFlatContext(base: string): void {
+  writeFileSync(
+    join(base, ".gsd", "phases", "01-m001", "01-CONTEXT.md"),
+    "# M001: Test Milestone\n\nContext written by discuss phase.\n",
+  );
+}
+
 describe("Gate 1b discussion handoff in checkAutoStartAfterDiscuss", () => {
   let base: string;
   let cap: MockCapture;
@@ -142,4 +157,78 @@ describe("Gate 1b discussion handoff in checkAutoStartAfterDiscuss", () => {
     );
     assert.equal(gate1bLog, undefined, "Gate 1b must not log when CONTEXT.md is absent");
   });
+
+  test("flat-phase CONTEXT.md accepts handoff without a legacy milestone context file", () => {
+    base = mkFlatBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Test Milestone", status: "queued" });
+    writeFlatContext(base);
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      startAuto: false,
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const result = checkAutoStartAfterDiscuss();
+
+    assert.equal(result, true, "flat-phase context must be found by the handoff");
+    assert.equal(cap.messages.length, 0, "startAuto=false must suppress scheduling");
+    assert.deepEqual(cap.notifies[0], {
+      msg: "Milestone M001 context captured. Continuing the planning pipeline.",
+      level: "success",
+    });
+  });
+
+  test("DB-unavailable recovery blocks handoff instead of reporting success", () => {
+    base = mkFlatBase();
+    writeFlatContext(base);
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      startAuto: false,
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const result = checkAutoStartAfterDiscuss();
+
+    assert.equal(result, false, "handoff must fail closed when the DB row cannot be confirmed");
+    assert.equal(cap.messages.length, 0, "must not schedule auto-start when DB is unavailable");
+    assert.equal(
+      cap.notifies.some(n => n.level === "success"),
+      false,
+      "must not report a successful handoff when DB recovery was skipped",
+    );
+    assert.ok(_getPendingAutoStart(base), "pending handoff should remain for a later recovery attempt");
+  });
+
+  test("missing DB row with CONTEXT.md inserts a queued row and accepts handoff", () => {
+    base = mkFlatBase();
+    openDatabase(":memory:");
+    writeFlatContext(base);
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      startAuto: false,
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const result = checkAutoStartAfterDiscuss();
+
+    assert.equal(result, true, "successful insert should recover the missing row");
+    assert.equal(getMilestone("M001")?.status, "queued");
+    assert.deepEqual(cap.notifies[0], {
+      msg: "Milestone M001 context captured. Continuing the planning pipeline.",
+      level: "success",
+    });
+  });
 });

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/guided-flow-session-isolation.test.ts

@@ -20,6 +20,7 @@ import {
   clearPendingAutoStart,
   checkAutoStartAfterDiscuss,
 } from "../guided-flow.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
 
 function pendingInput(basePath: string, milestoneId: string) {
   return {
@@ -34,6 +35,7 @@ function pendingInput(basePath: string, milestoneId: string) {
 
 describe("#2985 Bug 3 — concurrent discuss sessions must be independent", () => {
   beforeEach(() => {
+    closeDatabase();
     clearPendingAutoStart();
   });
 
@@ -75,6 +77,7 @@ describe("#2985 Bug 3 — concurrent discuss sessions must be independent", () =
 
 describe("#2985 Bug 4 — getDiscussionMilestoneId must be keyed by basePath", () => {
   beforeEach(() => {
+    closeDatabase();
     clearPendingAutoStart();
   });
 
@@ -110,6 +113,7 @@ describe("#2985 Bug 4 — getDiscussionMilestoneId must be keyed by basePath", (
 test("checkAutoStartAfterDiscuss ignores missing manifest for single-milestone discuss on established project", () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-auto-start-manifest-"));
   try {
+    openDatabase(":memory:");
     const gsdDir = join(base, ".gsd");
     const milestoneDir = join(gsdDir, "milestones", "M001");
     mkdirSync(milestoneDir, { recursive: true });
@@ -132,6 +136,7 @@ test("checkAutoStartAfterDiscuss ignores missing manifest for single-milestone d
     const started = checkAutoStartAfterDiscuss();
     assert.equal(started, true, "project history alone should not require a manifest");
   } finally {
+    closeDatabase();
     clearPendingAutoStart();
     rmSync(base, { recursive: true, force: true });
   }
@@ -151,6 +156,7 @@ test("checkAutoStartAfterDiscuss(basePath) selects the matching pending entry wh
   }
 
   try {
+    openDatabase(":memory:");
     clearPendingAutoStart();
     writeReadyArtifacts(projectA, "M001");
     writeReadyArtifacts(projectB, "M002");
@@ -172,6 +178,7 @@ test("checkAutoStartAfterDiscuss(basePath) selects the matching pending entry wh
     assert.equal(getDiscussionMilestoneId(projectA), "M001", "projectA should remain pending");
     assert.equal(getDiscussionMilestoneId(projectB), null, "projectB should be cleared after start");
   } finally {
+    closeDatabase();
     clearPendingAutoStart();
     rmSync(projectA, { recursive: true, force: true });
     rmSync(projectB, { recursive: true, force: true });
@@ -183,6 +190,7 @@ test("checkAutoStartAfterDiscuss can accept context handoff without scheduling a
   let waitForIdleCalls = 0;
   const notifications: string[] = [];
   try {
+    openDatabase(":memory:");
     const gsdDir = join(base, ".gsd");
     const milestoneDir = join(gsdDir, "milestones", "M001");
     mkdirSync(milestoneDir, { recursive: true });
@@ -215,6 +223,7 @@ test("checkAutoStartAfterDiscuss can accept context handoff without scheduling a
     assert.equal(waitForIdleCalls, 0, "headless-owned auto start must not schedule guided-flow auto");
     assert.equal(getDiscussionMilestoneId(base), null, "accepted handoff should still be cleared");
   } finally {
+    closeDatabase();
     clearPendingAutoStart();
     rmSync(base, { recursive: true, force: true });
   }

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));