@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,1406 @@
+/**
+ * Ideas — Idea capture, CRUD, manifest-based ID allocation, state transitions,
+ * and section-aware parsing/building with Discussion Log and Research Log support.
+ *
+ * Provides the data model and operations for the ideas lifecycle:
+ * create, update, append-note, list, reject, restore, move-state,
+ * discuss-save, research-save, appendDiscussionEntry, and appendResearchEntry.
+ *
+ * Ideas are stored as markdown files with YAML frontmatter in
+ * .planning/ideas/{pending,done,rejected}/ directories.
+ * A manifest.json tracks the next available sequential ID (never reused).
+ *
+ * Section order: Body > ## Notes > ## Discussion Log > ## Research Log
+ * Sections are optional; headings only appear when content exists.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, generateSlugInternal, output, error } = require('./core.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { extractNameFromAuthor } = require('./identity.cjs');
+
+// ─── Manifest Management ─────────────────────────────────────────────────────
+
+/**
+ * Load the ideas manifest from .planning/ideas/manifest.json.
+ * Returns { next_id: N }. If missing, returns { next_id: 1 }.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ next_id: number }}
+ */
+function loadManifest(cwd) {
+  const manifestPath = path.join(getPlanningRoot(cwd), 'ideas', 'manifest.json');
+  const content = safeReadFile(manifestPath);
+  if (!content) return { next_id: 1 };
+  try {
+    const parsed = JSON.parse(content);
+    return { next_id: parsed.next_id || 1 };
+  } catch {
+    return { next_id: 1 };
+  }
+}
+
+/**
+ * Save the ideas manifest to .planning/ideas/manifest.json.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ next_id: number }} manifest
+ */
+function saveManifest(cwd, manifest) {
+  const manifestDir = path.join(getPlanningRoot(cwd), 'ideas');
+  fs.mkdirSync(manifestDir, { recursive: true });
+  const manifestPath = path.join(manifestDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Allocate a new unique ID from the manifest. Increments next_id and saves.
+ * Returns zero-padded 3-digit string (e.g., "001", "042").
+ * IDs are never reused -- next_id only goes up.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Zero-padded ID string
+ */
+function allocateId(cwd) {
+  const manifest = loadManifest(cwd);
+  const id = manifest.next_id;
+  manifest.next_id = id + 1;
+  saveManifest(cwd, manifest);
+  return String(id).padStart(3, '0');
+}
+
+// ─── Directory & File Helpers ─────────────────────────────────────────────────
+
+const IDEA_STATES = ['pending', 'done', 'rejected', 'consolidated'];
+
+/**
+ * Ensure .planning/ideas/{pending,done,rejected}/ directories exist.
+ *
+ * @param {string} cwd - Working directory
+ */
+function ensureIdeasDirs(cwd) {
+  for (const state of IDEA_STATES) {
+    fs.mkdirSync(path.join(getPlanningRoot(cwd), 'ideas', state), { recursive: true });
+  }
+}
+
+/**
+ * Parse YAML frontmatter from idea file content.
+ * Uses simple regex parsing (no YAML library -- zero-dependency project).
+ *
+ * Section-aware: splits content after frontmatter into body, notes,
+ * discussionLog, and researchLog based on H2 markers.
+ * Section markers are case-sensitive: `## Notes`, `## Discussion Log`, `## Research Log`.
+ *
+ * @param {string} content - File content
+ * @returns {{ frontmatter: object, body: string, notes: string, discussionLog: string, researchLog: string }}
+ */
+function parseIdeaFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]+?)\n---\n?([\s\S]*)/);
+  if (!match) return { frontmatter: {}, body: content, notes: '', discussionLog: '', researchLog: '' };
+
+  const yaml = match[1];
+  const remaining = match[2] || '';
+  const frontmatter = {};
+
+  const lines = yaml.split('\n');
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+
+    // Handle array values (tags)
+    const arrayMatch = line.match(/^(\w+):\s*\[([^\]]*)\]/);
+    if (arrayMatch) {
+      const key = arrayMatch[1];
+      const values = arrayMatch[2]
+        .split(',')
+        .map(v => v.trim().replace(/^["']|["']$/g, ''))
+        .filter(v => v !== '');
+      frontmatter[key] = values;
+      continue;
+    }
+
+    // Handle simple key: value
+    const kvMatch = line.match(/^(\w+):\s*(.*)/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      let value = kvMatch[2].trim();
+      // Remove quotes
+      value = value.replace(/^["']|["']$/g, '');
+      // Parse numeric id
+      if (key === 'id') {
+        frontmatter[key] = parseInt(value, 10);
+      } else {
+        frontmatter[key] = value;
+      }
+    }
+  }
+
+  // Split remaining content into sections using H2 markers (case-sensitive)
+  const sectionMarkers = [
+    { key: 'notes', heading: '## Notes' },
+    { key: 'discussionLog', heading: '## Discussion Log' },
+    { key: 'researchLog', heading: '## Research Log' },
+  ];
+
+  // Find position of each marker in the remaining content
+  const positions = [];
+  for (const marker of sectionMarkers) {
+    // Match the heading at the start of a line (after newline or at start)
+    const pattern = new RegExp('(?:^|\\n)(' + marker.heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')\\n');
+    const m = remaining.match(pattern);
+    if (m) {
+      // Find the actual index of the heading in remaining
+      const idx = remaining.indexOf(m[1], m.index);
+      positions.push({ key: marker.key, heading: marker.heading, index: idx });
+    }
+  }
+
+  // Sort positions by index
+  positions.sort((a, b) => a.index - b.index);
+
+  // Extract body (everything before first section marker, or all content if no markers)
+  let body = '';
+  const sections = { notes: '', discussionLog: '', researchLog: '' };
+
+  if (positions.length === 0) {
+    body = remaining;
+  } else {
+    body = remaining.substring(0, positions[0].index);
+    // Extract each section's content
+    for (let i = 0; i < positions.length; i++) {
+      const pos = positions[i];
+      const headingEnd = pos.index + pos.heading.length + 1; // +1 for the newline after heading
+      const nextStart = (i + 1 < positions.length) ? positions[i + 1].index : remaining.length;
+      sections[pos.key] = remaining.substring(headingEnd, nextStart);
+    }
+  }
+
+  // Trim trailing whitespace from sections but preserve internal formatting
+  // Remove leading newline from section content (the one right after the heading)
+  for (const key of Object.keys(sections)) {
+    if (sections[key]) {
+      sections[key] = sections[key].replace(/^\n/, '');
+    }
+  }
+
+  return { frontmatter, body, notes: sections.notes, discussionLog: sections.discussionLog, researchLog: sections.researchLog };
+}
+
+/**
+ * Build idea file content from frontmatter and sections.
+ *
+ * Assembles sections in order: body, ## Notes, ## Discussion Log, ## Research Log.
+ * Section headings are only emitted when the section has non-empty content.
+ *
+ * @param {object} frontmatter - Frontmatter fields
+ * @param {string} body - Body content
+ * @param {string} [notes=''] - Notes section content (without ## Notes heading)
+ * @param {string} [discussionLog=''] - Discussion Log content (without ## Discussion Log heading)
+ * @param {string} [researchLog=''] - Research Log content (without ## Research Log heading)
+ * @returns {string} Full file content
+ */
+function buildIdeaContent(frontmatter, body, notes, discussionLog, researchLog) {
+  notes = notes || '';
+  discussionLog = discussionLog || '';
+  researchLog = researchLog || '';
+
+  let yaml = '---\n';
+  yaml += `id: ${frontmatter.id}\n`;
+  yaml += `title: "${frontmatter.title}"\n`;
+  if (frontmatter.tags && frontmatter.tags.length > 0) {
+    yaml += `tags: [${frontmatter.tags.map(t => `"${t}"`).join(', ')}]\n`;
+  } else {
+    yaml += 'tags: []\n';
+  }
+  yaml += `created: ${frontmatter.created}\n`;
+  yaml += `updated: ${frontmatter.updated}\n`;
+  if (frontmatter.author) {
+    yaml += `author: "${frontmatter.author}"\n`;
+  }
+  if (frontmatter.updated_by) {
+    yaml += `updated_by: "${frontmatter.updated_by}"\n`;
+  }
+  if (frontmatter.consolidated_from && frontmatter.consolidated_from.length > 0) {
+    yaml += `consolidated_from: [${frontmatter.consolidated_from.map(id => `"${id}"`).join(', ')}]\n`;
+  }
+  if (frontmatter.consolidated_into) {
+    yaml += `consolidated_into: "${frontmatter.consolidated_into}"\n`;
+  }
+  yaml += '---\n';
+
+  // Body
+  if (body) {
+    yaml += '\n' + body;
+  }
+
+  // Ensure a blank line before sections
+  if (notes || discussionLog || researchLog) {
+    // Ensure the body ends with a newline for clean separation
+    if (!yaml.endsWith('\n')) {
+      yaml += '\n';
+    }
+  }
+
+  // Notes section
+  if (notes) {
+    yaml += '\n## Notes\n\n' + notes;
+    if (!notes.endsWith('\n')) {
+      yaml += '\n';
+    }
+  }
+
+  // Discussion Log section
+  if (discussionLog) {
+    yaml += '\n## Discussion Log\n\n' + discussionLog;
+    if (!discussionLog.endsWith('\n')) {
+      yaml += '\n';
+    }
+  }
+
+  // Research Log section
+  if (researchLog) {
+    yaml += '\n## Research Log\n\n' + researchLog;
+    if (!researchLog.endsWith('\n')) {
+      yaml += '\n';
+    }
+  }
+
+  return yaml;
+}
+
+/**
+ * Find an idea file by numeric ID or exact filename across all state directories.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Numeric ID (e.g., "42", "042") or filename
+ * @returns {{ path: string, state: string, filename: string, frontmatter: object, body: string, notes: string, discussionLog: string, researchLog: string } | null}
+ */
+function findIdeaFile(cwd, idOrFilename) {
+  if (!idOrFilename) return null;
+
+  const idStr = idOrFilename.replace(/^0+/, '') || '0';
+  const paddedId = String(parseInt(idStr, 10)).padStart(3, '0');
+
+  for (const state of IDEA_STATES) {
+    const dir = path.join(getPlanningRoot(cwd), 'ideas', state);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      // Match by ID prefix
+      if (file.startsWith(paddedId + '-')) {
+        const content = safeReadFile(path.join(dir, file));
+        if (!content) continue;
+        const { frontmatter, body, notes, discussionLog, researchLog } = parseIdeaFrontmatter(content);
+        return { path: path.join(dir, file), state, filename: file, frontmatter, body, notes, discussionLog, researchLog };
+      }
+      // Match by exact filename
+      if (file === idOrFilename) {
+        const content = safeReadFile(path.join(dir, file));
+        if (!content) continue;
+        const { frontmatter, body, notes, discussionLog, researchLog } = parseIdeaFrontmatter(content);
+        return { path: path.join(dir, file), state, filename: file, frontmatter, body, notes, discussionLog, researchLog };
+      }
+    }
+  }
+
+  return null;
+}
+
+// ─── CRUD Operations ──────────────────────────────────────────────────────────
+
+/**
+ * Create a new idea with auto-assigned ID.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} title - Idea title
+ * @param {string} body - Freeform body text
+ * @param {string} tags - Comma-separated tags string (or null)
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string (e.g., "Name <email>"). When provided, sets author and updated_by.
+ */
+function cmdIdeasCreate(cwd, title, body, tags, raw, author) {
+  if (!title) {
+    error('title required for ideas create');
+  }
+
+  ensureIdeasDirs(cwd);
+
+  const id = allocateId(cwd);
+  const slug = generateSlugInternal(title);
+  const filename = `${id}-${slug}.md`;
+  const planRoot = getPlanningRoot(cwd);
+  const planRootRel = path.relative(cwd, planRoot) || '.';
+  const filePath = path.join(planRoot, 'ideas', 'pending', filename);
+  const now = new Date().toISOString();
+
+  const parsedTags = tags
+    ? tags.split(',').map(t => t.trim()).filter(t => t !== '')
+    : [];
+
+  const frontmatter = {
+    id: parseInt(id, 10),
+    title,
+    tags: parsedTags,
+    created: now,
+    updated: now,
+  };
+
+  if (author) {
+    frontmatter.author = author;
+    frontmatter.updated_by = author;
+  }
+
+  const content = buildIdeaContent(frontmatter, body || '');
+  fs.writeFileSync(filePath, content, 'utf-8');
+
+  const result = {
+    id: parseInt(id, 10),
+    filename,
+    path: path.join(planRootRel, 'ideas', 'pending', filename),
+    title,
+  };
+  output(result, raw);
+}
+
+/**
+ * Update a field on an existing idea.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} field - Field to update (title, body, tags)
+ * @param {string} value - New value
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by (never changes original author).
+ */
+function cmdIdeasUpdate(cwd, idOrFilename, field, value, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas update');
+  }
+  if (!field) {
+    error('field required for ideas update');
+  }
+  if (value === null || value === undefined) {
+    error('value required for ideas update');
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  const fm = idea.frontmatter;
+  let oldValue;
+  let body = idea.body;
+
+  if (field === 'title') {
+    oldValue = fm.title;
+    fm.title = value;
+  } else if (field === 'body') {
+    oldValue = body.trim();
+    body = value;
+  } else if (field === 'tags') {
+    oldValue = (fm.tags || []).join(', ');
+    fm.tags = value.split(',').map(t => t.trim()).filter(t => t !== '');
+  } else {
+    error(`unknown field: ${field}. Use title, body, or tags`);
+  }
+
+  fm.updated = new Date().toISOString();
+  if (author) {
+    fm.updated_by = author;
+  }
+
+  const content = buildIdeaContent(fm, body, idea.notes, idea.discussionLog, idea.researchLog);
+  fs.writeFileSync(idea.path, content, 'utf-8');
+
+  // If title changed, rename the file
+  let newFilename = idea.filename;
+  if (field === 'title') {
+    const idPadded = String(fm.id).padStart(3, '0');
+    const newSlug = generateSlugInternal(value);
+    newFilename = `${idPadded}-${newSlug}.md`;
+    if (newFilename !== idea.filename) {
+      const newPath = path.join(path.dirname(idea.path), newFilename);
+      fs.renameSync(idea.path, newPath);
+    }
+  }
+
+  const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+  const result = {
+    id: fm.id,
+    filename: newFilename,
+    path: path.join(planRootRel, 'ideas', idea.state, newFilename),
+    field,
+    old_value: oldValue,
+    new_value: value,
+  };
+  output(result, raw);
+}
+
+/**
+ * Append a timestamped note to an idea.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} noteText - Note text
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by (never changes original author).
+ */
+function cmdIdeasAppendNote(cwd, idOrFilename, noteText, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas append-note');
+  }
+  if (!noteText) {
+    error('note required for ideas append-note');
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  const fm = idea.frontmatter;
+  fm.updated = new Date().toISOString();
+  if (author) {
+    fm.updated_by = author;
+  }
+
+  const now = new Date().toISOString().split('T')[0];
+  const noteEntry = `---\n**${now}:** ${noteText}\n`;
+
+  // Append new note to existing notes section
+  const updatedNotes = idea.notes
+    ? idea.notes + noteEntry
+    : noteEntry;
+
+  const content = buildIdeaContent(fm, idea.body, updatedNotes, idea.discussionLog, idea.researchLog);
+  fs.writeFileSync(idea.path, content, 'utf-8');
+
+  const result = {
+    id: fm.id,
+    filename: idea.filename,
+    note_added: true,
+  };
+  output(result, raw);
+}
+
+/**
+ * List ideas grouped by state with optional filtering.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ state: string|null, tag: string|null, include_orphan_check: boolean, include_consolidated: boolean, show_all: boolean }} options
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdIdeasList(cwd, options, raw) {
+  const ideas = [];
+  const counts = { pending: 0, done: 0, rejected: 0, consolidated: 0, total: 0 };
+  const orphanedIds = [];
+
+  // Determine which states to iterate
+  let statesToList;
+  if (options.state) {
+    statesToList = [options.state];
+  } else if (options.include_consolidated) {
+    statesToList = ['consolidated'];
+  } else if (options.show_all) {
+    statesToList = IDEA_STATES;
+  } else {
+    statesToList = ['pending', 'done', 'rejected']; // default: hide consolidated
+  }
+
+  for (const state of statesToList) {
+
+    const dir = path.join(getPlanningRoot(cwd), 'ideas', state);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const content = safeReadFile(path.join(dir, file));
+      if (!content) continue;
+
+      const { frontmatter, discussionLog, researchLog } = parseIdeaFrontmatter(content);
+
+      // Tag filter (case-insensitive)
+      if (options.tag) {
+        const tagLower = options.tag.toLowerCase();
+        const tags = (frontmatter.tags || []).map(t => t.toLowerCase());
+        if (!tags.includes(tagLower)) continue;
+      }
+
+      // Author filter (case-insensitive substring match on name-only)
+      const authorName = extractNameFromAuthor(frontmatter.author || '');
+      if (options.author) {
+        const filterAuthor = options.author.toLowerCase();
+        if (!authorName.toLowerCase().includes(filterAuthor)) continue;
+      }
+
+      const ideaObj = {
+        id: frontmatter.id,
+        title: frontmatter.title || '',
+        tags: frontmatter.tags || [],
+        created: frontmatter.created || '',
+        updated: frontmatter.updated || '',
+        author: authorName,
+        state,
+        filename: file,
+        discussed: !!(discussionLog && discussionLog.trim().length > 0),
+        researched: !!(researchLog && researchLog.trim().length > 0),
+      };
+
+      if (state === 'consolidated' && frontmatter.consolidated_into) {
+        ideaObj.consolidated_into = frontmatter.consolidated_into;
+      }
+
+      ideas.push(ideaObj);
+
+      counts[state]++;
+      counts.total++;
+    }
+  }
+
+  // Orphan check: scan specs for references to done idea IDs
+  if (options.include_orphan_check) {
+    const doneIdeas = ideas.filter(i => i.state === 'done');
+    const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+
+    let specContent = '';
+    try {
+      const specFiles = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+      for (const sf of specFiles) {
+        specContent += safeReadFile(path.join(specsDir, sf)) || '';
+      }
+    } catch {
+      // No specs dir
+    }
+
+    for (const idea of doneIdeas) {
+      const idPadded = String(idea.id).padStart(3, '0');
+      // Check if any spec references this idea's ID
+      if (!specContent.includes(idPadded) && !specContent.includes(String(idea.id))) {
+        idea.orphaned = true;
+        orphanedIds.push(idea.id);
+      }
+    }
+  }
+
+  const result = {
+    ideas,
+    counts,
+    orphaned_ids: orphanedIds,
+  };
+  output(result, raw);
+}
+
+/**
+ * Reject an idea (move from pending to rejected).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} reason - Rejection reason (optional)
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by before move.
+ */
+function cmdIdeasReject(cwd, idOrFilename, reason, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas reject');
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  if (idea.state !== 'pending') {
+    if (idea.state === 'rejected') {
+      error(`idea ${idOrFilename} is already rejected`);
+    }
+    error(`idea ${idOrFilename} is in ${idea.state} state, only pending ideas can be rejected`);
+  }
+
+  // Re-parse file to get all sections
+  const currentContent = safeReadFile(idea.path) || '';
+  const { frontmatter: fm, body: bd, notes: nt, discussionLog: dl, researchLog: rl } = parseIdeaFrontmatter(currentContent);
+
+  // Append rejection reason to notes section if provided
+  let updatedNotes = nt;
+  if (reason) {
+    const now = new Date().toISOString().split('T')[0];
+    const reasonEntry = `---\n**Rejected (${now}):** ${reason}\n`;
+    updatedNotes = nt ? nt + reasonEntry : reasonEntry;
+  }
+
+  // Set updated_by if author provided
+  if (author) {
+    fm.updated_by = author;
+    fm.updated = new Date().toISOString();
+  }
+
+  // Rebuild with all sections preserved
+  const rebuilt = buildIdeaContent(fm, bd, updatedNotes, dl, rl);
+  fs.writeFileSync(idea.path, rebuilt, 'utf-8');
+
+  ensureIdeasDirs(cwd);
+
+  // Git mv from pending to rejected
+  const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+  const fromRel = path.join(planRootRel, 'ideas', 'pending', idea.filename);
+  const toRel = path.join(planRootRel, 'ideas', 'rejected', idea.filename);
+  execGit(cwd, ['mv', fromRel, toRel]);
+
+  // Auto-commit
+  execGit(cwd, ['add', '-A']);
+  const title = idea.frontmatter.title || idea.filename;
+  const idNum = idea.frontmatter.id || idOrFilename;
+  execGit(cwd, ['commit', '-m', `ideas: reject #${idNum} - ${title}`]);
+
+  const result = {
+    id: idea.frontmatter.id,
+    filename: idea.filename,
+    from: idea.state,
+    to: 'rejected',
+    reason: reason || null,
+  };
+  output(result, raw);
+}
+
+/**
+ * Restore an idea to pending (from rejected or done).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by before move.
+ */
+function cmdIdeasRestore(cwd, idOrFilename, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas restore');
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  if (idea.state === 'pending') {
+    error(`idea ${idOrFilename} is already in pending`);
+  }
+
+  // Remove consolidated_into when restoring from consolidated state
+  if (idea.state === 'consolidated') {
+    const currentContent = safeReadFile(idea.path) || '';
+    const { frontmatter: fm, body: bd, notes: nt, discussionLog: dl, researchLog: rl } = parseIdeaFrontmatter(currentContent);
+    delete fm.consolidated_into;
+    fm.updated = new Date().toISOString();
+    if (author) {
+      fm.updated_by = author;
+    }
+    fs.writeFileSync(idea.path, buildIdeaContent(fm, bd, nt, dl, rl), 'utf-8');
+  } else if (author) {
+    // Set updated_by for non-consolidated restores
+    const currentContent = safeReadFile(idea.path) || '';
+    const { frontmatter: fm, body: bd, notes: nt, discussionLog: dl, researchLog: rl } = parseIdeaFrontmatter(currentContent);
+    fm.updated_by = author;
+    fm.updated = new Date().toISOString();
+    fs.writeFileSync(idea.path, buildIdeaContent(fm, bd, nt, dl, rl), 'utf-8');
+  }
+
+  ensureIdeasDirs(cwd);
+
+  // Git mv to pending (keep rejection reason in file as history)
+  const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+  const fromRel = path.join(planRootRel, 'ideas', idea.state, idea.filename);
+  const toRel = path.join(planRootRel, 'ideas', 'pending', idea.filename);
+  execGit(cwd, ['mv', fromRel, toRel]);
+
+  // Auto-commit
+  execGit(cwd, ['add', '-A']);
+  const title = idea.frontmatter.title || idea.filename;
+  const idNum = idea.frontmatter.id || idOrFilename;
+  execGit(cwd, ['commit', '-m', `ideas: restore #${idNum} - ${title} to pending`]);
+
+  const result = {
+    id: idea.frontmatter.id,
+    filename: idea.filename,
+    from: idea.state,
+    to: 'pending',
+  };
+  output(result, raw);
+}
+
+/**
+ * Move an idea to a target state (general-purpose state transition).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} targetState - Target state (pending, done, rejected)
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by before move.
+ */
+function cmdIdeasMoveState(cwd, idOrFilename, targetState, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas move-state');
+  }
+  if (!targetState) {
+    error('target state required for ideas move-state');
+  }
+  if (!IDEA_STATES.includes(targetState)) {
+    error(`invalid state: ${targetState}. Use ${IDEA_STATES.join(', ')}`);
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  if (idea.state === targetState) {
+    error(`idea ${idOrFilename} is already in ${targetState}`);
+  }
+
+  // Set updated_by if author provided
+  if (author) {
+    const currentContent = safeReadFile(idea.path) || '';
+    const { frontmatter: fm, body: bd, notes: nt, discussionLog: dl, researchLog: rl } = parseIdeaFrontmatter(currentContent);
+    fm.updated_by = author;
+    fm.updated = new Date().toISOString();
+    fs.writeFileSync(idea.path, buildIdeaContent(fm, bd, nt, dl, rl), 'utf-8');
+  }
+
+  ensureIdeasDirs(cwd);
+
+  // Git mv
+  const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+  const fromRel = path.join(planRootRel, 'ideas', idea.state, idea.filename);
+  const toRel = path.join(planRootRel, 'ideas', targetState, idea.filename);
+  execGit(cwd, ['mv', fromRel, toRel]);
+
+  // Auto-commit
+  execGit(cwd, ['add', '-A']);
+  const title = idea.frontmatter.title || idea.filename;
+  const idNum = idea.frontmatter.id || idOrFilename;
+  execGit(cwd, ['commit', '-m', `ideas: move #${idNum} - ${title} to ${targetState}`]);
+
+  const result = {
+    id: idea.frontmatter.id,
+    filename: idea.filename,
+    from: idea.state,
+    to: targetState,
+  };
+  output(result, raw);
+}
+
+// ─── Section Entry Helpers ────────────────────────────────────────────────────
+
+/**
+ * Append a discussion entry to an idea's content string.
+ *
+ * Parses the content, formats a new H3 entry, prepends it to the existing
+ * discussionLog (newest first), rebuilds, and returns the full content.
+ *
+ * @param {string} content - Full idea file content string
+ * @param {{ date: string, keyInsights: string, refinedProblem: string, refinedApproach: string, openQuestions: string, decision: string }} entry
+ * @returns {string} Updated full idea content
+ */
+function appendDiscussionEntry(content, entry) {
+  const parsed = parseIdeaFrontmatter(content);
+
+  const entryBlock = [
+    `### Discussion — ${entry.date}`,
+    '',
+    `**Key Insights:** ${entry.keyInsights}`,
+    `**Refined Problem:** ${entry.refinedProblem}`,
+    `**Refined Approach:** ${entry.refinedApproach}`,
+    `**Open Questions:** ${entry.openQuestions}`,
+    `**Decision:** ${entry.decision}`,
+    '',
+  ].join('\n');
+
+  // Prepend new entry to existing discussion log (newest first)
+  const updatedDiscussionLog = parsed.discussionLog
+    ? entryBlock + parsed.discussionLog
+    : entryBlock;
+
+  return buildIdeaContent(
+    parsed.frontmatter,
+    parsed.body,
+    parsed.notes,
+    updatedDiscussionLog,
+    parsed.researchLog
+  );
+}
+
+/**
+ * Append a research entry to an idea's content string.
+ *
+ * Parses the content, formats a new H3 entry, prepends it to the existing
+ * researchLog (newest first), rebuilds, and returns the full content.
+ *
+ * @param {string} content - Full idea file content string
+ * @param {{ date: string, summary: string, keyFindings: string, recommendation: string, documentLink: string, outcome: string }} entry
+ * @returns {string} Updated full idea content
+ */
+function appendResearchEntry(content, entry) {
+  const parsed = parseIdeaFrontmatter(content);
+
+  const entryBlock = [
+    `### Research — ${entry.date}`,
+    '',
+    `**Summary:** ${entry.summary}`,
+    `**Key Findings:** ${entry.keyFindings}`,
+    `**Recommendation:** ${entry.recommendation}`,
+    `**Document:** ${entry.documentLink}`,
+    `**Outcome:** ${entry.outcome}`,
+    '',
+  ].join('\n');
+
+  // Prepend new entry to existing research log (newest first)
+  const updatedResearchLog = parsed.researchLog
+    ? entryBlock + parsed.researchLog
+    : entryBlock;
+
+  return buildIdeaContent(
+    parsed.frontmatter,
+    parsed.body,
+    parsed.notes,
+    parsed.discussionLog,
+    updatedResearchLog
+  );
+}
+
+// ─── Discussion Save Command ──────────────────────────────────────────────────
+
+/**
+ * Save a structured discussion entry to an idea file.
+ *
+ * Reads the idea, calls appendDiscussionEntry, updates the Updated timestamp,
+ * optionally sets updated_by, rebuilds all sections, writes the file, and
+ * returns JSON confirmation.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} entryJson - JSON string with { date, keyInsights, refinedProblem, refinedApproach, openQuestions, decision }
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by.
+ */
+function cmdIdeasDiscussSave(cwd, idOrFilename, entryJson, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas discuss-save');
+  }
+  if (!entryJson) {
+    error('entry required for ideas discuss-save');
+  }
+
+  let entry;
+  try {
+    entry = JSON.parse(entryJson);
+  } catch (e) {
+    error('invalid JSON for --entry: ' + e.message);
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  // Read full file content
+  const content = fs.readFileSync(idea.path, 'utf-8');
+
+  // Append the discussion entry (handles prepend/newest-first)
+  const withEntry = appendDiscussionEntry(content, entry);
+
+  // Re-parse to get updated sections and frontmatter
+  const parsed = parseIdeaFrontmatter(withEntry);
+  const fm = parsed.frontmatter;
+
+  // Update timestamp
+  fm.updated = new Date().toISOString();
+  if (author) {
+    fm.updated_by = author;
+  }
+
+  // Rebuild with all sections preserved
+  const updatedContent = buildIdeaContent(fm, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog);
+  fs.writeFileSync(idea.path, updatedContent, 'utf-8');
+
+  // Compute relative path for output
+  const relPath = path.relative(cwd, idea.path);
+
+  output({ id: fm.id, filename: idea.filename, path: relPath, state: idea.state }, raw);
+}
+
+// ─── Research Save Command ─────────────────────────────────────────────────────
+
+/**
+ * Save a structured research entry to an idea file.
+ *
+ * Reads the idea, calls appendResearchEntry, updates the Updated timestamp,
+ * optionally sets updated_by, rebuilds all sections, writes the file, and
+ * returns JSON confirmation.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Idea ID or filename
+ * @param {string} entryJson - JSON string with { date, summary, keyFindings, recommendation, documentLink, outcome }
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string. When provided, sets updated_by.
+ */
+function cmdIdeasResearchSave(cwd, idOrFilename, entryJson, raw, author) {
+  if (!idOrFilename) {
+    error('id required for ideas research-save');
+  }
+  if (!entryJson) {
+    error('entry required for ideas research-save');
+  }
+
+  let entry;
+  try {
+    entry = JSON.parse(entryJson);
+  } catch (e) {
+    error('invalid JSON for --entry: ' + e.message);
+  }
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) {
+    error(`idea not found: ${idOrFilename}`);
+  }
+
+  // Read full file content
+  const content = fs.readFileSync(idea.path, 'utf-8');
+
+  // Append the research entry (handles prepend/newest-first)
+  const withEntry = appendResearchEntry(content, entry);
+
+  // Re-parse to get updated sections and frontmatter
+  const parsed = parseIdeaFrontmatter(withEntry);
+  const fm = parsed.frontmatter;
+
+  // Update timestamp
+  fm.updated = new Date().toISOString();
+  if (author) {
+    fm.updated_by = author;
+  }
+
+  // Rebuild with all sections preserved
+  const updatedContent = buildIdeaContent(fm, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog);
+  fs.writeFileSync(idea.path, updatedContent, 'utf-8');
+
+  // Compute relative path for output
+  const relPath = path.relative(cwd, idea.path);
+
+  output({ id: fm.id, filename: idea.filename, path: relPath, state: idea.state }, raw);
+}
+
+// ─── Consolidation Note Helper ────────────────────────────────────────────────
+
+/**
+ * Append a consolidation note to a source idea file.
+ *
+ * Records that this idea was consolidated into a new combined idea,
+ * with the new idea's ID, title, and date. Called before moving
+ * source ideas to consolidated/.
+ *
+ * @param {string} ideaPath - Absolute path to the idea file
+ * @param {string} newIdeaId - The ID of the consolidated idea (e.g., "042")
+ * @param {string} newIdeaTitle - The title of the consolidated idea
+ * @param {string} date - Date string (e.g., "2026-03-10")
+ * @returns {string} Updated file content
+ */
+function appendConsolidationNote(ideaPath, newIdeaId, newIdeaTitle, date) {
+  const content = safeReadFile(ideaPath) || '';
+  const { frontmatter, body, notes, discussionLog, researchLog } = parseIdeaFrontmatter(content);
+
+  const noteLine = `- Consolidated into #${newIdeaId} (${newIdeaTitle}) on ${date}\n`;
+
+  // Append to existing notes or start new notes section
+  const updatedNotes = notes ? notes + noteLine : noteLine;
+
+  const updatedContent = buildIdeaContent(frontmatter, body, updatedNotes, discussionLog, researchLog);
+  fs.writeFileSync(ideaPath, updatedContent, 'utf-8');
+
+  return updatedContent;
+}
+
+// ─── Consolidate Command ──────────────────────────────────────────────────────
+
+/**
+ * Consolidate 2+ pending ideas into a single new idea.
+ *
+ * Validates all source IDs exist and are pending, creates a new idea with
+ * consolidated_from, annotates each source with consolidated_into and a
+ * consolidation note, moves sources to consolidated/, and commits atomically.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ ids: string, title: string, body?: string, tags?: string, discussion?: string, research?: string }} options
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string
+ */
+function cmdIdeasConsolidate(cwd, options, raw, author) {
+  const { ids, title, body, tags, discussion, research } = options;
+
+  // Validate required inputs
+  if (!title) error('title required for ideas consolidate');
+  if (!ids) error('ids required for ideas consolidate');
+
+  const idList = ids.split(',').map(s => s.trim()).filter(Boolean);
+  if (idList.length < 2) error('at least 2 idea IDs required for consolidation');
+
+  // Resolve and validate all source ideas BEFORE making any changes
+  const sourceIdeas = [];
+  for (const id of idList) {
+    const idea = findIdeaFile(cwd, id);
+    if (!idea) error(`idea not found: ${id}`);
+    if (idea.state !== 'pending') error(`idea ${id} is not in pending state (current: ${idea.state})`);
+    sourceIdeas.push(idea);
+  }
+
+  ensureIdeasDirs(cwd);
+
+  // Collect tags: union of all source tags + provided tags (deduplicated)
+  const allTags = new Set();
+  for (const idea of sourceIdeas) {
+    if (idea.frontmatter.tags && Array.isArray(idea.frontmatter.tags)) {
+      idea.frontmatter.tags.forEach(t => allTags.add(t));
+    }
+  }
+  if (tags) {
+    tags.split(',').map(t => t.trim()).filter(Boolean).forEach(t => allTags.add(t));
+  }
+
+  // Allocate new ID and prepare file paths
+  const newId = allocateId(cwd);
+  const slug = generateSlugInternal(title);
+  const filename = `${newId}-${slug}.md`;
+  const planRoot = getPlanningRoot(cwd);
+  const planRootRel = path.relative(cwd, planRoot) || '.';
+  const filePath = path.join(planRoot, 'ideas', 'pending', filename);
+  const now = new Date().toISOString();
+  const dateStr = now.split('T')[0];
+
+  // Build new idea frontmatter
+  const frontmatter = {
+    id: parseInt(newId, 10),
+    title,
+    tags: [...allTags],
+    created: now,
+    updated: now,
+  };
+  if (author) {
+    frontmatter.author = author;
+    frontmatter.updated_by = author;
+  }
+  frontmatter.consolidated_from = sourceIdeas.map(i => String(i.frontmatter.id).padStart(3, '0'));
+
+  // Write new consolidated idea to pending/
+  const content = buildIdeaContent(frontmatter, body || '', '', discussion || '', research || '');
+  fs.writeFileSync(filePath, content, 'utf-8');
+
+  // Annotate and move each source idea
+  const movedFiles = [];
+  for (const idea of sourceIdeas) {
+    // Set consolidated_into on source idea
+    const srcContent = safeReadFile(idea.path) || '';
+    const parsed = parseIdeaFrontmatter(srcContent);
+    parsed.frontmatter.consolidated_into = newId;
+    parsed.frontmatter.updated = now;
+    if (author) parsed.frontmatter.updated_by = author;
+    fs.writeFileSync(idea.path, buildIdeaContent(parsed.frontmatter, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog), 'utf-8');
+
+    // Append consolidation note
+    appendConsolidationNote(idea.path, newId, title, dateStr);
+
+    // Git mv source from pending/ to consolidated/
+    const fromRel = path.join(planRootRel, 'ideas', 'pending', idea.filename);
+    const toRel = path.join(planRootRel, 'ideas', 'consolidated', idea.filename);
+    execGit(cwd, ['mv', fromRel, toRel]);
+
+    movedFiles.push({
+      id: idea.frontmatter.id,
+      filename: idea.filename,
+      from: 'pending',
+      to: 'consolidated',
+    });
+  }
+
+  // Atomic git commit
+  execGit(cwd, ['add', '-A']);
+  const sourceIdsStr = sourceIdeas.map(i => `#${i.frontmatter.id}`).join(', ');
+  execGit(cwd, ['commit', '-m', `ideas: consolidate ${sourceIdsStr} -> #${parseInt(newId, 10)} - ${title}`]);
+
+  // Return structured JSON
+  const result = {
+    id: parseInt(newId, 10),
+    filename,
+    path: path.join(planRootRel, 'ideas', 'pending', filename),
+    title,
+    consolidated_from: frontmatter.consolidated_from,
+    moved_files: movedFiles,
+  };
+  output(result, raw);
+}
+
+// ─── Find Related Ideas ───────────────────────────────────────────────────────
+
+/**
+ * Find ideas related to an anchor idea by tag overlap (Jaccard similarity).
+ *
+ * Scores all other pending ideas against the anchor, groups by match level,
+ * applies threshold filtering, and returns full content for downstream AI scoring.
+ *
+ * Match levels (Jaccard similarity ratio):
+ *   HIGH:   ratio >= 0.5
+ *   MEDIUM: ratio >= 0.2
+ *   LOW:    ratio > 0
+ *   NONE:   ratio === 0 (excluded from results)
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ id: string, threshold: string }} options
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdIdeasFindRelated(cwd, options, raw) {
+  const { id, threshold } = options;
+
+  if (!id) {
+    error('id required for ideas find-related');
+  }
+
+  // 1. Find and validate anchor idea
+  const anchor = findIdeaFile(cwd, id);
+  if (!anchor) {
+    error('Idea #' + id + ' not found');
+  }
+
+  const anchorTags = anchor.frontmatter.tags || [];
+
+  // 2. Load all other pending ideas
+  const pendingDir = path.join(getPlanningRoot(cwd), 'ideas', 'pending');
+  let pendingFiles;
+  try {
+    pendingFiles = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+  } catch {
+    pendingFiles = [];
+  }
+
+  // 3. Score each candidate for tag overlap
+  const matchLevelOrder = { HIGH: 0, MEDIUM: 1, LOW: 2, NONE: 3 };
+  const candidates = [];
+
+  for (const file of pendingFiles) {
+    const content = safeReadFile(path.join(pendingDir, file));
+    if (!content) continue;
+
+    const parsed = parseIdeaFrontmatter(content);
+    const candidateId = parsed.frontmatter.id;
+
+    // Skip the anchor idea itself
+    if (candidateId === anchor.frontmatter.id) continue;
+
+    const candidateTags = parsed.frontmatter.tags || [];
+
+    // Jaccard similarity: intersection / union
+    const sharedSet = new Set(anchorTags.filter(t => candidateTags.includes(t)));
+    const unionSet = new Set([...anchorTags, ...candidateTags]);
+    const shared = [...sharedSet];
+    const ratio = unionSet.size === 0 ? 0 : shared.length / unionSet.size;
+
+    // Round ratio to avoid floating point display issues
+    const roundedRatio = Math.round(ratio * 100) / 100;
+
+    // 4. Assign match levels
+    let matchLevel;
+    if (ratio >= 0.5) {
+      matchLevel = 'HIGH';
+    } else if (ratio >= 0.2) {
+      matchLevel = 'MEDIUM';
+    } else if (ratio > 0) {
+      matchLevel = 'LOW';
+    } else {
+      matchLevel = 'NONE';
+    }
+
+    // Exclude NONE (zero overlap) entirely
+    if (matchLevel === 'NONE') continue;
+
+    candidates.push({
+      id: candidateId,
+      title: parsed.frontmatter.title || '',
+      tags: candidateTags,
+      body: parsed.body || '',
+      notes: parsed.notes || '',
+      discussion_log: parsed.discussionLog || '',
+      research_log: parsed.researchLog || '',
+      tag_overlap: {
+        shared,
+        ratio: roundedRatio,
+      },
+      match_level: matchLevel,
+      _ratio: ratio, // internal for sorting
+    });
+  }
+
+  // 5. Apply threshold filter
+  const thresholdLevel = (threshold || 'medium').toLowerCase();
+  let allowedLevels;
+  if (thresholdLevel === 'high') {
+    allowedLevels = new Set(['HIGH']);
+  } else if (thresholdLevel === 'medium') {
+    allowedLevels = new Set(['HIGH', 'MEDIUM']);
+  } else {
+    // 'low' — include HIGH, MEDIUM, LOW (still excludes NONE)
+    allowedLevels = new Set(['HIGH', 'MEDIUM', 'LOW']);
+  }
+
+  const filtered = candidates.filter(c => allowedLevels.has(c.match_level));
+
+  // 6. Sort results: HIGH first, then MEDIUM, then LOW
+  //    Within same level, sort by ratio descending
+  filtered.sort((a, b) => {
+    const levelDiff = matchLevelOrder[a.match_level] - matchLevelOrder[b.match_level];
+    if (levelDiff !== 0) return levelDiff;
+    return b._ratio - a._ratio;
+  });
+
+  // 7. Build result — remove internal _ratio field
+  const results = filtered.map(c => {
+    const { _ratio, ...rest } = c;
+    return rest;
+  });
+
+  // Counts
+  const counts = { high: 0, medium: 0, low: 0, total: results.length };
+  for (const r of results) {
+    if (r.match_level === 'HIGH') counts.high++;
+    else if (r.match_level === 'MEDIUM') counts.medium++;
+    else if (r.match_level === 'LOW') counts.low++;
+  }
+
+  // 8. Output JSON
+  const result = {
+    anchor: {
+      id: anchor.frontmatter.id,
+      title: anchor.frontmatter.title || '',
+      tags: anchorTags,
+    },
+    results,
+    counts,
+    threshold: thresholdLevel,
+  };
+
+  output(result, raw);
+}
+
+// ─── Undo Consolidation Command ───────────────────────────────────────────────
+
+/**
+ * Undo a consolidation: restore all source ideas to pending and delete the consolidated idea.
+ *
+ * Given the ID of the consolidated result idea (the one with consolidated_from),
+ * this function:
+ * 1. Finds the consolidated idea and reads its consolidated_from list
+ * 2. For each source ID in consolidated_from:
+ *    a. Finds the source idea in consolidated/ state
+ *    b. Removes consolidated_into from its frontmatter
+ *    c. Git mv from consolidated/ to pending/
+ * 3. Deletes the consolidated idea file from pending/ (git rm)
+ * 4. Creates a single atomic git commit
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - ID of the consolidated result idea
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string
+ */
+function cmdIdeasUndoConsolidation(cwd, idOrFilename, raw, author) {
+  if (!idOrFilename) error('id required for ideas undo-consolidation');
+
+  const idea = findIdeaFile(cwd, idOrFilename);
+  if (!idea) error(`idea not found: ${idOrFilename}`);
+
+  // Validate that this is a consolidated idea (has consolidated_from)
+  const consolidatedFrom = idea.frontmatter.consolidated_from;
+  if (!consolidatedFrom || !Array.isArray(consolidatedFrom) || consolidatedFrom.length === 0) {
+    error(`idea ${idOrFilename} is not a consolidated idea (no consolidated_from field)`);
+  }
+
+  const planRoot = getPlanningRoot(cwd);
+  const planRootRel = path.relative(cwd, planRoot) || '.';
+  const restoredIds = [];
+
+  // Restore each source idea from consolidated/ to pending/
+  for (const sourceId of consolidatedFrom) {
+    const sourceIdea = findIdeaFile(cwd, sourceId);
+    if (!sourceIdea) {
+      error(`source idea #${sourceId} not found during undo`);
+    }
+    if (sourceIdea.state !== 'consolidated') {
+      error(`source idea #${sourceId} is in ${sourceIdea.state} state, expected consolidated`);
+    }
+
+    // Remove consolidated_into from frontmatter
+    const srcContent = safeReadFile(sourceIdea.path) || '';
+    const parsed = parseIdeaFrontmatter(srcContent);
+    delete parsed.frontmatter.consolidated_into;
+    parsed.frontmatter.updated = new Date().toISOString();
+    if (author) parsed.frontmatter.updated_by = author;
+    fs.writeFileSync(sourceIdea.path, buildIdeaContent(parsed.frontmatter, parsed.body, parsed.notes, parsed.discussionLog, parsed.researchLog), 'utf-8');
+
+    // Git mv from consolidated/ to pending/
+    const fromRel = path.join(planRootRel, 'ideas', 'consolidated', sourceIdea.filename);
+    const toRel = path.join(planRootRel, 'ideas', 'pending', sourceIdea.filename);
+    execGit(cwd, ['mv', fromRel, toRel]);
+
+    restoredIds.push(parseInt(sourceId, 10));
+  }
+
+  // Delete the consolidated result idea
+  const ideaRel = path.join(planRootRel, 'ideas', idea.state, idea.filename);
+  execGit(cwd, ['rm', ideaRel]);
+
+  // Atomic git commit
+  execGit(cwd, ['add', '-A']);
+  const title = idea.frontmatter.title || idea.filename;
+  const idNum = idea.frontmatter.id || idOrFilename;
+  execGit(cwd, ['commit', '-m', `ideas: undo consolidation #${idNum} - ${title}`]);
+
+  const result = {
+    undone_idea_id: idea.frontmatter.id,
+    title,
+    restored_ids: restoredIds,
+    deleted_file: idea.filename,
+  };
+  output(result, raw);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  IDEA_STATES,
+  loadManifest,
+  saveManifest,
+  allocateId,
+  ensureIdeasDirs,
+  parseIdeaFrontmatter,
+  buildIdeaContent,
+  appendDiscussionEntry,
+  appendResearchEntry,
+  appendConsolidationNote,
+  findIdeaFile,
+  cmdIdeasCreate,
+  cmdIdeasUpdate,
+  cmdIdeasAppendNote,
+  cmdIdeasList,
+  cmdIdeasReject,
+  cmdIdeasRestore,
+  cmdIdeasMoveState,
+  cmdIdeasDiscussSave,
+  cmdIdeasResearchSave,
+  cmdIdeasConsolidate,
+  cmdIdeasFindRelated,
+  cmdIdeasUndoConsolidation,
+};