gsd-pi 2.4.0 → 2.5.1

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

@@ -1,4 +1,4 @@
-import { parseRoadmap, parsePlan, parseSummary, parseContinue, parseRequirementCounts } from '../files.ts';
+import { parseRoadmap, parsePlan, parseSummary, parseContinue, parseRequirementCounts, parseSecretsManifest, formatSecretsManifest } from '../files.ts';
 
 let passed = 0;
 let failed = 0;
@@ -1249,97 +1249,243 @@ console.log('\n=== parseRequirementCounts: total is sum of all section counts ==
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// parseSummary: bare scalar frontmatter fields (regression test for #91)
+// parseSecretsManifest / formatSecretsManifest tests
 // ═══════════════════════════════════════════════════════════════════════════
 
-console.log('\n=== parseSummary: bare scalar "none" coerced to string array (#91) ===');
+console.log('\n=== parseSecretsManifest: full manifest with 3 keys ===');
 {
-  const content = `---
-id: T04
-parent: S03
-milestone: M001
-provides:
-  - iOS rules
-key_files:
-  - .claude/rules/swift-style.md
-key_decisions: none
-patterns_established: none
-drill_down_paths: none
-observability_surfaces: none — static reference files
-affects: single-value
----
+  const content = `# Secrets Manifest
 
-# T04: iOS Rules
+**Milestone:** M003
+**Generated:** 2025-06-15T10:00:00Z
 
-**Created iOS-specific rules.**
+### OPENAI_API_KEY
 
-## What Happened
+**Service:** OpenAI
+**Dashboard:** https://platform.openai.com/api-keys
+**Format hint:** starts with sk-
+**Status:** pending
+**Destination:** dotenv
 
-Added rules.
+1. Go to https://platform.openai.com/api-keys
+2. Click "Create new secret key"
+3. Copy the key immediately — it won't be shown again
 
-## Deviations
+### STRIPE_SECRET_KEY
 
-None.
+**Service:** Stripe
+**Dashboard:** https://dashboard.stripe.com/apikeys
+**Format hint:** starts with sk_test_ or sk_live_
+**Status:** collected
+**Destination:** dotenv
+
+1. Go to https://dashboard.stripe.com/apikeys
+2. Reveal the secret key
+3. Copy it
+
+### SUPABASE_URL
+
+**Service:** Supabase
+**Dashboard:** https://app.supabase.com/project/settings/api
+**Format hint:** https://<project-ref>.supabase.co
+**Status:** skipped
+**Destination:** vercel
+
+1. Go to project settings in Supabase
+2. Copy the URL from the API section
 `;
 
-  const s = parseSummary(content);
+  const m = parseSecretsManifest(content);
+
+  assertEq(m.milestone, 'M003', 'manifest milestone');
+  assertEq(m.generatedAt, '2025-06-15T10:00:00Z', 'manifest generatedAt');
+  assertEq(m.entries.length, 3, 'three entries');
+
+  // First entry
+  assertEq(m.entries[0].key, 'OPENAI_API_KEY', 'entry 0 key');
+  assertEq(m.entries[0].service, 'OpenAI', 'entry 0 service');
+  assertEq(m.entries[0].dashboardUrl, 'https://platform.openai.com/api-keys', 'entry 0 dashboardUrl');
+  assertEq(m.entries[0].formatHint, 'starts with sk-', 'entry 0 formatHint');
+  assertEq(m.entries[0].status, 'pending', 'entry 0 status');
+  assertEq(m.entries[0].destination, 'dotenv', 'entry 0 destination');
+  assertEq(m.entries[0].guidance.length, 3, 'entry 0 guidance count');
+  assertEq(m.entries[0].guidance[0], 'Go to https://platform.openai.com/api-keys', 'entry 0 guidance[0]');
+  assertEq(m.entries[0].guidance[2], 'Copy the key immediately — it won\'t be shown again', 'entry 0 guidance[2]');
+
+  // Second entry
+  assertEq(m.entries[1].key, 'STRIPE_SECRET_KEY', 'entry 1 key');
+  assertEq(m.entries[1].service, 'Stripe', 'entry 1 service');
+  assertEq(m.entries[1].status, 'collected', 'entry 1 status');
+  assertEq(m.entries[1].formatHint, 'starts with sk_test_ or sk_live_', 'entry 1 formatHint');
+  assertEq(m.entries[1].guidance.length, 3, 'entry 1 guidance count');
+
+  // Third entry
+  assertEq(m.entries[2].key, 'SUPABASE_URL', 'entry 2 key');
+  assertEq(m.entries[2].status, 'skipped', 'entry 2 status');
+  assertEq(m.entries[2].destination, 'vercel', 'entry 2 destination');
+  assertEq(m.entries[2].guidance.length, 2, 'entry 2 guidance count');
+}
+
+console.log('\n=== parseSecretsManifest: single-key manifest ===');
+{
+  const content = `# Secrets Manifest
+
+**Milestone:** M001
+**Generated:** 2025-06-15T12:00:00Z
 
-  // Array fields should remain arrays
-  assertEq(s.frontmatter.provides.length, 1, '#91: provides array preserved');
-  assertEq(s.frontmatter.provides[0], 'iOS rules', '#91: provides value');
-  assertEq(s.frontmatter.key_files.length, 1, '#91: key_files array preserved');
+### DATABASE_URL
 
-  // Bare scalar "none" must be coerced to ["none"], not crash
-  assertEq(Array.isArray(s.frontmatter.key_decisions), true, '#91: key_decisions is array');
-  assertEq(s.frontmatter.key_decisions.length, 1, '#91: key_decisions has 1 element');
-  assertEq(s.frontmatter.key_decisions[0], 'none', '#91: key_decisions[0] is "none"');
+**Service:** PostgreSQL
+**Dashboard:** https://console.neon.tech
+**Format hint:** postgresql://...
+**Status:** pending
+**Destination:** dotenv
 
-  assertEq(Array.isArray(s.frontmatter.patterns_established), true, '#91: patterns_established is array');
-  assertEq(s.frontmatter.patterns_established.length, 1, '#91: patterns_established coerced');
+1. Create a database on Neon
+2. Copy the connection string
+`;
 
-  assertEq(Array.isArray(s.frontmatter.drill_down_paths), true, '#91: drill_down_paths is array');
-  assertEq(s.frontmatter.drill_down_paths.length, 1, '#91: drill_down_paths coerced');
+  const m = parseSecretsManifest(content);
+  assertEq(m.milestone, 'M001', 'single-key milestone');
+  assertEq(m.entries.length, 1, 'single entry');
+  assertEq(m.entries[0].key, 'DATABASE_URL', 'single entry key');
+  assertEq(m.entries[0].service, 'PostgreSQL', 'single entry service');
+  assertEq(m.entries[0].guidance.length, 2, 'single entry guidance count');
+}
 
-  // Scalar with spaces: "none — static reference files"
-  assertEq(Array.isArray(s.frontmatter.observability_surfaces), true, '#91: observability_surfaces is array');
-  assertEq(s.frontmatter.observability_surfaces.length, 1, '#91: observability_surfaces coerced');
-  assertEq(s.frontmatter.observability_surfaces[0], 'none — static reference files', '#91: full scalar preserved');
+console.log('\n=== parseSecretsManifest: empty/no-secrets manifest ===');
+{
+  const content = `# Secrets Manifest
 
-  // Single value (not "none") also coerced
-  assertEq(Array.isArray(s.frontmatter.affects), true, '#91: affects is array');
-  assertEq(s.frontmatter.affects.length, 1, '#91: affects single value coerced');
-  assertEq(s.frontmatter.affects[0], 'single-value', '#91: affects value');
+**Milestone:** M002
+**Generated:** 2025-06-15T14:00:00Z
+`;
 
-  // .slice().join() must not crash (the original bug)
-  const decisions = s.frontmatter.key_decisions.slice(0, 2).join('; ');
-  assertEq(decisions, 'none', '#91: .slice().join() works on coerced array');
+  const m = parseSecretsManifest(content);
+  assertEq(m.milestone, 'M002', 'empty manifest milestone');
+  assertEq(m.generatedAt, '2025-06-15T14:00:00Z', 'empty manifest generatedAt');
+  assertEq(m.entries.length, 0, 'no entries in empty manifest');
 }
 
-console.log('\n=== parseSummary: missing/empty frontmatter fields yield empty arrays ===');
+console.log('\n=== parseSecretsManifest: missing optional fields default correctly ===');
 {
-  const content = `---
-id: T05
-parent: S04
-milestone: M001
----
+  const content = `# Secrets Manifest
 
-# T05: Minimal Summary
+**Milestone:** M004
+**Generated:** 2025-06-15T16:00:00Z
 
-**Minimal.**
+### SOME_API_KEY
 
-## What Happened
+**Service:** SomeService
 
-Nothing.
+1. Get the key from the dashboard
 `;
 
-  const s = parseSummary(content);
-  assertEq(s.frontmatter.provides.length, 0, 'missing provides = empty array');
-  assertEq(s.frontmatter.key_decisions.length, 0, 'missing key_decisions = empty array');
-  assertEq(s.frontmatter.affects.length, 0, 'missing affects = empty array');
-  assertEq(s.frontmatter.key_files.length, 0, 'missing key_files = empty array');
-  assertEq(s.frontmatter.patterns_established.length, 0, 'missing patterns_established = empty array');
-  assertEq(s.frontmatter.drill_down_paths.length, 0, 'missing drill_down_paths = empty array');
-  assertEq(s.frontmatter.observability_surfaces.length, 0, 'missing observability_surfaces = empty array');
+  const m = parseSecretsManifest(content);
+  assertEq(m.entries.length, 1, 'one entry with missing fields');
+  assertEq(m.entries[0].key, 'SOME_API_KEY', 'key parsed');
+  assertEq(m.entries[0].service, 'SomeService', 'service parsed');
+  assertEq(m.entries[0].dashboardUrl, '', 'missing dashboardUrl defaults to empty string');
+  assertEq(m.entries[0].formatHint, '', 'missing formatHint defaults to empty string');
+  assertEq(m.entries[0].status, 'pending', 'missing status defaults to pending');
+  assertEq(m.entries[0].destination, 'dotenv', 'missing destination defaults to dotenv');
+  assertEq(m.entries[0].guidance.length, 1, 'guidance still parsed');
+}
+
+console.log('\n=== parseSecretsManifest: all three status values parse ===');
+{
+  for (const status of ['pending', 'collected', 'skipped'] as const) {
+    const content = `# Secrets Manifest
+
+**Milestone:** M005
+**Generated:** 2025-06-15T18:00:00Z
+
+### TEST_KEY
+
+**Service:** TestService
+**Status:** ${status}
+
+1. Do something
+`;
+
+    const m = parseSecretsManifest(content);
+    assertEq(m.entries[0].status, status, `status variant: ${status}`);
+  }
+}
+
+console.log('\n=== parseSecretsManifest: invalid status defaults to pending ===');
+{
+  const content = `# Secrets Manifest
+
+**Milestone:** M006
+**Generated:** 2025-06-15T20:00:00Z
+
+### BAD_STATUS_KEY
+
+**Service:** TestService
+**Status:** invalid_value
+
+1. Some step
+`;
+
+  const m = parseSecretsManifest(content);
+  assertEq(m.entries[0].status, 'pending', 'invalid status defaults to pending');
+}
+
+console.log('\n=== parseSecretsManifest + formatSecretsManifest: round-trip ===');
+{
+  const original = `# Secrets Manifest
+
+**Milestone:** M007
+**Generated:** 2025-06-16T10:00:00Z
+
+### OPENAI_API_KEY
+
+**Service:** OpenAI
+**Dashboard:** https://platform.openai.com/api-keys
+**Format hint:** starts with sk-
+**Status:** pending
+**Destination:** dotenv
+
+1. Go to the API keys page
+2. Create a new key
+3. Copy it
+
+### REDIS_URL
+
+**Service:** Upstash
+**Dashboard:** https://console.upstash.com
+**Format hint:** redis://...
+**Status:** collected
+**Destination:** vercel
+
+1. Open Upstash console
+2. Copy the Redis URL
+`;
+
+  const parsed1 = parseSecretsManifest(original);
+  const formatted = formatSecretsManifest(parsed1);
+  const parsed2 = parseSecretsManifest(formatted);
+
+  // Verify semantic equality after round-trip
+  assertEq(parsed2.milestone, parsed1.milestone, 'round-trip milestone');
+  assertEq(parsed2.generatedAt, parsed1.generatedAt, 'round-trip generatedAt');
+  assertEq(parsed2.entries.length, parsed1.entries.length, 'round-trip entry count');
+
+  for (let i = 0; i < parsed1.entries.length; i++) {
+    const e1 = parsed1.entries[i];
+    const e2 = parsed2.entries[i];
+    assertEq(e2.key, e1.key, `round-trip entry ${i} key`);
+    assertEq(e2.service, e1.service, `round-trip entry ${i} service`);
+    assertEq(e2.dashboardUrl, e1.dashboardUrl, `round-trip entry ${i} dashboardUrl`);
+    assertEq(e2.formatHint, e1.formatHint, `round-trip entry ${i} formatHint`);
+    assertEq(e2.status, e1.status, `round-trip entry ${i} status`);
+    assertEq(e2.destination, e1.destination, `round-trip entry ${i} destination`);
+    assertEq(e2.guidance.length, e1.guidance.length, `round-trip entry ${i} guidance length`);
+    for (let j = 0; j < e1.guidance.length; j++) {
+      assertEq(e2.guidance[j], e1.guidance[j], `round-trip entry ${i} guidance[${j}]`);
+    }
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

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

@@ -385,7 +385,6 @@ console.log('\n=== prompt: replan-slice template loads and substitutes variables
     sliceTitle: 'Test Slice',
     slicePath: '.gsd/milestones/M001/slices/S01',
     planPath: '.gsd/milestones/M001/slices/S01/S01-PLAN.md',
-    blockerTaskId: 'T02',
     inlinedContext: '## Inlined Context\n\nTest context here.',
   });
 
@@ -393,7 +392,6 @@ console.log('\n=== prompt: replan-slice template loads and substitutes variables
   assert(prompt.includes('S01'), 'prompt contains sliceId');
   assert(prompt.includes('Test Slice'), 'prompt contains sliceTitle');
   assert(prompt.includes('.gsd/milestones/M001/slices/S01/S01-PLAN.md'), 'prompt contains planPath');
-  assert(prompt.includes('T02'), 'prompt contains blockerTaskId');
   assert(prompt.includes('Test context here'), 'prompt contains inlined context');
 }
 

package/src/resources/extensions/gsd/tests/secure-env-collect.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Tests for secure_env_collect utility functions:
+ * - checkExistingEnvKeys: detects keys already present in .env file or process.env
+ * - detectDestination: infers write destination from project files
+ *
+ * Uses temp directories for filesystem isolation.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { checkExistingEnvKeys, detectDestination } from "../../get-secrets-from-user.ts";
+
+function makeTempDir(prefix: string): string {
+	const dir = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+// ─── checkExistingEnvKeys ─────────────────────────────────────────────────────
+
+test("secure_env_collect: checkExistingEnvKeys — key found in .env file", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	try {
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "API_KEY=secret123\nOTHER=val\n");
+		const result = await checkExistingEnvKeys(["API_KEY"], envPath);
+		assert.deepStrictEqual(result, ["API_KEY"]);
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key found in process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_ENV_KEY_12345;
+	try {
+		process.env.GSD_TEST_ENV_KEY_12345 = "some-value";
+		const envPath = join(tmp, ".env"); // file doesn't exist
+		const result = await checkExistingEnvKeys(["GSD_TEST_ENV_KEY_12345"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_ENV_KEY_12345"]);
+	} finally {
+		delete process.env.GSD_TEST_ENV_KEY_12345;
+		if (savedVal !== undefined) process.env.GSD_TEST_ENV_KEY_12345 = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key found in both .env and process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_BOTH_KEY;
+	try {
+		process.env.GSD_TEST_BOTH_KEY = "from-env";
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "GSD_TEST_BOTH_KEY=from-file\n");
+		const result = await checkExistingEnvKeys(["GSD_TEST_BOTH_KEY"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_BOTH_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_BOTH_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_BOTH_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key not found anywhere", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	try {
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "OTHER_KEY=val\n");
+		// Ensure it's not in process.env
+		delete process.env.DEFINITELY_NOT_SET_KEY_XYZ;
+		const result = await checkExistingEnvKeys(["DEFINITELY_NOT_SET_KEY_XYZ"], envPath);
+		assert.deepStrictEqual(result, []);
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — .env file doesn't exist (ENOENT), still checks process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_ENOENT_KEY;
+	try {
+		process.env.GSD_TEST_ENOENT_KEY = "exists-in-process";
+		const envPath = join(tmp, "nonexistent.env");
+		const result = await checkExistingEnvKeys(["GSD_TEST_ENOENT_KEY", "MISSING_KEY_XYZ"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_ENOENT_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_ENOENT_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_ENOENT_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — empty-string value in process.env counts as existing", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_EMPTY_KEY;
+	try {
+		process.env.GSD_TEST_EMPTY_KEY = "";
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "");
+		const result = await checkExistingEnvKeys(["GSD_TEST_EMPTY_KEY"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_EMPTY_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_EMPTY_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_EMPTY_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — returns only existing keys from input list", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const saved1 = process.env.GSD_TEST_EXISTS_A;
+	const saved2 = process.env.GSD_TEST_EXISTS_B;
+	try {
+		process.env.GSD_TEST_EXISTS_A = "val-a";
+		delete process.env.GSD_TEST_EXISTS_B;
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "FILE_KEY=val\n");
+		const result = await checkExistingEnvKeys(
+			["GSD_TEST_EXISTS_A", "GSD_TEST_EXISTS_B", "FILE_KEY", "NOPE_KEY"],
+			envPath,
+		);
+		assert.deepStrictEqual(result.sort(), ["FILE_KEY", "GSD_TEST_EXISTS_A"]);
+	} finally {
+		delete process.env.GSD_TEST_EXISTS_A;
+		delete process.env.GSD_TEST_EXISTS_B;
+		if (saved1 !== undefined) process.env.GSD_TEST_EXISTS_A = saved1;
+		if (saved2 !== undefined) process.env.GSD_TEST_EXISTS_B = saved2;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+// ─── detectDestination ────────────────────────────────────────────────────────
+
+test("secure_env_collect: detectDestination — returns 'vercel' when vercel.json exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "vercel.json"), "{}");
+		assert.equal(detectDestination(tmp), "vercel");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — returns 'convex' when convex/ dir exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		mkdirSync(join(tmp, "convex"));
+		assert.equal(detectDestination(tmp), "convex");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — returns 'dotenv' when neither exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		assert.equal(detectDestination(tmp), "dotenv");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — vercel takes priority when both exist", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "vercel.json"), "{}");
+		mkdirSync(join(tmp, "convex"));
+		assert.equal(detectDestination(tmp), "vercel");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — convex file (not dir) does not trigger convex", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "convex"), "not a directory");
+		assert.equal(detectDestination(tmp), "dotenv");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});

package/src/resources/extensions/gsd/types.ts

@@ -116,6 +116,26 @@ export interface Continue {
   nextAction: string;
 }
 
+// ─── Secrets Manifest ──────────────────────────────────────────────────────
+
+export type SecretsManifestEntryStatus = 'pending' | 'collected' | 'skipped';
+
+export interface SecretsManifestEntry {
+  key: string;              // e.g. "OPENAI_API_KEY"
+  service: string;          // e.g. "OpenAI"
+  dashboardUrl: string;     // e.g. "https://platform.openai.com/api-keys" — empty if unknown
+  guidance: string[];       // numbered setup steps
+  formatHint: string;       // e.g. "starts with sk-" — empty if unknown
+  status: SecretsManifestEntryStatus;
+  destination: string;      // e.g. "dotenv", "vercel", "convex"
+}
+
+export interface SecretsManifest {
+  milestone: string;        // e.g. "M001"
+  generatedAt: string;      // ISO 8601 timestamp
+  entries: SecretsManifestEntry[];
+}
+
 // ─── GSD State (Derived Dashboard) ────────────────────────────────────────
 
 export interface ActiveRef {

package/src/resources/extensions/gsd/worktree-command.ts

@@ -19,6 +19,7 @@ import {
   createWorktree,
   listWorktrees,
   removeWorktree,
+  mergeWorktreeToMain,
   diffWorktreeAll,
   diffWorktreeNumstat,
   getMainBranch,
@@ -28,7 +29,9 @@ import {
   worktreeBranchName,
   worktreePath,
 } from "./worktree-manager.js";
+import { inferCommitType } from "./git-service.js";
 import type { FileLineStat } from "./worktree-manager.js";
+import { execSync } from "node:child_process";
 import { existsSync, realpathSync, readFileSync, readdirSync, rmSync, unlinkSync, utimesSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 
@@ -349,13 +352,14 @@ async function handleCreate(
   ctx: ExtensionCommandContext,
 ): Promise<void> {
   try {
+    // Auto-commit dirty files before leaving current workspace (must happen
+    // before createWorktree so the new worktree forks from committed HEAD)
+    const commitMsg = autoCommitCurrentBranch(basePath, "worktree-switch", name);
+
     // Create from the main tree, not from inside another worktree
     const mainBase = originalCwd ?? basePath;
     const info = createWorktree(mainBase, name);
 
-    // Auto-commit dirty files before leaving current workspace
-    const commitMsg = autoCommitCurrentBranch(basePath, "worktree-switch", name);
-
     // Track original cwd before switching
     if (!originalCwd) originalCwd = basePath;
 
@@ -655,9 +659,8 @@ async function handleMerge(
       return;
     }
 
-    // Switch to the main tree before dispatching the merge.
-    // The LLM needs to run git merge --squash from the main branch, and if
-    // it later removes the worktree, the agent's CWD must not be inside it.
+    // Switch to the main tree before merging.
+    // Must be on the main branch to run git merge --squash.
     if (originalCwd) {
       const prevCwd = process.cwd();
       process.chdir(basePath);
@@ -665,6 +668,45 @@ async function handleMerge(
       originalCwd = null;
     }
 
+    // --- Deterministic merge path (preferred) ---
+    // Try a direct squash-merge first. Only fall back to LLM on conflict.
+    const commitType = inferCommitType(name);
+    const commitMessage = `${commitType}(${name}): merge worktree ${name}`;
+    try {
+      mergeWorktreeToMain(basePath, name, commitMessage);
+      ctx.ui.notify(
+        [
+          `${CLR.ok("✓")} Merged ${CLR.name(name)} → ${CLR.branch(mainBranch)} ${CLR.muted("(deterministic squash)")}`,
+          "",
+          `  ${totalChanges} file${totalChanges === 1 ? "" : "s"} changed, ${CLR.ok(`+${totalAdded}`)} ${RED}-${totalRemoved}${RESET} lines`,
+          `  ${CLR.muted("commit:")} ${commitMessage}`,
+        ].join("\n"),
+        "info",
+      );
+      return;
+    } catch (mergeErr) {
+      const mergeMsg = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
+      const isConflict = /conflict/i.test(mergeMsg);
+
+      if (isConflict) {
+        // Abort the failed merge so the working tree is clean for LLM retry
+        try {
+          execSync("git merge --abort", { cwd: basePath, stdio: "pipe" });
+        } catch { /* already clean */ }
+
+        ctx.ui.notify(
+          `${CLR.muted("Deterministic merge hit conflicts — falling back to LLM-guided merge.")}`,
+          "warning",
+        );
+        // Fall through to LLM dispatch below
+      } else {
+        // Non-conflict error — surface it directly, don't fall back
+        ctx.ui.notify(`Failed to merge: ${mergeMsg}`, "error");
+        return;
+      }
+    }
+
+    // --- LLM fallback path (conflict resolution) ---
     // Format file lists for the prompt
     const formatFiles = (files: string[]) =>
       files.length > 0 ? files.map(f => `- \`${f}\``).join("\n") : "_(none)_";