lean-spec 0.2.1 → 0.2.2

package/dist/{chunk-ER23B6KS.js → chunk-7MCDTSVE.js}

@@ -3,18 +3,19 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import * as fs9 from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
 import * as path2 from 'path';
 import { dirname, join } from 'path';
 import chalk16 from 'chalk';
-import matter from 'gray-matter';
-import yaml from 'js-yaml';
+import matter4 from 'gray-matter';
+import yaml3 from 'js-yaml';
 import { spawn, execSync } from 'child_process';
 import ora from 'ora';
 import stripAnsi from 'strip-ansi';
 import { fileURLToPath } from 'url';
 import { select } from '@inquirer/prompts';
-import { ComplexityValidator, TokenCounter, countTokens } from '@leanspec/core';
-import dayjs2 from 'dayjs';
+import { encoding_for_model } from 'tiktoken';
+import dayjs3 from 'dayjs';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { readFileSync } from 'fs';
@@ -142,13 +143,13 @@ async function loadSubFiles(specDir, options = {}) {
       if (entry.name === "README.md") continue;
       if (entry.isDirectory()) continue;
       const filePath = path2.join(specDir, entry.name);
-      const stat5 = await fs9.stat(filePath);
+      const stat6 = await fs9.stat(filePath);
       const ext = path2.extname(entry.name).toLowerCase();
       const isDocument = ext === ".md";
       const subFile = {
         name: entry.name,
         path: filePath,
-        size: stat5.size,
+        size: stat6.size,
         type: isDocument ? "document" : "asset"
       };
       if (isDocument && options.includeContent) {
@@ -669,9 +670,9 @@ async function createSpec(name, options = {}) {
     const title = options.title || name;
     const varContext = await buildVariableContext(config, { name: title, date });
     content = resolveVariables(template, varContext);
-    const parsed = matter(content, {
+    const parsed = matter4(content, {
       engines: {
-        yaml: (str) => yaml.load(str, { schema: yaml.FAILSAFE_SCHEMA })
+        yaml: (str) => yaml3.load(str, { schema: yaml3.FAILSAFE_SCHEMA })
       }
     });
     normalizeDateFields(parsed.data);
@@ -694,9 +695,9 @@ async function createSpec(name, options = {}) {
       frontmatter: parsed.data
     };
     parsed.content = resolveVariables(parsed.content, contextWithFrontmatter);
-    const { enrichWithTimestamps } = await import('./frontmatter-R2DANL5X.js');
-    enrichWithTimestamps(parsed.data);
-    content = matter.stringify(parsed.content, parsed.data);
+    const { enrichWithTimestamps: enrichWithTimestamps2 } = await import('./frontmatter-R2DANL5X.js');
+    enrichWithTimestamps2(parsed.data);
+    content = matter4.stringify(parsed.content, parsed.data);
     if (options.description) {
       content = content.replace(
         /## Overview\s+<!-- What are we solving\? Why now\? -->/,
@@ -1330,8 +1331,8 @@ async function listTemplates(cwd = process.cwd()) {
   console.log(chalk16.cyan("Available files:"));
   for (const file of templateFiles) {
     const filePath = path2.join(templatesDir, file);
-    const stat5 = await fs9.stat(filePath);
-    const sizeKB = (stat5.size / 1024).toFixed(1);
+    const stat6 = await fs9.stat(filePath);
+    const sizeKB = (stat6.size / 1024).toFixed(1);
     console.log(`  ${file} (${sizeKB} KB)`);
   }
   console.log("");
@@ -1840,9 +1841,9 @@ var FrontmatterValidator = class {
     const warnings = [];
     let parsed;
     try {
-      parsed = matter(content, {
+      parsed = matter4(content, {
         engines: {
-          yaml: (str) => yaml.load(str, { schema: yaml.FAILSAFE_SCHEMA })
+          yaml: (str) => yaml3.load(str, { schema: yaml3.FAILSAFE_SCHEMA })
         }
       });
     } catch (error) {
@@ -1970,7 +1971,7 @@ var StructureValidator = class {
     const warnings = [];
     let parsed;
     try {
-      parsed = matter(content);
+      parsed = matter4(content);
     } catch (error) {
       errors.push({
         message: "Failed to parse frontmatter",
@@ -1987,33 +1988,6 @@ var StructureValidator = class {
       });
     }
     const headings = this.extractHeadings(body);
-    for (const requiredSection of this.requiredSections) {
-      const found = headings.some(
-        (h) => h.level === 2 && h.text.toLowerCase() === requiredSection.toLowerCase()
-      );
-      if (!found) {
-        if (this.strict) {
-          errors.push({
-            message: `Missing required section: ## ${requiredSection}`,
-            suggestion: `Add ## ${requiredSection} section to the spec`
-          });
-        } else {
-          warnings.push({
-            message: `Recommended section missing: ## ${requiredSection}`,
-            suggestion: `Consider adding ## ${requiredSection} section`
-          });
-        }
-      }
-    }
-    const emptySections = this.findEmptySections(body, headings);
-    for (const section of emptySections) {
-      if (this.requiredSections.some((req) => req.toLowerCase() === section.toLowerCase())) {
-        warnings.push({
-          message: `Empty required section: ## ${section}`,
-          suggestion: "Add content to this section or remove it"
-        });
-      }
-    }
     const duplicates = this.findDuplicateHeaders(headings);
     for (const dup of duplicates) {
       errors.push({
@@ -2296,9 +2270,1099 @@ var CorruptionValidator = class {
         suggestion: "Check for missing closing * in markdown content (not code blocks)"
       });
     }
-    return errors;
+    return errors;
+  }
+};
+function normalizeDateFields2(data) {
+  const dateFields = ["created", "completed", "updated", "due"];
+  for (const field of dateFields) {
+    if (data[field] instanceof Date) {
+      data[field] = data[field].toISOString().split("T")[0];
+    }
+  }
+}
+function enrichWithTimestamps(data, previousData) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (!data.created_at) {
+    data.created_at = now;
+  }
+  if (previousData) {
+    data.updated_at = now;
+  }
+  if (data.status === "complete" && previousData?.status !== "complete" && !data.completed_at) {
+    data.completed_at = now;
+    if (!data.completed) {
+      data.completed = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    }
+  }
+  if (previousData && data.status !== previousData.status) {
+    if (!Array.isArray(data.transitions)) {
+      data.transitions = [];
+    }
+    data.transitions.push({
+      status: data.status,
+      at: now
+    });
+  }
+}
+function normalizeTagsField(data) {
+  if (data.tags && typeof data.tags === "string") {
+    try {
+      const parsed = JSON.parse(data.tags);
+      if (Array.isArray(parsed)) {
+        data.tags = parsed;
+      }
+    } catch {
+      data.tags = data.tags.split(",").map((t) => t.trim());
+    }
+  }
+}
+function validateCustomFields(frontmatter, config) {
+  {
+    return frontmatter;
+  }
+}
+function parseFrontmatterFromString(content, filePath, config) {
+  try {
+    const parsed = matter4(content, {
+      engines: {
+        yaml: (str) => yaml3.load(str, { schema: yaml3.FAILSAFE_SCHEMA })
+      }
+    });
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+      return parseFallbackFields(content);
+    }
+    if (!parsed.data.status) {
+      if (filePath) ;
+      return null;
+    }
+    if (!parsed.data.created) {
+      if (filePath) ;
+      return null;
+    }
+    const validStatuses = ["planned", "in-progress", "complete", "archived"];
+    if (!validStatuses.includes(parsed.data.status)) {
+      if (filePath) ;
+    }
+    if (parsed.data.priority) {
+      const validPriorities = ["low", "medium", "high", "critical"];
+      if (!validPriorities.includes(parsed.data.priority)) {
+        if (filePath) ;
+      }
+    }
+    normalizeTagsField(parsed.data);
+    const knownFields = [
+      "status",
+      "created",
+      "tags",
+      "priority",
+      "related",
+      "depends_on",
+      "updated",
+      "completed",
+      "assignee",
+      "reviewer",
+      "issue",
+      "pr",
+      "epic",
+      "breaking",
+      "due",
+      "created_at",
+      "updated_at",
+      "completed_at",
+      "transitions"
+    ];
+    const customFields = config?.frontmatter?.custom ? Object.keys(config.frontmatter.custom) : [];
+    const allKnownFields = [...knownFields, ...customFields];
+    const unknownFields = Object.keys(parsed.data).filter((k) => !allKnownFields.includes(k));
+    if (unknownFields.length > 0 && filePath) ;
+    const validatedData = validateCustomFields(parsed.data, config);
+    return validatedData;
+  } catch (error) {
+    console.error(`Error parsing frontmatter${""}:`, error);
+    return null;
+  }
+}
+function parseFallbackFields(content) {
+  const statusMatch = content.match(/\*\*Status\*\*:\s*(?:📅\s*)?(\w+(?:-\w+)?)/i);
+  const createdMatch = content.match(/\*\*Created\*\*:\s*(\d{4}-\d{2}-\d{2})/);
+  if (statusMatch && createdMatch) {
+    const status = statusMatch[1].toLowerCase().replace(/\s+/g, "-");
+    const created = createdMatch[1];
+    return {
+      status,
+      created
+    };
+  }
+  return null;
+}
+function createUpdatedFrontmatter(existingContent, updates) {
+  const parsed = matter4(existingContent, {
+    engines: {
+      yaml: (str) => yaml3.load(str, { schema: yaml3.FAILSAFE_SCHEMA })
+    }
+  });
+  const previousData = { ...parsed.data };
+  const newData = { ...parsed.data, ...updates };
+  normalizeDateFields2(newData);
+  enrichWithTimestamps(newData, previousData);
+  if (updates.status === "complete" && !newData.completed) {
+    newData.completed = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  }
+  if ("updated" in parsed.data) {
+    newData.updated = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  }
+  let updatedContent = parsed.content;
+  updatedContent = updateVisualMetadata(updatedContent, newData);
+  const newContent = matter4.stringify(updatedContent, newData);
+  return {
+    content: newContent,
+    frontmatter: newData
+  };
+}
+function updateVisualMetadata(content, frontmatter) {
+  const statusEmoji = getStatusEmojiPlain(frontmatter.status);
+  const statusLabel = frontmatter.status.charAt(0).toUpperCase() + frontmatter.status.slice(1).replace("-", " ");
+  const created = frontmatter.created;
+  let metadataLine = `> **Status**: ${statusEmoji} ${statusLabel}`;
+  if (frontmatter.priority) {
+    const priorityLabel = frontmatter.priority.charAt(0).toUpperCase() + frontmatter.priority.slice(1);
+    metadataLine += ` \xB7 **Priority**: ${priorityLabel}`;
+  }
+  metadataLine += ` \xB7 **Created**: ${created}`;
+  if (frontmatter.tags && frontmatter.tags.length > 0) {
+    metadataLine += ` \xB7 **Tags**: ${frontmatter.tags.join(", ")}`;
+  }
+  let secondLine = "";
+  if (frontmatter.assignee || frontmatter.reviewer) {
+    const assignee = frontmatter.assignee || "TBD";
+    const reviewer = frontmatter.reviewer || "TBD";
+    secondLine = `
+> **Assignee**: ${assignee} \xB7 **Reviewer**: ${reviewer}`;
+  }
+  const metadataPattern = /^>\s+\*\*Status\*\*:.*(?:\n>\s+\*\*Assignee\*\*:.*)?/m;
+  if (metadataPattern.test(content)) {
+    return content.replace(metadataPattern, metadataLine + secondLine);
+  } else {
+    const titleMatch = content.match(/^#\s+.+$/m);
+    if (titleMatch) {
+      const insertPos = titleMatch.index + titleMatch[0].length;
+      return content.slice(0, insertPos) + "\n\n" + metadataLine + secondLine + "\n" + content.slice(insertPos);
+    }
+  }
+  return content;
+}
+function getStatusEmojiPlain(status) {
+  switch (status) {
+    case "planned":
+      return "\u{1F4C5}";
+    case "in-progress":
+      return "\u23F3";
+    case "complete":
+      return "\u2705";
+    case "archived":
+      return "\u{1F4E6}";
+    default:
+      return "\u{1F4C4}";
+  }
+}
+function parseMarkdownSections(content) {
+  const lines = content.split("\n");
+  const sections = [];
+  const sectionStack = [];
+  let inCodeBlock = false;
+  let currentLineNum = 1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    currentLineNum = i + 1;
+    if (line.trimStart().startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) {
+      continue;
+    }
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const title = headingMatch[2].trim();
+      while (sectionStack.length > 0 && sectionStack[sectionStack.length - 1].level >= level) {
+        const closedSection = sectionStack.pop();
+        closedSection.endLine = currentLineNum - 1;
+        closedSection.lineCount = closedSection.endLine - closedSection.startLine + 1;
+      }
+      const newSection = {
+        title,
+        level,
+        startLine: currentLineNum,
+        endLine: lines.length,
+        // Will be updated when section closes
+        lineCount: 0,
+        // Will be calculated when section closes
+        subsections: []
+      };
+      if (sectionStack.length > 0) {
+        sectionStack[sectionStack.length - 1].subsections.push(newSection);
+      } else {
+        sections.push(newSection);
+      }
+      sectionStack.push(newSection);
+    }
+  }
+  while (sectionStack.length > 0) {
+    const closedSection = sectionStack.pop();
+    closedSection.endLine = lines.length;
+    closedSection.lineCount = closedSection.endLine - closedSection.startLine + 1;
+  }
+  return sections;
+}
+function flattenSections(sections) {
+  const result = [];
+  for (const section of sections) {
+    result.push(section);
+    result.push(...flattenSections(section.subsections));
+  }
+  return result;
+}
+function extractLines(content, startLine, endLine) {
+  const lines = content.split("\n");
+  if (startLine < 1 || endLine < startLine || startLine > lines.length || endLine > lines.length) {
+    throw new Error(`Invalid line range: ${startLine}-${endLine}`);
+  }
+  const extracted = lines.slice(startLine - 1, endLine);
+  return extracted.join("\n");
+}
+function removeLines(content, startLine, endLine) {
+  const lines = content.split("\n");
+  if (startLine < 1 || endLine < startLine || startLine > lines.length) {
+    throw new Error(`Invalid line range: ${startLine}-${endLine}`);
+  }
+  lines.splice(startLine - 1, endLine - startLine + 1);
+  return lines.join("\n");
+}
+function countLines(content) {
+  return content.split("\n").length;
+}
+function analyzeMarkdownStructure(content) {
+  const lines = content.split("\n");
+  const sections = parseMarkdownSections(content);
+  const allSections = flattenSections(sections);
+  const levelCounts = { h1: 0, h2: 0, h3: 0, h4: 0, h5: 0, h6: 0, total: 0 };
+  for (const section of allSections) {
+    levelCounts[`h${section.level}`]++;
+    levelCounts.total++;
+  }
+  let codeBlocks = 0;
+  let inCodeBlock = false;
+  for (const line of lines) {
+    if (line.trimStart().startsWith("```")) {
+      if (!inCodeBlock) {
+        codeBlocks++;
+      }
+      inCodeBlock = !inCodeBlock;
+    }
+  }
+  let maxNesting = 0;
+  function calculateNesting(secs, depth) {
+    for (const section of secs) {
+      maxNesting = Math.max(maxNesting, depth);
+      calculateNesting(section.subsections, depth + 1);
+    }
+  }
+  calculateNesting(sections, 1);
+  return {
+    lines: lines.length,
+    sections,
+    allSections,
+    sectionsByLevel: levelCounts,
+    codeBlocks,
+    maxNesting
+  };
+}
+var TokenCounter = class {
+  encoding;
+  constructor() {
+    this.encoding = encoding_for_model("gpt-4");
+  }
+  /**
+   * Clean up resources (important to prevent memory leaks)
+   */
+  dispose() {
+    this.encoding.free();
+  }
+  /**
+   * Count tokens in a string
+   */
+  countString(text) {
+    const tokens = this.encoding.encode(text);
+    return tokens.length;
+  }
+  /**
+   * Count tokens in content (convenience method for analyze command)
+   * Alias for countString - provided for clarity in command usage
+   */
+  async countTokensInContent(content) {
+    return this.countString(content);
+  }
+  /**
+   * Count tokens in a single file
+   */
+  async countFile(filePath, options = {}) {
+    const content = await fs9.readFile(filePath, "utf-8");
+    const tokens = this.countString(content);
+    const lines = content.split("\n").length;
+    const result = {
+      total: tokens,
+      files: [{
+        path: filePath,
+        tokens,
+        lines
+      }]
+    };
+    if (options.detailed) {
+      result.breakdown = await this.analyzeBreakdown(content);
+    }
+    return result;
+  }
+  /**
+   * Count tokens in a spec (including sub-specs if requested)
+   */
+  async countSpec(specPath, options = {}) {
+    const stats = await fs9.stat(specPath);
+    if (stats.isFile()) {
+      return this.countFile(specPath, options);
+    }
+    const files = await fs9.readdir(specPath);
+    const mdFiles = files.filter((f) => f.endsWith(".md"));
+    const filesToCount = [];
+    if (mdFiles.includes("README.md")) {
+      filesToCount.push("README.md");
+    }
+    if (options.includeSubSpecs) {
+      mdFiles.forEach((f) => {
+        if (f !== "README.md") {
+          filesToCount.push(f);
+        }
+      });
+    }
+    const fileCounts = [];
+    let totalTokens = 0;
+    let totalBreakdown;
+    if (options.detailed) {
+      totalBreakdown = {
+        code: 0,
+        prose: 0,
+        tables: 0,
+        frontmatter: 0
+      };
+    }
+    for (const file of filesToCount) {
+      const filePath = path2.join(specPath, file);
+      const content = await fs9.readFile(filePath, "utf-8");
+      const tokens = this.countString(content);
+      const lines = content.split("\n").length;
+      fileCounts.push({
+        path: file,
+        tokens,
+        lines
+      });
+      totalTokens += tokens;
+      if (options.detailed && totalBreakdown) {
+        const breakdown = await this.analyzeBreakdown(content);
+        totalBreakdown.code += breakdown.code;
+        totalBreakdown.prose += breakdown.prose;
+        totalBreakdown.tables += breakdown.tables;
+        totalBreakdown.frontmatter += breakdown.frontmatter;
+      }
+    }
+    return {
+      total: totalTokens,
+      files: fileCounts,
+      breakdown: totalBreakdown
+    };
+  }
+  /**
+   * Analyze token breakdown by content type
+   */
+  async analyzeBreakdown(content) {
+    const breakdown = {
+      code: 0,
+      prose: 0,
+      tables: 0,
+      frontmatter: 0
+    };
+    let body = content;
+    let frontmatterContent = "";
+    try {
+      const parsed = matter4(content);
+      body = parsed.content;
+      frontmatterContent = parsed.matter;
+      breakdown.frontmatter = this.countString(frontmatterContent);
+    } catch {
+    }
+    let inCodeBlock = false;
+    let inTable = false;
+    const lines = body.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      if (trimmed.startsWith("```")) {
+        inCodeBlock = !inCodeBlock;
+        breakdown.code += this.countString(line + "\n");
+        continue;
+      }
+      if (inCodeBlock) {
+        breakdown.code += this.countString(line + "\n");
+        continue;
+      }
+      const isTableSeparator = trimmed.includes("|") && /[-:]{3,}/.test(trimmed);
+      const isTableRow = trimmed.includes("|") && trimmed.startsWith("|");
+      if (isTableSeparator || inTable && isTableRow) {
+        inTable = true;
+        breakdown.tables += this.countString(line + "\n");
+        continue;
+      } else if (inTable && !isTableRow) {
+        inTable = false;
+      }
+      breakdown.prose += this.countString(line + "\n");
+    }
+    return breakdown;
+  }
+  /**
+   * Check if content fits within token limit
+   */
+  isWithinLimit(count, limit) {
+    return count.total <= limit;
+  }
+  /**
+   * Format token count for display
+   */
+  formatCount(count, verbose = false) {
+    if (!verbose) {
+      return `${count.total.toLocaleString()} tokens`;
+    }
+    const lines = [
+      `Total: ${count.total.toLocaleString()} tokens`,
+      "",
+      "Files:"
+    ];
+    for (const file of count.files) {
+      const lineInfo = file.lines ? ` (${file.lines} lines)` : "";
+      lines.push(`  ${file.path}: ${file.tokens.toLocaleString()} tokens${lineInfo}`);
+    }
+    if (count.breakdown) {
+      const b = count.breakdown;
+      const total = b.code + b.prose + b.tables + b.frontmatter;
+      lines.push("");
+      lines.push("Content Breakdown:");
+      lines.push(`  Prose:       ${b.prose.toLocaleString()} tokens (${Math.round(b.prose / total * 100)}%)`);
+      lines.push(`  Code:        ${b.code.toLocaleString()} tokens (${Math.round(b.code / total * 100)}%)`);
+      lines.push(`  Tables:      ${b.tables.toLocaleString()} tokens (${Math.round(b.tables / total * 100)}%)`);
+      lines.push(`  Frontmatter: ${b.frontmatter.toLocaleString()} tokens (${Math.round(b.frontmatter / total * 100)}%)`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get performance indicators based on token count
+   * Based on research from spec 066
+   */
+  getPerformanceIndicators(tokenCount) {
+    const baselineTokens = 1200;
+    const costMultiplier = Math.round(tokenCount / baselineTokens * 10) / 10;
+    if (tokenCount < 2e3) {
+      return {
+        level: "excellent",
+        costMultiplier,
+        effectiveness: 100,
+        recommendation: "Optimal size for Context Economy"
+      };
+    } else if (tokenCount < 3500) {
+      return {
+        level: "good",
+        costMultiplier,
+        effectiveness: 95,
+        recommendation: "Good size, no action needed"
+      };
+    } else if (tokenCount < 5e3) {
+      return {
+        level: "warning",
+        costMultiplier,
+        effectiveness: 85,
+        recommendation: "Consider simplification or sub-specs"
+      };
+    } else {
+      return {
+        level: "problem",
+        costMultiplier,
+        effectiveness: 70,
+        recommendation: "Should split - elevated token count"
+      };
+    }
+  }
+};
+async function countTokens(input, options) {
+  const counter = new TokenCounter();
+  try {
+    if (typeof input === "string") {
+      return {
+        total: counter.countString(input),
+        files: []
+      };
+    } else if ("content" in input) {
+      return {
+        total: counter.countString(input.content),
+        files: []
+      };
+    } else if ("filePath" in input) {
+      return await counter.countFile(input.filePath, options);
+    } else if ("specPath" in input) {
+      return await counter.countSpec(input.specPath, options);
+    }
+    throw new Error("Invalid input type");
+  } finally {
+    counter.dispose();
+  }
+}
+var ComplexityValidator = class {
+  name = "complexity";
+  description = "Direct token threshold validation with independent structure checks";
+  excellentThreshold;
+  goodThreshold;
+  warningThreshold;
+  maxLines;
+  warningLines;
+  constructor(options = {}) {
+    this.excellentThreshold = options.excellentThreshold ?? 2e3;
+    this.goodThreshold = options.goodThreshold ?? 3500;
+    this.warningThreshold = options.warningThreshold ?? 5e3;
+    this.maxLines = options.maxLines ?? 500;
+    this.warningLines = options.warningLines ?? 400;
+  }
+  async validate(spec, content) {
+    const errors = [];
+    const warnings = [];
+    const metrics = await this.analyzeComplexity(content, spec);
+    const tokenValidation = this.validateTokens(metrics.tokenCount);
+    if (tokenValidation.level === "error") {
+      errors.push({
+        message: tokenValidation.message,
+        suggestion: "Consider splitting for Context Economy (attention and cognitive load)"
+      });
+    } else if (tokenValidation.level === "warning") {
+      warnings.push({
+        message: tokenValidation.message,
+        suggestion: "Consider simplification or splitting into sub-specs"
+      });
+    }
+    const structureChecks = this.checkStructure(metrics);
+    for (const check of structureChecks) {
+      if (!check.passed && check.message) {
+        warnings.push({
+          message: check.message,
+          suggestion: check.suggestion
+        });
+      }
+    }
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+  /**
+   * Validate token count with direct thresholds
+   */
+  validateTokens(tokens) {
+    if (tokens > this.warningThreshold) {
+      return {
+        level: "error",
+        message: `Spec has ${tokens.toLocaleString()} tokens (threshold: ${this.warningThreshold.toLocaleString()}) - should split`
+      };
+    }
+    if (tokens > this.goodThreshold) {
+      return {
+        level: "warning",
+        message: `Spec has ${tokens.toLocaleString()} tokens (threshold: ${this.goodThreshold.toLocaleString()})`
+      };
+    }
+    if (tokens > this.excellentThreshold) {
+      return {
+        level: "info",
+        message: `Spec has ${tokens.toLocaleString()} tokens - acceptable, watch for growth`
+      };
+    }
+    return {
+      level: "excellent",
+      message: `Spec has ${tokens.toLocaleString()} tokens - excellent`
+    };
+  }
+  /**
+   * Check structure quality independently
+   */
+  checkStructure(metrics) {
+    const checks = [];
+    if (metrics.hasSubSpecs) {
+      if (metrics.tokenCount > this.excellentThreshold) {
+        checks.push({
+          passed: true,
+          message: `Uses ${metrics.subSpecCount} sub-spec file${metrics.subSpecCount > 1 ? "s" : ""} for progressive disclosure`
+        });
+      }
+    } else if (metrics.tokenCount > this.goodThreshold) {
+      checks.push({
+        passed: false,
+        message: "Consider using sub-spec files (DESIGN.md, IMPLEMENTATION.md, etc.)",
+        suggestion: "Progressive disclosure reduces cognitive load for large specs"
+      });
+    }
+    if (metrics.sectionCount >= 15 && metrics.sectionCount <= 35) {
+      if (metrics.tokenCount > this.excellentThreshold) {
+        checks.push({
+          passed: true,
+          message: `Good sectioning (${metrics.sectionCount} sections) enables cognitive chunking`
+        });
+      }
+    } else if (metrics.sectionCount < 8 && metrics.lineCount > 200) {
+      checks.push({
+        passed: false,
+        message: `Only ${metrics.sectionCount} sections - too monolithic`,
+        suggestion: "Break into 15-35 sections for better readability (7\xB12 cognitive chunks)"
+      });
+    }
+    if (metrics.codeBlockCount > 20) {
+      checks.push({
+        passed: false,
+        message: `High code block density (${metrics.codeBlockCount} blocks)`,
+        suggestion: "Consider moving examples to separate files or sub-specs"
+      });
+    }
+    return checks;
+  }
+  /**
+   * Analyze complexity metrics from spec content
+   */
+  async analyzeComplexity(content, spec) {
+    let body;
+    try {
+      const parsed = matter4(content);
+      body = parsed.content;
+    } catch {
+      body = content;
+    }
+    const lines = content.split("\n");
+    const lineCount = lines.length;
+    let sectionCount = 0;
+    let inCodeBlock = false;
+    for (const line of lines) {
+      if (line.trim().startsWith("```")) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (!inCodeBlock && line.match(/^#{2,4}\s/)) {
+        sectionCount++;
+      }
+    }
+    const codeBlockCount = Math.floor((content.match(/```/g) || []).length / 2);
+    const listItemCount = lines.filter((line) => line.match(/^[\s]*[-*]\s/) || line.match(/^[\s]*\d+\.\s/)).length;
+    const tableCount = lines.filter((line) => line.includes("|") && line.match(/[-:]{3,}/)).length;
+    const counter = new TokenCounter();
+    const tokenCount = counter.countString(content);
+    counter.dispose();
+    let hasSubSpecs = false;
+    let subSpecCount = 0;
+    try {
+      const specDir = path2.dirname(spec.filePath);
+      const files = await fs9.readdir(specDir);
+      const mdFiles = files.filter(
+        (f) => f.endsWith(".md") && f !== "README.md"
+      );
+      hasSubSpecs = mdFiles.length > 0;
+      subSpecCount = mdFiles.length;
+    } catch (error) {
+      hasSubSpecs = /\b(DESIGN|IMPLEMENTATION|TESTING|CONFIGURATION|API|MIGRATION)\.md\b/.test(content);
+      const subSpecMatches = content.match(/\b[A-Z-]+\.md\b/g) || [];
+      const uniqueSubSpecs = new Set(subSpecMatches.filter((m) => m !== "README.md"));
+      subSpecCount = uniqueSubSpecs.size;
+    }
+    const averageSectionLength = sectionCount > 0 ? Math.round(lineCount / sectionCount) : 0;
+    return {
+      lineCount,
+      tokenCount,
+      sectionCount,
+      codeBlockCount,
+      listItemCount,
+      tableCount,
+      hasSubSpecs,
+      subSpecCount,
+      averageSectionLength
+    };
+  }
+};
+var FIELD_WEIGHTS = {
+  title: 100,
+  name: 70,
+  tags: 70,
+  description: 50,
+  content: 10
+};
+function calculateMatchScore(match, queryTerms, totalMatches, matchPosition) {
+  let score = FIELD_WEIGHTS[match.field];
+  match.text.toLowerCase();
+  const hasExactMatch = queryTerms.some((term) => {
+    const regex = new RegExp(`\\b${escapeRegex(term)}\\b`, "i");
+    return regex.test(match.text);
+  });
+  if (hasExactMatch) {
+    score *= 2;
+  }
+  const positionBonus = Math.max(1, 1.5 - matchPosition * 0.1);
+  score *= positionBonus;
+  const frequencyFactor = Math.min(1, 3 / totalMatches);
+  score *= frequencyFactor;
+  return Math.min(100, score * 10);
+}
+function calculateSpecScore(matches) {
+  if (matches.length === 0) return 0;
+  const fieldScores = {};
+  for (const match of matches) {
+    const field = match.field;
+    const currentScore = fieldScores[field] || 0;
+    fieldScores[field] = Math.max(currentScore, match.score);
+  }
+  let totalScore = 0;
+  let totalWeight = 0;
+  for (const [field, score] of Object.entries(fieldScores)) {
+    const weight = FIELD_WEIGHTS[field] || 1;
+    totalScore += score * weight;
+    totalWeight += weight;
+  }
+  return totalWeight > 0 ? Math.round(totalScore / totalWeight) : 0;
+}
+function containsAllTerms(text, queryTerms) {
+  const textLower = text.toLowerCase();
+  return queryTerms.every((term) => textLower.includes(term));
+}
+function countOccurrences(text, queryTerms) {
+  const textLower = text.toLowerCase();
+  let count = 0;
+  for (const term of queryTerms) {
+    const regex = new RegExp(escapeRegex(term), "gi");
+    const matches = textLower.match(regex);
+    count += matches ? matches.length : 0;
+  }
+  return count;
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findMatchPositions(text, queryTerms) {
+  const positions = [];
+  const textLower = text.toLowerCase();
+  for (const term of queryTerms) {
+    const termLower = term.toLowerCase();
+    let index = 0;
+    while ((index = textLower.indexOf(termLower, index)) !== -1) {
+      positions.push([index, index + term.length]);
+      index += term.length;
+    }
+  }
+  positions.sort((a, b) => a[0] - b[0]);
+  const merged = [];
+  for (const pos of positions) {
+    if (merged.length === 0) {
+      merged.push(pos);
+    } else {
+      const last = merged[merged.length - 1];
+      if (pos[0] <= last[1]) {
+        last[1] = Math.max(last[1], pos[1]);
+      } else {
+        merged.push(pos);
+      }
+    }
+  }
+  return merged;
+}
+function extractContext(text, matchIndex, queryTerms, contextLength = 80) {
+  const lines = text.split("\n");
+  const matchLine = lines[matchIndex] || "";
+  if (matchLine.length <= contextLength * 2) {
+    const highlights2 = findMatchPositions(matchLine, queryTerms);
+    return { text: matchLine, highlights: highlights2 };
+  }
+  const matchLineLower = matchLine.toLowerCase();
+  let firstMatchPos = matchLine.length;
+  for (const term of queryTerms) {
+    const pos = matchLineLower.indexOf(term.toLowerCase());
+    if (pos !== -1 && pos < firstMatchPos) {
+      firstMatchPos = pos;
+    }
+  }
+  const start = Math.max(0, firstMatchPos - contextLength);
+  const end = Math.min(matchLine.length, firstMatchPos + contextLength);
+  let contextText = matchLine.substring(start, end);
+  if (start > 0) contextText = "..." + contextText;
+  if (end < matchLine.length) contextText = contextText + "...";
+  const highlights = findMatchPositions(contextText, queryTerms);
+  return { text: contextText, highlights };
+}
+function extractSmartContext(text, matchIndex, queryTerms, contextLength = 80) {
+  const lines = text.split("\n");
+  const matchLine = lines[matchIndex] || "";
+  if (matchLine.length <= contextLength * 2) {
+    return extractContext(text, matchIndex, queryTerms, contextLength);
+  }
+  const matchLineLower = matchLine.toLowerCase();
+  let firstMatchPos = matchLine.length;
+  for (const term of queryTerms) {
+    const pos = matchLineLower.indexOf(term.toLowerCase());
+    if (pos !== -1 && pos < firstMatchPos) {
+      firstMatchPos = pos;
+    }
+  }
+  let start = Math.max(0, firstMatchPos - contextLength);
+  let end = Math.min(matchLine.length, firstMatchPos + contextLength);
+  const beforeText = matchLine.substring(0, start);
+  const lastSentence = beforeText.lastIndexOf(". ");
+  if (lastSentence !== -1 && start - lastSentence < 20) {
+    start = lastSentence + 2;
+  }
+  const afterText = matchLine.substring(end);
+  const nextSentence = afterText.indexOf(". ");
+  if (nextSentence !== -1 && nextSentence < 20) {
+    end = end + nextSentence + 1;
+  }
+  let contextText = matchLine.substring(start, end);
+  if (start > 0) contextText = "..." + contextText;
+  if (end < matchLine.length) contextText = contextText + "...";
+  const highlights = findMatchPositions(contextText, queryTerms);
+  return { text: contextText, highlights };
+}
+function deduplicateMatches(matches, minDistance = 3) {
+  if (matches.length === 0) return matches;
+  const sorted = [...matches].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return (a.lineNumber || 0) - (b.lineNumber || 0);
+  });
+  const deduplicated = [];
+  const usedLines = /* @__PURE__ */ new Set();
+  for (const match of sorted) {
+    if (match.field !== "content") {
+      deduplicated.push(match);
+      continue;
+    }
+    const lineNum = match.lineNumber || 0;
+    let tooClose = false;
+    for (let i = lineNum - minDistance; i <= lineNum + minDistance; i++) {
+      if (usedLines.has(i)) {
+        tooClose = true;
+        break;
+      }
+    }
+    if (!tooClose) {
+      deduplicated.push(match);
+      usedLines.add(lineNum);
+    }
+  }
+  return deduplicated.sort((a, b) => {
+    const fieldOrder = { title: 0, name: 1, tags: 2, description: 3, content: 4 };
+    const orderA = fieldOrder[a.field];
+    const orderB = fieldOrder[b.field];
+    if (orderA !== orderB) return orderA - orderB;
+    return b.score - a.score;
+  });
+}
+function limitMatches(matches, maxMatches = 5) {
+  if (matches.length <= maxMatches) return matches;
+  const fieldMatches = {
+    title: [],
+    name: [],
+    tags: [],
+    description: [],
+    content: []
+  };
+  for (const match of matches) {
+    fieldMatches[match.field].push(match);
+  }
+  const nonContent = [
+    ...fieldMatches.title,
+    ...fieldMatches.name,
+    ...fieldMatches.tags,
+    ...fieldMatches.description
+  ];
+  const contentMatches = fieldMatches.content.sort((a, b) => b.score - a.score).slice(0, Math.max(0, maxMatches - nonContent.length));
+  return [...nonContent, ...contentMatches];
+}
+function searchSpecs(query, specs, options = {}) {
+  const startTime = Date.now();
+  const queryTerms = query.trim().toLowerCase().split(/\s+/).filter((term) => term.length > 0);
+  if (queryTerms.length === 0) {
+    return {
+      results: [],
+      metadata: {
+        totalResults: 0,
+        searchTime: Date.now() - startTime,
+        query,
+        specsSearched: specs.length
+      }
+    };
+  }
+  const maxMatchesPerSpec = options.maxMatchesPerSpec || 5;
+  const contextLength = options.contextLength || 80;
+  const results = [];
+  for (const spec of specs) {
+    const matches = searchSpec(spec, queryTerms, contextLength);
+    if (matches.length > 0) {
+      let processedMatches = deduplicateMatches(matches, 3);
+      processedMatches = limitMatches(processedMatches, maxMatchesPerSpec);
+      const score = calculateSpecScore(processedMatches);
+      results.push({
+        spec: specToSearchResult(spec),
+        score,
+        totalMatches: matches.length,
+        matches: processedMatches
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  return {
+    results,
+    metadata: {
+      totalResults: results.length,
+      searchTime: Date.now() - startTime,
+      query,
+      specsSearched: specs.length
+    }
+  };
+}
+function searchSpec(spec, queryTerms, contextLength) {
+  const matches = [];
+  if (spec.title && containsAllTerms(spec.title, queryTerms)) {
+    const occurrences = countOccurrences(spec.title, queryTerms);
+    const highlights = findMatchPositions(spec.title, queryTerms);
+    const score = calculateMatchScore(
+      { field: "title", text: spec.title },
+      queryTerms,
+      1,
+      0
+    );
+    matches.push({
+      field: "title",
+      text: spec.title,
+      score,
+      highlights,
+      occurrences
+    });
+  }
+  if (spec.name && containsAllTerms(spec.name, queryTerms)) {
+    const occurrences = countOccurrences(spec.name, queryTerms);
+    const highlights = findMatchPositions(spec.name, queryTerms);
+    const score = calculateMatchScore(
+      { field: "name", text: spec.name },
+      queryTerms,
+      1,
+      0
+    );
+    matches.push({
+      field: "name",
+      text: spec.name,
+      score,
+      highlights,
+      occurrences
+    });
+  }
+  if (spec.tags && spec.tags.length > 0) {
+    for (const tag of spec.tags) {
+      if (containsAllTerms(tag, queryTerms)) {
+        const occurrences = countOccurrences(tag, queryTerms);
+        const highlights = findMatchPositions(tag, queryTerms);
+        const score = calculateMatchScore(
+          { field: "tags", text: tag },
+          queryTerms,
+          spec.tags.length,
+          spec.tags.indexOf(tag)
+        );
+        matches.push({
+          field: "tags",
+          text: tag,
+          score,
+          highlights,
+          occurrences
+        });
+      }
+    }
+  }
+  if (spec.description && containsAllTerms(spec.description, queryTerms)) {
+    const occurrences = countOccurrences(spec.description, queryTerms);
+    const highlights = findMatchPositions(spec.description, queryTerms);
+    const score = calculateMatchScore(
+      { field: "description", text: spec.description },
+      queryTerms,
+      1,
+      0
+    );
+    matches.push({
+      field: "description",
+      text: spec.description,
+      score,
+      highlights,
+      occurrences
+    });
+  }
+  if (spec.content) {
+    const contentMatches = searchContent(
+      spec.content,
+      queryTerms,
+      contextLength
+    );
+    matches.push(...contentMatches);
+  }
+  return matches;
+}
+function searchContent(content, queryTerms, contextLength) {
+  const matches = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (containsAllTerms(line, queryTerms)) {
+      const occurrences = countOccurrences(line, queryTerms);
+      const { text, highlights } = extractSmartContext(
+        content,
+        i,
+        queryTerms,
+        contextLength
+      );
+      const score = calculateMatchScore(
+        { field: "content", text: line },
+        queryTerms,
+        lines.length,
+        i
+      );
+      matches.push({
+        field: "content",
+        text,
+        lineNumber: i + 1,
+        // 1-based line numbers
+        score,
+        highlights,
+        occurrences
+      });
+    }
   }
-};
+  return matches;
+}
+function specToSearchResult(spec) {
+  return {
+    name: spec.name,
+    path: spec.path,
+    status: spec.status,
+    priority: spec.priority,
+    tags: spec.tags,
+    title: spec.title,
+    description: spec.description
+  };
+}
+
+// src/validators/sub-spec.ts
 var SubSpecValidator = class {
   name = "sub-specs";
   description = "Validate sub-spec files using direct token thresholds (spec 071)";
@@ -2306,13 +3370,11 @@ var SubSpecValidator = class {
   goodThreshold;
   warningThreshold;
   maxLines;
-  checkCrossReferences;
   constructor(options = {}) {
     this.excellentThreshold = options.excellentThreshold ?? 2e3;
     this.goodThreshold = options.goodThreshold ?? 3500;
     this.warningThreshold = options.warningThreshold ?? 5e3;
     this.maxLines = options.maxLines ?? 500;
-    this.checkCrossReferences = options.checkCrossReferences ?? true;
   }
   async validate(spec, content) {
     const errors = [];
@@ -2325,9 +3387,6 @@ var SubSpecValidator = class {
     this.validateNamingConventions(subSpecs, warnings);
     await this.validateComplexity(subSpecs, errors, warnings);
     this.checkOrphanedSubSpecs(subSpecs, content, warnings);
-    if (this.checkCrossReferences) {
-      await this.validateCrossReferences(subSpecs, spec, warnings);
-    }
     return {
       passed: errors.length === 0,
       errors,
@@ -2390,12 +3449,6 @@ var SubSpecValidator = class {
           suggestion: "Break into 15-35 sections for better readability (7\xB12 cognitive chunks)"
         });
       }
-      if (lineCount > this.maxLines) {
-        warnings.push({
-          message: `Sub-spec ${subSpec.name} is very long (${lineCount} lines)`,
-          suggestion: "Consider splitting even if token count is acceptable"
-        });
-      }
     }
   }
   /**
@@ -2415,29 +3468,6 @@ var SubSpecValidator = class {
       }
     }
   }
-  /**
-   * Validate cross-document references between sub-specs
-   */
-  async validateCrossReferences(subSpecs, spec, warnings) {
-    const validFileNames = new Set(subSpecs.map((s) => s.name));
-    validFileNames.add("README.md");
-    for (const subSpec of subSpecs) {
-      if (!subSpec.content) {
-        continue;
-      }
-      const linkRegex = /\[([^\]]+)\]\((?:\.\/)?(([^)]+)\.md)\)/g;
-      let match;
-      while ((match = linkRegex.exec(subSpec.content)) !== null) {
-        const referencedFile = match[2];
-        if (!validFileNames.has(referencedFile)) {
-          warnings.push({
-            message: `Broken reference in ${subSpec.name}: ${referencedFile} not found`,
-            suggestion: `Check if ${referencedFile} exists or update the link`
-          });
-        }
-      }
-    }
-  }
 };
 function groupIssuesByFile(results) {
   const fileMap = /* @__PURE__ */ new Map();
@@ -2911,7 +3941,7 @@ function isCriticalOverdue(spec) {
   if (!spec.frontmatter.due) {
     return false;
   }
-  const isOverdue = dayjs2(spec.frontmatter.due).isBefore(dayjs2(), "day");
+  const isOverdue = dayjs3(spec.frontmatter.due).isBefore(dayjs3(), "day");
   const isCritical = spec.frontmatter.priority === "critical" || spec.frontmatter.priority === "high";
   return isOverdue && isCritical;
 }
@@ -2923,7 +3953,7 @@ function isLongRunning(spec) {
   if (!updatedAt) {
     return false;
   }
-  const daysSinceUpdate = dayjs2().diff(dayjs2(updatedAt), "day");
+  const daysSinceUpdate = dayjs3().diff(dayjs3(updatedAt), "day");
   return daysSinceUpdate > 7;
 }
 function calculateCompletion(specs) {
@@ -2975,8 +4005,8 @@ function calculateCycleTime(spec) {
   if (!createdAt || !completedAt) {
     return null;
   }
-  const created = dayjs2(createdAt);
-  const completed = dayjs2(completedAt);
+  const created = dayjs3(createdAt);
+  const completed = dayjs3(completedAt);
   return completed.diff(created, "day", true);
 }
 function calculateLeadTime(spec, fromStatus, toStatus) {
@@ -2989,12 +4019,12 @@ function calculateLeadTime(spec, fromStatus, toStatus) {
   if (!fromTransition || !toTransition) {
     return null;
   }
-  const from = dayjs2(fromTransition.at);
-  const to = dayjs2(toTransition.at);
+  const from = dayjs3(fromTransition.at);
+  const to = dayjs3(toTransition.at);
   return to.diff(from, "day", true);
 }
 function calculateThroughput(specs, days) {
-  const cutoff = dayjs2().subtract(days, "day");
+  const cutoff = dayjs3().subtract(days, "day");
   return specs.filter((s) => {
     if (s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived") {
       return false;
@@ -3003,19 +4033,19 @@ function calculateThroughput(specs, days) {
     if (!completedAt) {
       return false;
     }
-    return dayjs2(completedAt).isAfter(cutoff);
+    return dayjs3(completedAt).isAfter(cutoff);
   }).length;
 }
-function calculateWIP(specs, date = dayjs2()) {
+function calculateWIP(specs, date = dayjs3()) {
   return specs.filter((s) => {
     const createdAt = s.frontmatter.created_at || s.frontmatter.created;
-    const created = dayjs2(createdAt);
+    const created = dayjs3(createdAt);
     if (created.isAfter(date)) {
       return false;
     }
     const completedAt = s.frontmatter.completed_at || s.frontmatter.completed;
     if (completedAt) {
-      const completed = dayjs2(completedAt);
+      const completed = dayjs3(completedAt);
       return completed.isAfter(date);
     }
     return s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived";
@@ -3032,19 +4062,19 @@ function calculateVelocityMetrics(specs) {
   const avgInProgressToComplete = inProgressToCompleteTimes.length > 0 ? inProgressToCompleteTimes.reduce((sum, t) => sum + t, 0) / inProgressToCompleteTimes.length : 0;
   const throughputWeek = calculateThroughput(specs, 7);
   const throughputMonth = calculateThroughput(specs, 30);
-  const prevWeekStart = dayjs2().subtract(14, "day");
-  const prevWeekEnd = dayjs2().subtract(7, "day");
+  const prevWeekStart = dayjs3().subtract(14, "day");
+  const prevWeekEnd = dayjs3().subtract(7, "day");
   const throughputPrevWeek = specs.filter((s) => {
     const completedAt = s.frontmatter.completed_at || s.frontmatter.completed;
     if (!completedAt) return false;
-    const completed = dayjs2(completedAt);
+    const completed = dayjs3(completedAt);
     return completed.isAfter(prevWeekStart) && !completed.isAfter(prevWeekEnd);
   }).length;
   const throughputTrend = throughputWeek > throughputPrevWeek ? "up" : throughputWeek < throughputPrevWeek ? "down" : "stable";
   const currentWIP = calculateWIP(specs);
   const wipSamples = [];
   for (let i = 0; i < 30; i++) {
-    const sampleDate = dayjs2().subtract(i, "day");
+    const sampleDate = dayjs3().subtract(i, "day");
     wipSamples.push(calculateWIP(specs, sampleDate));
   }
   const avgWIP = wipSamples.length > 0 ? wipSamples.reduce((sum, w) => sum + w, 0) / wipSamples.length : 0;
@@ -3249,7 +4279,7 @@ function countSpecsByStatusAndPriority(specs) {
 function generateInsights(specs) {
   const insights = [];
   const criticalOverdue = specs.filter(
-    (s) => s.frontmatter.priority === "critical" && s.frontmatter.due && dayjs2(s.frontmatter.due).isBefore(dayjs2(), "day") && s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived"
+    (s) => s.frontmatter.priority === "critical" && s.frontmatter.due && dayjs3(s.frontmatter.due).isBefore(dayjs3(), "day") && s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived"
   );
   if (criticalOverdue.length > 0) {
     insights.push({
@@ -3259,7 +4289,7 @@ function generateInsights(specs) {
     });
   }
   const highOverdue = specs.filter(
-    (s) => s.frontmatter.priority === "high" && s.frontmatter.due && dayjs2(s.frontmatter.due).isBefore(dayjs2(), "day") && s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived"
+    (s) => s.frontmatter.priority === "high" && s.frontmatter.due && dayjs3(s.frontmatter.due).isBefore(dayjs3(), "day") && s.frontmatter.status !== "complete" && s.frontmatter.status !== "archived"
   );
   if (highOverdue.length > 0) {
     insights.push({
@@ -3276,7 +4306,7 @@ function generateInsights(specs) {
     if (!updatedAt) {
       return false;
     }
-    const daysSinceUpdate = dayjs2().diff(dayjs2(updatedAt), "day");
+    const daysSinceUpdate = dayjs3().diff(dayjs3(updatedAt), "day");
     return daysSinceUpdate > 7;
   });
   if (longRunning.length > 0) {
@@ -3309,14 +4339,14 @@ function generateInsights(specs) {
   return insights.slice(0, 5);
 }
 function getSpecInsightDetails(spec) {
-  if (spec.frontmatter.due && dayjs2(spec.frontmatter.due).isBefore(dayjs2(), "day") && spec.frontmatter.status !== "complete" && spec.frontmatter.status !== "archived") {
-    const daysOverdue = dayjs2().diff(dayjs2(spec.frontmatter.due), "day");
+  if (spec.frontmatter.due && dayjs3(spec.frontmatter.due).isBefore(dayjs3(), "day") && spec.frontmatter.status !== "complete" && spec.frontmatter.status !== "archived") {
+    const daysOverdue = dayjs3().diff(dayjs3(spec.frontmatter.due), "day");
     return `overdue by ${daysOverdue} day${daysOverdue > 1 ? "s" : ""}`;
   }
   if (spec.frontmatter.status === "in-progress") {
     const updatedAt = spec.frontmatter.updated || spec.frontmatter.updated_at || spec.frontmatter.created || spec.frontmatter.created_at;
     if (updatedAt) {
-      const daysSinceUpdate = dayjs2().diff(dayjs2(updatedAt), "day");
+      const daysSinceUpdate = dayjs3().diff(dayjs3(updatedAt), "day");
       if (daysSinceUpdate > 7) {
         return `in-progress for ${daysSinceUpdate} days`;
       }
@@ -3416,7 +4446,7 @@ async function statsCommand(options) {
         const criticalInProgress = specs.filter((s) => s.frontmatter.priority === "critical" && s.frontmatter.status === "in-progress").length;
         const criticalComplete = specs.filter((s) => s.frontmatter.priority === "critical" && s.frontmatter.status === "complete").length;
         const criticalOverdue = specs.filter(
-          (s) => s.frontmatter.priority === "critical" && s.frontmatter.due && dayjs2(s.frontmatter.due).isBefore(dayjs2(), "day") && s.frontmatter.status !== "complete"
+          (s) => s.frontmatter.priority === "critical" && s.frontmatter.due && dayjs3(s.frontmatter.due).isBefore(dayjs3(), "day") && s.frontmatter.status !== "complete"
         ).length;
         const parts = [];
         if (criticalPlanned > 0) parts.push(chalk16.dim(`${criticalPlanned} planned`));
@@ -3430,7 +4460,7 @@ async function statsCommand(options) {
         const highInProgress = specs.filter((s) => s.frontmatter.priority === "high" && s.frontmatter.status === "in-progress").length;
         const highComplete = specs.filter((s) => s.frontmatter.priority === "high" && s.frontmatter.status === "complete").length;
         const highOverdue = specs.filter(
-          (s) => s.frontmatter.priority === "high" && s.frontmatter.due && dayjs2(s.frontmatter.due).isBefore(dayjs2(), "day") && s.frontmatter.status !== "complete"
+          (s) => s.frontmatter.priority === "high" && s.frontmatter.due && dayjs3(s.frontmatter.due).isBefore(dayjs3(), "day") && s.frontmatter.status !== "complete"
         ).length;
         const parts = [];
         if (highPlanned > 0) parts.push(chalk16.dim(`${highPlanned} planned`));
@@ -3592,18 +4622,18 @@ async function statsCommand(options) {
   }
   if (showTimeline) {
     const days = 30;
-    const today = dayjs2();
+    const today = dayjs3();
     const startDate = today.subtract(days, "day");
     const createdByDate = {};
     const completedByDate = {};
     for (const spec of specs) {
-      const created = dayjs2(spec.frontmatter.created);
+      const created = dayjs3(spec.frontmatter.created);
       if (created.isAfter(startDate)) {
         const dateKey = created.format("YYYY-MM-DD");
         createdByDate[dateKey] = (createdByDate[dateKey] || 0) + 1;
       }
       if (spec.frontmatter.completed) {
-        const completed = dayjs2(spec.frontmatter.completed);
+        const completed = dayjs3(spec.frontmatter.completed);
         if (completed.isAfter(startDate)) {
           const dateKey = completed.format("YYYY-MM-DD");
           completedByDate[dateKey] = (completedByDate[dateKey] || 0) + 1;
@@ -3742,27 +4772,21 @@ async function searchCommand(query, options) {
     console.log("No specs found matching filters.");
     return;
   }
-  const results = [];
-  const queryLower = query.toLowerCase();
-  for (const spec of specs) {
-    if (!spec.content) continue;
-    const matches = [];
-    const lines = spec.content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (line.toLowerCase().includes(queryLower)) {
-        const contextStart = Math.max(0, i - 1);
-        const contextEnd = Math.min(lines.length - 1, i + 1);
-        const context = lines.slice(contextStart, contextEnd + 1);
-        const matchLine = context[i - contextStart];
-        const highlighted = highlightMatch(matchLine, query);
-        matches.push(highlighted);
-      }
-    }
-    if (matches.length > 0) {
-      results.push({ spec, matches });
-    }
-  }
+  const searchableSpecs = specs.map((spec) => ({
+    path: spec.path,
+    name: spec.path,
+    status: spec.frontmatter.status,
+    priority: spec.frontmatter.priority,
+    tags: spec.frontmatter.tags,
+    title: spec.frontmatter.title,
+    description: spec.frontmatter.description,
+    content: spec.content
+  }));
+  const searchResult = searchSpecs(query, searchableSpecs, {
+    maxMatchesPerSpec: 5,
+    contextLength: 80
+  });
+  const { results, metadata } = searchResult;
   if (results.length === 0) {
     console.log("");
     console.log(chalk16.yellow(`\u{1F50D} No specs found matching "${sanitizeUserInput(query)}"`));
@@ -3779,45 +4803,68 @@ async function searchCommand(query, options) {
   }
   console.log("");
   console.log(chalk16.green(`\u{1F50D} Found ${results.length} spec${results.length === 1 ? "" : "s"} matching "${sanitizeUserInput(query)}"`));
+  console.log(chalk16.gray(`   Searched ${metadata.specsSearched} specs in ${metadata.searchTime}ms`));
   if (Object.keys(filter).length > 0) {
     const filters = [];
     if (options.status) filters.push(`status=${sanitizeUserInput(options.status)}`);
     if (options.tag) filters.push(`tag=${sanitizeUserInput(options.tag)}`);
     if (options.priority) filters.push(`priority=${sanitizeUserInput(options.priority)}`);
     if (options.assignee) filters.push(`assignee=${sanitizeUserInput(options.assignee)}`);
-    console.log(chalk16.gray(`With filters: ${filters.join(", ")}`));
+    console.log(chalk16.gray(`   With filters: ${filters.join(", ")}`));
   }
   console.log("");
   for (const result of results) {
-    const { spec, matches } = result;
-    console.log(chalk16.cyan(`${spec.frontmatter.status === "in-progress" ? "\u{1F528}" : spec.frontmatter.status === "complete" ? "\u2705" : "\u{1F4C5}"} ${sanitizeUserInput(spec.path)}`));
+    const { spec, matches, score, totalMatches } = result;
+    const statusEmoji = spec.status === "in-progress" ? "\u{1F528}" : spec.status === "complete" ? "\u2705" : "\u{1F4C5}";
+    console.log(chalk16.cyan(`${statusEmoji} ${sanitizeUserInput(spec.path)} ${chalk16.gray(`(${score}% match)`)}`));
     const meta = [];
-    if (spec.frontmatter.priority) {
-      const priorityEmoji = spec.frontmatter.priority === "critical" ? "\u{1F534}" : spec.frontmatter.priority === "high" ? "\u{1F7E1}" : spec.frontmatter.priority === "medium" ? "\u{1F7E0}" : "\u{1F7E2}";
-      meta.push(`${priorityEmoji} ${sanitizeUserInput(spec.frontmatter.priority)}`);
+    if (spec.priority) {
+      const priorityEmoji = spec.priority === "critical" ? "\u{1F534}" : spec.priority === "high" ? "\u{1F7E1}" : spec.priority === "medium" ? "\u{1F7E0}" : "\u{1F7E2}";
+      meta.push(`${priorityEmoji} ${sanitizeUserInput(spec.priority)}`);
     }
-    if (spec.frontmatter.tags && spec.frontmatter.tags.length > 0) {
-      meta.push(`[${spec.frontmatter.tags.map((tag) => sanitizeUserInput(tag)).join(", ")}]`);
+    if (spec.tags && spec.tags.length > 0) {
+      meta.push(`[${spec.tags.map((tag) => sanitizeUserInput(tag)).join(", ")}]`);
     }
     if (meta.length > 0) {
-      console.log(chalk16.gray(`  ${meta.join(" \u2022 ")}`));
+      console.log(chalk16.gray(`   ${meta.join(" \u2022 ")}`));
     }
-    const maxMatches = 3;
-    for (let i = 0; i < Math.min(matches.length, maxMatches); i++) {
-      console.log(`  ${chalk16.gray("Match:")} ${matches[i].trim()}`);
+    const titleMatch = matches.find((m) => m.field === "title");
+    if (titleMatch) {
+      console.log(`   ${chalk16.bold("Title:")} ${highlightMatches(titleMatch.text, titleMatch.highlights)}`);
+    }
+    const descMatch = matches.find((m) => m.field === "description");
+    if (descMatch) {
+      console.log(`   ${chalk16.bold("Description:")} ${highlightMatches(descMatch.text, descMatch.highlights)}`);
+    }
+    const tagMatches = matches.filter((m) => m.field === "tags");
+    if (tagMatches.length > 0) {
+      console.log(`   ${chalk16.bold("Tags:")} ${tagMatches.map((m) => highlightMatches(m.text, m.highlights)).join(", ")}`);
+    }
+    const contentMatches = matches.filter((m) => m.field === "content");
+    if (contentMatches.length > 0) {
+      console.log(`   ${chalk16.bold("Content matches:")}`);
+      for (const match of contentMatches) {
+        const lineInfo = match.lineNumber ? chalk16.gray(`[L${match.lineNumber}]`) : "";
+        console.log(`   ${lineInfo} ${highlightMatches(match.text, match.highlights)}`);
+      }
     }
-    if (matches.length > maxMatches) {
-      console.log(chalk16.gray(`  ... and ${matches.length - maxMatches} more match${matches.length - maxMatches === 1 ? "" : "es"}`));
+    if (totalMatches > matches.length) {
+      console.log(chalk16.gray(`   ... and ${totalMatches - matches.length} more match${totalMatches - matches.length === 1 ? "" : "es"}`));
     }
     console.log("");
   }
 }
-function highlightMatch(text, query) {
-  const regex = new RegExp(`(${escapeRegex(query)})`, "gi");
-  return text.replace(regex, chalk16.yellow("$1"));
-}
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function highlightMatches(text, highlights) {
+  if (highlights.length === 0) return text;
+  let result = "";
+  let lastEnd = 0;
+  for (const [start, end] of highlights) {
+    result += text.substring(lastEnd, start);
+    result += chalk16.yellow(text.substring(start, end));
+    lastEnd = end;
+  }
+  result += text.substring(lastEnd);
+  return result;
 }
 async function depsCommand(specPath, options) {
   await autoCheckIfEnabled();
@@ -3899,8 +4946,8 @@ function findDependencies(spec, specMap) {
     if (dep) {
       deps.push(dep);
     } else {
-      for (const [path21, s] of specMap.entries()) {
-        if (path21.includes(depPath)) {
+      for (const [path26, s] of specMap.entries()) {
+        if (path26.includes(depPath)) {
           deps.push(s);
           break;
         }
@@ -3932,8 +4979,8 @@ function findRelated(spec, specMap) {
     if (rel) {
       related.push(rel);
     } else {
-      for (const [path21, s] of specMap.entries()) {
-        if (path21.includes(relPath)) {
+      for (const [path26, s] of specMap.entries()) {
+        if (path26.includes(relPath)) {
           related.push(s);
           break;
         }
@@ -4016,13 +5063,13 @@ async function timelineCommand(options) {
     console.log("No specs found.");
     return;
   }
-  const today = dayjs2();
+  const today = dayjs3();
   const startDate = today.subtract(days, "day");
   const createdByDate = {};
   const completedByDate = {};
   const createdByMonth = {};
   for (const spec of specs) {
-    const created = dayjs2(spec.frontmatter.created);
+    const created = dayjs3(spec.frontmatter.created);
     if (created.isAfter(startDate)) {
       const dateKey = created.format("YYYY-MM-DD");
       createdByDate[dateKey] = (createdByDate[dateKey] || 0) + 1;
@@ -4030,7 +5077,7 @@ async function timelineCommand(options) {
     const monthKey = created.format("MMM YYYY");
     createdByMonth[monthKey] = (createdByMonth[monthKey] || 0) + 1;
     if (spec.frontmatter.completed) {
-      const completed = dayjs2(spec.frontmatter.completed);
+      const completed = dayjs3(spec.frontmatter.completed);
       if (completed.isAfter(startDate)) {
         const dateKey = completed.format("YYYY-MM-DD");
         completedByDate[dateKey] = (completedByDate[dateKey] || 0) + 1;
@@ -4063,8 +5110,8 @@ async function timelineCommand(options) {
     console.log("");
   }
   const sortedMonths = Object.entries(createdByMonth).sort((a, b) => {
-    const dateA = dayjs2(a[0], "MMM YYYY");
-    const dateB = dayjs2(b[0], "MMM YYYY");
+    const dateA = dayjs3(a[0], "MMM YYYY");
+    const dateB = dayjs3(b[0], "MMM YYYY");
     return dateB.diff(dateA);
   }).slice(0, 6);
   if (sortedMonths.length > 0) {
@@ -4085,12 +5132,12 @@ async function timelineCommand(options) {
   }
   const last7Days = specs.filter((s) => {
     if (!s.frontmatter.completed) return false;
-    const completed = dayjs2(s.frontmatter.completed);
+    const completed = dayjs3(s.frontmatter.completed);
     return completed.isAfter(today.subtract(7, "day"));
   }).length;
   const last30Days = specs.filter((s) => {
     if (!s.frontmatter.completed) return false;
-    const completed = dayjs2(s.frontmatter.completed);
+    const completed = dayjs3(s.frontmatter.completed);
     return completed.isAfter(today.subtract(30, "day"));
   }).length;
   console.log(chalk16.bold("\u2705 Completion Rate"));
@@ -4105,14 +5152,14 @@ async function timelineCommand(options) {
   if (options.byTag) {
     const tagStats = {};
     for (const spec of specs) {
-      const created = dayjs2(spec.frontmatter.created);
+      const created = dayjs3(spec.frontmatter.created);
       const isInRange = created.isAfter(startDate);
       if (isInRange && spec.frontmatter.tags) {
         for (const tag of spec.frontmatter.tags) {
           if (!tagStats[tag]) tagStats[tag] = { created: 0, completed: 0 };
           tagStats[tag].created++;
           if (spec.frontmatter.completed) {
-            const completed = dayjs2(spec.frontmatter.completed);
+            const completed = dayjs3(spec.frontmatter.completed);
             if (completed.isAfter(startDate)) {
               tagStats[tag].completed++;
             }
@@ -4133,14 +5180,14 @@ async function timelineCommand(options) {
     const assigneeStats = {};
     for (const spec of specs) {
       if (!spec.frontmatter.assignee) continue;
-      const created = dayjs2(spec.frontmatter.created);
+      const created = dayjs3(spec.frontmatter.created);
       const isInRange = created.isAfter(startDate);
       if (isInRange) {
         const assignee = spec.frontmatter.assignee;
         if (!assigneeStats[assignee]) assigneeStats[assignee] = { created: 0, completed: 0 };
         assigneeStats[assignee].created++;
         if (spec.frontmatter.completed) {
-          const completed = dayjs2(spec.frontmatter.completed);
+          const completed = dayjs3(spec.frontmatter.completed);
           if (completed.isAfter(startDate)) {
             assigneeStats[assignee].completed++;
           }
@@ -4219,18 +5266,18 @@ async function ganttCommand(options) {
       if (a.frontmatter.due && !b.frontmatter.due) return -1;
       if (!a.frontmatter.due && b.frontmatter.due) return 1;
       if (a.frontmatter.due && b.frontmatter.due) {
-        return dayjs2(a.frontmatter.due).diff(dayjs2(b.frontmatter.due));
+        return dayjs3(a.frontmatter.due).diff(dayjs3(b.frontmatter.due));
       }
       return 0;
     });
   };
-  const today = dayjs2();
+  const today = dayjs3();
   const startDate = today.startOf("week");
   const endDate = startDate.add(weeks, "week");
   const inProgress = relevantSpecs.filter((s) => s.frontmatter.status === "in-progress").length;
   const planned = relevantSpecs.filter((s) => s.frontmatter.status === "planned").length;
   const overdue = relevantSpecs.filter(
-    (s) => s.frontmatter.due && dayjs2(s.frontmatter.due).isBefore(today) && s.frontmatter.status !== "complete"
+    (s) => s.frontmatter.due && dayjs3(s.frontmatter.due).isBefore(today) && s.frontmatter.status !== "complete"
   ).length;
   console.log(chalk16.bold.cyan(`\u{1F4C5} Gantt Chart (${weeks} weeks from ${startDate.format("MMM D, YYYY")})`));
   console.log("");
@@ -4296,7 +5343,7 @@ function renderSpecRow(spec, startDate, endDate, weeks, today) {
 function renderTimelineBar(spec, startDate, endDate, weeks, today) {
   const charsPerWeek = 8;
   const totalChars = weeks * charsPerWeek;
-  const due = dayjs2(spec.frontmatter.due);
+  const due = dayjs3(spec.frontmatter.due);
   const specStart = today;
   const startDaysFromStart = specStart.diff(startDate, "day");
   const dueDaysFromStart = due.diff(startDate, "day");
@@ -4471,6 +5518,450 @@ async function tokensAllCommand(options = {}) {
   console.log(chalk16.dim("Legend: \u2705 excellent (<2K) | \u{1F44D} good (<3.5K) | \u26A0\uFE0F  warning (<5K) | \u{1F534} problem (>5K)"));
   console.log("");
 }
+async function analyzeCommand(specPath, options = {}) {
+  await autoCheckIfEnabled();
+  const counter = new TokenCounter();
+  try {
+    const config = await loadConfig();
+    const cwd = process.cwd();
+    const specsDir = path2.join(cwd, config.specsDir);
+    const resolvedPath = await resolveSpecPath(specPath, cwd, specsDir);
+    if (!resolvedPath) {
+      throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
+    }
+    const specName = path2.basename(resolvedPath);
+    const readmePath = path2.join(resolvedPath, "README.md");
+    const content = await readFile(readmePath, "utf-8");
+    const structure = analyzeMarkdownStructure(content);
+    const tokenResult = await counter.countSpec(resolvedPath, {
+      detailed: true,
+      includeSubSpecs: false
+      // Only analyze README.md for structure
+    });
+    const indicators = counter.getPerformanceIndicators(tokenResult.total);
+    const sectionsWithTokens = await Promise.all(
+      structure.allSections.map(async (section) => {
+        const sectionContent = content.split("\n").slice(section.startLine - 1, section.endLine).join("\n");
+        const sectionTokens = await counter.countTokensInContent(sectionContent);
+        return {
+          section: section.title,
+          level: section.level,
+          lineRange: [section.startLine, section.endLine],
+          tokens: sectionTokens,
+          subsections: section.subsections.map((s) => s.title)
+        };
+      })
+    );
+    const recommendation = generateRecommendation(tokenResult.total, structure, indicators.level);
+    const result = {
+      spec: specName,
+      path: resolvedPath,
+      metrics: {
+        tokens: tokenResult.total,
+        lines: structure.lines,
+        characters: content.length,
+        sections: structure.sectionsByLevel,
+        codeBlocks: structure.codeBlocks,
+        maxNesting: structure.maxNesting
+      },
+      threshold: {
+        status: indicators.level,
+        limit: getThresholdLimit(indicators.level),
+        message: indicators.recommendation
+      },
+      structure: sectionsWithTokens,
+      recommendation
+    };
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    displayAnalysis(result, options.verbose);
+  } finally {
+    counter.dispose();
+  }
+}
+function generateRecommendation(tokens, structure, level) {
+  if (tokens < 2e3) {
+    return {
+      action: "none",
+      reason: "Spec is under 2,000 tokens (optimal)",
+      confidence: "high"
+    };
+  }
+  if (tokens < 3500) {
+    return {
+      action: "compact",
+      reason: "Spec could benefit from removing redundancy",
+      confidence: "medium"
+    };
+  }
+  if (tokens < 5e3) {
+    const h2Count = structure.sectionsByLevel.h2;
+    if (h2Count >= 3) {
+      return {
+        action: "split",
+        reason: `Exceeds 3,500 token threshold with ${h2Count} concerns`,
+        confidence: "high"
+      };
+    } else {
+      return {
+        action: "split",
+        reason: "Exceeds 3,500 token threshold",
+        confidence: "medium"
+      };
+    }
+  }
+  return {
+    action: "split",
+    reason: "Critically oversized - must split immediately",
+    confidence: "high"
+  };
+}
+function getThresholdLimit(level) {
+  switch (level) {
+    case "excellent":
+      return 2e3;
+    case "good":
+      return 3500;
+    case "warning":
+      return 5e3;
+    case "problem":
+      return 5e3;
+    default:
+      return 2e3;
+  }
+}
+function displayAnalysis(result, verbose) {
+  console.log(chalk16.bold.cyan(`\u{1F4CA} Spec Analysis: ${result.spec}`));
+  console.log("");
+  const statusEmoji = result.threshold.status === "excellent" ? "\u2705" : result.threshold.status === "good" ? "\u{1F44D}" : result.threshold.status === "warning" ? "\u26A0\uFE0F" : "\u{1F534}";
+  const tokenColor = result.threshold.status === "excellent" || result.threshold.status === "good" ? chalk16.cyan : result.threshold.status === "warning" ? chalk16.yellow : chalk16.red;
+  console.log(chalk16.bold("Token Count:"), tokenColor(result.metrics.tokens.toLocaleString()), "tokens", statusEmoji);
+  console.log(chalk16.dim(`  Threshold: ${result.threshold.limit.toLocaleString()} tokens`));
+  console.log(chalk16.dim(`  Status: ${result.threshold.message}`));
+  console.log("");
+  console.log(chalk16.bold("Structure:"));
+  console.log(`  Lines: ${chalk16.cyan(result.metrics.lines.toLocaleString())}`);
+  console.log(`  Sections: ${chalk16.cyan(result.metrics.sections.total)} (H1:${result.metrics.sections.h1}, H2:${result.metrics.sections.h2}, H3:${result.metrics.sections.h3}, H4:${result.metrics.sections.h4})`);
+  console.log(`  Code blocks: ${chalk16.cyan(result.metrics.codeBlocks)}`);
+  console.log(`  Max nesting: ${chalk16.cyan(result.metrics.maxNesting)} levels`);
+  console.log("");
+  if (verbose && result.structure.length > 0) {
+    const topSections = result.structure.filter((s) => s.level <= 2).sort((a, b) => b.tokens - a.tokens).slice(0, 5);
+    console.log(chalk16.bold("Top Sections by Size:"));
+    console.log("");
+    for (let i = 0; i < topSections.length; i++) {
+      const s = topSections[i];
+      const percentage = Math.round(s.tokens / result.metrics.tokens * 100);
+      const indent = "  ".repeat(s.level - 1);
+      console.log(`  ${i + 1}. ${indent}${s.section}`);
+      console.log(`     ${chalk16.cyan(s.tokens.toLocaleString())} tokens / ${s.lineRange[1] - s.lineRange[0] + 1} lines ${chalk16.dim(`(${percentage}%)`)}`);
+      console.log(chalk16.dim(`     Lines ${s.lineRange[0]}-${s.lineRange[1]}`));
+    }
+    console.log("");
+  }
+  const actionColor = result.recommendation.action === "none" ? chalk16.green : result.recommendation.action === "compact" ? chalk16.yellow : result.recommendation.action === "split" ? chalk16.red : chalk16.blue;
+  console.log(chalk16.bold("Recommendation:"), actionColor(result.recommendation.action.toUpperCase()));
+  console.log(chalk16.dim(`  ${result.recommendation.reason}`));
+  console.log(chalk16.dim(`  Confidence: ${result.recommendation.confidence}`));
+  console.log("");
+  if (result.recommendation.action === "split") {
+    console.log(chalk16.dim("\u{1F4A1} Use `lean-spec split` to partition into sub-specs"));
+    console.log(chalk16.dim("\u{1F4A1} Consider splitting by H2 sections (concerns)"));
+  } else if (result.recommendation.action === "compact") {
+    console.log(chalk16.dim("\u{1F4A1} Use `lean-spec compact` to remove redundancy"));
+  }
+  console.log("");
+}
+async function splitCommand(specPath, options) {
+  await autoCheckIfEnabled();
+  try {
+    if (!options.outputs || options.outputs.length === 0) {
+      throw new Error("At least one --output option is required");
+    }
+    const config = await loadConfig();
+    const cwd = process.cwd();
+    const specsDir = path2.join(cwd, config.specsDir);
+    const resolvedPath = await resolveSpecPath(specPath, cwd, specsDir);
+    if (!resolvedPath) {
+      throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
+    }
+    const specName = path2.basename(resolvedPath);
+    const readmePath = path2.join(resolvedPath, "README.md");
+    const content = await readFile(readmePath, "utf-8");
+    const parsedOutputs = parseOutputSpecs(options.outputs);
+    validateNoOverlaps(parsedOutputs);
+    const extractions = [];
+    for (const output of parsedOutputs) {
+      const extracted = extractLines(content, output.startLine, output.endLine);
+      const lineCount = countLines(extracted);
+      extractions.push({
+        file: output.file,
+        content: extracted,
+        tokens: 0,
+        // Will be calculated in dry-run or actual execution
+        lines: lineCount
+      });
+    }
+    if (options.dryRun) {
+      await displayDryRun(specName, extractions);
+      return;
+    }
+    await executeSplit(resolvedPath, specName, content, extractions, options);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(chalk16.red(`Error: ${error.message}`));
+    }
+    throw error;
+  }
+}
+function parseOutputSpecs(outputs) {
+  const parsed = [];
+  for (const output of outputs) {
+    const match = output.lines.match(/^(\d+)-(\d+)$/);
+    if (!match) {
+      throw new Error(`Invalid line range format: ${output.lines}. Expected format: "1-150"`);
+    }
+    const startLine = parseInt(match[1], 10);
+    const endLine = parseInt(match[2], 10);
+    if (startLine < 1 || endLine < startLine) {
+      throw new Error(`Invalid line range: ${output.lines}`);
+    }
+    parsed.push({
+      file: output.file,
+      startLine,
+      endLine
+    });
+  }
+  return parsed;
+}
+function validateNoOverlaps(outputs) {
+  const sorted = [...outputs].sort((a, b) => a.startLine - b.startLine);
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const current = sorted[i];
+    const next = sorted[i + 1];
+    if (current.endLine >= next.startLine) {
+      throw new Error(
+        `Overlapping line ranges: ${current.file} (${current.startLine}-${current.endLine}) overlaps with ${next.file} (${next.startLine}-${next.endLine})`
+      );
+    }
+  }
+}
+async function displayDryRun(specName, extractions) {
+  console.log(chalk16.bold.cyan(`\u{1F4CB} Split Preview: ${specName}`));
+  console.log("");
+  console.log(chalk16.bold("Would create:"));
+  console.log("");
+  for (const ext of extractions) {
+    console.log(`  ${chalk16.cyan(ext.file)}`);
+    console.log(`    Lines: ${ext.lines}`);
+    const previewLines = ext.content.split("\n").slice(0, 3);
+    console.log(chalk16.dim("    Preview:"));
+    for (const line of previewLines) {
+      console.log(chalk16.dim(`      ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+    }
+    console.log("");
+  }
+  console.log(chalk16.dim("No files modified (dry run)"));
+  console.log(chalk16.dim("Run without --dry-run to apply changes"));
+  console.log("");
+}
+async function executeSplit(specPath, specName, originalContent, extractions, options) {
+  console.log(chalk16.bold.cyan(`\u2702\uFE0F  Splitting: ${specName}`));
+  console.log("");
+  const frontmatter = parseFrontmatterFromString(originalContent);
+  for (const ext of extractions) {
+    const outputPath = path2.join(specPath, ext.file);
+    let finalContent = ext.content;
+    if (ext.file === "README.md" && frontmatter) {
+      const { content: contentWithFrontmatter } = createUpdatedFrontmatter(
+        ext.content,
+        frontmatter
+      );
+      finalContent = contentWithFrontmatter;
+    }
+    await writeFile(outputPath, finalContent, "utf-8");
+    console.log(chalk16.green(`\u2713 Created ${ext.file} (${ext.lines} lines)`));
+  }
+  if (options.updateRefs) {
+    const readmePath = path2.join(specPath, "README.md");
+    const readmeContent = await readFile(readmePath, "utf-8");
+    const updatedReadme = await addSubSpecLinks(
+      readmeContent,
+      extractions.map((e) => e.file).filter((f) => f !== "README.md")
+    );
+    await writeFile(readmePath, updatedReadme, "utf-8");
+    console.log(chalk16.green(`\u2713 Updated README.md with sub-spec links`));
+  }
+  console.log("");
+  console.log(chalk16.bold.green("Split complete!"));
+  console.log(chalk16.dim(`Created ${extractions.length} files in ${specName}`));
+  console.log("");
+}
+async function addSubSpecLinks(content, subSpecs) {
+  if (subSpecs.length === 0) {
+    return content;
+  }
+  if (content.includes("## Sub-Specs") || content.includes("## Sub-specs")) {
+    return content;
+  }
+  const lines = content.split("\n");
+  let insertIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].toLowerCase();
+    if (line.includes("## implementation") || line.includes("## plan") || line.includes("## test")) {
+      insertIndex = i;
+      break;
+    }
+  }
+  if (insertIndex === -1) {
+    insertIndex = lines.length;
+  }
+  const subSpecsSection = [
+    "",
+    "## Sub-Specs",
+    "",
+    "This spec is organized using sub-spec files:",
+    "",
+    ...subSpecs.map((file) => {
+      const name = file.replace(".md", "");
+      return `- **[${name}](./${file})** - ${getFileDescription(file)}`;
+    }),
+    ""
+  ];
+  lines.splice(insertIndex, 0, ...subSpecsSection);
+  return lines.join("\n");
+}
+function getFileDescription(file) {
+  const lower = file.toLowerCase();
+  if (lower.includes("design")) return "Architecture and design details";
+  if (lower.includes("implementation")) return "Implementation plan and phases";
+  if (lower.includes("testing") || lower.includes("test")) return "Test strategy and cases";
+  if (lower.includes("rationale")) return "Design rationale and decisions";
+  if (lower.includes("api")) return "API specification";
+  if (lower.includes("migration")) return "Migration plan and strategy";
+  if (lower.includes("context")) return "Context and research";
+  return "Additional documentation";
+}
+async function compactCommand(specPath, options) {
+  await autoCheckIfEnabled();
+  try {
+    if (!options.removes || options.removes.length === 0) {
+      throw new Error("At least one --remove option is required");
+    }
+    const config = await loadConfig();
+    const cwd = process.cwd();
+    const specsDir = path2.join(cwd, config.specsDir);
+    const resolvedPath = await resolveSpecPath(specPath, cwd, specsDir);
+    if (!resolvedPath) {
+      throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
+    }
+    const specName = path2.basename(resolvedPath);
+    const readmePath = path2.join(resolvedPath, "README.md");
+    const content = await readFile(readmePath, "utf-8");
+    const parsedRemoves = parseRemoveSpecs(options.removes);
+    validateNoOverlaps2(parsedRemoves);
+    if (options.dryRun) {
+      await displayDryRun2(specName, content, parsedRemoves);
+      return;
+    }
+    await executeCompact(readmePath, specName, content, parsedRemoves);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(chalk16.red(`Error: ${error.message}`));
+    }
+    throw error;
+  }
+}
+function parseRemoveSpecs(removes) {
+  const parsed = [];
+  for (let i = 0; i < removes.length; i++) {
+    const spec = removes[i];
+    const match = spec.match(/^(\d+)-(\d+)$/);
+    if (!match) {
+      throw new Error(`Invalid line range format: ${spec}. Expected format: "145-153"`);
+    }
+    const startLine = parseInt(match[1], 10);
+    const endLine = parseInt(match[2], 10);
+    if (startLine < 1 || endLine < startLine) {
+      throw new Error(`Invalid line range: ${spec}`);
+    }
+    parsed.push({
+      startLine,
+      endLine,
+      originalIndex: i
+    });
+  }
+  return parsed;
+}
+function validateNoOverlaps2(removes) {
+  const sorted = [...removes].sort((a, b) => a.startLine - b.startLine);
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const current = sorted[i];
+    const next = sorted[i + 1];
+    if (current.endLine >= next.startLine) {
+      throw new Error(
+        `Overlapping line ranges: ${current.startLine}-${current.endLine} overlaps with ${next.startLine}-${next.endLine}`
+      );
+    }
+  }
+}
+async function displayDryRun2(specName, content, removes) {
+  console.log(chalk16.bold.cyan(`\u{1F4CB} Compact Preview: ${specName}`));
+  console.log("");
+  console.log(chalk16.bold("Would remove:"));
+  console.log("");
+  let totalLines = 0;
+  for (const remove of removes) {
+    const lineCount = remove.endLine - remove.startLine + 1;
+    totalLines += lineCount;
+    const removedContent = extractLines(content, remove.startLine, remove.endLine);
+    const previewLines = removedContent.split("\n").slice(0, 3);
+    console.log(`  Lines ${remove.startLine}-${remove.endLine} (${lineCount} lines)`);
+    console.log(chalk16.dim("    Preview:"));
+    for (const line of previewLines) {
+      console.log(chalk16.dim(`      ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+    }
+    if (removedContent.split("\n").length > 3) {
+      console.log(chalk16.dim(`      ... (${removedContent.split("\n").length - 3} more lines)`));
+    }
+    console.log("");
+  }
+  const originalLines = countLines(content);
+  const remainingLines = originalLines - totalLines;
+  const percentage = Math.round(totalLines / originalLines * 100);
+  console.log(chalk16.bold("Summary:"));
+  console.log(`  Original lines:  ${chalk16.cyan(originalLines)}`);
+  console.log(`  Removing:        ${chalk16.yellow(totalLines)} lines (${percentage}%)`);
+  console.log(`  Remaining lines: ${chalk16.cyan(remainingLines)}`);
+  console.log("");
+  console.log(chalk16.dim("No files modified (dry run)"));
+  console.log(chalk16.dim("Run without --dry-run to apply changes"));
+  console.log("");
+}
+async function executeCompact(readmePath, specName, content, removes) {
+  console.log(chalk16.bold.cyan(`\u{1F5DC}\uFE0F  Compacting: ${specName}`));
+  console.log("");
+  const sorted = [...removes].sort((a, b) => b.startLine - a.startLine);
+  let updatedContent = content;
+  let totalRemoved = 0;
+  for (const remove of sorted) {
+    const lineCount = remove.endLine - remove.startLine + 1;
+    updatedContent = removeLines(updatedContent, remove.startLine, remove.endLine);
+    totalRemoved += lineCount;
+    console.log(chalk16.green(`\u2713 Removed lines ${remove.startLine}-${remove.endLine} (${lineCount} lines)`));
+  }
+  await writeFile(readmePath, updatedContent, "utf-8");
+  const originalLines = countLines(content);
+  const finalLines = countLines(updatedContent);
+  const percentage = Math.round(totalRemoved / originalLines * 100);
+  console.log("");
+  console.log(chalk16.bold.green("Compaction complete!"));
+  console.log(chalk16.dim(`Removed ${totalRemoved} lines (${percentage}%)`));
+  console.log(chalk16.dim(`${originalLines} \u2192 ${finalLines} lines`));
+  console.log("");
+}
 marked.use(markedTerminal());
 async function readSpecContent(specPath, cwd = process.cwd()) {
   const config = await loadConfig(cwd);
@@ -4756,24 +6247,46 @@ async function searchSpecsData(query, options) {
     includeContent: true,
     filter
   });
-  const results = [];
-  const queryLower = query.toLowerCase();
-  for (const spec of specs) {
-    if (!spec.content) continue;
-    const matches = [];
-    const lines = spec.content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (line.toLowerCase().includes(queryLower)) {
-        matches.push(line.trim());
-        if (matches.length >= 5) break;
-      }
-    }
-    if (matches.length > 0) {
-      results.push({ spec: specToData(spec), matches });
-    }
-  }
-  return results;
+  const searchableSpecs = specs.map((spec) => ({
+    path: spec.path,
+    name: spec.path,
+    status: spec.frontmatter.status,
+    priority: spec.frontmatter.priority,
+    tags: spec.frontmatter.tags,
+    title: spec.frontmatter.title,
+    description: spec.frontmatter.description,
+    content: spec.content
+  }));
+  const searchResult = searchSpecs(query, searchableSpecs, {
+    maxMatchesPerSpec: 5,
+    contextLength: 80
+  });
+  return {
+    results: searchResult.results.map((result) => ({
+      spec: {
+        name: result.spec.name,
+        path: result.spec.path,
+        status: result.spec.status,
+        created: specs.find((s) => s.path === result.spec.path)?.frontmatter.created || "",
+        title: result.spec.title,
+        tags: result.spec.tags,
+        priority: result.spec.priority,
+        assignee: specs.find((s) => s.path === result.spec.path)?.frontmatter.assignee,
+        description: result.spec.description,
+        customFields: specs.find((s) => s.path === result.spec.path)?.frontmatter.custom
+      },
+      score: result.score,
+      totalMatches: result.totalMatches,
+      matches: result.matches.map((match) => ({
+        field: match.field,
+        text: match.text,
+        lineNumber: match.lineNumber,
+        score: match.score,
+        highlights: match.highlights
+      }))
+    })),
+    metadata: searchResult.metadata
+  };
 }
 async function readSpecData(specPath) {
   const cwd = process.cwd();
@@ -4909,28 +6422,44 @@ async function createMcpServer() {
     "search",
     {
       title: "Search Specs",
-      description: "Full-text search across all specification content. Use this when you need to find specs by keyword, topic, or concept. Returns matching specs with relevant excerpts.",
+      description: "Intelligent relevance-ranked search across all specification content. Uses field-weighted scoring (title > tags > description > content) to return the most relevant specs. Returns matching specs with relevance scores, highlighted excerpts, and metadata.",
       inputSchema: {
-        query: z.string().describe("Search term or phrase to find in spec content. Searches across titles, descriptions, and body text."),
+        query: z.string().describe("Search term or phrase to find in spec content. Multiple terms are combined with AND logic. Searches across titles, tags, descriptions, and body text with intelligent relevance ranking."),
         status: z.enum(["planned", "in-progress", "complete", "archived"]).optional().describe("Limit search to specs with this status."),
         tags: z.array(z.string()).optional().describe("Limit search to specs with these tags."),
         priority: z.enum(["low", "medium", "high", "critical"]).optional().describe("Limit search to specs with this priority.")
       },
       outputSchema: {
-        results: z.array(z.any())
+        results: z.array(z.object({
+          spec: z.any(),
+          score: z.number(),
+          totalMatches: z.number(),
+          matches: z.array(z.object({
+            field: z.string(),
+            text: z.string(),
+            lineNumber: z.number().optional(),
+            score: z.number(),
+            highlights: z.array(z.tuple([z.number(), z.number()]))
+          }))
+        })),
+        metadata: z.object({
+          totalResults: z.number(),
+          searchTime: z.number(),
+          query: z.string(),
+          specsSearched: z.number()
+        })
       }
     },
     async (input) => {
       try {
-        const results = await searchSpecsData(input.query, {
+        const searchResult = await searchSpecsData(input.query, {
           status: input.status,
           tags: input.tags,
           priority: input.priority
         });
-        const output = { results };
         return {
-          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-          structuredContent: output
+          content: [{ type: "text", text: JSON.stringify(searchResult, null, 2) }],
+          structuredContent: searchResult
         };
       } catch (error) {
         const errorMessage = formatErrorMessage("Error searching specs", error);
@@ -5442,6 +6971,81 @@ ${result.content}`;
       }
     }
   );
+  server.registerTool(
+    "tokens",
+    {
+      title: "Count Tokens",
+      description: "Count tokens in spec or sub-spec for LLM context management. Use this before loading specs to check if they fit in context budget.",
+      inputSchema: {
+        specPath: z.string().describe('Spec name, number, or file path (e.g., "059", "unified-dashboard", "059/DESIGN.md")'),
+        includeSubSpecs: z.boolean().optional().describe("Include all sub-spec files in count (default: false)"),
+        detailed: z.boolean().optional().describe("Return breakdown by content type (code, prose, tables, frontmatter)")
+      },
+      outputSchema: {
+        spec: z.string(),
+        total: z.number(),
+        files: z.array(z.any()),
+        breakdown: z.any().optional(),
+        performance: z.any().optional(),
+        recommendation: z.string().optional()
+      }
+    },
+    async (input) => {
+      const counter = new TokenCounter();
+      try {
+        const config = await loadConfig();
+        const cwd = process.cwd();
+        const specsDir = path2.join(cwd, config.specsDir);
+        const resolvedPath = await resolveSpecPath(input.specPath, cwd, specsDir);
+        if (!resolvedPath) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              error: `Spec not found: ${input.specPath}`,
+              code: "SPEC_NOT_FOUND"
+            }, null, 2) }],
+            isError: true
+          };
+        }
+        const specName = path2.basename(resolvedPath);
+        const result = await counter.countSpec(resolvedPath, {
+          detailed: input.detailed,
+          includeSubSpecs: input.includeSubSpecs
+        });
+        const output = {
+          spec: specName,
+          total: result.total,
+          files: result.files
+        };
+        if (input.detailed && result.breakdown) {
+          output.breakdown = result.breakdown;
+          const indicators = counter.getPerformanceIndicators(result.total);
+          output.performance = {
+            level: indicators.level,
+            costMultiplier: indicators.costMultiplier,
+            effectiveness: indicators.effectiveness,
+            recommendation: indicators.recommendation
+          };
+        }
+        if (result.total > 5e3) {
+          output.recommendation = "\u26A0\uFE0F Total >5K tokens - consider loading README.md only";
+        } else if (result.total > 3500) {
+          output.recommendation = "\u26A0\uFE0F Total >3.5K tokens - consider loading in sections";
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        const errorMessage = formatErrorMessage("Error counting tokens", error);
+        return {
+          content: [{ type: "text", text: errorMessage }],
+          isError: true
+        };
+      } finally {
+        counter.dispose();
+      }
+    }
+  );
   server.registerResource(
     "spec",
     new ResourceTemplate("spec://{specPath}", { list: void 0 }),
@@ -5621,6 +7225,6 @@ Please search for this topic and show me the dependencies between related specs.
   return server;
 }
 
-export { addTemplate, archiveSpec, backfillTimestamps, boardCommand, checkSpecs, copyTemplate, createMcpServer, createSpec, depsCommand, filesCommand, ganttCommand, initProject, listSpecs, listTemplates, mcpCommand, migrateCommand, openCommand, removeTemplate, searchCommand, showTemplate, statsCommand, timelineCommand, tokensAllCommand, tokensCommand, updateSpec, validateCommand, viewCommand };
-//# sourceMappingURL=chunk-ER23B6KS.js.map
-//# sourceMappingURL=chunk-ER23B6KS.js.map
+export { addTemplate, analyzeCommand, archiveSpec, backfillTimestamps, boardCommand, checkSpecs, compactCommand, copyTemplate, createMcpServer, createSpec, depsCommand, filesCommand, ganttCommand, initProject, listSpecs, listTemplates, mcpCommand, migrateCommand, openCommand, removeTemplate, searchCommand, showTemplate, splitCommand, statsCommand, timelineCommand, tokensAllCommand, tokensCommand, updateSpec, validateCommand, viewCommand };
+//# sourceMappingURL=chunk-7MCDTSVE.js.map
+//# sourceMappingURL=chunk-7MCDTSVE.js.map