deepflow 0.1.106 → 0.1.108

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)}`);
+  });
+});

package/bin/worktree-deps.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * deepflow worktree-deps
+ * Symlinks node_modules from the main repo into a worktree so that
+ * TypeScript / LSP / builds resolve dependencies without a full install.
+ *
+ * Usage: node bin/worktree-deps.js --source /path/to/repo --worktree /path/to/worktree
+ *
+ * Walks the source repo looking for node_modules directories (max depth 2)
+ * and creates corresponding symlinks in the worktree.
+ *
+ * Exit codes: 0=OK, 1=ERROR
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--source' && args[i + 1]) opts.source = args[++i];
+    else if (args[i] === '--worktree' && args[i + 1]) opts.worktree = args[++i];
+  }
+  if (!opts.source || !opts.worktree) {
+    console.error('Usage: node bin/worktree-deps.js --source <repo> --worktree <worktree>');
+    process.exit(1);
+  }
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Find node_modules directories (depth 0 and 1 level of nesting)
+// ---------------------------------------------------------------------------
+
+function findNodeModules(root) {
+  const results = [];
+
+  // Root node_modules
+  const rootNM = path.join(root, 'node_modules');
+  if (fs.existsSync(rootNM)) {
+    results.push('node_modules');
+  }
+
+  // Scan common monorepo directory patterns for nested node_modules
+  const monorepoPatterns = ['packages', 'apps', 'libs', 'services', 'modules', 'plugins'];
+
+  for (const dir of monorepoPatterns) {
+    const dirPath = path.join(root, dir);
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath);
+    } catch (_) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry);
+      if (!fs.statSync(entryPath).isDirectory()) continue;
+
+      const nm = path.join(entryPath, 'node_modules');
+      if (fs.existsSync(nm)) {
+        results.push(path.join(dir, entry, 'node_modules'));
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Create symlinks
+// ---------------------------------------------------------------------------
+
+function symlinkDeps(source, worktree) {
+  const nodeModulesPaths = findNodeModules(source);
+
+  if (nodeModulesPaths.length === 0) {
+    console.log('{"linked":0,"message":"no node_modules found in source"}');
+    return;
+  }
+
+  let linked = 0;
+  const errors = [];
+
+  for (const relPath of nodeModulesPaths) {
+    const srcAbs = path.join(source, relPath);
+    const dstAbs = path.join(worktree, relPath);
+
+    // Skip if already exists (symlink or directory)
+    if (fs.existsSync(dstAbs)) {
+      continue;
+    }
+
+    // Ensure parent directory exists in worktree
+    const parent = path.dirname(dstAbs);
+    if (!fs.existsSync(parent)) {
+      fs.mkdirSync(parent, { recursive: true });
+    }
+
+    try {
+      fs.symlinkSync(srcAbs, dstAbs, 'dir');
+      linked++;
+    } catch (err) {
+      errors.push({ path: relPath, error: err.message });
+    }
+  }
+
+  const result = { linked, total: nodeModulesPaths.length };
+  if (errors.length > 0) result.errors = errors;
+  console.log(JSON.stringify(result));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const opts = parseArgs();
+symlinkDeps(opts.source, opts.worktree);

package/hooks/df-spec-lint.js

@@ -123,12 +123,23 @@ function computeLayer(content) {
  * @param {string} content  - The raw markdown content of the spec file.
  * @param {object} opts
  * @param {'interactive'|'auto'} opts.mode
+ * @param {string|null} opts.filename - Optional filename (basename) used for stem validation.
  * @returns {{ hard: string[], advisory: string[] }}
  */
-function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
+function validateSpec(content, { mode = 'interactive', specsDir = null, filename = null } = {}) {
   const hard = [];
   const advisory = [];
 
+  // ── Spec filename stem validation ────────────────────────────────────
+  if (filename !== null) {
+    let stem = path.basename(filename, '.md');
+    stem = stem.replace(/^(doing-|done-)/, '');
+    const SAFE_STEM = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+    if (!SAFE_STEM.test(stem)) {
+      hard.push(`Spec filename stem contains unsafe characters: "${stem}"`);
+    }
+  }
+
   // ── Frontmatter: parse and validate derives-from ─────────────────────
   const { frontmatter } = parseFrontmatter(content);
   if (frontmatter['derives-from'] !== undefined) {
@@ -339,7 +350,7 @@ if (require.main === module) {
   const content = fs.readFileSync(filePath, 'utf8');
   const mode = process.argv.includes('--auto') ? 'auto' : 'interactive';
   const specsDir = path.resolve(path.dirname(filePath));
-  const result = validateSpec(content, { mode, specsDir });
+  const result = validateSpec(content, { mode, specsDir, filename: path.basename(filePath) });
 
   if (result.hard.length > 0) {
     console.error('HARD invariant failures:');

package/hooks/df-spec-lint.test.js

@@ -410,3 +410,136 @@ describe('derives-from validation', () => {
     assert.deepEqual(resultWith.hard, resultWithout.hard);
   });
 });
+
+// ---------------------------------------------------------------------------
+// validateSpec — spec filename stem validation
+// ---------------------------------------------------------------------------
+
+describe('validateSpec stem validation', () => {
+  test('valid plain name passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('valid name with numbers passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-v2-fix.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('single character name passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'a.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('doing- prefix is stripped before validation', () => {
+    const result = validateSpec(fullSpec(), { filename: 'doing-my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('done- prefix is stripped before validation', () => {
+    const result = validateSpec(fullSpec(), { filename: 'done-my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('filename with dollar sign is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-$bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with backtick is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-`bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with pipe character is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec|bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with semicolon is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec;bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with ampersand is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec&bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with space is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with path traversal (..) is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '..evil.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with leading hyphen is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '-leading.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with trailing hyphen is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'trailing-.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('empty stem (only prefix) is rejected as hard failure', () => {
+    // A filename of just "doing-.md" strips to empty string
+    const result = validateSpec(fullSpec(), { filename: 'doing-.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('empty filename stem (.md only) is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('stem validation failure is in hard array, not advisory', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec$bad.md' });
+    const hardErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    const advisoryErrors = result.advisory.filter((m) => m.includes('unsafe characters'));
+    assert.equal(hardErrors.length, 1);
+    assert.equal(advisoryErrors.length, 0);
+  });
+
+  test('no filename passed (null) skips stem validation', () => {
+    // No filename option — stem check should not run
+    const result = validateSpec(fullSpec());
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('all existing repo spec names pass validation', () => {
+    const existingNames = [
+      'done-dashboard-model-cost-fixes.md',
+      'done-orchestrator-v2.md',
+      'done-plan-cleanup.md',
+      'done-plan-fanout.md',
+      'done-quality-gates.md',
+    ];
+    for (const filename of existingNames) {
+      const result = validateSpec(fullSpec(), { filename });
+      const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+      assert.equal(stemErrors.length, 0, `Expected ${filename} to pass but got stem errors`);
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.106",
+  "version": "0.1.108",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",