all-hands-cli 0.1.14 → 0.1.16

package/.allhands/harness/src/commands/complexity.ts

@@ -1,7 +1,7 @@
 /**
  * Complexity command - Get complexity metrics for files or directories.
  *
- * Uses ctags to count symbols for broader language support.
+ * Provides line counts and estimated token counts for source files.
  *
  * Command:
  *   ah complexity <path>  - Get complexity metrics
@@ -17,15 +17,11 @@ import {
   CommandResult,
 } from "../lib/base-command.js";
 import { getProjectRoot } from "../lib/git.js";
-import {
-  checkCtagsAvailable,
-  generateCtagsIndex,
-  getFileSymbols,
-} from "../lib/ctags.js";
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java", ".swift", ".rb", ".kt"];
 
 /**
  * Get complexity metrics for a file or directory.
- * Uses ctags to count symbols instead of AST parsing.
  */
 async function complexity(pathArg: string): Promise<CommandResult> {
   const projectRoot = getProjectRoot();
@@ -41,70 +37,27 @@ async function complexity(pathArg: string): Promise<CommandResult> {
     };
   }
 
-  // Check ctags availability
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
   const stat = statSync(absolutePath);
 
   if (stat.isFile()) {
-    // Single file complexity
     const content = readFileSync(absolutePath, "utf-8");
     const lines = content.split("\n").length;
 
-    // Get symbols via ctags
-    const { index } = generateCtagsIndex(projectRoot, { target: relativePath });
-    const symbols = getFileSymbols(index, relativePath);
-
-    const functions = symbols.filter(
-      (s) => s.kind === "function" || s.kind === "method"
-    ).length;
-    const classes = symbols.filter((s) => s.kind === "class").length;
-    const interfaces = symbols.filter(
-      (s) => s.kind === "interface" || s.kind === "type"
-    ).length;
-
-    // Count imports/exports with regex (simple heuristic)
-    const importMatches = content.match(/^import\s/gm);
-    const exportMatches = content.match(/^export\s/gm);
-
     return {
       success: true,
       data: {
         path: relativePath,
         type: "file",
-        metrics: {
-          lines,
-          functions,
-          classes,
-          interfaces,
-          imports: importMatches?.length || 0,
-          exports: exportMatches?.length || 0,
-          total_symbols: symbols.length,
-        },
+        metrics: { lines },
         estimated_tokens: Math.ceil(lines * 10),
       },
     };
   }
 
   // Directory complexity
-  const { index, entryCount } = generateCtagsIndex(projectRoot, {
-    target: relativePath,
-  });
-
-  // Aggregate stats
   let totalLines = 0;
-  let totalFunctions = 0;
-  let totalClasses = 0;
-  let totalInterfaces = 0;
   let fileCount = 0;
 
-  // Find source files and count lines
   const countDir = (dir: string): void => {
     const entries = readdirSync(dir);
     for (const entry of entries) {
@@ -115,7 +68,7 @@ async function complexity(pathArg: string): Promise<CommandResult> {
         countDir(fullPath);
       } else {
         const ext = extname(entry);
-        if ([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java"].includes(ext)) {
+        if (SOURCE_EXTENSIONS.includes(ext)) {
           fileCount++;
           const content = readFileSync(fullPath, "utf-8");
           totalLines += content.split("\n").length;
@@ -126,34 +79,13 @@ async function complexity(pathArg: string): Promise<CommandResult> {
 
   countDir(absolutePath);
 
-  // Count symbol types from index
-  for (const fileMap of Array.from(index.values())) {
-    for (const entries of Array.from(fileMap.values())) {
-      for (const entry of entries) {
-        if (entry.kind === "function" || entry.kind === "method") {
-          totalFunctions++;
-        } else if (entry.kind === "class") {
-          totalClasses++;
-        } else if (entry.kind === "interface" || entry.kind === "type") {
-          totalInterfaces++;
-        }
-      }
-    }
-  }
-
   return {
     success: true,
     data: {
       path: relativePath,
       type: "directory",
       file_count: fileCount,
-      metrics: {
-        lines: totalLines,
-        functions: totalFunctions,
-        classes: totalClasses,
-        interfaces: totalInterfaces,
-        total_symbols: entryCount,
-      },
+      metrics: { lines: totalLines },
       estimated_tokens: Math.ceil(totalLines * 10),
     },
   };

package/.allhands/harness/src/commands/docs.ts

@@ -1,8 +1,8 @@
 /**
  * Documentation commands - validation and reference finalization.
  *
- * Uses ctags for symbol lookup (instead of AST parsing) for broader language support
- * and simpler implementation.
+ * Symbols in refs are author-provided labels. Staleness is detected via
+ * file-level git blob hashes.
  *
  * Commands:
  *   ah docs validate [--path <path>]  - Validate all refs in docs/
@@ -19,15 +19,10 @@ import {
   executeCommand,
   parseContext,
 } from "../lib/base-command.js";
-import {
-  checkCtagsAvailable,
-  findSymbolInFile,
-  generateCtagsIndex,
-} from "../lib/ctags.js";
 import {
   batchGetBlobHashes,
   findMarkdownFiles,
-  isCodeFile,
+  REF_PATTERN,
   validateDocsAsync,
 } from "../lib/docs-validation.js";
 import { getProjectRoot } from "../lib/git.js";
@@ -44,15 +39,6 @@ async function validate(docsPath: string, options?: { useCache?: boolean }): Pro
     ? docsPath
     : join(projectRoot, docsPath);
 
-  // Check ctags availability first
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
   const excludePaths = EXCLUDED_DOC_PATHS.map((p) => join(projectRoot, p));
 
   // Run validation (with optional caching)
@@ -261,25 +247,7 @@ function finalizeSingleFile(
       continue;
     }
 
-    // For non-code files (markdown, yaml, json, etc.), treat symbol as a label (no ctags lookup)
-    if (!isCodeFile(placeholder.file)) {
-      const fullRef = `[ref:${placeholder.file}:${placeholder.symbol}:${hashResult.hash}]`;
-      finalizedContent = finalizedContent.replaceAll(placeholder.match, fullRef);
-      replacements.push({ from: placeholder.match, to: fullRef });
-      continue;
-    }
-
-    // For code files with symbol refs, verify symbol exists via ctags
-    const entry = findSymbolInFile(absoluteFilePath, placeholder.symbol, projectRoot);
-    if (!entry) {
-      errors.push({
-        placeholder: placeholder.match,
-        reason: `Symbol '${placeholder.symbol}' not found in ${placeholder.file}`,
-      });
-      continue;
-    }
-
-    // Create full ref
+    // Symbol is an author-provided label — produce the full ref with hash directly
     const fullRef = `[ref:${placeholder.file}:${placeholder.symbol}:${hashResult.hash}]`;
     finalizedContent = finalizedContent.replaceAll(placeholder.match, fullRef);
     replacements.push({ from: placeholder.match, to: fullRef });
@@ -371,18 +339,6 @@ async function finalize(docsPath: string, options?: { refresh?: boolean }): Prom
     };
   }
 
-  // Check ctags availability
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
-  // Generate ctags index for symbol lookup
-  generateCtagsIndex(projectRoot);
-
   // Determine if path is a file or directory
   const excludePaths = EXCLUDED_DOC_PATHS.map((p) => join(projectRoot, p));
   const stat = statSync(absolutePath);

package/.allhands/harness/src/lib/docs-validation.ts

@@ -2,11 +2,11 @@
  * Documentation validation utilities.
  *
  * Validates references in documentation files against the actual codebase
- * using ctags for symbol lookup and git for staleness detection.
+ * using git blob hashes for staleness detection.
  *
  * Reference formats:
- *   [ref:file:symbol:hash] - Symbol reference (validated via ctags)
- *   [ref:file::hash]       - File-only reference (no symbol validation)
+ *   [ref:file:symbol:hash] - Symbol reference (symbol is an author-provided label)
+ *   [ref:file::hash]       - File-only reference
  *
  * Where hash = git blob hash (content-addressable, stable across merges/rebases)
  */
@@ -14,40 +14,8 @@
 import { spawnSync } from "child_process";
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { extname, join, relative } from "path";
+import { join, relative } from "path";
 import matter from "gray-matter";
-import { CtagsIndex, generateCtagsIndex, generateCtagsIndexAsync, lookupSymbol } from "./ctags.js";
-
-/**
- * File extensions that ctags can process (programming languages).
- * Files with other extensions are treated as non-code where symbols are just labels.
- */
-const CODE_EXTENSIONS = new Set([
-  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",  // TypeScript/JavaScript
-  ".py", ".pyw",                                   // Python
-  ".go",                                           // Go
-  ".rs",                                           // Rust
-  ".java",                                         // Java
-  ".rb",                                           // Ruby
-  ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp",      // C/C++
-  ".cs",                                           // C#
-  ".php",                                          // PHP
-  ".kt", ".kts",                                   // Kotlin
-  ".swift",                                        // Swift
-  ".scala",                                        // Scala
-  ".lua",                                          // Lua
-  ".sh", ".bash", ".zsh",                         // Shell scripts
-  ".vim",                                          // Vim script
-  ".el",                                           // Emacs Lisp
-]);
-
-/**
- * Check if a file is a code file that ctags can process.
- */
-export function isCodeFile(filePath: string): boolean {
-  const ext = extname(filePath).toLowerCase();
-  return CODE_EXTENSIONS.has(ext);
-}
 
 /**
  * Validation cache for faster repeated validation runs.
@@ -484,13 +452,11 @@ export function findMarkdownFiles(dir: string, excludeReadme = false, excludePat
 /**
  * Validate a single reference.
  * @param ref - The parsed reference to validate
- * @param ctagsIndex - The ctags index for symbol lookup
  * @param projectRoot - The project root directory
  * @param hashCache - Optional pre-fetched hash map for performance
  */
 export function validateRef(
   ref: ParsedRef,
-  ctagsIndex: CtagsIndex,
   projectRoot: string,
   hashCache?: Map<string, { hash: string; success: boolean }>
 ): ValidatedRef {
@@ -525,49 +491,12 @@ export function validateRef(
     };
   }
 
-  // File-only reference: just check hash
-  if (ref.isFileOnly) {
-    if (currentHash !== ref.hash) {
-      return {
-        ...ref,
-        state: "stale",
-        reason: "File has been modified",
-        currentHash,
-      };
-    }
-    return { ...ref, state: "valid" };
-  }
-
-  // Non-code files (markdown, yaml, json, etc.): treat symbol as label, just check hash
-  if (!isCodeFile(ref.file)) {
-    if (currentHash !== ref.hash) {
-      return {
-        ...ref,
-        state: "stale",
-        reason: "File has been modified",
-        currentHash,
-      };
-    }
-    return { ...ref, state: "valid" };
-  }
-
-  // Code file symbol reference: check symbol exists via ctags
-  const entries = lookupSymbol(ctagsIndex, ref.file, ref.symbol!);
-
-  if (entries.length === 0) {
-    return {
-      ...ref,
-      state: "invalid",
-      reason: `Symbol '${ref.symbol}' not found in ${ref.file}`,
-    };
-  }
-
-  // Check hash staleness (using file-level hash for ctags approach)
+  // Check hash staleness (symbols are author-provided labels, not verified)
   if (currentHash !== ref.hash) {
     return {
       ...ref,
       state: "stale",
-      reason: "File has been modified since reference was created",
+      reason: "File has been modified",
       currentHash,
     };
   }
@@ -581,7 +510,7 @@ export function validateRef(
 export function validateDocs(
   docsPath: string,
   projectRoot: string,
-  options?: { ctagsIndex?: CtagsIndex; useCache?: boolean; excludePaths?: string[] }
+  options?: { useCache?: boolean; excludePaths?: string[] }
 ): ValidationResult {
   // Initialize result
   const result: ValidationResult = {
@@ -627,11 +556,6 @@ export function validateDocs(
     refFileHashes: {},
   };
 
-  // Generate ctags index (or use provided one)
-  const ctagsIndex =
-    options?.ctagsIndex ||
-    generateCtagsIndex(projectRoot).index;
-
   // Helper to get/create doc file entry
   const getDocEntry = (docFile: string): DocFileIssues => {
     if (!result.by_doc_file[docFile]) {
@@ -759,7 +683,7 @@ export function validateDocs(
 
   // Validate each reference (using cached hashes)
   for (const ref of allRefs) {
-    const validated = validateRef(ref, ctagsIndex, projectRoot, hashCache);
+    const validated = validateRef(ref, projectRoot, hashCache);
 
     if (validated.state === "valid") {
       result.valid_count++;
@@ -856,52 +780,12 @@ export function validateDocs(
 
 /**
  * Validate all documentation in a directory (async version).
- *
- * Identical to validateDocs but uses generateCtagsIndexAsync to avoid
- * blocking the event loop during ctags execution.
+ * Kept async for API compatibility. Delegates directly to validateDocs.
  */
 export async function validateDocsAsync(
   docsPath: string,
   projectRoot: string,
-  options?: { ctagsIndex?: CtagsIndex; useCache?: boolean; excludePaths?: string[] }
+  options?: { useCache?: boolean; excludePaths?: string[] }
 ): Promise<ValidationResult> {
-  // If a ctags index was provided, delegate to the sync version directly
-  if (options?.ctagsIndex) {
-    return validateDocs(docsPath, projectRoot, options);
-  }
-
-  // Generate ctags index asynchronously
-  const ctagsResult = await generateCtagsIndexAsync(projectRoot);
-
-  // If ctags is unavailable or failed, run validation with the empty map
-  // (to prevent a sync fallback that would also fail), then strip out the
-  // symbol-ref invalids that are false positives from the empty index.
-  if (!ctagsResult.success) {
-    const baseResult = validateDocs(docsPath, projectRoot, {
-      ...options,
-      ctagsIndex: ctagsResult.index, // empty map — avoids sync fallback
-    });
-    // Remove symbol-ref invalid entries (they're false positives from empty index)
-    const symbolInvalidCount = baseResult.invalid.filter((i) =>
-      i.reason.startsWith("Symbol '")
-    ).length;
-    baseResult.invalid = baseResult.invalid.filter(
-      (i) => !i.reason.startsWith("Symbol '")
-    );
-    // Also strip from per-doc entries
-    for (const entry of Object.values(baseResult.by_doc_file)) {
-      entry.invalid = entry.invalid.filter(
-        (i) => !i.reason.startsWith("Symbol '")
-      );
-    }
-    baseResult.invalid_count -= symbolInvalidCount;
-    baseResult.message = `ctags unavailable: ${ctagsResult.error ?? "unknown error"} — symbol ref validation skipped`;
-    return baseResult;
-  }
-
-  // Delegate to sync validateDocs with the pre-built index
-  return validateDocs(docsPath, projectRoot, {
-    ...options,
-    ctagsIndex: ctagsResult.index,
-  });
+  return validateDocs(docsPath, projectRoot, options);
 }

package/.allhands/skills/harness-maintenance/references/validation-tooling.md

@@ -80,6 +80,7 @@ Prompt files reference suites in `validation_suites` frontmatter. During executi
 
 - **External tooling** (xctrace, simctl, playwright, etc.) — Document explicitly: commands, flags, use cases inline with motivations. Stable and unfamiliar to agents by default. Example from xcode-automation: `xcrun xctrace record --template 'Time Profiler' --device '<UDID>' --attach '<PID>'` — flags, ordering constraints, and PID discovery are external tool knowledge that belongs in the suite.
 - **Internal codebase commands** — Document patterns, not inventories: teach discovery (`package.json` scripts, `--help`), naming conventions, motivations for test categories. Pattern-based suites age gracefully; command inventories require constant maintenance.
+- **Anti-pattern — exhaustive command tables**: A deterministic section listing every `test:*` command as individual rows goes stale as suites evolve. Instead: document the minimum CI gate command explicitly, teach the naming pattern, point to the source of truth (e.g., `package.json`), and explain how to choose scope. The agent reads the source at execution time — always fresher than a static table.
 
 ## Decision Tree Requirement
 
@@ -117,6 +118,24 @@ New suites: draft, then test on a feature branch before marking guidance as prov
 
 The plan/handoff document persists as the hypothesis record for future work.
 
+## Established Practice vs Unvalidated Ideas
+
+Suites contain two kinds of guidance, both authoritative:
+
+- **Established practice**: Verified hands-on. Stated authoritatively — agents follow directly.
+- **Unvalidated ideas**: Worth pursuing but not yet exercised. Authoritative as direction — agents encountering them should attempt, assess feasibility, and document outcomes.
+
+Ideas carry an implicit mandate: try to make them work, then capture what happened (see Learnings Destination). Over time, ideas that prove out become established practice. Ideas that prove infeasible get revised or removed. This is the crystallization lifecycle applied to the documentation itself.
+
+## Learnings Destination
+
+When agents discover something during validation:
+
+- **Suite-level learnings** (about the validation *practice*) → update the suite doc directly. The suite is what agents read — improvements compound immediately. Examples: tool flag doesn't work on this OS, one approach is more reliable than another.
+- **Task-specific learnings** (about *what was validated*) → knowledge compounding via prompt files or knowledge docs. Examples: endpoint edge case behavior, migration quirks.
+
+Distinction: if it helps any agent validating in this domain regardless of task, it belongs in the suite. If it's specific to a feature, it compounds through knowledge docs.
+
 ## Cross-Referencing Between Suites
 
 - **Reference** for complex multi-step setup — point to the authoritative suite's decision tree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-hands-cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Agentic harness for model-first software development",
   "type": "module",
   "bin": {

package/.allhands/harness/src/lib/__tests__/ctags.test.ts

@@ -1,244 +0,0 @@
-/**
- * Tests for ctags utilities.
- *
- * Note: These tests require universal-ctags to be installed.
- * Tests are skipped if ctags is not available.
- */
-
-import { describe, expect, it, beforeAll } from "vitest";
-import { join } from "path";
-import { writeFileSync, mkdirSync, rmSync, existsSync } from "fs";
-import {
-  checkCtagsAvailable,
-  generateCtagsIndex,
-  lookupSymbol,
-  searchSymbol,
-  getFileSymbols,
-  generateFileCtags,
-  findSymbolInFile,
-  CtagsIndex,
-} from "../ctags.js";
-
-// Check if ctags is available for tests
-const ctagsCheck = checkCtagsAvailable();
-const hasCtagsInstalled = ctagsCheck.available;
-
-describe("checkCtagsAvailable", () => {
-  it("returns availability status", () => {
-    const result = checkCtagsAvailable();
-    expect(result).toHaveProperty("available");
-
-    if (result.available) {
-      expect(result.version).toBeDefined();
-    } else {
-      expect(result.error).toBeDefined();
-    }
-  });
-});
-
-// Skip remaining tests if ctags not installed
-describe.skipIf(!hasCtagsInstalled)("ctags with installed ctags", () => {
-  const testDir = join(process.cwd(), ".test-ctags-temp");
-  const testFile = join(testDir, "test-sample.ts");
-
-  const sampleCode = `
-// Test TypeScript file for ctags tests
-
-export class MyClass {
-  private value: number;
-
-  constructor(value: number) {
-    this.value = value;
-  }
-
-  getValue(): number {
-    return this.value;
-  }
-
-  setValue(newValue: number): void {
-    this.value = newValue;
-  }
-}
-
-export interface MyInterface {
-  name: string;
-  age: number;
-}
-
-export function myFunction(arg: string): string {
-  return arg.toUpperCase();
-}
-
-export const MY_CONSTANT = 42;
-
-type MyType = string | number;
-`;
-
-  beforeAll(() => {
-    // Create test directory and file
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true });
-    }
-    mkdirSync(testDir, { recursive: true });
-    writeFileSync(testFile, sampleCode, "utf-8");
-
-    return () => {
-      // Cleanup
-      if (existsSync(testDir)) {
-        rmSync(testDir, { recursive: true });
-      }
-    };
-  });
-
-  describe("generateFileCtags", () => {
-    it("generates ctags for a single file", () => {
-      const result = generateFileCtags(testFile, testDir);
-
-      expect(result.success).toBe(true);
-      expect(result.entries.length).toBeGreaterThan(0);
-
-      // Should find known symbols
-      const symbolNames = result.entries.map((e) => e.name);
-      expect(symbolNames).toContain("MyClass");
-      expect(symbolNames).toContain("myFunction");
-    });
-
-    it("returns error for non-existent file", () => {
-      const result = generateFileCtags(join(testDir, "nonexistent.ts"), testDir);
-
-      expect(result.success).toBe(false);
-      expect(result.error).toBeDefined();
-    });
-
-    it("includes symbol metadata", () => {
-      const result = generateFileCtags(testFile, testDir);
-      expect(result.success).toBe(true);
-
-      const classEntry = result.entries.find((e) => e.name === "MyClass");
-      expect(classEntry).toBeDefined();
-      expect(classEntry!.kind).toBe("class");
-      expect(classEntry!.line).toBeGreaterThan(0);
-    });
-  });
-
-  describe("generateCtagsIndex", () => {
-    it("generates index for directory", () => {
-      const result = generateCtagsIndex(testDir);
-
-      expect(result.success).toBe(true);
-      expect(result.entryCount).toBeGreaterThan(0);
-      expect(result.index.size).toBeGreaterThan(0);
-    });
-
-    it("indexes symbols by file and name", () => {
-      const { index, success } = generateCtagsIndex(testDir);
-      expect(success).toBe(true);
-
-      // The file path should be relative to cwd
-      const relPath = "test-sample.ts";
-      const fileMap = index.get(relPath);
-      expect(fileMap).toBeDefined();
-
-      // Should have MyClass
-      const myClass = fileMap!.get("MyClass");
-      expect(myClass).toBeDefined();
-      expect(myClass!.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe("lookupSymbol", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("finds symbol in specific file", () => {
-      const entries = lookupSymbol(index, "test-sample.ts", "MyClass");
-
-      expect(entries.length).toBeGreaterThan(0);
-      expect(entries[0].name).toBe("MyClass");
-    });
-
-    it("returns empty array for non-existent symbol", () => {
-      const entries = lookupSymbol(index, "test-sample.ts", "NonExistent");
-      expect(entries).toHaveLength(0);
-    });
-
-    it("returns empty array for non-existent file", () => {
-      const entries = lookupSymbol(index, "nonexistent.ts", "MyClass");
-      expect(entries).toHaveLength(0);
-    });
-  });
-
-  describe("searchSymbol", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("finds symbol across all files", () => {
-      const results = searchSymbol(index, "MyClass");
-
-      expect(results.length).toBeGreaterThan(0);
-      expect(results[0].name).toBe("MyClass");
-      expect(results[0].file).toBeDefined();
-    });
-
-    it("returns empty for non-existent symbol", () => {
-      const results = searchSymbol(index, "NonExistent");
-      expect(results).toHaveLength(0);
-    });
-  });
-
-  describe("getFileSymbols", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("returns all symbols in a file", () => {
-      const symbols = getFileSymbols(index, "test-sample.ts");
-
-      expect(symbols.length).toBeGreaterThan(0);
-
-      // Should include class, function, interface
-      const names = symbols.map((s) => s.name);
-      expect(names).toContain("MyClass");
-      expect(names).toContain("myFunction");
-    });
-
-    it("returns symbols sorted by line number", () => {
-      const symbols = getFileSymbols(index, "test-sample.ts");
-
-      for (let i = 1; i < symbols.length; i++) {
-        expect(symbols[i].line).toBeGreaterThanOrEqual(symbols[i - 1].line);
-      }
-    });
-
-    it("returns empty for non-existent file", () => {
-      const symbols = getFileSymbols(index, "nonexistent.ts");
-      expect(symbols).toHaveLength(0);
-    });
-  });
-
-  describe("findSymbolInFile", () => {
-    it("finds symbol in file", () => {
-      const entry = findSymbolInFile(testFile, "MyClass", testDir);
-
-      expect(entry).not.toBeNull();
-      expect(entry!.name).toBe("MyClass");
-      expect(entry!.kind).toBe("class");
-    });
-
-    it("returns null for non-existent symbol", () => {
-      const entry = findSymbolInFile(testFile, "NonExistent", testDir);
-      expect(entry).toBeNull();
-    });
-  });
-});

package/.allhands/harness/src/lib/ctags.ts

@@ -1,497 +0,0 @@
-/**
- * Ctags utilities for symbol lookup and validation.
- *
- * Uses universal-ctags to generate a symbol index for fast O(1) lookups.
- * This enables documentation reference validation without AST parsing.
- */
-
-import { spawn, spawnSync } from "child_process";
-import { existsSync } from "fs";
-
-/**
- * Single ctags entry representing a symbol in a file.
- */
-export interface CtagsEntry {
-  name: string;
-  path: string;
-  line: number;
-  kind: string;
-  signature?: string;
-}
-
-/**
- * Indexed ctags data for O(1) lookups.
- * Structure: Map<file, Map<symbol, CtagsEntry[]>>
- * Multiple entries per symbol possible (overloads, same name in different scopes).
- */
-export type CtagsIndex = Map<string, Map<string, CtagsEntry[]>>;
-
-/**
- * Common paths where universal-ctags might be installed.
- * Checked in order before falling back to PATH.
- */
-const CTAGS_PATHS = [
-  "/opt/homebrew/bin/ctags", // macOS ARM homebrew
-  "/usr/local/bin/ctags", // macOS Intel homebrew / Linux
-  "/usr/bin/ctags", // System PATH (may be BSD ctags)
-  "ctags", // Fall back to PATH
-];
-
-/** Cached path to universal-ctags binary */
-let cachedCtagsPath: string | null = null;
-
-/**
- * Find the universal-ctags binary, checking common paths first.
- */
-function findUniversalCtags(): { path: string; version: string } | null {
-  for (const ctagsPath of CTAGS_PATHS) {
-    // Skip absolute paths that don't exist
-    if (ctagsPath.startsWith("/") && !existsSync(ctagsPath)) {
-      continue;
-    }
-
-    const result = spawnSync(ctagsPath, ["--version"], { encoding: "utf-8" });
-
-    if (result.status !== 0) {
-      continue;
-    }
-
-    const output = result.stdout || "";
-    if (output.includes("Universal Ctags") || output.includes("universal-ctags")) {
-      const versionMatch = output.match(/Universal Ctags\s+([\d.]+)/i);
-      const version = versionMatch ? versionMatch[1] : "unknown";
-      return { path: ctagsPath, version };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Get the path to universal-ctags (cached).
- */
-export function getCtagsPath(): string | null {
-  if (cachedCtagsPath !== null) {
-    return cachedCtagsPath;
-  }
-
-  const found = findUniversalCtags();
-  if (found) {
-    cachedCtagsPath = found.path;
-    return cachedCtagsPath;
-  }
-
-  return null;
-}
-
-/**
- * Check if ctags (universal-ctags) is available.
- */
-export function checkCtagsAvailable(): { available: boolean; version?: string; error?: string; path?: string } {
-  const found = findUniversalCtags();
-
-  if (!found) {
-    return {
-      available: false,
-      error:
-        "Universal Ctags not found. Install with: brew install universal-ctags\n" +
-        "Note: The BSD ctags that ships with macOS is not compatible.",
-    };
-  }
-
-  cachedCtagsPath = found.path;
-
-  return {
-    available: true,
-    version: found.version,
-    path: found.path,
-  };
-}
-
-/**
- * Parse a single line of ctags JSON output.
- */
-function parseCtagsLine(line: string): CtagsEntry | null {
-  try {
-    const entry = JSON.parse(line);
-
-    // Skip ptag entries (pseudo-tags with metadata)
-    if (entry._type === "ptag") {
-      return null;
-    }
-
-    if (entry._type !== "tag" || !entry.name || !entry.path) {
-      return null;
-    }
-
-    return {
-      name: entry.name,
-      path: entry.path,
-      line: entry.line || 0,
-      kind: entry.kind || "unknown",
-      signature: entry.signature,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Generate a ctags index for a directory.
- *
- * Uses ctags with JSON output format for reliable parsing.
- * Excludes common non-source directories.
- */
-export function generateCtagsIndex(
-  cwd: string,
-  options?: {
-    /** Additional exclude patterns */
-    exclude?: string[];
-    /** Specific file or directory to index (relative to cwd) */
-    target?: string;
-  }
-): { index: CtagsIndex; success: boolean; error?: string; entryCount: number } {
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return {
-      index: new Map(),
-      success: false,
-      error: check.error,
-      entryCount: 0,
-    };
-  }
-
-  const excludes = [
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    ...(options?.exclude || []),
-  ];
-
-  const args = [
-    "-R",
-    "--output-format=json",
-    "--fields=+nKS", // +n=line number, +K=kind, +S=signature
-    "-o",
-    "-", // Output to stdout
-  ];
-
-  // Add exclude patterns
-  for (const exclude of excludes) {
-    args.push(`--exclude=${exclude}`);
-  }
-
-  // Add target if specified, otherwise index current directory
-  const target = options?.target || ".";
-  args.push(target);
-
-  const ctagsPath = getCtagsPath()!;
-  const result = spawnSync(ctagsPath, args, {
-    encoding: "utf-8",
-    cwd,
-    maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large repos
-  });
-
-  if (result.status !== 0) {
-    return {
-      index: new Map(),
-      success: false,
-      error: `ctags failed: ${result.stderr || "unknown error"}`,
-      entryCount: 0,
-    };
-  }
-
-  // Parse JSON output into index
-  const index: CtagsIndex = new Map();
-  let entryCount = 0;
-
-  const lines = result.stdout.split("\n");
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    const entry = parseCtagsLine(line);
-    if (!entry) continue;
-
-    entryCount++;
-
-    // Get or create file map
-    let fileMap = index.get(entry.path);
-    if (!fileMap) {
-      fileMap = new Map();
-      index.set(entry.path, fileMap);
-    }
-
-    // Get or create symbol array
-    let symbols = fileMap.get(entry.name);
-    if (!symbols) {
-      symbols = [];
-      fileMap.set(entry.name, symbols);
-    }
-
-    symbols.push(entry);
-  }
-
-  return { index, success: true, entryCount };
-}
-
-/**
- * Look up a symbol in a specific file.
- *
- * Returns all matching entries (may have multiple for overloads).
- */
-export function lookupSymbol(
-  index: CtagsIndex,
-  filePath: string,
-  symbolName: string
-): CtagsEntry[] {
-  const fileMap = index.get(filePath);
-  if (!fileMap) {
-    return [];
-  }
-
-  return fileMap.get(symbolName) || [];
-}
-
-/**
- * Look up a symbol in any file (for searching).
- *
- * Returns all matching entries across all files.
- */
-export function searchSymbol(
-  index: CtagsIndex,
-  symbolName: string
-): Array<CtagsEntry & { file: string }> {
-  const results: Array<CtagsEntry & { file: string }> = [];
-
-  for (const [file, fileMap] of index) {
-    const entries = fileMap.get(symbolName);
-    if (entries) {
-      for (const entry of entries) {
-        results.push({ ...entry, file });
-      }
-    }
-  }
-
-  return results;
-}
-
-/**
- * Get all symbols in a file.
- */
-export function getFileSymbols(index: CtagsIndex, filePath: string): CtagsEntry[] {
-  const fileMap = index.get(filePath);
-  if (!fileMap) {
-    return [];
-  }
-
-  const symbols: CtagsEntry[] = [];
-  for (const entries of fileMap.values()) {
-    symbols.push(...entries);
-  }
-
-  // Sort by line number
-  return symbols.sort((a, b) => a.line - b.line);
-}
-
-/**
- * Generate ctags for a single file (faster for format-reference command).
- */
-export function generateFileCtags(
-  filePath: string,
-  cwd: string
-): { entries: CtagsEntry[]; success: boolean; error?: string } {
-  if (!existsSync(filePath)) {
-    return { entries: [], success: false, error: "File not found" };
-  }
-
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return { entries: [], success: false, error: check.error };
-  }
-
-  const args = [
-    "--output-format=json",
-    "--fields=+nKS",
-    "-o",
-    "-",
-    filePath,
-  ];
-
-  const ctagsPath = getCtagsPath()!;
-  const result = spawnSync(ctagsPath, args, {
-    encoding: "utf-8",
-    cwd,
-    maxBuffer: 10 * 1024 * 1024, // 10MB buffer
-  });
-
-  if (result.status !== 0) {
-    return {
-      entries: [],
-      success: false,
-      error: `ctags failed: ${result.stderr || "unknown error"}`,
-    };
-  }
-
-  const entries: CtagsEntry[] = [];
-  const lines = result.stdout.split("\n");
-
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    const entry = parseCtagsLine(line);
-    if (entry) {
-      entries.push(entry);
-    }
-  }
-
-  return { entries, success: true };
-}
-
-/**
- * Find a specific symbol in a file (convenience function).
- * Uses single-file ctags for efficiency.
- */
-export function findSymbolInFile(
-  filePath: string,
-  symbolName: string,
-  cwd: string
-): CtagsEntry | null {
-  const { entries, success } = generateFileCtags(filePath, cwd);
-  if (!success) {
-    return null;
-  }
-
-  // Return first match (usually there's only one)
-  return entries.find((e) => e.name === symbolName) || null;
-}
-
-/**
- * Generate a ctags index asynchronously (non-blocking).
- *
- * Same behavior as generateCtagsIndex but uses spawn instead of spawnSync,
- * keeping the event loop free during the ctags process.
- */
-export async function generateCtagsIndexAsync(
-  cwd: string,
-  options?: {
-    /** Additional exclude patterns */
-    exclude?: string[];
-    /** Specific file or directory to index (relative to cwd) */
-    target?: string;
-  }
-): Promise<{ index: CtagsIndex; success: boolean; error?: string; entryCount: number }> {
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return {
-      index: new Map(),
-      success: false,
-      error: check.error,
-      entryCount: 0,
-    };
-  }
-
-  const excludes = [
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    ...(options?.exclude || []),
-  ];
-
-  const args = [
-    "-R",
-    "--output-format=json",
-    "--fields=+nKS",
-    "-o",
-    "-",
-  ];
-
-  for (const exclude of excludes) {
-    args.push(`--exclude=${exclude}`);
-  }
-
-  const target = options?.target || ".";
-  args.push(target);
-
-  const ctagsPath = getCtagsPath()!;
-
-  return new Promise((resolve) => {
-    const child = spawn(ctagsPath, args, {
-      cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-
-    const chunks: Buffer[] = [];
-    let stderrOutput = "";
-
-    child.stdout?.on("data", (data: Buffer) => {
-      chunks.push(data);
-    });
-
-    child.stderr?.on("data", (data: Buffer) => {
-      stderrOutput += data.toString();
-    });
-
-    child.on("close", (code) => {
-      if (code !== 0) {
-        resolve({
-          index: new Map(),
-          success: false,
-          error: `ctags failed: ${stderrOutput || "unknown error"}`,
-          entryCount: 0,
-        });
-        return;
-      }
-
-      const stdout = Buffer.concat(chunks).toString("utf-8");
-      const index: CtagsIndex = new Map();
-      let entryCount = 0;
-
-      const lines = stdout.split("\n");
-      for (const line of lines) {
-        if (!line.trim()) continue;
-
-        const entry = parseCtagsLine(line);
-        if (!entry) continue;
-
-        entryCount++;
-
-        let fileMap = index.get(entry.path);
-        if (!fileMap) {
-          fileMap = new Map();
-          index.set(entry.path, fileMap);
-        }
-
-        let symbols = fileMap.get(entry.name);
-        if (!symbols) {
-          symbols = [];
-          fileMap.set(entry.name, symbols);
-        }
-
-        symbols.push(entry);
-      }
-
-      resolve({ index, success: true, entryCount });
-    });
-
-    child.on("error", (err) => {
-      resolve({
-        index: new Map(),
-        success: false,
-        error: `ctags spawn error: ${err.message}`,
-        entryCount: 0,
-      });
-    });
-  });
-}