@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,1303 @@
+/**
+ * Specs — Structured PRD spec CRUD operations and lifecycle management
+ *
+ * Provides the data model and operations for the spec lifecycle:
+ * create, list, update-status, append-review-history, and finalize.
+ * Specs are stored as markdown files with YAML frontmatter in
+ * .planning/specs/ (flat directory, no subdirectories).
+ */
+
+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');
+
+// ─── Directory Helpers ────────────────────────────────────────────────────────
+
+const SPEC_STATUSES = ['draft', 'review', 'final'];
+
+/**
+ * Normalize spec status to two-state machine (draft/final).
+ * Maps deprecated 'review' and 'in-review' to 'draft'.
+ *
+ * @param {string} status - Raw status value
+ * @returns {string} Normalized status ('draft' or 'final')
+ */
+function normalizeStatus(status) {
+  if (status === 'final') return 'final';
+  if (status === 'draft') return 'draft';
+  if (status === 'review' || status === 'in-review') return 'draft';
+  return 'draft';
+}
+
+/**
+ * Ensure .planning/specs/ directory exists.
+ *
+ * @param {string} cwd - Working directory
+ */
+function ensureSpecsDir(cwd) {
+  fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
+}
+
+// ─── Milestone State ─────────────────────────────────────────────────────────
+
+/**
+ * Get the set of shipped milestone versions from MILESTONES.md.
+ * Parses headings of the form: ## vX.Y Name (Shipped: DATE)
+ *
+ * @param {string} cwd - Working directory
+ * @returns {Set<string>} Set of shipped milestone version strings (e.g., "v12.0")
+ */
+function getShippedMilestones(cwd) {
+  const milestonesPath = path.join(getPlanningRoot(cwd), 'MILESTONES.md');
+  const content = safeReadFile(milestonesPath);
+  if (!content) return new Set();
+
+  const shipped = new Set();
+  const pattern = /^## (v\d+\.\d+)\s+.*\(Shipped:/gm;
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    shipped.add(match[1]);
+  }
+  return shipped;
+}
+
+// ─── Frontmatter Parsing ──────────────────────────────────────────────────────
+
+/**
+ * Parse YAML frontmatter from spec file content.
+ * Uses simple regex parsing (no YAML library -- zero-dependency project).
+ *
+ * @param {string} content - File content
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseSpecFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]+?)\n---\n?([\s\S]*)/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const yaml = match[1];
+  const body = match[2] || '';
+  const frontmatter = {};
+
+  const lines = yaml.split('\n');
+  let currentArrayKey = null;
+  let currentArray = [];
+
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+
+    // Handle multi-line array items (indented with -)
+    if (currentArrayKey && /^\s+-\s+/.test(line)) {
+      const value = line.replace(/^\s+-\s+/, '').replace(/^["']|["']$/g, '');
+      currentArray.push(value);
+      continue;
+    } else if (currentArrayKey) {
+      // End of multi-line array
+      frontmatter[currentArrayKey] = currentArray;
+      currentArrayKey = null;
+      currentArray = [];
+    }
+
+    // Handle inline array values (e.g., source_ideas: ["a", "b"])
+    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 array start (key followed by nothing or empty)
+    const arrayStartMatch = line.match(/^([\w_]+):\s*$/);
+    if (arrayStartMatch) {
+      currentArrayKey = arrayStartMatch[1];
+      currentArray = [];
+      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, '');
+      frontmatter[key] = value;
+    }
+  }
+
+  // Flush any remaining array
+  if (currentArrayKey) {
+    frontmatter[currentArrayKey] = currentArray;
+  }
+
+  return { frontmatter, body };
+}
+
+// ─── Dual-Format Support ─────────────────────────────────────────────────────
+
+/**
+ * Detect the frontmatter format of spec file content.
+ *
+ * @param {string} content - File content
+ * @returns {'yaml' | 'bold-key' | 'none'}
+ */
+function detectSpecFormat(content) {
+  if (!content) return 'none';
+
+  // YAML format: starts with ---\n
+  if (/^---\n/.test(content)) return 'yaml';
+
+  // Bold-key format: has **Key:** pattern before any --- delimiter or ## section heading
+  const lines = content.split('\n');
+  for (const line of lines) {
+    // Stop at --- horizontal rule
+    if (/^---\s*$/.test(line)) break;
+    // Stop at ## section heading
+    if (/^## /.test(line)) break;
+    // Found a bold-key line
+    if (/^\*\*[^*]+:\*\*/.test(line)) return 'bold-key';
+  }
+
+  return 'none';
+}
+
+/**
+ * Parse bold-key frontmatter from spec file content.
+ * Extracts **Key:** Value pairs from the top of the file.
+ *
+ * @param {string} content - File content
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseBoldKeyFrontmatter(content) {
+  if (!content) return { frontmatter: {}, body: content || '' };
+
+  const lines = content.split('\n');
+  const frontmatter = {};
+  let bodyStartIndex = 0;
+
+  // Bold-key to frontmatter key mapping
+  const keyMap = {
+    'Status': 'status',
+    'Author': 'author',
+    'Date': 'created',
+    'Updated': 'updated',
+    'Version': 'version',
+    'Approved Date': 'approved_date',
+    'Milestones': 'milestones',
+    'Source Ideas': 'source_ideas',
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Extract title from # Title line
+    const titleMatch = line.match(/^# (.+)$/);
+    if (titleMatch && !frontmatter.title) {
+      frontmatter.title = titleMatch[1].trim();
+      bodyStartIndex = i + 1;
+      continue;
+    }
+
+    // Stop at --- horizontal rule (body starts after it)
+    if (/^---\s*$/.test(line)) {
+      bodyStartIndex = i + 1;
+      break;
+    }
+
+    // Stop at ## section heading (body starts here)
+    if (/^## /.test(line)) {
+      bodyStartIndex = i;
+      break;
+    }
+
+    // Extract bold-key values
+    const boldKeyMatch = line.match(/^\*\*([^*]+):\*\*\s*(.*)/);
+    if (boldKeyMatch) {
+      const rawKey = boldKeyMatch[1].trim();
+      const rawValue = boldKeyMatch[2].trim();
+      const mappedKey = keyMap[rawKey];
+
+      if (mappedKey) {
+        if (mappedKey === 'status') {
+          // Lowercase the value: Draft -> draft, Final -> final
+          frontmatter[mappedKey] = rawValue.toLowerCase();
+        } else if (mappedKey === 'milestones' || mappedKey === 'source_ideas') {
+          // Split comma-separated values into array
+          frontmatter[mappedKey] = rawValue
+            .split(',')
+            .map(v => v.trim())
+            .filter(v => v !== '');
+        } else {
+          frontmatter[mappedKey] = rawValue;
+        }
+      }
+
+      bodyStartIndex = i + 1;
+      continue;
+    }
+
+    // Skip empty lines in the frontmatter area
+    if (line.trim() === '') {
+      bodyStartIndex = i + 1;
+      continue;
+    }
+
+    // Non-matching non-empty line that isn't a title or bold-key -- stop
+    bodyStartIndex = i;
+    break;
+  }
+
+  // Generate id from title if not present
+  if (frontmatter.title && !frontmatter.id) {
+    const slug = generateSlugInternal(frontmatter.title);
+    frontmatter.id = `spec-${slug}`;
+  }
+
+  const body = lines.slice(bodyStartIndex).join('\n');
+  return { frontmatter, body };
+}
+
+/**
+ * Build spec file content in bold-key format from frontmatter object and body.
+ *
+ * @param {object} frontmatter - Frontmatter fields
+ * @param {string} body - Body content
+ * @returns {string} Full file content
+ */
+function buildBoldKeyContent(frontmatter, body) {
+  let content = '';
+
+  // Title first
+  if (frontmatter.title) {
+    content += `# ${frontmatter.title}\n\n`;
+  }
+
+  // Status (title-case: draft -> Draft, final -> Final)
+  if (frontmatter.status) {
+    const titleCased = frontmatter.status.charAt(0).toUpperCase() + frontmatter.status.slice(1);
+    content += `**Status:** ${titleCased}\n`;
+  }
+
+  // Author
+  if (frontmatter.author) {
+    content += `**Author:** ${frontmatter.author}\n`;
+  }
+
+  // Date (maps from 'created')
+  if (frontmatter.created) {
+    content += `**Date:** ${frontmatter.created}\n`;
+  }
+
+  // Updated
+  if (frontmatter.updated) {
+    content += `**Updated:** ${frontmatter.updated}\n`;
+  }
+
+  // Version
+  if (frontmatter.version) {
+    content += `**Version:** ${frontmatter.version}\n`;
+  }
+
+  // Approved Date
+  if (frontmatter.approved_date) {
+    content += `**Approved Date:** ${frontmatter.approved_date}\n`;
+  }
+
+  // Milestones (comma-separated)
+  if (frontmatter.milestones && frontmatter.milestones.length > 0) {
+    content += `**Milestones:** ${frontmatter.milestones.join(', ')}\n`;
+  }
+
+  // Source Ideas (comma-separated)
+  if (frontmatter.source_ideas && frontmatter.source_ideas.length > 0) {
+    content += `**Source Ideas:** ${frontmatter.source_ideas.join(', ')}\n`;
+  }
+
+  // Separator and body
+  content += '\n---\n';
+
+  if (body) {
+    const trimmedBody = body.replace(/^\n+/, '');
+    content += '\n' + trimmedBody;
+  }
+
+  return content;
+}
+
+/**
+ * Build spec file content from frontmatter object and body string.
+ *
+ * @param {object} frontmatter - Frontmatter fields
+ * @param {string} body - Body content
+ * @returns {string} Full file content
+ */
+function buildSpecContent(frontmatter, body) {
+  let yaml = '---\n';
+  yaml += `id: ${frontmatter.id}\n`;
+  yaml += `title: "${frontmatter.title}"\n`;
+  yaml += `status: ${frontmatter.status}\n`;
+
+  if (frontmatter.source_ideas && frontmatter.source_ideas.length > 0) {
+    yaml += 'source_ideas:\n';
+    for (const idea of frontmatter.source_ideas) {
+      yaml += `  - "${idea}"\n`;
+    }
+  } else {
+    yaml += 'source_ideas: []\n';
+  }
+
+  if (frontmatter.source_document) {
+    yaml += `source_document: "${frontmatter.source_document}"\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.version) {
+    yaml += `version: ${frontmatter.version}\n`;
+  }
+  if (frontmatter.approved_date) {
+    yaml += `approved_date: ${frontmatter.approved_date}\n`;
+  }
+  if (frontmatter.milestones && frontmatter.milestones.length > 0) {
+    yaml += 'milestones:\n';
+    for (const m of frontmatter.milestones) {
+      yaml += `  - "${m}"\n`;
+    }
+  }
+  yaml += '---\n';
+
+  if (body) {
+    // Ensure body starts with newline for clean separation
+    const trimmedBody = body.replace(/^\n+/, '');
+    yaml += '\n' + trimmedBody;
+  }
+
+  return yaml;
+}
+
+// ─── Find Spec ────────────────────────────────────────────────────────────────
+
+/**
+ * Find a spec file by id or filename.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id (e.g., "spec-review-config") or filename
+ * @returns {{ filename: string, path: string, frontmatter: object, body: string } | null}
+ */
+function findSpecFile(cwd, idOrFilename) {
+  if (!idOrFilename) return null;
+
+  const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+  let files;
+  try {
+    files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+  } catch {
+    return null;
+  }
+
+  // Helper to normalize a parsed result before returning
+  function normalizeResult(file, frontmatter, body) {
+    frontmatter.status = normalizeStatus(frontmatter.status || 'draft');
+    if (!frontmatter.version) {
+      frontmatter.version = '0.1';
+    }
+    return { filename: file, path: path.join(specsDir, file), frontmatter, body };
+  }
+
+  // First pass: exact matches
+  const parsed = [];
+  for (const file of files) {
+    const content = safeReadFile(path.join(specsDir, file));
+    if (!content) continue;
+
+    // Dual-format support: detect format and use appropriate parser
+    const format = detectSpecFormat(content);
+    const { frontmatter, body } = format === 'bold-key'
+      ? parseBoldKeyFrontmatter(content)
+      : parseSpecFrontmatter(content);
+
+    // Match by id
+    if (frontmatter.id === idOrFilename) {
+      return normalizeResult(file, frontmatter, body);
+    }
+
+    // Match by exact filename
+    if (file === idOrFilename) {
+      return normalizeResult(file, frontmatter, body);
+    }
+
+    // Match by filename without .md extension
+    if (file === idOrFilename + '.md') {
+      return normalizeResult(file, frontmatter, body);
+    }
+
+    parsed.push({ file, frontmatter, body });
+  }
+
+  // Second pass: substring matching on id and title (case-insensitive)
+  const searchLower = idOrFilename.toLowerCase();
+  for (const entry of parsed) {
+    const idLower = (entry.frontmatter.id || '').toLowerCase();
+    const titleLower = (entry.frontmatter.title || '').toLowerCase();
+
+    if (idLower.includes(searchLower) || titleLower.includes(searchLower)) {
+      return normalizeResult(entry.file, entry.frontmatter, entry.body);
+    }
+  }
+
+  return null;
+}
+
+// ─── CRUD Operations ──────────────────────────────────────────────────────────
+
+/**
+ * Create a new spec file.
+ *
+ * @param {string} cwd - Working directory
+ * @param {object} options - { title, source_ideas: ["001-slug.md", ...], body }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsCreate(cwd, options, raw) {
+  if (!options || !options.title) {
+    error('title required for specs create');
+  }
+
+  ensureSpecsDir(cwd);
+
+  const slug = generateSlugInternal(options.title);
+  const id = `spec-${slug}`;
+  const filename = `${id}.md`;
+  const planRoot = getPlanningRoot(cwd);
+  const planRootRel = path.relative(cwd, planRoot) || '.';
+  const filePath = path.join(planRoot, 'specs', filename);
+  const now = new Date().toISOString();
+
+  const sourceIdeas = options.source_ideas || [];
+  const sourceDocument = options.source_document || null;
+
+  const frontmatter = {
+    id,
+    title: options.title,
+    status: 'draft',
+    source_ideas: sourceIdeas,
+    created: now,
+    updated: now,
+    version: '1.0',
+  };
+
+  if (sourceDocument) {
+    frontmatter.source_document = sourceDocument;
+  }
+
+  if (options.author) {
+    frontmatter.author = options.author;
+    frontmatter.updated_by = options.author;
+  }
+
+  const body = options.body || '';
+  const content = buildSpecContent(frontmatter, body);
+  fs.writeFileSync(filePath, content, 'utf-8');
+
+  const result = {
+    id,
+    filename,
+    path: path.join(planRootRel, 'specs', filename),
+    title: options.title,
+    status: 'draft',
+    source_ideas: sourceIdeas,
+    source_document: sourceDocument,
+  };
+  output(result, raw);
+}
+
+/**
+ * Derive aggregate implementation status from linked milestones.
+ * @param {string[]|undefined} milestones - Array of milestone version strings
+ * @param {Set<string>} shippedMilestones - Set of shipped milestone versions
+ * @returns {'none'|'in-progress'|'completed'}
+ */
+function deriveImplementationStatus(milestones, shippedMilestones) {
+  if (!milestones || milestones.length === 0) return 'none';
+  const allShipped = milestones.every(m => shippedMilestones.has(m));
+  return allShipped ? 'completed' : 'in-progress';
+}
+
+/**
+ * Derive per-milestone state details.
+ * @param {string[]|undefined} milestones - Array of milestone version strings
+ * @param {Set<string>} shippedMilestones - Set of shipped milestone versions
+ * @returns {Array<{version: string, state: string}>}
+ */
+function deriveMilestoneDetails(milestones, shippedMilestones) {
+  if (!milestones || milestones.length === 0) return [];
+  return milestones.map(m => ({
+    version: m,
+    state: shippedMilestones.has(m) ? 'completed' : 'in-progress',
+  }));
+}
+
+/**
+ * List all specs with optional status filter.
+ *
+ * @param {string} cwd - Working directory
+ * @param {object} options - { status: null|"draft"|"review"|"final" }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsList(cwd, options, raw) {
+  const specs = [];
+  const counts = { draft: 0, final: 0, total: 0 };
+
+  const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+  let files;
+  try {
+    files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+  } catch {
+    // No specs directory
+    output({ specs, counts }, raw);
+    return;
+  }
+
+  const shippedMilestones = getShippedMilestones(cwd);
+
+  for (const file of files) {
+    const content = safeReadFile(path.join(specsDir, file));
+    if (!content) continue;
+
+    const format = detectSpecFormat(content);
+    const { frontmatter } = format === 'bold-key'
+      ? parseBoldKeyFrontmatter(content)
+      : parseSpecFrontmatter(content);
+    const status = normalizeStatus(frontmatter.status || 'draft');
+
+    // Status filter
+    if (options && options.status && status !== options.status) continue;
+
+    // Author filter (case-insensitive substring match on name-only)
+    const authorName = extractNameFromAuthor(frontmatter.author || '');
+    if (options && options.author) {
+      const filterAuthor = options.author.toLowerCase();
+      if (!authorName.toLowerCase().includes(filterAuthor)) continue;
+    }
+
+    specs.push({
+      id: frontmatter.id || '',
+      title: frontmatter.title || '',
+      status,
+      version: frontmatter.version || '',
+      milestones: frontmatter.milestones || [],
+      implementation_status: deriveImplementationStatus(frontmatter.milestones, shippedMilestones),
+      milestone_details: deriveMilestoneDetails(frontmatter.milestones, shippedMilestones),
+      source_ideas: frontmatter.source_ideas || [],
+      source_document: frontmatter.source_document || '',
+      created: frontmatter.created || '',
+      updated: frontmatter.updated || '',
+      author: authorName,
+      filename: file,
+    });
+
+    if (counts[status] !== undefined) {
+      counts[status]++;
+    }
+    counts.total++;
+  }
+
+  output({ specs, counts }, raw);
+}
+
+/**
+ * Update spec status field.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {string} newStatus - New status (draft, review, final)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsUpdateStatus(cwd, idOrFilename, newStatus, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs update-status');
+  }
+  if (!newStatus) {
+    error('status required for specs update-status');
+  }
+  if (!SPEC_STATUSES.includes(newStatus)) {
+    error(`invalid status: ${newStatus}. Use draft, review, or final`);
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    error(`spec not found: ${idOrFilename}`);
+  }
+
+  const previousStatus = spec.frontmatter.status;
+  spec.frontmatter.status = newStatus;
+  spec.frontmatter.updated = new Date().toISOString();
+  if (author) {
+    spec.frontmatter.updated_by = author;
+  }
+
+  const content = buildSpecContent(spec.frontmatter, spec.body);
+  fs.writeFileSync(spec.path, content, 'utf-8');
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    status: newStatus,
+    previous_status: previousStatus,
+  };
+  output(result, raw);
+}
+
+/**
+ * Append a review round to the spec's Review History section.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {string} historyEntry - Formatted markdown for one review round
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsAppendReviewHistory(cwd, idOrFilename, historyEntry, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs append-review');
+  }
+  if (!historyEntry) {
+    error('entry required for specs append-review');
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    error(`spec not found: ${idOrFilename}`);
+  }
+
+  spec.frontmatter.updated = new Date().toISOString();
+  if (author) {
+    spec.frontmatter.updated_by = author;
+  }
+
+  // Normalize literal \n sequences to real newlines (CLI passes escaped newlines)
+  historyEntry = historyEntry.replace(/\\n/g, '\n');
+
+  // Inject "Applied by" attribution into the review history entry
+  if (author) {
+    const appliedByName = extractNameFromAuthor(author);
+    // Insert "**Applied by:** Name" after the first line (### Round N heading)
+    const firstNewline = historyEntry.indexOf('\n');
+    if (firstNewline !== -1) {
+      historyEntry = historyEntry.slice(0, firstNewline + 1) +
+        '**Applied by:** ' + appliedByName + '\n' +
+        historyEntry.slice(firstNewline + 1);
+    } else {
+      // Entry is a single line — append attribution after it
+      historyEntry = historyEntry + '\n**Applied by:** ' + appliedByName;
+    }
+  }
+
+  let body = spec.body;
+
+  // Find the ## Review History section
+  const reviewHistoryPattern = /## Review History\n/;
+  const reviewMatch = body.match(reviewHistoryPattern);
+
+  if (reviewMatch) {
+    // Find the position after "## Review History\n"
+    const insertPos = reviewMatch.index + reviewMatch[0].length;
+    // Find existing content after the header (before next ## section or end)
+    const afterHeader = body.slice(insertPos);
+    const nextSectionMatch = afterHeader.match(/\n## [^#]/);
+    const existingContent = nextSectionMatch
+      ? afterHeader.slice(0, nextSectionMatch.index)
+      : afterHeader;
+
+    // Append the new entry after existing review history content
+    const newContent = existingContent.trimEnd() + '\n\n' + historyEntry + '\n';
+
+    if (nextSectionMatch) {
+      body = body.slice(0, insertPos) + newContent + afterHeader.slice(nextSectionMatch.index);
+    } else {
+      body = body.slice(0, insertPos) + newContent;
+    }
+  } else {
+    // No Review History section exists -- append it
+    body = body.trimEnd() + '\n\n## Review History\n\n' + historyEntry + '\n';
+  }
+
+  const content = buildSpecContent(spec.frontmatter, body);
+  fs.writeFileSync(spec.path, content, 'utf-8');
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    appended: true,
+  };
+  output(result, raw);
+}
+
+/**
+ * Finalize a spec: set status to final, move source ideas to done.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsFinalize(cwd, idOrFilename, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs finalize');
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    error(`spec not found: ${idOrFilename}`);
+  }
+
+  // Guard: already finalized
+  if (spec.frontmatter.status === 'final') {
+    error(`spec already final: ${spec.frontmatter.id}. Cannot re-finalize.`);
+  }
+
+  // Set status to final
+  spec.frontmatter.status = 'final';
+  spec.frontmatter.updated = new Date().toISOString();
+  if (author) {
+    spec.frontmatter.updated_by = author;
+  }
+
+  const content = buildSpecContent(spec.frontmatter, spec.body);
+  fs.writeFileSync(spec.path, content, 'utf-8');
+
+  // Move source ideas to done
+  const ideasMoved = [];
+  const ideasFailed = [];
+  const sourceIdeas = spec.frontmatter.source_ideas || [];
+
+  for (const ideaFilename of sourceIdeas) {
+    // Extract idea ID from filename (e.g., "001-slug.md" -> "001")
+    const idMatch = ideaFilename.match(/^(\d+)/);
+    if (!idMatch) {
+      ideasFailed.push({ idea: ideaFilename, reason: 'could not parse ID' });
+      continue;
+    }
+    const ideaId = idMatch[1];
+
+    try {
+      // Move ideas to done manually (ideas.cjs cmd functions call process.exit,
+      // so we use the internal helpers directly instead)
+      // Instead, do the move manually following the same pattern
+      const { findIdeaFile, ensureIdeasDirs } = require('./ideas.cjs');
+      const idea = findIdeaFile(cwd, ideaId);
+
+      if (!idea) {
+        ideasFailed.push({ idea: ideaFilename, reason: 'idea not found' });
+        continue;
+      }
+
+      if (idea.state === 'done') {
+        // Already done, skip
+        ideasMoved.push(ideaFilename);
+        continue;
+      }
+
+      if (idea.state === 'consolidated') {
+        // Consolidated ideas cannot be used as spec sources
+        ideasFailed.push({ idea: ideaFilename, reason: 'idea is consolidated' });
+        continue;
+      }
+
+      ensureIdeasDirs(cwd);
+
+      const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+      const fromRel = path.join(planRootRel, 'ideas', idea.state, idea.filename);
+      const toRel = path.join(planRootRel, 'ideas', 'done', idea.filename);
+      const mvResult = execGit(cwd, ['mv', fromRel, toRel]);
+
+      if (mvResult.exitCode !== 0) {
+        ideasFailed.push({ idea: ideaFilename, reason: mvResult.stderr || 'git mv failed' });
+        continue;
+      }
+
+      ideasMoved.push(ideaFilename);
+    } catch (err) {
+      ideasFailed.push({ idea: ideaFilename, reason: err.message || 'unknown error' });
+    }
+  }
+
+  // Move associated research documents and update links in idea files
+  const researchDocsMoved = [];
+
+  for (const ideaFilename of ideasMoved) {
+    try {
+      // Extract slug from idea filename: "001-my-idea.md" -> "my-idea"
+      const slug = ideaFilename.replace(/^\d+-/, '').replace(/\.md$/, '');
+      const researchDocName = `${slug}-research.md`;
+      const specPlanRoot = getPlanningRoot(cwd);
+      const specPlanRootRel = path.relative(cwd, specPlanRoot) || '.';
+      const sourcePath = path.join(specPlanRoot, 'docs', 'ideas', 'pending', researchDocName);
+
+      // Skip if no research doc exists (graceful handling)
+      if (!fs.existsSync(sourcePath)) continue;
+
+      // Ensure done directory exists
+      fs.mkdirSync(path.join(specPlanRoot, 'docs', 'ideas', 'done'), { recursive: true });
+
+      const sourceRel = path.join(specPlanRootRel, 'docs', 'ideas', 'pending', researchDocName);
+      const targetRel = path.join(specPlanRootRel, 'docs', 'ideas', 'done', researchDocName);
+      const mvResult = execGit(cwd, ['mv', sourceRel, targetRel]);
+
+      if (mvResult.exitCode !== 0) continue;
+
+      researchDocsMoved.push(researchDocName);
+
+      // Update documentLink paths in the idea file (now in done/)
+      const ideaDonePath = path.join(getPlanningRoot(cwd), 'ideas', 'done', ideaFilename);
+      if (fs.existsSync(ideaDonePath)) {
+        let ideaContent = fs.readFileSync(ideaDonePath, 'utf-8');
+        // Replace pending/ paths with done/ for this research doc
+        const pendingPattern = `docs/ideas/pending/${researchDocName}`;
+        const doneReplacement = `docs/ideas/done/${researchDocName}`;
+        if (ideaContent.includes(pendingPattern)) {
+          ideaContent = ideaContent.split(pendingPattern).join(doneReplacement);
+          fs.writeFileSync(ideaDonePath, ideaContent, 'utf-8');
+        }
+      }
+    } catch {
+      // Graceful handling: skip on any error
+    }
+  }
+
+  // Auto-commit the spec status change and idea moves
+  execGit(cwd, ['add', '-A']);
+  const title = spec.frontmatter.title || spec.frontmatter.id;
+  execGit(cwd, ['commit', '-m', `specs: finalize ${spec.frontmatter.id} - ${title}`]);
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    status: 'final',
+    ideas_moved: ideasMoved,
+    ideas_failed: ideasFailed,
+    research_docs_moved: researchDocsMoved,
+  };
+  output(result, raw);
+}
+
+// ─── Set Status (two-state machine) ──────────────────────────────────────────
+
+/**
+ * Set spec status, enforcing the two-state machine (draft/final only).
+ * Rejects deprecated 'review' and 'in-review' with clear message.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {string} newStatus - New status (draft or final)
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string for updated_by
+ */
+function cmdSpecsSetStatus(cwd, idOrFilename, newStatus, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs set-status');
+  }
+  if (!newStatus) {
+    error('status required for specs set-status');
+  }
+
+  // Reject deprecated statuses with specific message
+  if (newStatus === 'review' || newStatus === 'in-review') {
+    error(`Status '${newStatus}' is deprecated. Valid statuses: draft, final`);
+  }
+
+  // Validate against two-state machine (hardcoded, NOT using SPEC_STATUSES)
+  const validStatuses = ['draft', 'final'];
+  if (!validStatuses.includes(newStatus)) {
+    error(`Invalid status '${newStatus}'. Valid statuses: draft, final`);
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    // Build fuzzy suggestions
+    const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+    const suggestions = [];
+    try {
+      const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+      const searchLower = idOrFilename.toLowerCase();
+      for (const file of files) {
+        const content = safeReadFile(path.join(specsDir, file));
+        if (!content) continue;
+        const format = detectSpecFormat(content);
+        const { frontmatter } = format === 'bold-key'
+          ? parseBoldKeyFrontmatter(content)
+          : parseSpecFrontmatter(content);
+        const idLower = (frontmatter.id || '').toLowerCase();
+        const titleLower = (frontmatter.title || '').toLowerCase();
+        if (idLower.includes(searchLower) || titleLower.includes(searchLower)) {
+          suggestions.push(frontmatter.id || file);
+        }
+        if (suggestions.length >= 3) break;
+      }
+    } catch { /* ignore */ }
+    const suggestionText = suggestions.length > 0
+      ? `. Did you mean: ${suggestions.join(', ')}?`
+      : '';
+    error(`spec not found: ${idOrFilename}${suggestionText}`);
+  }
+
+  // Read the raw file content to detect format
+  const fileContent = fs.readFileSync(spec.path, 'utf-8');
+  const format = detectSpecFormat(fileContent);
+
+  // Track the previous status (normalized from what was stored)
+  const previousStatus = spec.frontmatter.status;
+
+  // Update frontmatter
+  spec.frontmatter.status = newStatus;
+  spec.frontmatter.updated = new Date().toISOString();
+  if (newStatus === 'final') {
+    spec.frontmatter.approved_date = new Date().toISOString().split('T')[0];
+  }
+  if (author) {
+    spec.frontmatter.updated_by = author;
+  }
+
+  // Write back using the correct builder
+  const content = format === 'bold-key'
+    ? buildBoldKeyContent(spec.frontmatter, spec.body)
+    : buildSpecContent(spec.frontmatter, spec.body);
+  fs.writeFileSync(spec.path, content, 'utf-8');
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    previous_status: previousStatus,
+    status: newStatus,
+    message: `\u2713 ${spec.filename}: ${previousStatus} \u2192 ${newStatus}`,
+  };
+  output(result, raw);
+}
+
+// ─── Validate ────────────────────────────────────────────────────────────────
+
+/**
+ * Validate a spec for completeness, producing tiered error/warning/info output.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdSpecsValidate(cwd, idOrFilename, raw) {
+  if (!idOrFilename) {
+    error('id required for specs validate');
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    // Build fuzzy suggestions
+    const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+    const suggestions = [];
+    try {
+      const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+      const searchLower = idOrFilename.toLowerCase();
+      for (const file of files) {
+        const content = safeReadFile(path.join(specsDir, file));
+        if (!content) continue;
+        const fmt = detectSpecFormat(content);
+        const { frontmatter } = fmt === 'bold-key'
+          ? parseBoldKeyFrontmatter(content)
+          : parseSpecFrontmatter(content);
+        const idLower = (frontmatter.id || '').toLowerCase();
+        const titleLower = (frontmatter.title || '').toLowerCase();
+        if (idLower.includes(searchLower) || titleLower.includes(searchLower)) {
+          suggestions.push(frontmatter.id || file);
+        }
+        if (suggestions.length >= 3) break;
+      }
+    } catch { /* ignore */ }
+    const suggestionText = suggestions.length > 0
+      ? `. Did you mean: ${suggestions.join(', ')}?`
+      : '';
+    error(`spec not found: ${idOrFilename}${suggestionText}`);
+  }
+
+  // Read the full body content (use the spec.body from findSpecFile)
+  const fullContent = fs.readFileSync(spec.path, 'utf-8');
+
+  // Parse section headings from the full content
+  const lines = fullContent.split('\n');
+  const sectionsFound = [];
+  for (const line of lines) {
+    const sectionMatch = line.match(/^##\s+(?:\d+\.\s+)?(.*)/);
+    if (sectionMatch) {
+      sectionsFound.push(sectionMatch[1].trim());
+    }
+  }
+
+  const errors = [];
+  const warnings = [];
+  const info = [];
+
+  // P0 (errors): Problem/Problem Statement, Requirements, Non-Goals/Scope
+  const problemPattern = /^##\s+(?:\d+\.\s+)?(?:Problem(?:\s+Statement)?)/im;
+  const requirementsPattern = /^##\s+(?:\d+\.\s+)?Requirements/im;
+  const nonGoalsPattern = /^##\s+(?:\d+\.\s+)?(?:Non[- ]Goals|Scope)/im;
+
+  if (!problemPattern.test(fullContent)) {
+    errors.push({ code: 'MISSING_SECTION', section: 'Problem', tier: 'P0', message: 'Missing required section: Problem' });
+  }
+  if (!requirementsPattern.test(fullContent)) {
+    errors.push({ code: 'MISSING_SECTION', section: 'Requirements', tier: 'P0', message: 'Missing required section: Requirements' });
+  }
+  if (!nonGoalsPattern.test(fullContent)) {
+    errors.push({ code: 'MISSING_SECTION', section: 'Non-Goals', tier: 'P0', message: 'Missing required section: Non-Goals' });
+  }
+
+  // Check for P0 requirement subsection under Requirements
+  const p0Pattern = /^###\s+P0/im;
+  if (requirementsPattern.test(fullContent) && !p0Pattern.test(fullContent)) {
+    errors.push({ code: 'NO_P0_REQUIREMENT', message: 'No P0 requirement found in Requirements section' });
+  }
+
+  // P1 (warnings): User Stories, Success Metrics
+  const userStoriesPattern = /^##\s+(?:\d+\.\s+)?User\s+Stories/im;
+  const successMetricsPattern = /^##\s+(?:\d+\.\s+)?Success\s+Metrics/im;
+
+  if (!userStoriesPattern.test(fullContent)) {
+    warnings.push({ code: 'MISSING_SECTION', section: 'User Stories', tier: 'P1', message: 'Missing recommended section: User Stories' });
+  }
+  if (!successMetricsPattern.test(fullContent)) {
+    warnings.push({ code: 'MISSING_SECTION', section: 'Success Metrics', tier: 'P1', message: 'Missing recommended section: Success Metrics' });
+  }
+
+  const implNotesPattern = /^##\s+(?:\d+\.\s+)?Implementation\s+Notes/im;
+  if (!implNotesPattern.test(fullContent)) {
+    warnings.push({ code: 'MISSING_SECTION', section: 'Implementation Notes', tier: 'P1', message: 'Missing recommended section: Implementation Notes' });
+  }
+
+  // P2 (info): other sections that are present (metadata sections excluded)
+  const metadataSections = ['Refinement Log', 'Review History'];
+  for (const section of sectionsFound) {
+    // Skip P0 and P1 sections (already classified)
+    if (/^(?:Problem(?:\s+Statement)?|Requirements|Non[- ]Goals|Scope|User\s+Stories|Success\s+Metrics|Implementation\s+Notes)$/i.test(section)) continue;
+    // Skip metadata sections
+    if (metadataSections.some(m => section.toLowerCase() === m.toLowerCase())) continue;
+    info.push({ section, tier: 'P2', message: `Additional section found: ${section}` });
+  }
+
+  const result = {
+    id: spec.frontmatter.id,
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    info,
+    sections_found: sectionsFound,
+    error_count: errors.length,
+    warning_count: warnings.length,
+  };
+
+  if (raw) {
+    // Format as grouped list for raw mode
+    let text = '';
+    if (errors.length > 0) {
+      text += 'Errors:\n';
+      for (const e of errors) text += `  - [${e.code}] ${e.message}\n`;
+    }
+    if (warnings.length > 0) {
+      text += 'Warnings:\n';
+      for (const w of warnings) text += `  - [${w.code}] ${w.message}\n`;
+    }
+    text += `\nErrors: ${errors.length}, Warnings: ${warnings.length}\n`;
+    text += errors.length === 0 ? 'PASS' : 'FAIL';
+    process.stdout.write(text + '\n');
+  } else {
+    output(result);
+  }
+}
+
+// ─── Add Log Entry ───────────────────────────────────────────────────────────
+
+/**
+ * Add a log entry to the spec's Refinement Log table.
+ * Creates the section if it does not exist.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {string} date - Entry date
+ * @param {string} version - Version string
+ * @param {string} action - Action type (Created, Refined, Approved, Imported)
+ * @param {string} summary - Entry summary
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string for attribution
+ */
+function cmdSpecsAddLogEntry(cwd, idOrFilename, date, version, action, summary, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs add-log-entry');
+  }
+  if (!date) {
+    error('date required for specs add-log-entry');
+  }
+  if (!version) {
+    error('version required for specs add-log-entry');
+  }
+  if (!action) {
+    error('action required for specs add-log-entry');
+  }
+  if (!summary) {
+    error('summary required for specs add-log-entry');
+  }
+
+  // Validate action
+  const validActions = ['Created', 'Refined', 'Approved', 'Imported'];
+  if (!validActions.includes(action)) {
+    error(`Invalid action '${action}'. Valid actions: ${validActions.join(', ')}`);
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    error(`spec not found: ${idOrFilename}`);
+  }
+
+  // Read the full file content from disk to preserve exact formatting
+  let fileContent = fs.readFileSync(spec.path, 'utf-8');
+
+  // Look for existing Refinement Log section
+  const logSectionPattern = /^## Refinement Log/m;
+  const logMatch = fileContent.match(logSectionPattern);
+
+  if (logMatch) {
+    // Find the last table row after the section heading
+    const afterSection = fileContent.slice(logMatch.index);
+    const afterLines = afterSection.split('\n');
+    let lastTableRowIndex = -1;
+
+    for (let i = 0; i < afterLines.length; i++) {
+      if (/^\|/.test(afterLines[i])) {
+        lastTableRowIndex = i;
+      }
+    }
+
+    if (lastTableRowIndex !== -1) {
+      // Insert new row after the last table row
+      afterLines.splice(lastTableRowIndex + 1, 0, `| ${date} | ${version} | ${action} | ${summary} |`);
+      fileContent = fileContent.slice(0, logMatch.index) + afterLines.join('\n');
+    } else {
+      // Section exists but no table — add table after heading
+      const insertPos = logMatch.index + logMatch[0].length;
+      const tableContent = `\n\n| Date | Version | Action | Summary |\n|------|---------|--------|--------|\n| ${date} | ${version} | ${action} | ${summary} |`;
+      fileContent = fileContent.slice(0, insertPos) + tableContent + fileContent.slice(insertPos);
+    }
+  } else {
+    // Section does not exist — append to end of file
+    const tableContent = `\n## Refinement Log\n\n| Date | Version | Action | Summary |\n|------|---------|--------|--------|\n| ${date} | ${version} | ${action} | ${summary} |\n`;
+    fileContent = fileContent.trimEnd() + '\n' + tableContent;
+  }
+
+  fs.writeFileSync(spec.path, fileContent, 'utf-8');
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    action,
+    version,
+    summary,
+    message: `\u2713 ${spec.filename}: ${action} log entry added (v${version})`,
+  };
+  output(result, raw);
+}
+
+// ─── Link Milestone ──────────────────────────────────────────────────────────
+
+/**
+ * Link a milestone to a spec by adding it to the milestones array.
+ * No duplicates allowed.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} idOrFilename - Spec id or filename
+ * @param {string} milestone - Milestone version string (e.g., "v13.0")
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string for updated_by
+ */
+function cmdSpecsLinkMilestone(cwd, idOrFilename, milestone, raw, author) {
+  if (!idOrFilename) {
+    error('id required for specs link-milestone');
+  }
+  if (!milestone) {
+    error('milestone required for specs link-milestone');
+  }
+
+  const spec = findSpecFile(cwd, idOrFilename);
+  if (!spec) {
+    error(`spec not found: ${idOrFilename}`);
+  }
+
+  // Read file content and detect format
+  const fileContent = fs.readFileSync(spec.path, 'utf-8');
+  const format = detectSpecFormat(fileContent);
+
+  // Check for duplicate
+  const milestones = spec.frontmatter.milestones || [];
+  if (milestones.includes(milestone)) {
+    const result = {
+      id: spec.frontmatter.id,
+      filename: spec.filename,
+      milestone,
+      milestones,
+      message: `${spec.filename}: already linked to ${milestone}`,
+    };
+    output(result, raw);
+    return;
+  }
+
+  // Add milestone
+  milestones.push(milestone);
+  spec.frontmatter.milestones = milestones;
+
+  // Update timestamp and author
+  spec.frontmatter.updated = new Date().toISOString();
+  if (author) {
+    spec.frontmatter.updated_by = author;
+  }
+
+  // Write back using correct format builder
+  const content = format === 'bold-key'
+    ? buildBoldKeyContent(spec.frontmatter, spec.body)
+    : buildSpecContent(spec.frontmatter, spec.body);
+  fs.writeFileSync(spec.path, content, 'utf-8');
+
+  const result = {
+    id: spec.frontmatter.id,
+    filename: spec.filename,
+    milestone,
+    milestones: spec.frontmatter.milestones,
+    message: `\u2713 ${spec.filename}: linked to ${milestone}`,
+  };
+  output(result, raw);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  ensureSpecsDir,
+  normalizeStatus,
+  getShippedMilestones,
+  parseSpecFrontmatter,
+  detectSpecFormat,
+  parseBoldKeyFrontmatter,
+  buildBoldKeyContent,
+  buildSpecContent,
+  findSpecFile,
+  cmdSpecsCreate,
+  cmdSpecsList,
+  cmdSpecsUpdateStatus,
+  cmdSpecsAppendReviewHistory,
+  cmdSpecsFinalize,
+  cmdSpecsSetStatus,
+  cmdSpecsValidate,
+  cmdSpecsAddLogEntry,
+  cmdSpecsLinkMilestone,
+};