gsd-remix 1.0.0

package/get-shit-done/bin/lib/docs.cjs

@@ -0,0 +1,267 @@
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = require('./core.cjs');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.claude', '__pycache__',
+  'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+  '.vscode', '.idea',
+]);
+
+// ─── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {boolean}
+ */
+function hasGsdMarker(filePath) {
+  try {
+    const buf = Buffer.alloc(500);
+    const fd = fs.openSync(filePath, 'r');
+    const bytesRead = fs.readSync(fd, buf, 0, 500, 0);
+    fs.closeSync(fd);
+    return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Array<{path: string, has_gsd_marker: boolean}>}
+ */
+function scanExistingDocs(cwd) {
+  const MAX_DEPTH = 4;
+  const results = [];
+
+  /**
+   * Recursively walk a directory for .md files up to MAX_DEPTH levels.
+   * @param {string} dir - Directory to scan
+   * @param {number} depth - Current depth (1-based)
+   */
+  function walkDir(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(abs, depth + 1);
+        } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+          const rel = toPosixPath(path.relative(cwd, abs));
+          results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+        }
+      }
+    } catch { /* directory may not exist — best-effort */ }
+  }
+
+  // Scan root-level .md files (non-recursive)
+  try {
+    const entries = fs.readdirSync(cwd, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+        const abs = path.join(cwd, entry.name);
+        const rel = toPosixPath(path.relative(cwd, abs));
+        results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+      }
+    }
+  } catch { /* best-effort */ }
+
+  // Recursively scan docs/ directory
+  const docsDir = path.join(cwd, 'docs');
+  walkDir(docsDir, 1);
+
+  // Fallback: if docs/ does not exist, try documentation/ or doc/
+  try {
+    fs.statSync(docsDir);
+  } catch {
+    const alternatives = ['documentation', 'doc'];
+    for (const alt of alternatives) {
+      const altDir = path.join(cwd, alt);
+      try {
+        const stat = fs.statSync(altDir);
+        if (stat.isDirectory()) {
+          walkDir(altDir, 1);
+          break;
+        }
+      } catch { /* not present */ }
+    }
+  }
+
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean signal fields
+ */
+function detectProjectType(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  // has_cli_bin: package.json has a `bin` field
+  let has_cli_bin = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    has_cli_bin = !!(pkg.bin && (typeof pkg.bin === 'string' || Object.keys(pkg.bin).length > 0));
+  } catch { /* no package.json or invalid JSON */ }
+
+  // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      is_monorepo = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+    } catch { /* ignore */ }
+  }
+
+  // has_tests: common test directories or test frameworks in devDependencies
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      const devDeps = Object.keys(pkg.devDependencies || {});
+      has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    } catch { /* ignore */ }
+  }
+
+  // has_deploy_config: various deployment config files
+  const deployFiles = [
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+    '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+  ];
+  const has_deploy_config = deployFiles.some(f => exists(f));
+
+  return {
+    has_package_json: exists('package.json'),
+    has_api_routes: (
+      exists('src/app/api') || exists('routes') || exists('src/routes') ||
+      exists('api') || exists('server')
+    ),
+    has_cli_bin,
+    is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+    has_deploy_config,
+    is_monorepo,
+    has_tests,
+  };
+}
+
+/**
+ * Detect known documentation tooling in the project.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean detection fields
+ */
+function detectDocTooling(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  return {
+    docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+    vitepress: (
+      exists('.vitepress/config.js') ||
+      exists('.vitepress/config.ts') ||
+      exists('.vitepress/config.mts')
+    ),
+    mkdocs: exists('mkdocs.yml'),
+    storybook: exists('.storybook'),
+  };
+}
+
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ *
+ * @param {string} cwd - Project root
+ * @returns {string[]} Array of workspace glob patterns, or [] if not a monorepo
+ */
+function detectMonorepoWorkspaces(cwd) {
+  // pnpm-workspace.yaml
+  try {
+    const content = fs.readFileSync(path.join(cwd, 'pnpm-workspace.yaml'), 'utf-8');
+    const lines = content.split('\n');
+    const workspaces = [];
+    for (const line of lines) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  } catch { /* not present */ }
+
+  // package.json workspaces
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+      return pkg.workspaces;
+    }
+  } catch { /* not present or invalid */ }
+
+  // lerna.json
+  try {
+    const lerna = JSON.parse(fs.readFileSync(path.join(cwd, 'lerna.json'), 'utf-8'));
+    if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+      return lerna.packages;
+    }
+  } catch { /* not present or invalid */ }
+
+  return [];
+}
+
+// ─── Public commands ──────────────────────────────────────────────────────────
+
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ *
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - Pass raw JSON flag through to output()
+ */
+function cmdDocsInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const result = {
+    doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+    commit_docs: config.commit_docs,
+    existing_docs: scanExistingDocs(cwd),
+    project_type: detectProjectType(cwd),
+    doc_tooling: detectDocTooling(cwd),
+    monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+    planning_exists: pathExistsInternal(cwd, '.planning'),
+  };
+  // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+  result.project_root = cwd;
+  const agentStatus = checkAgentsInstalled();
+  result.agents_installed = agentStatus.agents_installed;
+  result.missing_agents = agentStatus.missing_agents;
+  output(result, raw);
+}
+
+module.exports = { cmdDocsInit };

package/get-shit-done/bin/lib/frontmatter.cjs

@@ -0,0 +1,379 @@
+/**
+ * Frontmatter — YAML frontmatter parsing, serialization, and CRUD commands
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, normalizeMd, output, error, atomicWriteFileSync } = require('./core.cjs');
+
+// ─── Parsing engine ───────────────────────────────────────────────────────────
+
+/**
+ * Split a YAML inline array body on commas, respecting quoted strings.
+ * e.g. '"a, b", c' → ['a, b', 'c']
+ */
+function splitInlineArray(body) {
+  const items = [];
+  let current = '';
+  let inQuote = null; // null | '"' | "'"
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ',') {
+      const trimmed = current.trim();
+      if (trimmed) items.push(trimmed);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  const trimmed = current.trim();
+  if (trimmed) items.push(trimmed);
+  return items;
+}
+
+function extractFrontmatter(content) {
+  const frontmatter = {};
+  // Match frontmatter only at byte 0 — a `---` block later in the document
+  // body (YAML examples, horizontal rules) must never be treated as frontmatter.
+  const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+  if (!match) return frontmatter;
+
+  const yaml = match[1];
+  const lines = yaml.split(/\r?\n/);
+
+  // Stack to track nested objects: [{obj, key, indent}]
+  // obj = object to write to, key = current key collecting array items, indent = indentation level
+  let stack = [{ obj: frontmatter, key: null, indent: -1 }];
+
+  for (const line of lines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+
+    // Calculate indentation (number of leading spaces)
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+
+    // Pop stack back to appropriate level
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1];
+
+    // Check for key: value pattern
+    const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (keyMatch) {
+      const key = keyMatch[2];
+      const value = keyMatch[3].trim();
+
+      if (value === '' || value === '[') {
+        // Key with no value or opening bracket — could be nested object or array
+        // We'll determine based on next lines, for now create placeholder
+        current.obj[key] = value === '[' ? [] : {};
+        current.key = null;
+        // Push new context for potential nested content
+        stack.push({ obj: current.obj[key], key: null, indent });
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        // Inline array: key: [a, b, c] — quote-aware split (REG-04 fix)
+        current.obj[key] = splitInlineArray(value.slice(1, -1));
+        current.key = null;
+      } else {
+        // Simple key: value
+        current.obj[key] = value.replace(/^["']|["']$/g, '');
+        current.key = null;
+      }
+    } else if (line.trim().startsWith('- ')) {
+      // Array item
+      const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+
+      // If current context is an empty object, convert to array
+      if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
+        // Find the key in parent that points to this object and convert it
+        const parent = stack.length > 1 ? stack[stack.length - 2] : null;
+        if (parent) {
+          for (const k of Object.keys(parent.obj)) {
+            if (parent.obj[k] === current.obj) {
+              parent.obj[k] = [itemValue];
+              current.obj = parent.obj[k];
+              break;
+            }
+          }
+        }
+      } else if (Array.isArray(current.obj)) {
+        current.obj.push(itemValue);
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+function reconstructFrontmatter(obj) {
+  const lines = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else if (value.every(v => typeof v === 'string') && value.length <= 3 && value.join(', ').length < 60) {
+        lines.push(`${key}: [${value.join(', ')}]`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+        }
+      }
+    } else if (typeof value === 'object') {
+      lines.push(`${key}:`);
+      for (const [subkey, subval] of Object.entries(value)) {
+        if (subval === null || subval === undefined) continue;
+        if (Array.isArray(subval)) {
+          if (subval.length === 0) {
+            lines.push(`  ${subkey}: []`);
+          } else if (subval.every(v => typeof v === 'string') && subval.length <= 3 && subval.join(', ').length < 60) {
+            lines.push(`  ${subkey}: [${subval.join(', ')}]`);
+          } else {
+            lines.push(`  ${subkey}:`);
+            for (const item of subval) {
+              lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+            }
+          }
+        } else if (typeof subval === 'object') {
+          lines.push(`  ${subkey}:`);
+          for (const [subsubkey, subsubval] of Object.entries(subval)) {
+            if (subsubval === null || subsubval === undefined) continue;
+            if (Array.isArray(subsubval)) {
+              if (subsubval.length === 0) {
+                lines.push(`    ${subsubkey}: []`);
+              } else {
+                lines.push(`    ${subsubkey}:`);
+                for (const item of subsubval) {
+                  lines.push(`      - ${item}`);
+                }
+              }
+            } else {
+              lines.push(`    ${subsubkey}: ${subsubval}`);
+            }
+          }
+        } else {
+          const sv = String(subval);
+          lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+        }
+      }
+    } else {
+      const sv = String(value);
+      if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
+        lines.push(`${key}: "${sv}"`);
+      } else {
+        lines.push(`${key}: ${sv}`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+function spliceFrontmatter(content, newObj) {
+  const yamlStr = reconstructFrontmatter(newObj);
+  const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
+  if (match) {
+    return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+  }
+  return `---\n${yamlStr}\n---\n\n` + content;
+}
+
+function parseMustHavesBlock(content, blockName) {
+  // Extract a specific block from must_haves in raw frontmatter YAML
+  // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}]
+  const fmMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+  if (!fmMatch) return [];
+
+  const yaml = fmMatch[1];
+
+  // Find must_haves: first to detect its indentation level
+  const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
+  if (!mustHavesMatch) return [];
+  const mustHavesIndent = mustHavesMatch[1].length;
+
+  // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves
+  // It must be indented more than must_haves but we detect the actual indent dynamically
+  const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm');
+  const blockMatch = yaml.match(blockPattern);
+  if (!blockMatch) return [];
+
+  const blockIndent = blockMatch[1].length;
+  // The block must be nested under must_haves (more indented)
+  if (blockIndent <= mustHavesIndent) return [];
+
+  // Find where the block starts in the yaml string
+  const blockStart = yaml.indexOf(blockMatch[0]);
+  if (blockStart === -1) return [];
+
+  const afterBlock = yaml.slice(blockStart);
+  const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
+
+  // List items are indented one level deeper than blockIndent
+  // Continuation KVs are indented one level deeper than list items
+  const items = [];
+  let current = null;
+  let listItemIndent = -1; // detected from first "- " line
+
+  for (const line of blockLines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+    const indent = line.match(/^(\s*)/)[1].length;
+    // Stop at same or lower indent level than the block header
+    if (indent <= blockIndent && line.trim() !== '') break;
+
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('- ')) {
+      // Detect list item indent from the first occurrence
+      if (listItemIndent === -1) listItemIndent = indent;
+
+      // Only treat as a top-level list item if at the expected indent
+      if (indent === listItemIndent) {
+        if (current) items.push(current);
+        current = {};
+        const afterDash = trimmed.slice(2);
+        // Check if it's a simple string item (no colon means not a key-value)
+        if (!afterDash.includes(':')) {
+          current = afterDash.replace(/^["']|["']$/g, '');
+        } else {
+          // Key-value on same line as dash: "- path: value"
+          const kvMatch = afterDash.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+          if (kvMatch) {
+            current = {};
+            current[kvMatch[1]] = kvMatch[2];
+          }
+        }
+        continue;
+      }
+    }
+
+    if (current && typeof current === 'object' && indent > listItemIndent) {
+      // Continuation key-value or nested array item
+      if (trimmed.startsWith('- ')) {
+        // Array item under a key
+        const arrVal = trimmed.slice(2).replace(/^["']|["']$/g, '');
+        const keys = Object.keys(current);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && !Array.isArray(current[lastKey])) {
+          current[lastKey] = current[lastKey] ? [current[lastKey]] : [];
+        }
+        if (lastKey) current[lastKey].push(arrVal);
+      } else {
+        const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+        if (kvMatch) {
+          const val = kvMatch[2];
+          // Try to parse as number
+          current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+        }
+      }
+    }
+  }
+  if (current) items.push(current);
+
+  // Warn when must_haves block exists but parsed as empty -- likely YAML formatting issue.
+  // This is a critical diagnostic: empty must_haves causes verification to silently degrade
+  // to Option C (LLM-derived truths) instead of checking documented contracts.
+  if (items.length === 0 && blockLines.length > 0) {
+    const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+    if (nonEmptyLines > 0) {
+      process.stderr.write(
+        `[gsd-tools] WARNING: must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+        `Possible YAML formatting issue — verification will fall back to LLM-derived truths.\n`
+      );
+    }
+  }
+
+  return items;
+}
+
+// ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+
+const FRONTMATTER_SCHEMAS = {
+  plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
+  verification: { required: ['phase', 'verified', 'status', 'score'] },
+};
+
+function cmdFrontmatterGet(cwd, filePath, field, raw) {
+  if (!filePath) { error('file path required'); }
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) { error('file path contains null bytes'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  if (field) {
+    const value = fm[field];
+    if (value === undefined) { output({ error: 'Field not found', field }, raw); return; }
+    output({ [field]: value }, raw, JSON.stringify(value));
+  } else {
+    output(fm, raw);
+  }
+}
+
+function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
+  if (!filePath || !field || value === undefined) { error('file, field, and value required'); }
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) { error('file path contains null bytes'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let parsedValue;
+  try { parsedValue = JSON.parse(value); } catch { parsedValue = value; }
+  fm[field] = parsedValue;
+  const newContent = spliceFrontmatter(content, fm);
+  atomicWriteFileSync(fullPath, normalizeMd(newContent));
+  output({ updated: true, field, value: parsedValue }, raw, 'true');
+}
+
+function cmdFrontmatterMerge(cwd, filePath, data, raw) {
+  if (!filePath || !data) { error('file and data required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let mergeData;
+  try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; }
+  Object.assign(fm, mergeData);
+  const newContent = spliceFrontmatter(content, fm);
+  atomicWriteFileSync(fullPath, normalizeMd(newContent));
+  output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true');
+}
+
+function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
+  if (!filePath || !schemaName) { error('file and schema required'); }
+  const schema = FRONTMATTER_SCHEMAS[schemaName];
+  if (!schema) { error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  const missing = schema.required.filter(f => fm[f] === undefined);
+  const present = schema.required.filter(f => fm[f] !== undefined);
+  output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+}
+
+module.exports = {
+  extractFrontmatter,
+  reconstructFrontmatter,
+  spliceFrontmatter,
+  parseMustHavesBlock,
+  FRONTMATTER_SCHEMAS,
+  cmdFrontmatterGet,
+  cmdFrontmatterSet,
+  cmdFrontmatterMerge,
+  cmdFrontmatterValidate,
+};