deepflow 0.1.107 → 0.1.108

package/bin/install.js

@@ -35,6 +35,23 @@ const GLOBAL_DIR = path.join(os.homedir(), '.claude');
 const PROJECT_DIR = path.join(process.cwd(), '.claude');
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
+/**
+ * Atomically write data to targetPath using a write-to-temp + rename pattern.
+ * If the write fails, the original file is left untouched and the temp file is
+ * cleaned up. Temp file is created in the same directory as the target so the
+ * rename is within the same filesystem (atomic on POSIX).
+ */
+function atomicWriteFileSync(targetPath, data) {
+  const tmpPath = targetPath + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, data);
+    fs.renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw err;
+  }
+}
+
 function updateGlobalPackage() {
   const currentVersion = require(path.join(PACKAGE_DIR, 'package.json')).version;
   try {
@@ -144,7 +161,7 @@ async function main() {
   // Copy bin utilities (plan-consolidator, wave-runner, ratchet)
   const binDest = path.join(CLAUDE_DIR, 'bin');
   fs.mkdirSync(binDest, { recursive: true });
-  for (const script of ['plan-consolidator.js', 'wave-runner.js', 'ratchet.js']) {
+  for (const script of ['plan-consolidator.js', 'wave-runner.js', 'ratchet.js', 'worktree-deps.js']) {
     const src = path.join(PACKAGE_DIR, 'bin', script);
     if (fs.existsSync(src)) {
       fs.copyFileSync(src, path.join(binDest, script));
@@ -211,7 +228,7 @@ async function main() {
   console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:auto, /df:update');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, browse-fetch, browse-verify, auto-cycle');
   console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
-  console.log('  bin/             — plan-consolidator, wave-runner, ratchet');
+  console.log('  bin/             — plan-consolidator, wave-runner, ratchet, worktree-deps');
   console.log('  templates/       — explore-protocol (auto-injected into Explore agents via hook)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker, invariant checker, worktree guard, explore protocol');
@@ -434,7 +451,7 @@ async function configureHooks(claudeDir) {
     console.log(`  ${c.dim}${file} copied (no @hook-event tag — not wired)${c.reset}`);
   }
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 
 function configureProjectSettings(claudeDir) {
@@ -457,7 +474,7 @@ function configureProjectSettings(claudeDir) {
   // Configure permissions for background agents
   configurePermissions(settings);
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
   log('LSP tool enabled + agent permissions configured (project)');
 }
 
@@ -614,6 +631,7 @@ async function uninstall() {
     'bin/plan-consolidator.js',
     'bin/wave-runner.js',
     'bin/ratchet.js',
+    'bin/worktree-deps.js',
     'templates'
   ];
 
@@ -675,7 +693,7 @@ async function uninstall() {
           console.log(`  ${c.green}✓${c.reset} Removed deepflow permissions from settings`);
         }
 
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
       } catch (e) {
         // Fail silently
       }
@@ -702,7 +720,7 @@ async function uninstall() {
           fs.unlinkSync(localSettingsPath);
           console.log(`  ${c.green}✓${c.reset} Removed settings.local.json (empty after cleanup)`);
         } else {
-          fs.writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
+          atomicWriteFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
           console.log(`  ${c.green}✓${c.reset} Removed deepflow settings from settings.local.json`);
         }
       } catch (e) {
@@ -717,7 +735,7 @@ async function uninstall() {
 }
 
 // Export for testing
-module.exports = { scanHookEvents, removeDeepflowHooks };
+module.exports = { scanHookEvents, removeDeepflowHooks, atomicWriteFileSync };
 
 // Only run main when executed directly (not when required by tests)
 if (require.main === module) {

package/bin/install.test.js

@@ -1040,3 +1040,116 @@ describe('copyDir security hardening (symlink & path traversal)', () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// 7. atomicWriteFileSync — write-to-temp + rename pattern
+// ---------------------------------------------------------------------------
+
+describe('atomicWriteFileSync', () => {
+  const { atomicWriteFileSync } = require('./install.js');
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmrf(tmpDir);
+  });
+
+  test('writes data to target file', () => {
+    const target = path.join(tmpDir, 'settings.json');
+    atomicWriteFileSync(target, '{"key":"value"}');
+    assert.equal(fs.readFileSync(target, 'utf8'), '{"key":"value"}');
+  });
+
+  test('leaves no .tmp artifact on success', () => {
+    const target = path.join(tmpDir, 'settings.json');
+    atomicWriteFileSync(target, 'data');
+    assert.ok(!fs.existsSync(target + '.tmp'), 'No .tmp file should remain after successful write');
+  });
+
+  test('overwrites existing target with new content', () => {
+    const target = path.join(tmpDir, 'settings.json');
+    fs.writeFileSync(target, 'original');
+    atomicWriteFileSync(target, 'updated');
+    assert.equal(fs.readFileSync(target, 'utf8'), 'updated');
+  });
+
+  test('leaves original untouched when write to temp fails', () => {
+    const target = path.join(tmpDir, 'settings.json');
+    fs.writeFileSync(target, 'safe-original');
+
+    // Force writeFileSync to fail by passing a directory path as the tmpPath target
+    // We do this by making the .tmp path a directory so writeFileSync throws EISDIR
+    const tmpPath = target + '.tmp';
+    fs.mkdirSync(tmpPath);
+
+    let threw = false;
+    try {
+      atomicWriteFileSync(target, 'should-not-overwrite');
+    } catch (_) {
+      threw = true;
+    }
+
+    assert.ok(threw, 'atomicWriteFileSync should rethrow write errors');
+    assert.equal(
+      fs.readFileSync(target, 'utf8'),
+      'safe-original',
+      'Original file must be untouched when temp write fails'
+    );
+  });
+
+  test('cleans up .tmp artifact when write fails', () => {
+    const target = path.join(tmpDir, 'settings.json');
+    const tmpPath = target + '.tmp';
+
+    // Intercept: write succeeds but rename fails
+    // We simulate this by making the target's parent dir read-only after the temp write
+    // Instead, test cleanup via the EISDIR approach (tmpPath is a dir — can't write into it)
+    // After EISDIR on writeFileSync(tmpPath), unlinkSync should clean it up.
+    // Since tmpPath was created as a dir in this test, unlinkSync would fail silently,
+    // but the dir itself was pre-existing. Let's use a simpler approach:
+    // patch by making target a directory, which causes renameSync to fail after temp write.
+
+    // Create a target that is a directory so renameSync(tmp, target) fails
+    fs.mkdirSync(target);
+    fs.writeFileSync(path.join(target, 'dummy'), 'x'); // non-empty so unlinkSync fails cleanly
+
+    let threw = false;
+    try {
+      atomicWriteFileSync(target, 'data');
+    } catch (_) {
+      threw = true;
+    }
+
+    assert.ok(threw, 'Should throw when rename fails');
+    // .tmp should be cleaned up
+    assert.ok(!fs.existsSync(tmpPath), '.tmp file should be cleaned up after rename failure');
+  });
+
+  test('source uses atomicWriteFileSync for all 4 settings writes', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // Count occurrences of atomicWriteFileSync calls (excluding the definition)
+    const calls = src.match(/atomicWriteFileSync\(/g) || [];
+    // 1 definition + 4 call sites = 5 total occurrences minimum
+    assert.ok(
+      calls.length >= 5,
+      `Expected at least 5 occurrences of atomicWriteFileSync (1 def + 4 calls), found ${calls.length}`
+    );
+  });
+
+  test('source exports atomicWriteFileSync for testing', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    assert.ok(
+      src.includes('atomicWriteFileSync') && src.includes('module.exports'),
+      'install.js should export atomicWriteFileSync'
+    );
+    const exportLine = src.match(/module\.exports\s*=\s*\{([^}]+)\}/);
+    assert.ok(exportLine, 'module.exports should be a plain object');
+    assert.ok(
+      exportLine[1].includes('atomicWriteFileSync'),
+      'module.exports should include atomicWriteFileSync'
+    );
+  });
+});

package/bin/plan-consolidator.js

@@ -23,12 +23,14 @@ const path = require('path');
 // ---------------------------------------------------------------------------
 
 function parseArgs(argv) {
-  const args = { plansDir: null };
+  const args = { plansDir: null, specsDir: null };
   let i = 2;
   while (i < argv.length) {
     const arg = argv[i];
     if (arg === '--plans-dir' && argv[i + 1]) {
       args.plansDir = argv[++i];
+    } else if (arg === '--specs-dir' && argv[i + 1]) {
+      args.specsDir = argv[++i];
     }
     i++;
   }
@@ -282,6 +284,22 @@ function main() {
     process.exit(1);
   }
 
+  // Stale-filter: when --specs-dir is set, remove mini-plans whose corresponding
+  // spec file does not exist in specsDir
+  if (args.specsDir) {
+    const specsDir = path.resolve(process.cwd(), args.specsDir);
+    entries = entries.filter(filename => {
+      const specPath = path.join(specsDir, filename);
+      if (!fs.existsSync(specPath)) {
+        process.stderr.write(
+          `plan-consolidator: skipping stale mini-plan ${filename} (no matching spec in ${args.specsDir})\n`
+        );
+        return false;
+      }
+      return true;
+    });
+  }
+
   if (entries.length === 0) {
     process.stdout.write('## Tasks\n\n(no mini-plan files found in ' + plansDir + ')\n');
     process.exit(0);

package/bin/plan-consolidator.test.js

@@ -880,3 +880,153 @@ describe('formatConsolidated — additional edge cases', () => {
     assert.ok(output.includes('Blocked by: T1, T2'));
   });
 });
+
+// ---------------------------------------------------------------------------
+// 10. parseArgs — --specs-dir (AC-1)
+// ---------------------------------------------------------------------------
+
+describe('parseArgs — --specs-dir', () => {
+  test('recognizes --specs-dir and stores it in args.specsDir', () => {
+    const args = parseArgs(['node', 'plan-consolidator.js', '--plans-dir', '/tmp/plans', '--specs-dir', 'specs/']);
+    assert.equal(args.specsDir, 'specs/');
+  });
+
+  test('specsDir is null when --specs-dir is not provided', () => {
+    const args = parseArgs(['node', 'plan-consolidator.js', '--plans-dir', '/tmp/plans']);
+    assert.equal(args.specsDir, null);
+  });
+
+  test('specsDir is null when --specs-dir has no following value', () => {
+    const args = parseArgs(['node', 'plan-consolidator.js', '--plans-dir', '/tmp/plans', '--specs-dir']);
+    assert.equal(args.specsDir, null);
+  });
+
+  test('--specs-dir works without --plans-dir (args are independent)', () => {
+    const args = parseArgs(['node', 'plan-consolidator.js', '--specs-dir', 'my-specs/']);
+    assert.equal(args.specsDir, 'my-specs/');
+    assert.equal(args.plansDir, null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 11. CLI integration — stale-filter with --specs-dir (AC-2, AC-3, AC-4)
+// ---------------------------------------------------------------------------
+
+describe('CLI integration — stale-filter', () => {
+  test('AC-2: mini-plan is included when matching spec exists in --specs-dir', () => {
+    const plansDir = makeTmpDir();
+    const specsDir = makeTmpDir();
+    try {
+      // Create a mini-plan doing-foo.md
+      fs.writeFileSync(path.join(plansDir, 'doing-foo.md'), `## Tasks
+- [ ] **T1**: Foo task
+`);
+      // Create matching spec in specsDir
+      fs.writeFileSync(path.join(specsDir, 'doing-foo.md'), '# Spec for foo\n');
+
+      const result = runConsolidator(['--plans-dir', plansDir, '--specs-dir', specsDir]);
+      assert.equal(result.code, 0);
+      assert.ok(result.stdout.includes('**T1**: Foo task'), 'task from matched mini-plan should appear in output');
+      assert.ok(!result.stderr.includes('skipping stale'), 'no stale warning should appear when spec exists');
+    } finally {
+      rmrf(plansDir);
+      rmrf(specsDir);
+    }
+  });
+
+  test('AC-3: mini-plan is excluded with stderr warning when spec is absent from --specs-dir', () => {
+    const plansDir = makeTmpDir();
+    const specsDir = makeTmpDir();
+    try {
+      // Create a mini-plan doing-bar.md
+      fs.writeFileSync(path.join(plansDir, 'doing-bar.md'), `## Tasks
+- [ ] **T1**: Bar task
+`);
+      // No matching spec in specsDir — specsDir is empty
+
+      const result = runConsolidator(['--plans-dir', plansDir, '--specs-dir', specsDir]);
+      assert.equal(result.code, 0);
+      assert.ok(!result.stdout.includes('**T1**: Bar task'), 'stale mini-plan task should be excluded from output');
+      assert.ok(result.stderr.includes('skipping stale mini-plan doing-bar.md'), 'stderr should warn about stale mini-plan');
+    } finally {
+      rmrf(plansDir);
+      rmrf(specsDir);
+    }
+  });
+
+  test('AC-3: stderr warning includes the specsDir path', () => {
+    const plansDir = makeTmpDir();
+    const specsDir = makeTmpDir();
+    try {
+      fs.writeFileSync(path.join(plansDir, 'doing-bar.md'), `## Tasks
+- [ ] **T1**: Bar task
+`);
+
+      const result = runConsolidator(['--plans-dir', plansDir, '--specs-dir', specsDir]);
+      // Warning format: "plan-consolidator: skipping stale mini-plan {filename} (no matching spec in {specsDir})"
+      assert.ok(result.stderr.includes('no matching spec in'), 'stderr should mention no matching spec');
+    } finally {
+      rmrf(plansDir);
+      rmrf(specsDir);
+    }
+  });
+
+  test('AC-2+AC-3: only matched mini-plans are included when some specs exist and some do not', () => {
+    const plansDir = makeTmpDir();
+    const specsDir = makeTmpDir();
+    try {
+      // Two mini-plans: doing-present.md (spec exists) and doing-stale.md (spec absent)
+      fs.writeFileSync(path.join(plansDir, 'doing-present.md'), `## Tasks
+- [ ] **T1**: Present task
+`);
+      fs.writeFileSync(path.join(plansDir, 'doing-stale.md'), `## Tasks
+- [ ] **T1**: Stale task
+`);
+      // Only doing-present.md has a spec
+      fs.writeFileSync(path.join(specsDir, 'doing-present.md'), '# Spec for present\n');
+
+      const result = runConsolidator(['--plans-dir', plansDir, '--specs-dir', specsDir]);
+      assert.equal(result.code, 0);
+      assert.ok(result.stdout.includes('Present task'), 'matched mini-plan task should be included');
+      assert.ok(!result.stdout.includes('Stale task'), 'stale mini-plan task should be excluded');
+      assert.ok(result.stderr.includes('skipping stale mini-plan doing-stale.md'), 'stderr should warn about stale entry');
+    } finally {
+      rmrf(plansDir);
+      rmrf(specsDir);
+    }
+  });
+
+  test('AC-4: without --specs-dir, all doing-* mini-plans are included (backward compatible)', () => {
+    const plansDir = makeTmpDir();
+    try {
+      fs.writeFileSync(path.join(plansDir, 'doing-alpha.md'), `## Tasks
+- [ ] **T1**: Alpha task
+`);
+      fs.writeFileSync(path.join(plansDir, 'doing-beta.md'), `## Tasks
+- [ ] **T1**: Beta task
+`);
+
+      const result = runConsolidator(['--plans-dir', plansDir]);
+      assert.equal(result.code, 0);
+      assert.ok(result.stdout.includes('Alpha task'), 'alpha mini-plan should be included without --specs-dir');
+      assert.ok(result.stdout.includes('Beta task'), 'beta mini-plan should be included without --specs-dir');
+    } finally {
+      rmrf(plansDir);
+    }
+  });
+
+  test('AC-4: backward-compat — no stale warnings emitted without --specs-dir', () => {
+    const plansDir = makeTmpDir();
+    try {
+      fs.writeFileSync(path.join(plansDir, 'doing-orphan.md'), `## Tasks
+- [ ] **T1**: Orphan task (no spec file anywhere)
+`);
+
+      const result = runConsolidator(['--plans-dir', plansDir]);
+      assert.equal(result.code, 0);
+      assert.ok(!result.stderr.includes('skipping stale'), 'no stale warnings without --specs-dir');
+    } finally {
+      rmrf(plansDir);
+    }
+  });
+});

package/bin/ratchet.js

@@ -74,7 +74,7 @@ function loadConfig(repoRoot) {
 // Snapshot: read auto-snapshot.txt and absolutize paths
 // ---------------------------------------------------------------------------
 
-function loadSnapshotFiles(repoRoot) {
+function loadSnapshotFiles(repoRoot, resolveBase = repoRoot) {
   const snapshotPath = path.join(repoRoot, '.deepflow', 'auto-snapshot.txt');
   if (!fs.existsSync(snapshotPath)) return [];
 
@@ -82,7 +82,7 @@ function loadSnapshotFiles(repoRoot) {
     .split('\n')
     .map(l => l.trim())
     .filter(l => l.length > 0)
-    .map(rel => path.join(repoRoot, rel));
+    .map(rel => path.join(resolveBase, rel));
 }
 
 // ---------------------------------------------------------------------------
@@ -340,13 +340,13 @@ function main() {
 
   const cfg = loadConfig(repoRoot);
   const projectType = detectProjectType(repoRoot);
-  const snapshotFiles = loadSnapshotFiles(repoRoot);
+  const snapshotFiles = loadSnapshotFiles(repoRoot, cwd);
   const cmds = buildCommands(repoRoot, projectType, snapshotFiles, cfg);
   // --snapshot flag overrides the snapshot-derived test command
   if (cliArgs.snapshot && fs.existsSync(cliArgs.snapshot)) {
     const snapFiles = fs.readFileSync(cliArgs.snapshot, 'utf8')
       .split('\n').map(l => l.trim()).filter(l => l.length > 0)
-      .map(rel => path.isAbsolute(rel) ? rel : path.join(repoRoot, rel));
+      .map(rel => path.isAbsolute(rel) ? rel : path.join(cwd, rel));
     if (snapFiles.length > 0 && projectType === 'node' && !cfg.test_command) {
       cmds.test = ['node', '--test', ...snapFiles];
     }
@@ -363,7 +363,7 @@ function main() {
       if (exe !== 'npx' && !commandExists(exe)) continue;
     }
 
-    const { ok, log } = runCommand(cmd, repoRoot);
+    const { ok, log } = runCommand(cmd, cwd);
 
     if (ok === null) {
       // executable spawning error — skip stage

package/bin/ratchet.test.js

@@ -1171,3 +1171,175 @@ describe('Subprocess integration — --task flag updates PLAN.md on PASS', () =>
     assert.ok(plan.includes('- [ ] **T42**'), 'PLAN.md should remain unchecked without --task');
   });
 });
+
+// ---------------------------------------------------------------------------
+// 19. Worktree cwd routing — commands execute in worktree path
+// ---------------------------------------------------------------------------
+
+describe('loadSnapshotFiles — resolveBase parameter resolves paths against cwd not repoRoot', () => {
+  let repoRoot;
+  let worktreeDir;
+
+  beforeEach(() => {
+    repoRoot = makeTmpDir();
+    worktreeDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmrf(repoRoot);
+    rmrf(worktreeDir);
+  });
+
+  test('resolveBase defaults to repoRoot when not provided', () => {
+    const deepflowDir = path.join(repoRoot, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'bin/ratchet.test.js\n'
+    );
+
+    const files = loadSnapshotFiles(repoRoot);
+    assert.equal(files.length, 1);
+    assert.equal(files[0], path.join(repoRoot, 'bin/ratchet.test.js'));
+  });
+
+  test('resolveBase overrides path resolution when cwd differs from repoRoot', () => {
+    // Snapshot lives in repoRoot's .deepflow dir, but paths should resolve against worktreeDir
+    const deepflowDir = path.join(repoRoot, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'bin/ratchet.test.js\ntest/integration.test.js\n'
+    );
+
+    // Pass worktreeDir as resolveBase — paths should resolve against it, not repoRoot
+    const files = loadSnapshotFiles(repoRoot, worktreeDir);
+    assert.equal(files.length, 2);
+    assert.equal(files[0], path.join(worktreeDir, 'bin/ratchet.test.js'));
+    assert.equal(files[1], path.join(worktreeDir, 'test/integration.test.js'));
+    // Confirm the paths do NOT point into repoRoot
+    assert.ok(!files[0].startsWith(repoRoot), 'resolveBase should override repoRoot for path resolution');
+  });
+
+  test('resolveBase changes where test files are expected to live', () => {
+    const deepflowDir = path.join(repoRoot, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'spec/my.test.js\n'
+    );
+
+    const filesFromRepo = loadSnapshotFiles(repoRoot, repoRoot);
+    const filesFromWorktree = loadSnapshotFiles(repoRoot, worktreeDir);
+
+    assert.equal(filesFromRepo[0], path.join(repoRoot, 'spec/my.test.js'));
+    assert.equal(filesFromWorktree[0], path.join(worktreeDir, 'spec/my.test.js'));
+    assert.notEqual(filesFromRepo[0], filesFromWorktree[0]);
+  });
+});
+
+describe('Subprocess integration — --worktree flag routes commands to worktree cwd', () => {
+  let repoDir;
+  let worktreeDir;
+
+  beforeEach(() => {
+    // Set up main repo
+    repoDir = makeTmpDir();
+    execFileSync('git', ['init'], { cwd: repoDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.email', 'test@test.com'], { cwd: repoDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.name', 'Test'], { cwd: repoDir, stdio: 'ignore' });
+    fs.writeFileSync(path.join(repoDir, 'dummy.txt'), 'hello');
+    execFileSync('git', ['add', '.'], { cwd: repoDir, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', 'init'], { cwd: repoDir, stdio: 'ignore' });
+
+    // Set up worktree directory as a separate git repo (simulating a worktree checkout)
+    worktreeDir = makeTmpDir();
+    execFileSync('git', ['init'], { cwd: worktreeDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.email', 'test@test.com'], { cwd: worktreeDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.name', 'Test'], { cwd: worktreeDir, stdio: 'ignore' });
+    fs.writeFileSync(path.join(worktreeDir, 'dummy.txt'), 'hello');
+    execFileSync('git', ['add', '.'], { cwd: worktreeDir, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', 'init'], { cwd: worktreeDir, stdio: 'ignore' });
+  });
+
+  afterEach(() => {
+    rmrf(repoDir);
+    rmrf(worktreeDir);
+  });
+
+  test('--worktree flag causes test command to execute in worktree path', () => {
+    // Write a test file in the WORKTREE dir that prints its cwd via process.cwd()
+    const testFile = path.join(worktreeDir, 'cwd-check.test.js');
+    fs.writeFileSync(testFile, [
+      "'use strict';",
+      "const { test } = require('node:test');",
+      "const assert = require('node:assert/strict');",
+      "const path = require('node:path');",
+      "test('cwd is worktree path', () => {",
+      "  // This file lives in the worktree dir — if cwd is correct, __dirname matches cwd prefix",
+      "  assert.ok(process.cwd().startsWith(path.dirname(__dirname) || '/'), 'cwd should be set');",
+      "});",
+    ].join('\n'));
+
+    // Write snapshot pointing to the test file (relative path from worktreeDir)
+    const deepflowDir = path.join(worktreeDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'cwd-check.test.js\n'
+    );
+
+    // Write package.json in worktreeDir so it's detected as node project
+    fs.writeFileSync(path.join(worktreeDir, 'package.json'), JSON.stringify({ name: 'test-worktree' }));
+
+    const result = spawnSync(process.execPath, [RATCHET_PATH, '--worktree', worktreeDir], {
+      cwd: repoDir,  // invoked from a different cwd (repoDir)
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const output = (result.stdout || '').trim();
+    assert.ok(output.length > 0, 'ratchet should produce output');
+    const parsed = JSON.parse(output);
+    // The test should pass because the test file exists in worktreeDir and runs correctly
+    assert.equal(parsed.result, 'PASS', `Expected PASS but got: ${JSON.stringify(parsed)}`);
+  });
+
+  test('--worktree flag: snapshot paths resolve against worktreeDir, not process.cwd()', () => {
+    // Place test file only in worktreeDir (NOT in repoDir)
+    const testFile = path.join(worktreeDir, 'only-in-worktree.test.js');
+    fs.writeFileSync(testFile, [
+      "'use strict';",
+      "const { test } = require('node:test');",
+      "const assert = require('node:assert/strict');",
+      "test('exists only in worktree', () => { assert.ok(true); });",
+    ].join('\n'));
+
+    // Snapshot is in worktreeDir's .deepflow
+    const deepflowDir = path.join(worktreeDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'only-in-worktree.test.js\n'
+    );
+    fs.writeFileSync(path.join(worktreeDir, 'package.json'), JSON.stringify({ name: 'wt' }));
+
+    // Verify the test file does NOT exist in repoDir (to confirm routing works)
+    assert.ok(
+      !fs.existsSync(path.join(repoDir, 'only-in-worktree.test.js')),
+      'Test file should not exist in repoDir'
+    );
+
+    const result = spawnSync(process.execPath, [RATCHET_PATH, '--worktree', worktreeDir], {
+      cwd: repoDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const output = (result.stdout || '').trim();
+    assert.ok(output.length > 0, 'ratchet should produce output');
+    const parsed = JSON.parse(output);
+    // PASS means the test file was found in worktreeDir — cwd routing works
+    assert.equal(parsed.result, 'PASS', `Expected PASS but got: ${JSON.stringify(parsed)}`);
+  });
+});