@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/ideas.test.cjs

@@ -0,0 +1,1417 @@
+/**
+ * Tests for ideas.cjs — findIdeaFile state detection, parseIdeaFrontmatter,
+ * and cmdIdeasReject guard behavior.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { createTempDir, cleanupDir, createTempProject } = require('./test-helpers.cjs');
+const { findIdeaFile, parseIdeaFrontmatter, ensureIdeasDirs, cmdIdeasCreate, loadManifest, IDEA_STATES, buildIdeaContent, cmdIdeasConsolidate, cmdIdeasFindRelated, cmdIdeasUndoConsolidation } = require('./ideas.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Creates an idea file in a specific state directory.
+ * @param {string} cwd - Temp directory root
+ * @param {string} state - One of: pending, rejected, done
+ * @param {number} id - Idea numeric ID
+ * @param {string} title - Idea title
+ * @returns {string} The filename created
+ */
+function createIdeaInState(cwd, state, id, title) {
+  const slug = title.toLowerCase().replace(/\s+/g, '-');
+  const paddedId = String(id).padStart(3, '0');
+  const filename = `${paddedId}-${slug}.md`;
+  const content = `---\nid: ${id}\ntitle: "${title}"\n---\n\nIdea body.\n`;
+  const dir = path.join(cwd, '.planning', 'ideas', state);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, filename), content, 'utf-8');
+  return filename;
+}
+
+// ─── findIdeaFile state detection ─────────────────────────────────────────────
+
+describe('findIdeaFile state detection', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-test-');
+    ensureIdeasDirs(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('returns state "pending" for idea in pending directory', () => {
+    createIdeaInState(tmpDir, 'pending', 1, 'Test Pending');
+    const idea = findIdeaFile(tmpDir, '1');
+    assert.ok(idea, 'findIdeaFile should return a result');
+    assert.strictEqual(idea.state, 'pending');
+  });
+
+  it('returns state "rejected" for idea in rejected directory', () => {
+    createIdeaInState(tmpDir, 'rejected', 2, 'Test Rejected');
+    const idea = findIdeaFile(tmpDir, '2');
+    assert.ok(idea, 'findIdeaFile should return a result');
+    assert.strictEqual(idea.state, 'rejected');
+  });
+
+  it('returns state "done" for idea in done directory', () => {
+    createIdeaInState(tmpDir, 'done', 3, 'Test Done');
+    const idea = findIdeaFile(tmpDir, '3');
+    assert.ok(idea, 'findIdeaFile should return a result');
+    assert.strictEqual(idea.state, 'done');
+  });
+
+  it('returns null for nonexistent idea', () => {
+    const idea = findIdeaFile(tmpDir, '999');
+    assert.strictEqual(idea, null);
+  });
+});
+
+// ─── parseIdeaFrontmatter ────────────────────────────────────────────────────
+
+describe('parseIdeaFrontmatter', () => {
+  it('parses frontmatter with id and title', () => {
+    const content = '---\nid: 5\ntitle: "My Great Idea"\n---\n\nSome body text.\n';
+    const result = parseIdeaFrontmatter(content);
+    assert.strictEqual(result.frontmatter.id, 5);
+    assert.strictEqual(result.frontmatter.title, 'My Great Idea');
+    assert.ok(result.body.includes('Some body text'));
+  });
+
+  it('returns empty frontmatter for content without YAML', () => {
+    const content = 'Just plain text with no frontmatter at all.';
+    const result = parseIdeaFrontmatter(content);
+    assert.deepStrictEqual(result.frontmatter, {});
+  });
+});
+
+// ─── consolidated state ──────────────────────────────────────────────────────
+
+describe('consolidated state', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-consolidated-test-');
+    ensureIdeasDirs(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('IDEA_STATES includes consolidated', () => {
+    assert.ok(IDEA_STATES.includes('consolidated'), 'IDEA_STATES should include "consolidated"');
+    assert.strictEqual(IDEA_STATES.length, 4, 'IDEA_STATES should have 4 entries');
+  });
+
+  it('ensureIdeasDirs creates consolidated/ directory', () => {
+    const consolidatedDir = path.join(tmpDir, '.planning', 'ideas', 'consolidated');
+    assert.ok(fs.existsSync(consolidatedDir), 'consolidated/ directory should exist');
+  });
+
+  it('findIdeaFile returns state "consolidated" for idea in consolidated/', () => {
+    createIdeaInState(tmpDir, 'consolidated', 10, 'Test Consolidated');
+    const idea = findIdeaFile(tmpDir, '10');
+    assert.ok(idea, 'findIdeaFile should return a result');
+    assert.strictEqual(idea.state, 'consolidated');
+  });
+});
+
+// ─── buildIdeaContent consolidation fields ──────────────────────────────────
+
+describe('buildIdeaContent consolidation fields', () => {
+  it('emits consolidated_from array in frontmatter', () => {
+    const fm = {
+      id: 5,
+      title: 'Consolidated Idea',
+      tags: ['infra'],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: ['001', '042', '003'],
+    };
+    const content = buildIdeaContent(fm, 'Body text.\n');
+    assert.ok(content.includes('consolidated_from: ["001", "042", "003"]'),
+      'Should emit consolidated_from array');
+  });
+
+  it('emits consolidated_into string in frontmatter', () => {
+    const fm = {
+      id: 1,
+      title: 'Source Idea',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_into: '005',
+    };
+    const content = buildIdeaContent(fm, 'Body text.\n');
+    assert.ok(content.includes('consolidated_into: "005"'),
+      'Should emit consolidated_into string');
+  });
+
+  it('omits consolidation fields when not present', () => {
+    const fm = {
+      id: 1,
+      title: 'Normal Idea',
+      tags: ['feature'],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+    };
+    const content = buildIdeaContent(fm, 'Body text.\n');
+    assert.ok(!content.includes('consolidated_from'),
+      'Should not include consolidated_from');
+    assert.ok(!content.includes('consolidated_into'),
+      'Should not include consolidated_into');
+  });
+
+  it('emits both consolidation fields when both present', () => {
+    const fm = {
+      id: 5,
+      title: 'Both Fields Idea',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: ['001', '002'],
+      consolidated_into: '010',
+    };
+    const content = buildIdeaContent(fm, 'Body.\n');
+    assert.ok(content.includes('consolidated_from: ["001", "002"]'),
+      'Should emit consolidated_from');
+    assert.ok(content.includes('consolidated_into: "010"'),
+      'Should emit consolidated_into');
+  });
+
+  it('omits consolidated_from when array is empty', () => {
+    const fm = {
+      id: 1,
+      title: 'Empty Array',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: [],
+    };
+    const content = buildIdeaContent(fm, 'Body.\n');
+    assert.ok(!content.includes('consolidated_from'),
+      'Should not emit consolidated_from for empty array');
+  });
+});
+
+// ─── parseIdeaFrontmatter consolidation fields ──────────────────────────────
+
+describe('parseIdeaFrontmatter consolidation fields', () => {
+  it('parses consolidated_from array', () => {
+    const content = [
+      '---',
+      'id: 5',
+      'title: "Consolidated Idea"',
+      'tags: ["infra"]',
+      'created: 2026-03-01T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      'consolidated_from: ["001", "042", "003"]',
+      '---',
+      '',
+      'Body.',
+      ''
+    ].join('\n');
+    const result = parseIdeaFrontmatter(content);
+    assert.deepStrictEqual(result.frontmatter.consolidated_from, ['001', '042', '003']);
+  });
+
+  it('parses consolidated_into string', () => {
+    const content = [
+      '---',
+      'id: 1',
+      'title: "Source Idea"',
+      'tags: []',
+      'created: 2026-03-01T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      'consolidated_into: "005"',
+      '---',
+      '',
+      'Body.',
+      ''
+    ].join('\n');
+    const result = parseIdeaFrontmatter(content);
+    assert.strictEqual(result.frontmatter.consolidated_into, '005');
+  });
+
+  it('parses idea with both consolidation fields', () => {
+    const content = [
+      '---',
+      'id: 5',
+      'title: "Both Fields"',
+      'tags: []',
+      'created: 2026-03-01T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      'consolidated_from: ["001", "002"]',
+      'consolidated_into: "010"',
+      '---',
+      '',
+      'Body.',
+      ''
+    ].join('\n');
+    const result = parseIdeaFrontmatter(content);
+    assert.deepStrictEqual(result.frontmatter.consolidated_from, ['001', '002']);
+    assert.strictEqual(result.frontmatter.consolidated_into, '010');
+  });
+
+  it('handles idea with neither consolidation field (backward compat)', () => {
+    const content = [
+      '---',
+      'id: 1',
+      'title: "Normal Idea"',
+      'tags: ["feature"]',
+      'created: 2026-03-01T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      '---',
+      '',
+      'Body.',
+      ''
+    ].join('\n');
+    const result = parseIdeaFrontmatter(content);
+    assert.strictEqual(result.frontmatter.consolidated_from, undefined);
+    assert.strictEqual(result.frontmatter.consolidated_into, undefined);
+    assert.strictEqual(result.frontmatter.title, 'Normal Idea');
+  });
+});
+
+// ─── Round-trip tests ────────────────────────────────────────────────────────
+
+describe('consolidation round-trip', () => {
+  it('consolidated idea round-trips through parse+build without data loss', () => {
+    const original = [
+      '---',
+      'id: 5',
+      'title: "Unified Monitoring"',
+      'tags: ["infra", "monitoring"]',
+      'created: 2026-02-15T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      'author: "Alice <alice@example.com>"',
+      'consolidated_from: ["001", "042", "003"]',
+      '---',
+      '',
+      '*Consolidated from ideas: #001 (Logging Pipeline), #042 (Alert System), #003 (Metrics Dashboard)*',
+      '',
+      'A unified monitoring approach combining logging, alerting, and dashboards.',
+      '',
+      '## Discussion Log',
+      '',
+      '### [from #042] Discussion — 2026-02-15',
+      '',
+      '**Key Insights:** Alerts need correlation',
+      '**Refined Problem:** Alert fatigue from uncorrelated events',
+      '**Refined Approach:** Correlation engine with ML',
+      '**Open Questions:** Budget for ML infrastructure?',
+      '**Decision:** Proceed with rule-based first',
+      '',
+      '## Research Log',
+      '',
+      '### [from #001] Research — 2026-02-10',
+      '',
+      '**Summary:** Evaluated ELK stack vs Loki',
+      '**Key Findings:** Loki is cheaper at scale',
+      '**Recommendation:** Start with Loki',
+      '**Document:** research-logging-2026.md',
+      '**Outcome:** Adopted Loki for logging',
+      ''
+    ].join('\n');
+
+    const parsed = parseIdeaFrontmatter(original);
+
+    // Verify key fields parsed correctly
+    assert.strictEqual(parsed.frontmatter.id, 5);
+    assert.strictEqual(parsed.frontmatter.title, 'Unified Monitoring');
+    assert.deepStrictEqual(parsed.frontmatter.consolidated_from, ['001', '042', '003']);
+    assert.ok(parsed.body.includes('Consolidated from ideas'));
+    assert.ok(parsed.discussionLog.includes('[from #042]'));
+    assert.ok(parsed.researchLog.includes('[from #001]'));
+
+    // Round-trip: build from parsed parts
+    const rebuilt = buildIdeaContent(
+      parsed.frontmatter, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog
+    );
+
+    // Parse again from rebuilt content
+    const reparsed = parseIdeaFrontmatter(rebuilt);
+
+    // Verify all fields survive the round-trip
+    assert.strictEqual(reparsed.frontmatter.id, 5);
+    assert.strictEqual(reparsed.frontmatter.title, 'Unified Monitoring');
+    assert.deepStrictEqual(reparsed.frontmatter.tags, ['infra', 'monitoring']);
+    assert.deepStrictEqual(reparsed.frontmatter.consolidated_from, ['001', '042', '003']);
+    assert.strictEqual(reparsed.frontmatter.author, 'Alice <alice@example.com>');
+    assert.ok(reparsed.body.includes('Consolidated from ideas'));
+    assert.ok(reparsed.discussionLog.includes('[from #042]'));
+    assert.ok(reparsed.researchLog.includes('[from #001]'));
+  });
+
+  it('source idea round-trips with consolidated_into field', () => {
+    const original = [
+      '---',
+      'id: 1',
+      'title: "Logging Pipeline"',
+      'tags: ["infra"]',
+      'created: 2026-01-01T00:00:00Z',
+      'updated: 2026-03-01T00:00:00Z',
+      'consolidated_into: "005"',
+      '---',
+      '',
+      'Original logging idea, now consolidated into #005.',
+      ''
+    ].join('\n');
+
+    const parsed = parseIdeaFrontmatter(original);
+    assert.strictEqual(parsed.frontmatter.consolidated_into, '005');
+
+    const rebuilt = buildIdeaContent(
+      parsed.frontmatter, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog
+    );
+    const reparsed = parseIdeaFrontmatter(rebuilt);
+
+    assert.strictEqual(reparsed.frontmatter.consolidated_into, '005');
+    assert.strictEqual(reparsed.frontmatter.title, 'Logging Pipeline');
+    assert.ok(reparsed.body.includes('consolidated into #005'));
+  });
+
+  it('existing idea without consolidation fields round-trips unchanged', () => {
+    const original = [
+      '---',
+      'id: 10',
+      'title: "Regular Feature"',
+      'tags: ["feature", "ui"]',
+      'created: 2026-01-15T00:00:00Z',
+      'updated: 2026-02-20T00:00:00Z',
+      'author: "Bob <bob@example.com>"',
+      'updated_by: "Carol <carol@example.com>"',
+      '---',
+      '',
+      'A regular feature idea with no consolidation.',
+      '',
+      '## Notes',
+      '',
+      '---',
+      '**2026-02-20:** Added implementation details',
+      ''
+    ].join('\n');
+
+    const parsed = parseIdeaFrontmatter(original);
+
+    // Verify no consolidation fields
+    assert.strictEqual(parsed.frontmatter.consolidated_from, undefined);
+    assert.strictEqual(parsed.frontmatter.consolidated_into, undefined);
+
+    const rebuilt = buildIdeaContent(
+      parsed.frontmatter, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog
+    );
+    const reparsed = parseIdeaFrontmatter(rebuilt);
+
+    // All original fields preserved
+    assert.strictEqual(reparsed.frontmatter.id, 10);
+    assert.strictEqual(reparsed.frontmatter.title, 'Regular Feature');
+    assert.deepStrictEqual(reparsed.frontmatter.tags, ['feature', 'ui']);
+    assert.strictEqual(reparsed.frontmatter.author, 'Bob <bob@example.com>');
+    assert.strictEqual(reparsed.frontmatter.updated_by, 'Carol <carol@example.com>');
+    assert.ok(reparsed.body.includes('regular feature idea'));
+    assert.ok(reparsed.notes.includes('Added implementation details'));
+
+    // No consolidation fields appeared
+    assert.strictEqual(reparsed.frontmatter.consolidated_from, undefined);
+    assert.strictEqual(reparsed.frontmatter.consolidated_into, undefined);
+    assert.ok(!rebuilt.includes('consolidated_from'));
+    assert.ok(!rebuilt.includes('consolidated_into'));
+  });
+
+  it('body with provenance line survives round-trip', () => {
+    const fm = {
+      id: 5,
+      title: 'Consolidated Idea',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: ['001', '042'],
+    };
+    const body = '*Consolidated from ideas: #001 (Logging Pipeline), #042 (Alert System)*\n\nMerged approach.\n';
+    const content = buildIdeaContent(fm, body);
+    const parsed = parseIdeaFrontmatter(content);
+    assert.ok(parsed.body.includes('Consolidated from ideas: #001'));
+    assert.ok(parsed.body.includes('#042 (Alert System)'));
+  });
+
+  it('discussion log with [from #ID] headings survives round-trip', () => {
+    const fm = {
+      id: 5,
+      title: 'Consolidated Idea',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: ['042'],
+    };
+    const discussionLog = '### [from #042] Discussion — 2026-02-15\n\n**Key Insights:** Important finding\n**Refined Problem:** Updated problem\n**Refined Approach:** New approach\n**Open Questions:** None\n**Decision:** Go ahead\n\n';
+    const content = buildIdeaContent(fm, 'Body.\n', '', discussionLog, '');
+    const parsed = parseIdeaFrontmatter(content);
+    assert.ok(parsed.discussionLog.includes('[from #042] Discussion'));
+    assert.ok(parsed.discussionLog.includes('Important finding'));
+  });
+
+  it('research log with [from #ID] headings survives round-trip', () => {
+    const fm = {
+      id: 5,
+      title: 'Consolidated Idea',
+      tags: [],
+      created: '2026-03-01T00:00:00Z',
+      updated: '2026-03-01T00:00:00Z',
+      consolidated_from: ['001'],
+    };
+    const researchLog = '### [from #001] Research — 2026-02-10\n\n**Summary:** Research summary\n**Key Findings:** Key finding\n**Recommendation:** Do this\n**Document:** doc.md\n**Outcome:** Done\n\n';
+    const content = buildIdeaContent(fm, 'Body.\n', '', '', researchLog);
+    const parsed = parseIdeaFrontmatter(content);
+    assert.ok(parsed.researchLog.includes('[from #001] Research'));
+    assert.ok(parsed.researchLog.includes('Research summary'));
+  });
+});
+
+// ─── cmdIdeasReject guard messages ───────────────────────────────────────────
+
+describe('cmdIdeasReject guard messages', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-reject-test-');
+    ensureIdeasDirs(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('errors with "already rejected" when rejecting a rejected idea', () => {
+    createIdeaInState(tmpDir, 'rejected', 1, 'Already Rejected');
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasReject('${escapedCwd}', '1', null, false)"`,
+        { cwd: path.join(__dirname), stderr: 'pipe', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('already rejected'),
+        `Expected "already rejected" in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('errors with "only pending ideas can be rejected" when rejecting a done idea', () => {
+    createIdeaInState(tmpDir, 'done', 2, 'Done Idea');
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasReject('${escapedCwd}', '2', null, false)"`,
+        { cwd: path.join(__dirname), stderr: 'pipe', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('only pending ideas can be rejected'),
+        `Expected "only pending ideas can be rejected" in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('errors with "idea not found" for nonexistent idea', () => {
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasReject('${escapedCwd}', '999', null, false)"`,
+        { cwd: path.join(__dirname), stderr: 'pipe', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('idea not found'),
+        `Expected "idea not found" in stderr, got: ${stderr}`
+      );
+    }
+  });
+});
+
+// ─── Root Layout ───────────────────────────────────────────────────────────────
+
+describe('ideas root layout', () => {
+  let fixture;
+  afterEach(() => { if (fixture) fixture.cleanup(); });
+
+  it('ensureIdeasDirs creates directories at root (not under .planning/)', () => {
+    fixture = createTempProject({ layout: 'root' });
+    ensureIdeasDirs(fixture.cwd);
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'ideas', 'pending')),
+      'ideas/pending should exist at root');
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'ideas', 'done')),
+      'ideas/done should exist at root');
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'ideas', 'rejected')),
+      'ideas/rejected should exist at root');
+    assert.ok(fs.existsSync(path.join(fixture.cwd, 'ideas', 'consolidated')),
+      'ideas/consolidated should exist at root');
+    assert.ok(!fs.existsSync(path.join(fixture.cwd, '.planning', 'ideas')),
+      '.planning/ideas should NOT exist in root layout');
+  });
+
+  it('findIdeaFile resolves ideas at root in root layout', () => {
+    fixture = createTempProject({ layout: 'root' });
+    // Create an idea directly at root/ideas/pending/
+    const ideasDir = path.join(fixture.cwd, 'ideas', 'pending');
+    fs.mkdirSync(ideasDir, { recursive: true });
+    const content = '---\nid: 1\ntitle: "Root Idea"\n---\n\nBody.\n';
+    fs.writeFileSync(path.join(ideasDir, '001-root-idea.md'), content, 'utf-8');
+
+    const idea = findIdeaFile(fixture.cwd, '1');
+    assert.ok(idea, 'findIdeaFile should find the idea in root layout');
+    assert.strictEqual(idea.state, 'pending');
+    assert.strictEqual(idea.filename, '001-root-idea.md');
+  });
+
+  it('loadManifest reads from root/ideas/manifest.json in root layout', () => {
+    fixture = createTempProject({ layout: 'root' });
+    const ideasDir = path.join(fixture.cwd, 'ideas');
+    fs.mkdirSync(ideasDir, { recursive: true });
+    fs.writeFileSync(path.join(ideasDir, 'manifest.json'), '{"next_id": 5}\n', 'utf-8');
+
+    const manifest = loadManifest(fixture.cwd);
+    assert.strictEqual(manifest.next_id, 5);
+  });
+});
+
+// ─── cmdIdeasConsolidate ──────────────────────────────────────────────────────
+
+describe('cmdIdeasConsolidate', () => {
+  let tmpDir;
+
+  /**
+   * Creates a pending idea file with proper frontmatter and updates the manifest.
+   */
+  function createPendingIdea(dir, id, title, tags = []) {
+    const paddedId = String(id).padStart(3, '0');
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const filename = `${paddedId}-${slug}.md`;
+    const now = new Date().toISOString();
+    const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+    const content = `---\nid: ${id}\ntitle: "${title}"\ntags: ${tagsStr}\ncreated: ${now}\nupdated: ${now}\n---\n\n${title} body.\n`;
+    const dir2 = path.join(dir, '.planning', 'ideas', 'pending');
+    fs.mkdirSync(dir2, { recursive: true });
+    fs.writeFileSync(path.join(dir2, filename), content, 'utf-8');
+    // Update manifest so allocateId returns next ID correctly
+    const manifestDir = path.join(dir, '.planning', 'ideas');
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = { next_id: 1 };
+    }
+    if (id >= manifest.next_id) {
+      manifest.next_id = id + 1;
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf-8');
+    return filename;
+  }
+
+  /**
+   * Creates an idea in a specified state directory with manifest update.
+   */
+  function createIdeaInStateCons(dir, id, title, state) {
+    const paddedId = String(id).padStart(3, '0');
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const filename = `${paddedId}-${slug}.md`;
+    const now = new Date().toISOString();
+    const content = `---\nid: ${id}\ntitle: "${title}"\ntags: []\ncreated: ${now}\nupdated: ${now}\n---\n\n${title} body.\n`;
+    const stateDir = path.join(dir, '.planning', 'ideas', state);
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, filename), content, 'utf-8');
+    const manifestDir = path.join(dir, '.planning', 'ideas');
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = { next_id: 1 };
+    }
+    if (id >= manifest.next_id) {
+      manifest.next_id = id + 1;
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf-8');
+    return filename;
+  }
+
+  /**
+   * Initializes a git repo with all IDEA_STATES directories and initial commit.
+   */
+  function initLocalGitRepo(dir) {
+    execSync('git init', { cwd: dir, stdio: 'pipe' });
+    execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'pipe' });
+    execSync('git config user.name "Test"', { cwd: dir, stdio: 'pipe' });
+    for (const state of ['pending', 'done', 'rejected', 'consolidated']) {
+      const stateDir = path.join(dir, '.planning', 'ideas', state);
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, '.gitkeep'), '', 'utf-8');
+    }
+    execSync('git add -A && git commit -m "init"', { cwd: dir, stdio: 'pipe' });
+  }
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-consolidate-test-');
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('consolidates 2 pending ideas into new idea', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Add retry logic', ['api']);
+    createPendingIdea(tmpDir, 2, 'Add timeout handling', ['api', 'reliability']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    // Call cmdIdeasConsolidate via subprocess to handle process.exit
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Resilient API calls' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result);
+
+    // New idea created in pending/
+    assert.strictEqual(json.id, 3);
+    assert.ok(json.filename.includes('resilient-api-calls'));
+    assert.deepStrictEqual(json.consolidated_from, ['001', '002']);
+    assert.strictEqual(json.moved_files.length, 2);
+
+    // Source ideas moved to consolidated/
+    const consolidatedDir = path.join(tmpDir, '.planning', 'ideas', 'consolidated');
+    const pendingDir = path.join(tmpDir, '.planning', 'ideas', 'pending');
+    const consolidatedFiles = fs.readdirSync(consolidatedDir).filter(f => f.endsWith('.md'));
+    assert.strictEqual(consolidatedFiles.length, 2);
+
+    // New idea still in pending/
+    const pendingFiles = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    assert.strictEqual(pendingFiles.length, 1);
+    assert.ok(pendingFiles[0].includes('resilient-api-calls'));
+
+    // Source ideas have consolidated_into set
+    for (const f of consolidatedFiles) {
+      const content = fs.readFileSync(path.join(consolidatedDir, f), 'utf-8');
+      assert.ok(content.includes('consolidated_into'), `${f} should have consolidated_into`);
+    }
+  });
+
+  it('rejects when source ID not found', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea one');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,99', title: 'Combined' }, false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(stderr.includes('idea not found: 99'), `Expected "idea not found: 99" in stderr, got: ${stderr}`);
+    }
+  });
+
+  it('rejects when source idea not in pending state', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea one');
+    createIdeaInStateCons(tmpDir, 2, 'Idea two', 'done');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Combined' }, false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('idea 2 is not in pending state (current: done)'),
+        `Expected state error in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('rejects when fewer than 2 IDs provided', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Solo idea');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1', title: 'Solo' }, false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('at least 2 idea IDs required'),
+        `Expected IDs error in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('rejects when title missing', () => {
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2' }, false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('title required'),
+        `Expected title error in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('merges tags from all sources with deduplication', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea A', ['api', 'auth']);
+    createPendingIdea(tmpDir, 2, 'Idea B', ['api', 'ui']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Unified', tags: 'performance' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result);
+
+    // Read the new idea file to check tags
+    const newIdeaPath = path.join(tmpDir, '.planning', 'ideas', 'pending', json.filename);
+    const content = fs.readFileSync(newIdeaPath, 'utf-8');
+    const parsed = parseIdeaFrontmatter(content);
+    const tags = parsed.frontmatter.tags;
+
+    assert.ok(tags.includes('api'), 'should include api');
+    assert.ok(tags.includes('auth'), 'should include auth');
+    assert.ok(tags.includes('ui'), 'should include ui');
+    assert.ok(tags.includes('performance'), 'should include performance');
+    // Deduplication: api should appear only once
+    assert.strictEqual(tags.filter(t => t === 'api').length, 1, 'api should not be duplicated');
+  });
+
+  it('creates atomic git commit with correct message format', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'First idea');
+    createPendingIdea(tmpDir, 2, 'Second idea');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Combined ideas' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+
+    const log = execSync('git log -1 --oneline', { cwd: tmpDir, encoding: 'utf-8' }).trim();
+    assert.ok(
+      log.includes('ideas: consolidate #1, #2 -> #3 - Combined ideas'),
+      `Expected commit message format, got: ${log}`
+    );
+  });
+
+  it('passes discussion and research through to new idea', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Discuss idea');
+    createPendingIdea(tmpDir, 2, 'Research idea');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const discussion = '### [from #1] Discussion -- 2026-03-10\\n\\n**Key Insights:** Important\\n';
+    const research = '### [from #2] Research -- 2026-03-10\\n\\n**Summary:** Found stuff\\n';
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'With logs', discussion: '${discussion}', research: '${research}' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result);
+
+    const newIdeaPath = path.join(tmpDir, '.planning', 'ideas', 'pending', json.filename);
+    const content = fs.readFileSync(newIdeaPath, 'utf-8');
+    assert.ok(content.includes('## Discussion Log'), 'should have Discussion Log section');
+    assert.ok(content.includes('## Research Log'), 'should have Research Log section');
+  });
+
+  it('appends consolidation note to each source before moving', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Source one');
+    createPendingIdea(tmpDir, 2, 'Source two');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Merged result' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+
+    // Check sources in consolidated/ have consolidation notes
+    const consolidatedDir = path.join(tmpDir, '.planning', 'ideas', 'consolidated');
+    const files = fs.readdirSync(consolidatedDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      const content = fs.readFileSync(path.join(consolidatedDir, f), 'utf-8');
+      assert.ok(
+        content.includes('Consolidated into #'),
+        `${f} should have consolidation note`
+      );
+      assert.ok(
+        content.includes('Merged result'),
+        `${f} consolidation note should mention new idea title`
+      );
+    }
+  });
+
+  it('returns structured JSON with new ID, path, and moved files', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Alpha');
+    createPendingIdea(tmpDir, 2, 'Beta');
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2', title: 'Combined' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result);
+
+    assert.strictEqual(typeof json.id, 'number');
+    assert.ok(json.filename);
+    assert.ok(json.path);
+    assert.ok(json.title);
+    assert.ok(Array.isArray(json.consolidated_from));
+    assert.ok(Array.isArray(json.moved_files));
+    assert.strictEqual(json.moved_files.length, 2);
+    for (const m of json.moved_files) {
+      assert.strictEqual(m.from, 'pending');
+      assert.strictEqual(m.to, 'consolidated');
+      assert.ok(m.filename);
+      assert.ok(typeof m.id === 'number');
+    }
+  });
+
+  it('consolidates 3 pending ideas with tag union', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea X', ['api']);
+    createPendingIdea(tmpDir, 2, 'Idea Y', ['api', 'db']);
+    createPendingIdea(tmpDir, 3, 'Idea Z', ['ui']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '1,2,3', title: 'Triple merge' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result);
+
+    assert.strictEqual(json.id, 4);
+    assert.deepStrictEqual(json.consolidated_from, ['001', '002', '003']);
+    assert.strictEqual(json.moved_files.length, 3);
+
+    // Check tags on new idea
+    const newIdeaPath = path.join(tmpDir, '.planning', 'ideas', 'pending', json.filename);
+    const content = fs.readFileSync(newIdeaPath, 'utf-8');
+    const parsed = parseIdeaFrontmatter(content);
+    assert.ok(parsed.frontmatter.tags.includes('api'));
+    assert.ok(parsed.frontmatter.tags.includes('db'));
+    assert.ok(parsed.frontmatter.tags.includes('ui'));
+    assert.strictEqual(parsed.frontmatter.tags.filter(t => t === 'api').length, 1);
+  });
+});
+
+// ─── cmdIdeasFindRelated ──────────────────────────────────────────────────────
+
+describe('cmdIdeasFindRelated', () => {
+  let tmpDir;
+
+  /**
+   * Creates a pending idea file with proper frontmatter and updates the manifest.
+   */
+  function createPendingIdea(dir, id, title, tags = [], body = '') {
+    const paddedId = String(id).padStart(3, '0');
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const filename = `${paddedId}-${slug}.md`;
+    const now = new Date().toISOString();
+    const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+    const content = `---\nid: ${id}\ntitle: "${title}"\ntags: ${tagsStr}\ncreated: ${now}\nupdated: ${now}\n---\n\n${body || title + ' body.'}\n`;
+    const dir2 = path.join(dir, '.planning', 'ideas', 'pending');
+    fs.mkdirSync(dir2, { recursive: true });
+    fs.writeFileSync(path.join(dir2, filename), content, 'utf-8');
+    // Update manifest so allocateId returns next ID correctly
+    const manifestDir = path.join(dir, '.planning', 'ideas');
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = { next_id: 1 };
+    }
+    if (id >= manifest.next_id) {
+      manifest.next_id = id + 1;
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf-8');
+    return filename;
+  }
+
+  /**
+   * Creates an idea in a specified state directory with manifest update.
+   */
+  function createIdeaInStateHelper(dir, id, title, state, tags = []) {
+    const paddedId = String(id).padStart(3, '0');
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const filename = `${paddedId}-${slug}.md`;
+    const now = new Date().toISOString();
+    const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+    const content = `---\nid: ${id}\ntitle: "${title}"\ntags: ${tagsStr}\ncreated: ${now}\nupdated: ${now}\n---\n\n${title} body.\n`;
+    const stateDir = path.join(dir, '.planning', 'ideas', state);
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, filename), content, 'utf-8');
+    const manifestDir = path.join(dir, '.planning', 'ideas');
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = { next_id: 1 };
+    }
+    if (id >= manifest.next_id) {
+      manifest.next_id = id + 1;
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf-8');
+    return filename;
+  }
+
+  /**
+   * Captures stdout from a function call (for raw=true JSON output).
+   */
+  function captureOutput(fn) {
+    const orig = process.stdout.write;
+    let captured = '';
+    process.stdout.write = function (chunk) {
+      captured += chunk;
+    };
+    try {
+      fn();
+    } finally {
+      process.stdout.write = orig;
+    }
+    return captured.trim();
+  }
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-find-related-test-');
+    ensureIdeasDirs(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('returns empty results when only the anchor idea exists', () => {
+    createPendingIdea(tmpDir, 1, 'Solo idea', ['api', 'reliability']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    assert.strictEqual(result.anchor.id, 1);
+    assert.strictEqual(result.results.length, 0);
+    assert.deepStrictEqual(result.counts, { high: 0, medium: 0, low: 0, total: 0 });
+  });
+
+  it('scores HIGH for ideas sharing all tags', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability']);
+    createPendingIdea(tmpDir, 2, 'Related idea', ['api', 'reliability']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    assert.strictEqual(result.results.length, 1);
+    assert.strictEqual(result.results[0].id, 2);
+    assert.strictEqual(result.results[0].match_level, 'HIGH');
+    assert.deepStrictEqual(result.results[0].tag_overlap.shared.sort(), ['api', 'reliability']);
+    assert.strictEqual(result.results[0].tag_overlap.ratio, 1.0);
+  });
+
+  it('scores MEDIUM for ideas sharing some tags', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability', 'error-handling']);
+    createPendingIdea(tmpDir, 2, 'Partial match', ['api', 'frontend']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    assert.strictEqual(result.results.length, 1);
+    assert.strictEqual(result.results[0].match_level, 'MEDIUM');
+    // Jaccard: 1 shared (api) / 4 union (api, reliability, error-handling, frontend) = 0.25
+    const ratio = result.results[0].tag_overlap.ratio;
+    assert.ok(ratio >= 0.2 && ratio < 0.5, `Expected MEDIUM ratio between 0.2 and 0.5, got ${ratio}`);
+  });
+
+  it('scores LOW for ideas sharing one tag out of many', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability', 'error-handling', 'monitoring']);
+    createPendingIdea(tmpDir, 2, 'Barely matching', ['api', 'frontend', 'design', 'ux']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    assert.strictEqual(result.results.length, 1);
+    assert.strictEqual(result.results[0].match_level, 'LOW');
+    // Jaccard: 1 shared (api) / 7 union = ~0.143
+    const ratio = result.results[0].tag_overlap.ratio;
+    assert.ok(ratio > 0 && ratio < 0.2, `Expected LOW ratio between 0 and 0.2, got ${ratio}`);
+  });
+
+  it('threshold=medium filters out LOW matches', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability']);
+    createPendingIdea(tmpDir, 2, 'No overlap', ['frontend']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'medium' }, true);
+    });
+    const result = JSON.parse(output);
+    // No shared tags -> NONE level -> filtered out even at 'low' threshold,
+    // but certainly at 'medium'
+    assert.strictEqual(result.results.length, 0);
+  });
+
+  it('threshold=high filters out MEDIUM and LOW matches', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability', 'error-handling']);
+    createPendingIdea(tmpDir, 2, 'Medium match', ['api', 'frontend']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'high' }, true);
+    });
+    const result = JSON.parse(output);
+    // Jaccard: 1/4 = 0.25 -> MEDIUM, should be filtered at threshold=high
+    assert.strictEqual(result.results.length, 0);
+  });
+
+  it('includes idea content in results for AI scoring', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api']);
+    createPendingIdea(tmpDir, 2, 'Content idea', ['api'], 'Detailed body about the API.');
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    assert.strictEqual(result.results.length, 1);
+    const item = result.results[0];
+    assert.ok('title' in item, 'result should include title');
+    assert.ok('tags' in item, 'result should include tags');
+    assert.ok('body' in item, 'result should include body');
+    assert.ok('notes' in item, 'result should include notes');
+    assert.ok('discussion_log' in item, 'result should include discussion_log');
+    assert.ok('research_log' in item, 'result should include research_log');
+  });
+
+  it('excludes non-pending ideas', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api']);
+    createIdeaInStateHelper(tmpDir, 2, 'Done idea', 'done', ['api']);
+    createPendingIdea(tmpDir, 3, 'Another pending', ['api']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    // Only idea 3 should appear (idea 2 is done, excluded)
+    assert.strictEqual(result.results.length, 1);
+    assert.strictEqual(result.results[0].id, 3);
+  });
+
+  it('errors when anchor idea not found', () => {
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasFindRelated('${escapedCwd}', { id: '999', threshold: 'low' }, true)"`,
+        { cwd: path.join(__dirname), stderr: 'pipe', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('not found'),
+        `Expected "not found" in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('groups results by match level in output sorted HIGH first', () => {
+    createPendingIdea(tmpDir, 1, 'Anchor idea', ['api', 'reliability']);
+    createPendingIdea(tmpDir, 2, 'High match', ['api', 'reliability']);
+    createPendingIdea(tmpDir, 3, 'Medium match', ['api', 'frontend', 'design']);
+    createPendingIdea(tmpDir, 4, 'Low match', ['frontend']);
+    const output = captureOutput(() => {
+      cmdIdeasFindRelated(tmpDir, { id: '1', threshold: 'low' }, true);
+    });
+    const result = JSON.parse(output);
+    // Idea 2: HIGH (2/2 = 1.0), Idea 3: MEDIUM (1/4 = 0.25), Idea 4: no overlap -> excluded
+    // Only ideas with overlap > 0 are included
+    const levels = result.results.map(r => r.match_level);
+    // HIGH should come before MEDIUM
+    const highIdx = levels.indexOf('HIGH');
+    const medIdx = levels.indexOf('MEDIUM');
+    if (highIdx !== -1 && medIdx !== -1) {
+      assert.ok(highIdx < medIdx, `HIGH (${highIdx}) should come before MEDIUM (${medIdx})`);
+    }
+    // Every result should have a match_level field
+    for (const r of result.results) {
+      assert.ok(['HIGH', 'MEDIUM', 'LOW'].includes(r.match_level),
+        `match_level should be HIGH, MEDIUM, or LOW, got: ${r.match_level}`);
+    }
+  });
+});
+
+// ─── cmdIdeasUndoConsolidation ────────────────────────────────────────────────
+
+describe('cmdIdeasUndoConsolidation', () => {
+  let tmpDir;
+
+  /**
+   * Creates a pending idea file with proper frontmatter and updates the manifest.
+   */
+  function createPendingIdea(dir, id, title, tags = []) {
+    const paddedId = String(id).padStart(3, '0');
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const filename = `${paddedId}-${slug}.md`;
+    const now = new Date().toISOString();
+    const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+    const content = `---\nid: ${id}\ntitle: "${title}"\ntags: ${tagsStr}\ncreated: ${now}\nupdated: ${now}\n---\n\n${title} body.\n`;
+    const dir2 = path.join(dir, '.planning', 'ideas', 'pending');
+    fs.mkdirSync(dir2, { recursive: true });
+    fs.writeFileSync(path.join(dir2, filename), content, 'utf-8');
+    // Update manifest so allocateId returns next ID correctly
+    const manifestDir = path.join(dir, '.planning', 'ideas');
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = { next_id: 1 };
+    }
+    if (id >= manifest.next_id) {
+      manifest.next_id = id + 1;
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf-8');
+    return filename;
+  }
+
+  /**
+   * Initializes a git repo with all IDEA_STATES directories and initial commit.
+   */
+  function initLocalGitRepo(dir) {
+    execSync('git init', { cwd: dir, stdio: 'pipe' });
+    execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'pipe' });
+    execSync('git config user.name "Test"', { cwd: dir, stdio: 'pipe' });
+    for (const state of ['pending', 'done', 'rejected', 'consolidated']) {
+      const stateDir = path.join(dir, '.planning', 'ideas', state);
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, '.gitkeep'), '', 'utf-8');
+    }
+    execSync('git add -A && git commit -m "init"', { cwd: dir, stdio: 'pipe' });
+  }
+
+  /**
+   * Consolidates ideas via subprocess (since it calls process.exit) and returns parsed JSON.
+   */
+  function consolidateViaSubprocess(dir, ids, title) {
+    const escapedCwd = dir.replace(/'/g, "\\'");
+    const result = execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasConsolidate('${escapedCwd}', { ids: '${ids}', title: '${title}' }, false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    return JSON.parse(result);
+  }
+
+  /**
+   * Calls cmdIdeasUndoConsolidation via subprocess (since it calls process.exit).
+   */
+  function undoViaSubprocess(dir, id) {
+    const escapedCwd = dir.replace(/'/g, "\\'");
+    return execSync(
+      `node -e "require('./ideas.cjs').cmdIdeasUndoConsolidation('${escapedCwd}', '${id}', false, null)"`,
+      { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+  }
+
+  beforeEach(() => {
+    tmpDir = createTempDir('ideas-undo-consolidation-test-');
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('undoes consolidation and restores source ideas to pending', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea Alpha', ['api']);
+    createPendingIdea(tmpDir, 2, 'Idea Beta', ['api', 'ui']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    // Consolidate ideas 1 and 2 into idea 3
+    consolidateViaSubprocess(tmpDir, '1,2', 'Merged Alpha Beta');
+
+    // Undo the consolidation
+    undoViaSubprocess(tmpDir, '3');
+
+    // Verify: idea 3 no longer exists in pending/
+    const pendingDir = path.join(tmpDir, '.planning', 'ideas', 'pending');
+    const pendingFiles = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    assert.ok(!pendingFiles.some(f => f.startsWith('003')), 'Consolidated idea 3 should be deleted from pending');
+
+    // Verify: ideas 1 and 2 are back in pending/
+    assert.ok(pendingFiles.some(f => f.startsWith('001')), 'Idea 1 should be restored to pending');
+    assert.ok(pendingFiles.some(f => f.startsWith('002')), 'Idea 2 should be restored to pending');
+
+    // Verify: consolidated/ has no idea files
+    const consolidatedDir = path.join(tmpDir, '.planning', 'ideas', 'consolidated');
+    const consolidatedFiles = fs.readdirSync(consolidatedDir).filter(f => f.endsWith('.md'));
+    assert.strictEqual(consolidatedFiles.length, 0, 'consolidated/ should have no idea files');
+  });
+
+  it('removes consolidated_into from restored source ideas', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Idea One', ['api']);
+    createPendingIdea(tmpDir, 2, 'Idea Two', ['db']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    consolidateViaSubprocess(tmpDir, '1,2', 'Combined One Two');
+    undoViaSubprocess(tmpDir, '3');
+
+    // Read each restored source idea and check consolidated_into is gone
+    const pendingDir = path.join(tmpDir, '.planning', 'ideas', 'pending');
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      const content = fs.readFileSync(path.join(pendingDir, f), 'utf-8');
+      const parsed = parseIdeaFrontmatter(content);
+      assert.ok(!('consolidated_into' in parsed.frontmatter),
+        `${f} should NOT have consolidated_into after undo`);
+    }
+  });
+
+  it('restored source ideas do not have consolidated_from', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Source X', ['api']);
+    createPendingIdea(tmpDir, 2, 'Source Y', ['ui']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    consolidateViaSubprocess(tmpDir, '1,2', 'Merged XY');
+    undoViaSubprocess(tmpDir, '3');
+
+    // Restored source ideas should NOT have consolidated_from (they never had it)
+    const pendingDir = path.join(tmpDir, '.planning', 'ideas', 'pending');
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      const content = fs.readFileSync(path.join(pendingDir, f), 'utf-8');
+      const parsed = parseIdeaFrontmatter(content);
+      assert.ok(!('consolidated_from' in parsed.frontmatter),
+        `${f} should NOT have consolidated_from after undo`);
+    }
+  });
+
+  it('returns structured JSON with undo details', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Detail A', ['api']);
+    createPendingIdea(tmpDir, 2, 'Detail B', ['db']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    consolidateViaSubprocess(tmpDir, '1,2', 'Detailed merge');
+    const result = undoViaSubprocess(tmpDir, '3');
+    const json = JSON.parse(result);
+
+    assert.ok('undone_idea_id' in json, 'result should have undone_idea_id');
+    assert.ok(Array.isArray(json.restored_ids), 'result should have restored_ids array');
+    assert.ok('deleted_file' in json, 'result should have deleted_file');
+    assert.strictEqual(json.undone_idea_id, 3);
+    assert.strictEqual(json.restored_ids.length, 2);
+  });
+
+  it('creates atomic git commit', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Commit A', ['api']);
+    createPendingIdea(tmpDir, 2, 'Commit B', ['db']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    consolidateViaSubprocess(tmpDir, '1,2', 'Commit merge');
+    undoViaSubprocess(tmpDir, '3');
+
+    const log = execSync('git log --oneline -1', { cwd: tmpDir, encoding: 'utf-8' }).trim();
+    assert.ok(
+      log.includes('ideas: undo consolidation #3'),
+      `Expected commit message with "ideas: undo consolidation #3", got: ${log}`
+    );
+  });
+
+  it('errors when idea not found', () => {
+    initLocalGitRepo(tmpDir);
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasUndoConsolidation('${escapedCwd}', '999', false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('not found'),
+        `Expected "not found" in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('errors when idea has no consolidated_from', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Plain idea', ['api']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    const escapedCwd = tmpDir.replace(/'/g, "\\'");
+    try {
+      execSync(
+        `node -e "require('./ideas.cjs').cmdIdeasUndoConsolidation('${escapedCwd}', '1', false, null)"`,
+        { cwd: path.join(__dirname), stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      assert.fail('should have exited with error');
+    } catch (err) {
+      const stderr = err.stderr.toString();
+      assert.ok(
+        stderr.includes('not a consolidated idea') || stderr.includes('no consolidated_from'),
+        `Expected consolidation error in stderr, got: ${stderr}`
+      );
+    }
+  });
+
+  it('handles 3+ source ideas', () => {
+    initLocalGitRepo(tmpDir);
+    createPendingIdea(tmpDir, 1, 'Triple A', ['api']);
+    createPendingIdea(tmpDir, 2, 'Triple B', ['db']);
+    createPendingIdea(tmpDir, 3, 'Triple C', ['ui']);
+    execSync('git add -A && git commit -m "add ideas"', { cwd: tmpDir, stdio: 'pipe' });
+
+    // Consolidate all 3 into idea 4
+    consolidateViaSubprocess(tmpDir, '1,2,3', 'Triple merge');
+
+    // Undo the consolidation
+    const result = undoViaSubprocess(tmpDir, '4');
+    const json = JSON.parse(result);
+
+    // All 3 source ideas should be restored to pending
+    const pendingDir = path.join(tmpDir, '.planning', 'ideas', 'pending');
+    const pendingFiles = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    assert.ok(pendingFiles.some(f => f.startsWith('001')), 'Idea 1 should be restored');
+    assert.ok(pendingFiles.some(f => f.startsWith('002')), 'Idea 2 should be restored');
+    assert.ok(pendingFiles.some(f => f.startsWith('003')), 'Idea 3 should be restored');
+
+    // Idea 4 should be deleted
+    assert.ok(!pendingFiles.some(f => f.startsWith('004')), 'Idea 4 should be deleted');
+
+    // JSON should show all 3 restored
+    assert.strictEqual(json.restored_ids.length, 3);
+    assert.strictEqual(json.undone_idea_id, 4);
+  });
+});