deepflow 0.1.106 → 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));
@@ -156,14 +173,21 @@ async function main() {
   if (level === 'global') {
     const hooksDir = path.join(PACKAGE_DIR, 'hooks');
     if (fs.existsSync(hooksDir)) {
-      for (const file of fs.readdirSync(hooksDir)) {
-        if (file.endsWith('.js')) {
-          fs.copyFileSync(
-            path.join(hooksDir, file),
-            path.join(CLAUDE_DIR, 'hooks', file)
-          );
+      const copyDirRecursive = (srcDir, destDir) => {
+        for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+          if (entry.isDirectory()) {
+            const subDest = path.join(destDir, entry.name);
+            fs.mkdirSync(subDest, { recursive: true });
+            copyDirRecursive(path.join(srcDir, entry.name), subDest);
+          } else if (entry.name.endsWith('.js')) {
+            fs.copyFileSync(
+              path.join(srcDir, entry.name),
+              path.join(destDir, entry.name)
+            );
+          }
         }
-      }
+      };
+      copyDirRecursive(hooksDir, path.join(CLAUDE_DIR, 'hooks'));
       log('Hooks installed');
     }
   }
@@ -204,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');
@@ -427,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) {
@@ -450,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)');
 }
 
@@ -607,6 +631,7 @@ async function uninstall() {
     'bin/plan-consolidator.js',
     'bin/wave-runner.js',
     'bin/ratchet.js',
+    'bin/worktree-deps.js',
     'templates'
   ];
 
@@ -620,6 +645,8 @@ async function uninstall() {
         }
       }
     }
+    // Remove hooks/lib (shared hook utilities)
+    toRemove.push('hooks/lib');
   }
 
   for (const item of toRemove) {
@@ -666,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
       }
@@ -693,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) {
@@ -707,7 +734,13 @@ async function uninstall() {
   console.log('');
 }
 
-main().catch(err => {
-  console.error('Installation failed:', err.message);
-  process.exit(1);
-});
+// Export for testing
+module.exports = { scanHookEvents, removeDeepflowHooks, atomicWriteFileSync };
+
+// Only run main when executed directly (not when required by tests)
+if (require.main === module) {
+  main().catch(err => {
+    console.error('Installation failed:', err.message);
+    process.exit(1);
+  });
+}

package/bin/install.test.js

@@ -590,217 +590,143 @@ describe('Uninstaller — file removal and settings cleanup', () => {
 });
 
 // ---------------------------------------------------------------------------
-// T4. command-usage hook registration (PreToolUse, PostToolUse, SessionEnd)
+// T4. command-usage hook registration via dynamic @hook-event tags
 // ---------------------------------------------------------------------------
 
 describe('T4 — command-usage hook registration in install.js', () => {
 
-  // -- Source-level checks: verify install.js registers df-command-usage.js --
+  // -- @hook-event tag: verify df-command-usage.js declares correct events --
 
-  test('source defines commandUsageCmd variable', () => {
-    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    const pattern = /commandUsageCmd\s*=\s*`node.*df-command-usage\.js/;
-    assert.ok(
-      pattern.test(src),
-      'install.js should define commandUsageCmd pointing to df-command-usage.js'
-    );
+  test('df-command-usage.js has @hook-event tag for PreToolUse, PostToolUse, SessionEnd', () => {
+    const hookPath = path.resolve(__dirname, '..', 'hooks', 'df-command-usage.js');
+    const content = fs.readFileSync(hookPath, 'utf8');
+    const firstLines = content.split('\n').slice(0, 10).join('\n');
+    const match = firstLines.match(/\/\/\s*@hook-event:\s*(.+)/);
+    assert.ok(match, 'df-command-usage.js should have @hook-event tag in first 10 lines');
+    const events = match[1].split(',').map(e => e.trim());
+    assert.ok(events.includes('PreToolUse'), 'Should declare PreToolUse event');
+    assert.ok(events.includes('PostToolUse'), 'Should declare PostToolUse event');
+    assert.ok(events.includes('SessionEnd'), 'Should declare SessionEnd event');
   });
 
-  test('source pushes command-usage hook to PreToolUse', () => {
-    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    // Find PreToolUse section — should contain a push with commandUsageCmd
-    const preToolUseSection = src.match(/PreToolUse[\s\S]*?log\('PreToolUse hook configured'\)/);
-    assert.ok(preToolUseSection, 'Should have a PreToolUse configuration section');
-    assert.ok(
-      preToolUseSection[0].includes('commandUsageCmd'),
-      'PreToolUse section should push commandUsageCmd'
-    );
-  });
+  // -- scanHookEvents: verify dynamic hook scanning maps events correctly --
 
-  test('source pushes command-usage hook to PostToolUse', () => {
-    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    // Find PostToolUse section
-    const postToolUseSection = src.match(/PostToolUse[\s\S]*?log\('PostToolUse hook configured'\)/);
-    assert.ok(postToolUseSection, 'Should have a PostToolUse configuration section');
-    assert.ok(
-      postToolUseSection[0].includes('commandUsageCmd'),
-      'PostToolUse section should push commandUsageCmd'
-    );
+  test('scanHookEvents maps df-command-usage.js to all three events', () => {
+    const { scanHookEvents } = require('./install.js');
+    const hooksDir = path.resolve(__dirname, '..', 'hooks');
+    const { eventMap } = scanHookEvents(hooksDir);
+    for (const event of ['PreToolUse', 'PostToolUse', 'SessionEnd']) {
+      assert.ok(eventMap.has(event), `eventMap should have ${event}`);
+      assert.ok(
+        eventMap.get(event).includes('df-command-usage.js'),
+        `${event} should include df-command-usage.js`
+      );
+    }
   });
 
-  test('source pushes command-usage hook to SessionEnd', () => {
+  // -- configureHooks uses dynamic wiring (no hardcoded per-hook variables) --
+
+  test('source uses scanHookEvents for dynamic hook wiring', () => {
     const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    // Find SessionEnd section — should include command-usage alongside quota-logger + dashboard-push
-    const sessionEndSection = src.match(/SessionEnd[\s\S]*?log\('Quota logger.*configured.*SessionEnd/);
-    assert.ok(sessionEndSection, 'Should have a SessionEnd configuration section');
-    assert.ok(
-      sessionEndSection[0].includes('commandUsageCmd'),
-      'SessionEnd section should push commandUsageCmd'
-    );
+    assert.ok(src.includes('scanHookEvents('), 'Should call scanHookEvents');
+    assert.ok(src.includes('for (const [event, files] of eventMap)'), 'Should iterate eventMap to wire hooks');
   });
 
-  test('source creates PreToolUse array if missing', () => {
+  test('source initializes event array if missing', () => {
     const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
     assert.ok(
-      src.includes("if (!settings.hooks.PreToolUse)"),
-      'install.js should initialize PreToolUse array if not present'
+      src.includes('if (!settings.hooks[event]) settings.hooks[event] = [];'),
+      'Should initialize event array dynamically'
     );
   });
 
-  // -- Dedup logic: filter removes existing command-usage before re-adding --
-
-  test('PreToolUse dedup filter removes existing df-command-usage entries', () => {
-    const preToolUse = [
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
-      { hooks: [{ type: 'command', command: 'node /usr/local/my-custom.js' }] },
-    ];
-
-    const filtered = preToolUse.filter(hook => {
-      const cmd = hook.hooks?.[0]?.command || '';
-      return !cmd.includes('df-command-usage');
-    });
+  // -- removeDeepflowHooks: generic removal of all /hooks/df- entries --
 
-    assert.equal(filtered.length, 1, 'Should remove existing df-command-usage hook');
-    assert.ok(filtered[0].hooks[0].command.includes('my-custom.js'), 'Should keep non-deepflow hooks');
+  test('removeDeepflowHooks removes df-command-usage from all events', () => {
+    const { removeDeepflowHooks } = require('./install.js');
+    const settings = {
+      hooks: {
+        PreToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+          { hooks: [{ type: 'command', command: 'node /usr/local/my-custom.js' }] },
+        ],
+        PostToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-tool-usage.js' }] },
+        ],
+        SessionEnd: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+          { hooks: [{ type: 'command', command: 'node /usr/local/keep.js' }] },
+        ],
+      }
+    };
+    removeDeepflowHooks(settings);
+    assert.equal(settings.hooks.PreToolUse.length, 1);
+    assert.ok(settings.hooks.PreToolUse[0].hooks[0].command.includes('my-custom.js'));
+    assert.ok(!('PostToolUse' in settings.hooks), 'PostToolUse should be deleted when only deepflow hooks');
+    assert.equal(settings.hooks.SessionEnd.length, 1);
+    assert.ok(settings.hooks.SessionEnd[0].hooks[0].command.includes('keep.js'));
   });
 
-  test('PostToolUse dedup filter removes df-command-usage alongside other deepflow hooks', () => {
-    const postToolUse = [
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-tool-usage.js' }] },
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-worktree-guard.js' }] },
-      { hooks: [{ type: 'command', command: 'node /usr/local/keep-me.js' }] },
-    ];
-
-    const filtered = postToolUse.filter(hook => {
-      const cmd = hook.hooks?.[0]?.command || '';
-      return !cmd.includes('df-tool-usage') &&
-             !cmd.includes('df-execution-history') &&
-             !cmd.includes('df-worktree-guard') &&
-             !cmd.includes('df-snapshot-guard') &&
-             !cmd.includes('df-invariant-check') &&
-             !cmd.includes('df-command-usage');
-    });
-
-    assert.equal(filtered.length, 1);
-    assert.ok(filtered[0].hooks[0].command.includes('keep-me.js'));
+  test('removeDeepflowHooks deletes event key when array becomes empty', () => {
+    const { removeDeepflowHooks } = require('./install.js');
+    const settings = {
+      hooks: {
+        PreToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+        ],
+      }
+    };
+    removeDeepflowHooks(settings);
+    assert.ok(!('PreToolUse' in (settings.hooks || {})), 'PreToolUse should be deleted when empty');
   });
 
-  test('SessionEnd dedup filter removes df-command-usage alongside quota-logger and dashboard-push', () => {
-    const sessionEnd = [
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-quota-logger.js' }] },
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-dashboard-push.js' }] },
-      { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
-      { hooks: [{ type: 'command', command: 'node /usr/local/keep.js' }] },
-    ];
-
-    const filtered = sessionEnd.filter(hook => {
-      const cmd = hook.hooks?.[0]?.command || '';
-      return !cmd.includes('df-quota-logger') &&
-             !cmd.includes('df-dashboard-push') &&
-             !cmd.includes('df-command-usage');
-    });
-
-    assert.equal(filtered.length, 1);
-    assert.ok(filtered[0].hooks[0].command.includes('keep.js'));
+  test('removeDeepflowHooks keeps non-deepflow hooks intact', () => {
+    const { removeDeepflowHooks } = require('./install.js');
+    const settings = {
+      hooks: {
+        PreToolUse: [
+          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
+          { hooks: [{ type: 'command', command: 'node /usr/local/custom-pre-hook.js' }] },
+        ],
+      }
+    };
+    removeDeepflowHooks(settings);
+    assert.ok('PreToolUse' in settings.hooks, 'PreToolUse should be kept when custom hooks remain');
+    assert.equal(settings.hooks.PreToolUse.length, 1);
+    assert.ok(settings.hooks.PreToolUse[0].hooks[0].command.includes('custom-pre-hook.js'));
   });
 
-  // -- Uninstall cleanup --
-
-  test('uninstall toRemove includes df-command-usage.js', () => {
-    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    // Find the toRemove.push(...) line for hooks in uninstall
-    assert.ok(
-      src.includes("'hooks/df-command-usage.js'"),
-      'toRemove should include hooks/df-command-usage.js for uninstall'
-    );
-  });
+  // -- Uninstall: dynamic df-*.js discovery --
 
-  test('uninstall SessionEnd filter removes df-command-usage', () => {
+  test('uninstall dynamically discovers df-*.js hooks to remove', () => {
     const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
-    // In the uninstall function, the SessionEnd filter should include df-command-usage
-    // Find the uninstall section's SessionEnd filter
     const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
     assert.ok(uninstallSection, 'Should have uninstall function');
-    // Check SessionEnd filter in uninstall includes command-usage
-    const sessionEndFilter = uninstallSection[0].match(/SessionEnd[\s\S]*?\.filter[\s\S]*?\);/);
-    assert.ok(sessionEndFilter, 'Should have SessionEnd filter in uninstall');
     assert.ok(
-      sessionEndFilter[0].includes('df-command-usage'),
-      'Uninstall SessionEnd filter should remove df-command-usage hooks'
+      uninstallSection[0].includes("file.startsWith('df-')") &&
+      uninstallSection[0].includes("file.endsWith('.js')"),
+      'Uninstall should dynamically find df-*.js hook files'
     );
   });
 
-  test('uninstall PostToolUse filter removes df-command-usage', () => {
+  test('uninstall uses removeDeepflowHooks for settings cleanup', () => {
     const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
     const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
-    const postToolUseFilter = uninstallSection[0].match(/PostToolUse[\s\S]*?\.filter[\s\S]*?\);/);
-    assert.ok(postToolUseFilter, 'Should have PostToolUse filter in uninstall');
     assert.ok(
-      postToolUseFilter[0].includes('df-command-usage'),
-      'Uninstall PostToolUse filter should remove df-command-usage hooks'
+      uninstallSection[0].includes('removeDeepflowHooks'),
+      'Uninstall should use removeDeepflowHooks for generic cleanup'
     );
   });
 
-  test('uninstall cleans up PreToolUse hooks', () => {
+  test('uninstall removes hooks/lib directory', () => {
     const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
     const uninstallSection = src.match(/async function uninstall[\s\S]+$/);
     assert.ok(
-      uninstallSection[0].includes('PreToolUse'),
-      'Uninstall function should handle PreToolUse cleanup'
-    );
-    // Verify it filters out df-command-usage from PreToolUse
-    const preToolUseFilter = uninstallSection[0].match(/PreToolUse[\s\S]*?\.filter[\s\S]*?\);/);
-    assert.ok(preToolUseFilter, 'Should have PreToolUse filter in uninstall');
-    assert.ok(
-      preToolUseFilter[0].includes('df-command-usage'),
-      'Uninstall PreToolUse filter should remove df-command-usage hooks'
+      uninstallSection[0].includes("hooks/lib"),
+      'Uninstall should remove hooks/lib directory'
     );
   });
-
-  test('uninstall deletes PreToolUse key when array becomes empty', () => {
-    // Reproduce the uninstall logic for PreToolUse
-    const settings = {
-      hooks: {
-        PreToolUse: [
-          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
-        ],
-      }
-    };
-
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
-      const cmd = hook.hooks?.[0]?.command || '';
-      return !cmd.includes('df-command-usage');
-    });
-    if (settings.hooks.PreToolUse.length === 0) {
-      delete settings.hooks.PreToolUse;
-    }
-
-    assert.ok(!('PreToolUse' in settings.hooks), 'PreToolUse should be deleted when empty after filtering');
-  });
-
-  test('uninstall keeps PreToolUse when non-deepflow hooks remain', () => {
-    const settings = {
-      hooks: {
-        PreToolUse: [
-          { hooks: [{ type: 'command', command: 'node /home/.claude/hooks/df-command-usage.js' }] },
-          { hooks: [{ type: 'command', command: 'node /usr/local/custom-pre-hook.js' }] },
-        ],
-      }
-    };
-
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(hook => {
-      const cmd = hook.hooks?.[0]?.command || '';
-      return !cmd.includes('df-command-usage');
-    });
-    if (settings.hooks.PreToolUse.length === 0) {
-      delete settings.hooks.PreToolUse;
-    }
-
-    assert.ok('PreToolUse' in settings.hooks, 'PreToolUse should be kept when custom hooks remain');
-    assert.equal(settings.hooks.PreToolUse.length, 1);
-    assert.ok(settings.hooks.PreToolUse[0].hooks[0].command.includes('custom-pre-hook.js'));
-  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1114,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);