homegraph 1.2.0 → 1.5.0

package/dist/bin/homegraph.js

@@ -60,8 +60,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
-const directory_1 = require("../directory");
 const utils_1 = require("../spec/utils");
+const config_1 = require("../spec/config");
+const directory_1 = require("../directory");
 const worktree_1 = require("../sync/worktree");
 const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
@@ -426,9 +427,9 @@ function main() {
         if (arktsDegraded.length > 0) {
             clack.log.warn('ArkTS index quality notice — see details below.');
             clack.note(`${arktsDegraded[0].message}\n\n` +
-                'Large ArkTS repos on Windows use an isolated indexer with enableMethodBodyBuild=true.\n' +
-                'If indexing failed, set HOMEGRAPH_ARKTS_STACK_SIZES_KB=65536,131072,262144 and retry:\n' +
-                '  node --stack-size=65536 dist/bin/homegraph.js index <path>', 'ArkTS quality notice');
+                'ArkTS Scene builds run in-process by default (fastest). If the indexer\n' +
+                'exits with a Windows stack overflow on a huge repo, opt into the isolated\n' +
+                'worker: HOMEGRAPH_ARKTS_ISOLATED=1 (optional HOMEGRAPH_ARKTS_STACK_SIZES_KB).', 'ArkTS quality notice');
         }
     }
     /**
@@ -793,6 +794,7 @@ function main() {
             const journalMode = cg.getJournalMode();
             const buildInfo = cg.getIndexBuildInfo();
             const reindexRecommended = cg.isIndexStale();
+            const indexState = cg.getIndexState();
             const ohosApi = cg.getOhosApiBinding();
             // JSON output mode
             if (options.json) {
@@ -823,6 +825,7 @@ function main() {
                         ? { version: ohosApi.version, packageName: ohosApi.packageName, dbPath: ohosApi.dbPath }
                         : null,
                     index: {
+                        state: indexState,
                         builtWithVersion: buildInfo.version,
                         builtWithExtractionVersion: buildInfo.extractionVersion,
                         currentExtractionVersion: extraction_version_1.EXTRACTION_VERSION,
@@ -845,14 +848,11 @@ function main() {
             console.log(`  Nodes:     ${formatNumber(stats.nodeCount)}`);
             console.log(`  Edges:     ${formatNumber(stats.edgeCount)}`);
             console.log(`  DB Size:   ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
-            // Surface the active SQLite backend (node:sqlite — Node's built-in real
-            // SQLite, full WAL + FTS5, no native build).
-            const backendLabel = chalk.green(`node:sqlite ${(0, glyphs_1.getGlyphs)().dash} built-in (full WAL)`);
+            // Prefer node:sqlite → better-sqlite3; wasm is last-resort (no WAL).
+            const backendLabel = backend === 'node-sqlite' ? chalk.green('node-sqlite')
+                : backend === 'native' ? chalk.green('native (better-sqlite3)')
+                    : chalk.yellow(`wasm ${(0, glyphs_1.getGlyphs)().dash} slower fallback; use Node 22.5+ or \`npm rebuild better-sqlite3\``);
             console.log(`  Backend:   ${backendLabel}`);
-            // Effective journal mode: 'wal' means concurrent reads never block on a
-            // writer; anything else means they can ("database is locked"). node:sqlite
-            // supports WAL everywhere, so a non-wal mode means the filesystem can't
-            // (network mounts, WSL2 /mnt). See issue #238.
             const journalLabel = journalMode === 'wal'
                 ? chalk.green('wal')
                 : chalk.yellow(`${journalMode || 'unknown'} ${(0, glyphs_1.getGlyphs)().dash} WAL inactive; reads can block on writes`);
@@ -2006,27 +2006,27 @@ function main() {
     // =============================================================================
     const specCommand = program
         .command('spec')
-        .description('Manage spec knowledge graph (reverse-mining, search, self-evolve)');
+        .description('Manage spec knowledge graph (build, mine, search, self-evolve)');
     /**
-     * homegraph spec mine
+     * homegraph spec build
      */
     specCommand
-        .command('mine')
-        .description('Reverse-mine spec knowledge from Git history')
+        .command('build')
+        .description('Build spec knowledge graph from scanned Git history')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--spec-storage-path <path>', 'Path to the .spec directory')
-        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('--spec-dir <path>', 'Path to the .spec directory')
         .option('-v, --verbose', 'Show detailed output')
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         try {
             const repoPath = path.resolve(options.path || process.cwd());
-            const specStoragePath = options.specStoragePath ?? path.join(repoPath, '.spec');
+            const specStoragePath = path.resolve(repoPath, options.specDir || '.spec');
             const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
-            const { runMiningPipeline } = await Promise.resolve().then(() => __importStar(require('../spec/mining/pipeline')));
-            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            const { runBuildPipeline } = await Promise.resolve().then(() => __importStar(require('../spec/build/pipeline')));
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/git')));
             const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const { createBuildProgressHandler } = await Promise.resolve().then(() => __importStar(require('../spec/ui')));
+            const dbPath = resolveDbPath(repoPath);
             if (!isGitRepo(repoPath)) {
                 error(`Not a git repository: ${repoPath}`);
                 process.exit(1);
@@ -2036,8 +2036,25 @@ function main() {
                 info(`Spec storage: ${specStoragePath}`);
                 info(`Database: ${dbPath}`);
             }
+            // Progress reporting (mirrors `spec mine`):
+            // - JSON mode: no progress output (only final JSON).
+            // - Verbose mode: plain-text lines with timestamps.
+            // - TTY (default): ANSI progress bar with phase + item details.
+            // - Pipe / non-TTY: fall back to verbose (5 % stepping).
+            const onProgress = options.json
+                ? undefined
+                : createBuildProgressHandler(options.verbose ? 'verbose' : process.stdout.isTTY ? 'bar' : 'verbose');
             const { db } = createDatabase(dbPath);
-            const result = runMiningPipeline(repoPath, specStoragePath, db);
+            const result = runBuildPipeline(repoPath, specStoragePath, db, onProgress);
+            if (result.upToDate) {
+                if (options.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    info('Spec knowledge graph is up to date — nothing to build.');
+                }
+                return;
+            }
             if (options.json) {
                 console.log(JSON.stringify(result, null, 2));
             }
@@ -2060,6 +2077,168 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * homegraph spec mine
+     *
+     * Mine design specs from Git history using AST analysis and LLM
+     */
+    specCommand
+        .command('mine')
+        .description('Mine design specs from Git history using AST analysis and LLM')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--limit <number>', 'Maximum commits to scan', '100')
+        .option('--output <path>', 'Output directory for generated specs', '.spec')
+        .option('--threshold <number>', 'Clustering similarity threshold (0-1)', '0.25')
+        .option('--max-cluster <number>', 'Maximum number of clusters', '10')
+        .option('--template <path>', 'Path to a spec template markdown file')
+        .option('--skip-llm', 'Skip LLM generation — only output clusters')
+        .option('-v, --verbose', 'Show detailed output')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const repoPath = path.resolve(options.path || process.cwd());
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/git')));
+            const { loadSpecConfig } = await Promise.resolve().then(() => __importStar(require('../spec/config')));
+            const { runMinePipeline } = await Promise.resolve().then(() => __importStar(require('../spec/mine/pipeline')));
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { createMineProgressHandler } = await Promise.resolve().then(() => __importStar(require('../spec/ui')));
+            if (!isGitRepo(repoPath)) {
+                error(`Not a git repository: ${repoPath}`);
+                process.exit(1);
+            }
+            // Parse numeric options
+            const limit = parseInt(options.limit || '100', 10);
+            if (isNaN(limit) || limit < 1 || limit > 1000) {
+                error('--limit must be an integer between 1 and 1000');
+                process.exit(1);
+            }
+            const threshold = parseFloat(options.threshold || '0.25');
+            if (isNaN(threshold) || threshold < 0 || threshold > 1) {
+                error('--threshold must be a number between 0 and 1');
+                process.exit(1);
+            }
+            const maxCluster = parseInt(options.maxCluster || '10', 10);
+            if (isNaN(maxCluster) || maxCluster < 1 || maxCluster > 50) {
+                error('--max-cluster must be an integer between 1 and 50');
+                process.exit(1);
+            }
+            // Resolve output directory: if meta.json exists, reuse its specStoragePath;
+            // otherwise fall back to --output option, then default '.spec'.
+            // All paths are resolved relative to repoPath so that relative values
+            // (e.g. '.spec', or a relative specStoragePath from meta.json) are
+            // anchored correctly regardless of cwd; absolute paths pass through unchanged.
+            const existingMeta = (0, utils_1.readMeta)(repoPath);
+            const outputDir = existingMeta
+                ? path.resolve(repoPath, existingMeta.specStoragePath)
+                : path.resolve(repoPath, options.output || '.spec');
+            // Load spec config for LLM setup
+            const specConfig = loadSpecConfig(repoPath);
+            const llmConfig = specConfig.llm;
+            const { resolveAgent } = await Promise.resolve().then(() => __importStar(require('../spec/llm/agents')));
+            const codingAgent = options.skipLlm ? null : resolveAgent();
+            if (!options.skipLlm && !llmConfig && !codingAgent) {
+                info('No coding agent (Claude Code / Codex / DevEco Code) detected and no LLM configuration found.\n' +
+                    'Set up "llm" in .homegraph/commit4spec/configs.json.\n' +
+                    '\n' +
+                    'All available options (fields marked * are required):\n' +
+                    '{\n' +
+                    '  "llm": {\n' +
+                    '    "provider":     "openai",          // * "openai" or "anthropic"\n' +
+                    '    "apiKey":       "sk-...",          // * API key string (plain text)\n' +
+                    '    "apiKeyEnv":   "OPENAI_API_KEY",   //   or read from env var (takes precedence)\n' +
+                    '    "model":        "gpt-4o",          // * model name (e.g. gpt-4o, claude-3-5-sonnet)\n' +
+                    '    "baseUrl":      "https://...",     //   custom endpoint (proxies / local models)\n' +
+                    '    "temperature":  0.2,               //   creativity control (default: 0.2)\n' +
+                    '    "maxTokens":    20000              //   max output tokens (default: 20000)\n' +
+                    '  }\n' +
+                    '}\n' +
+                    '\n' +
+                    'Continuing with --skip-llm (clustering only).');
+            }
+            else if (!options.skipLlm && !llmConfig && codingAgent) {
+                info(`Using ${codingAgent.displayName} (headless) for spec generation — no LLM configuration needed.`);
+            }
+            else if (!options.skipLlm && llmConfig && codingAgent) {
+                info(`Using ${codingAgent.displayName} (headless) for spec generation — configured LLM is kept as fallback.`);
+            }
+            const mineConfig = (0, config_1.createMineConfig)({
+                limit,
+                threshold,
+                maxCluster,
+                outputDir,
+                template: options.template,
+                skipLlm: !!options.skipLlm,
+            }, !!llmConfig || codingAgent !== null);
+            if (options.verbose) {
+                info(`Repository: ${repoPath}`);
+                info(`Limit: ${limit === 100 ? '100 (default)' : limit}`);
+                info(`Threshold: ${threshold}`);
+                info(`Max clusters: ${maxCluster}`);
+                info(`Output: ${outputDir}`);
+                info(`Skip LLM: ${mineConfig.skipLlm}`);
+                if (options.template) {
+                    info(`Template: ${options.template}`);
+                }
+            }
+            // Open knowledge graph database for persistence
+            let db;
+            try {
+                const dbPath = resolveDbPath(repoPath);
+                const created = createDatabase(dbPath);
+                db = created.db;
+            }
+            catch (err) {
+                // Non-fatal — spec generation and file output still work without DB
+                if (options.verbose) {
+                    warn(`Failed to open commit4spec.db: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Wire up progress reporting.
+            // - JSON mode: no progress output (only final JSON).
+            // - Verbose mode: plain-text lines with timestamps.
+            // - TTY (default): ANSI progress bar with phase + item details.
+            // - Pipe / non-TTY: fall back to verbose (5 % stepping).
+            let onProgress;
+            if (!options.json) {
+                onProgress = createMineProgressHandler(options.verbose ? 'verbose' : process.stdout.isTTY ? 'bar' : 'verbose');
+            }
+            let result;
+            try {
+                result = await runMinePipeline(repoPath, mineConfig, llmConfig, db, onProgress);
+            }
+            finally {
+                // Close database even if pipeline throws
+                try {
+                    db?.close();
+                }
+                catch { /* best effort */ }
+            }
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                success(`Scanned ${result.commitsScanned} commits, ` +
+                    `${result.changesFound} with structural changes, ` +
+                    `${result.clusters} clusters found.`);
+                if (result.specsGenerated > 0) {
+                    success(`${result.specsGenerated} specs generated in ${outputDir}/`);
+                }
+                if (result.specsWritten > 0) {
+                    info(`${result.specsWritten} spec(s), ${result.commitsWritten} commit(s), ${result.fragmentsWritten} fragment(s) written to commit4spec.db`);
+                }
+                if (result.errors.length > 0) {
+                    for (const err of result.errors) {
+                        warn(err);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            error(`Reverse pipeline failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * homegraph spec match <text>
      */
@@ -2067,7 +2246,6 @@ function main() {
         .command('match <text>')
         .description('Search the spec knowledge graph for a term or phrase')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--db-path <path>', 'Path to the SQLite database file')
         .option('--top-k <number>', 'Number of results to return', '5')
         .option('--no-fragments', 'Exclude code fragments from results')
         .option('-j, --json', 'Output as JSON')
@@ -2078,9 +2256,9 @@ function main() {
             const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
             const { resolveDbPath, computeBudgetProfile } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
             const { searchAndGetContext } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const dbPath = resolveDbPath(repoPath);
             if (!fs.existsSync(dbPath)) {
-                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                error(`Database not found at ${dbPath}. Run 'homegraph spec build/mine' first.`);
                 process.exit(1);
             }
             const created = createDatabase(dbPath);
@@ -2152,7 +2330,6 @@ function main() {
         .command('find <filePath>')
         .description('Find specs related to the given file path via code-fragment matching')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--db-path <path>', 'Path to the SQLite database file')
         .option('-j, --json', 'Output as JSON')
         .action(async (filePath, options) => {
         let db;
@@ -2161,9 +2338,9 @@ function main() {
             const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
             const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
             const { findSpecsByFilePath } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const dbPath = resolveDbPath(repoPath);
             if (!fs.existsSync(dbPath)) {
-                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                error(`Database not found at ${dbPath}. Run 'homegraph spec build/mine' first.`);
                 process.exit(1);
             }
             const created = createDatabase(dbPath);
@@ -2212,7 +2389,6 @@ function main() {
         .option('-f, --file <path>', 'File path for symbol disambiguation')
         .option('-l, --line <number>', 'Line number for symbol disambiguation')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--db-path <path>', 'Path to the SQLite database file')
         .option('--top-k <number>', 'Number of results to return', '10')
         .option('-j, --json', 'Output as JSON')
         .action(async (symbol, options) => {
@@ -2302,9 +2478,9 @@ function main() {
             const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
             const { findSpecsByCodeSymbol } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
             const { initSpecSchema, runSpecMigrations, getCurrentSpecVersion, CURRENT_SPEC_SCHEMA_VERSION } = await Promise.resolve().then(() => __importStar(require('../spec/db/schema')));
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const dbPath = resolveDbPath(repoPath);
             if (!fs.existsSync(dbPath)) {
-                console.log(chalk.yellow(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`));
+                console.log(chalk.yellow(`Database not found at ${dbPath}. Run 'homegraph spec build/mine' first.`));
                 return;
             }
             const created = createDatabase(dbPath);
@@ -2392,7 +2568,6 @@ function main() {
         .command('stats')
         .description('Show statistics about the spec knowledge graph')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--db-path <path>', 'Path to the SQLite database file')
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         let db;
@@ -2401,9 +2576,9 @@ function main() {
             const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
             const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
             const { getSpecStats } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const dbPath = resolveDbPath(repoPath);
             if (!fs.existsSync(dbPath)) {
-                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                error(`Database not found at ${dbPath}. Run 'homegraph spec build/mine' first.`);
                 process.exit(1);
             }
             const created = createDatabase(dbPath);
@@ -2422,7 +2597,7 @@ function main() {
                 console.log(`  Relations:   ${stats.relationCount}`);
                 console.log();
                 if (stats.specCount === 0) {
-                    info("No specs yet. Run 'homegraph spec mine' to build the knowledge graph.");
+                    info("No specs yet. Run 'homegraph spec build/mine' to build the knowledge graph.");
                 }
             }
         }
@@ -2451,10 +2626,19 @@ function main() {
         .description('Install a git post-commit hook that triggers spec evolution')
         .option('-p, --path <path>', 'Path to the repository')
         .option('-f, --force', 'Overwrite existing hook without prompting')
+        .option('-t, --commit-threshold <n>', 'Number of pending commits to accumulate before triggering evolve', (v) => {
+        const n = parseInt(v, 10);
+        if (isNaN(n) || n < 1) {
+            error('--commit-threshold must be a positive integer');
+            process.exit(1);
+        }
+        return n;
+    }, 3)
         .action(async (options) => {
         try {
             const repoPath = resolveSpecProjectPath(options.path);
-            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            const commitThreshold = options.commitThreshold ?? 3;
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/git')));
             if (!isGitRepo(repoPath)) {
                 error(`Not a git repository: ${repoPath}`);
                 process.exit(1);
@@ -2507,14 +2691,47 @@ function main() {
             const MARKER_END = '# <<< homegraph spec evolve hook <<<';
             const hookBlock = [
                 MARKER_BEGIN,
-                '# Triggers spec self-evolution after each commit. Runs in background.',
+                '# Triggers spec self-evolution after N commits have accumulated.',
+                '# Default threshold: 3 commits (configurable via --commit-threshold).',
                 '# Installed by: homegraph spec evolve install',
                 `# Logs: ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log`,
+                '',
+                `THRESHOLD=${commitThreshold}`,
+                `LOGS_DIR="${utils_1.SPEC_DATA_DIR}/logs"`,
+                `META_FILE="${utils_1.SPEC_DATA_DIR}/meta.json"`,
+                '',
+                '# Ensure logs directory exists',
+                'mkdir -p "$LOGS_DIR"',
+                '',
+                '# Read currentCommitID from meta.json',
+                'if [ -f "$META_FILE" ]; then',
+                '  CURRENT=$(sed -n \'s/.*"currentCommitID"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p\' "$META_FILE")',
+                'else',
+                '  echo "[$(date -Iseconds)] meta.json not found — run \'homegraph spec build\' or \'homegraph spec mine\' first" \\',
+                '      >> "$LOGS_DIR"/evolve-hook.log',
+                '  exit 0',
+                'fi',
+                '',
+                '# Count pending commits since last evolved commit',
+                'if [ -z "$CURRENT" ] || ! git rev-parse --quiet --verify "$CURRENT^{commit}" >/dev/null 2>&1; then',
+                '  # First run or anchor commit no longer exists — trigger immediately',
+                '  PENDING=$THRESHOLD',
+                'else',
+                '  PENDING=$(git rev-list --count "${CURRENT}..HEAD" 2>/dev/null || echo 0)',
+                'fi',
+                '',
+                'if [ "$PENDING" -lt "$THRESHOLD" ]; then',
+                '  echo "[$(date -Iseconds)] Pending: $PENDING/$THRESHOLD — skipping" \\',
+                '      >> "$LOGS_DIR"/evolve-hook.log',
+                '  exit 0',
+                'fi',
+                '',
+                '# Threshold reached — trigger evolution (async, non-blocking)',
                 '# Runtime guard: skip if homegraph is not available',
                 `HOMEGRAPH_BIN="${homegraphBin}"`,
                 'if [ -x "$HOMEGRAPH_BIN" ] || command -v homegraph >/dev/null 2>&1; then',
                 '  "${HOMEGRAPH_BIN:-homegraph}" spec evolve process --path "$(pwd)" --json \\',
-                `      >> ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log 2>&1 &`,
+                `      >> "$LOGS_DIR"/evolve-hook.log 2>&1 &`,
                 'fi',
                 MARKER_END,
             ].join('\n');
@@ -2549,6 +2766,7 @@ function main() {
             fs.writeFileSync(hookPath, content);
             fs.chmodSync(hookPath, 0o755);
             success(`Post-commit hook installed at ${hookPath}`);
+            info(`Threshold: ${commitThreshold} commit(s) — evolution triggers when pending commits reach this count`);
             info(`Logs written to ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log`);
         }
         catch (err) {
@@ -2566,7 +2784,7 @@ function main() {
         .action(async (options) => {
         try {
             const repoPath = resolveSpecProjectPath(options.path);
-            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/git')));
             if (!isGitRepo(repoPath)) {
                 error(`Not a git repository: ${repoPath}`);
                 process.exit(1);
@@ -2634,7 +2852,6 @@ function main() {
         .command('process')
         .description('Process commits through the spec self-evolve pipeline since last evolve')
         .option('-p, --path <path>', 'Path to the repository')
-        .option('--db-path <path>', 'Path to the SQLite database file')
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         let db;
@@ -2644,50 +2861,61 @@ function main() {
             const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
             const { initSpecSchema } = await Promise.resolve().then(() => __importStar(require('../spec/db/schema')));
             const { loadSpecConfig } = await Promise.resolve().then(() => __importStar(require('../spec/config')));
-            const { runBatchEvolvePipeline } = await Promise.resolve().then(() => __importStar(require('../spec/evolve/pipeline')));
-            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            const { runEvolvePipeline } = await Promise.resolve().then(() => __importStar(require('../spec/evolve/pipeline')));
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/git')));
             if (!isGitRepo(repoPath)) {
                 error(`Not a git repository: ${repoPath}`);
                 process.exit(1);
             }
-            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const dbPath = resolveDbPath(repoPath);
             const created = createDatabase(dbPath);
             db = created.db;
             initSpecSchema(db);
             const config = loadSpecConfig(repoPath);
-            const llmConfig = config.llm;
-            if (!llmConfig) {
-                warn('LLM not configured — Path B (LLM-based spec evolution) will be skipped.');
-                warn('Only Path A (commit message scope → GENERATE) will be processed.');
+            const { resolveAgent } = await Promise.resolve().then(() => __importStar(require('../spec/llm/agents')));
+            const codingAgent = resolveAgent();
+            if (!config.llm && !codingAgent) {
+                warn('No coding agent (Claude Code / Codex / DevEco Code) detected and LLM not configured — phase 3 (LLM-based spec evolution) will be skipped.');
+                warn('Phase 1 (commit-spec graph construction) will still run.');
                 warn('Configure LLM in .homegraph/commit4spec/configs.json for full functionality:\n' +
                     '{\n' +
                     '  "llm": {\n' +
-                    '    "provider": "openai",\n' +
-                    '    "apiKeyEnv": "OPENAI_API_KEY",\n' +
-                    '    "model": "gpt-4o"\n' +
+                    '    "provider":     "openai",          // * "openai" or "anthropic"\n' +
+                    '    "apiKey":       "sk-...",          // * API key string (plain text)\n' +
+                    '    "apiKeyEnv":   "OPENAI_API_KEY",   //   or read from env var (takes precedence)\n' +
+                    '    "model":        "gpt-4o",          // * model name\n' +
+                    '    "baseUrl":      "https://...",     //   custom endpoint\n' +
+                    '    "temperature":  0.2,               //   creativity control (default: 0.2)\n' +
+                    '    "maxTokens":    20000              //   max output tokens (default: 20000)\n' +
                     '  }\n' +
                     '}');
             }
-            const result = await runBatchEvolvePipeline(repoPath, db, llmConfig ?? undefined);
+            else if (!config.llm && codingAgent) {
+                info(`Using ${codingAgent.displayName} (headless) for phase 3 spec evolution — no LLM configuration needed.`);
+            }
+            else if (config.llm && codingAgent) {
+                info(`Using ${codingAgent.displayName} (headless) for phase 3 spec evolution — configured LLM is kept as fallback.`);
+            }
+            const result = await runEvolvePipeline(repoPath, db, config);
             if (options.json) {
                 console.log(JSON.stringify(result, null, 2));
             }
             else {
-                if (result.commitsProcessed === 0) {
+                if (result.commitsScanned === 0) {
                     console.log(chalk.green('No new commits to evolve.'));
                     console.log(`Last evolved commit: ${result.fromCommit ? result.fromCommit.slice(0, 7) : 'none'}`);
                     console.log(`Current HEAD: ${result.toCommit.slice(0, 7)}`);
                 }
                 else {
-                    console.log(chalk.bold(`Evolve complete: ${result.commitsProcessed} commit(s) processed`));
-                    console.log(`Range: ${result.fromCommit ? result.fromCommit.slice(0, 7) : 'none'} → ${result.toCommit.slice(0, 7)}`);
+                    console.log(chalk.bold(`Evolve complete: ${result.commitsScanned} commit(s) processed`));
+                    console.log(`Evolved to: ${result.toCommit.slice(0, 7)}`);
                     if (result.metaUpdated) {
                         console.log(chalk.green(`meta.json updated (currentCommitID = ${result.toCommit.slice(0, 7)})`));
                     }
-                    else if (result.failures > 0) {
-                        console.log(chalk.yellow(`⚠ meta.json NOT updated — ${result.failures} commit(s) failed`));
+                    else if (result.phaseOneFailures > 0) {
+                        console.log(chalk.yellow(`⚠ meta.json NOT updated — ${result.phaseOneFailures} commit(s) failed`));
                     }
-                    else if (result.skippedCommits > 0) {
+                    else if (result.phaseOneSkipped > 0) {
                         console.log(chalk.yellow('⚠ meta.json NOT updated — all commits were skipped (no Path A match, no LLM)'));
                     }
                     else {
@@ -2696,34 +2924,31 @@ function main() {
                     // Show per-commit summary
                     for (const r of result.perCommitResults) {
                         let prefix;
-                        if (r.skipped) {
+                        if (r.phaseOneSkipped) {
                             prefix = chalk.yellow('  ⚠');
                         }
                         else {
-                            prefix = r.persisted ? chalk.green('  ✓') : chalk.red('  ✗');
+                            prefix = r.matched ? chalk.green('  ✓') : chalk.red('  ✗');
                         }
                         console.log(`${prefix} ${r.commitHash.slice(0, 7)}`);
-                        if (r.skipped) {
-                            console.log(`    skipped: ${r.skipReason}`);
-                        }
-                        if (r.isLogicChange) {
-                            console.log(`    logic change: ${r.logicCheckReason}`);
+                        if (r.phaseOneSkipped) {
+                            console.log(`    skipped: ${r.phaseOneSkipReason}`);
                         }
-                        if (r.generateSpecId) {
-                            console.log(`    Path A - GENERATE ${r.generateSpecId}`);
+                        if (r.matchedSpecId) {
+                            console.log(`    Path A - GENERATE ${r.matchedSpecId}`);
                         }
                         for (const ev of r.evolvedSpecs) {
                             console.log(`    ${ev.specId}: ${ev.action}`);
                         }
                     }
                     // Aggregate summary
-                    const totalFragments = result.perCommitResults.reduce((s, r) => s + r.fragmentsCount, 0);
+                    const totalFragments = result.perCommitResults.reduce((s, r) => s + r.fragmentsInserted, 0);
                     const totalRelations = result.perCommitResults.reduce((s, r) => s + r.relationsCreated, 0);
-                    if (result.skippedCommits > 0) {
-                        console.log(chalk.yellow(`${result.skippedCommits} commit(s) skipped — no LLM configured, did not match Path A`));
+                    if (result.phaseOneSkipped > 0) {
+                        console.log(chalk.yellow(`${result.phaseOneSkipped} commit(s) skipped — no LLM configured, did not match Path A`));
                     }
-                    if (result.failures > 0) {
-                        console.log(chalk.red(`${result.failures} commit(s) failed — see details above`));
+                    if (result.phaseOneFailures > 0) {
+                        console.log(chalk.red(`${result.phaseOneFailures} commit(s) failed — see details above`));
                     }
                     console.log(`Summary: fragments=${totalFragments}, relations=${totalRelations}`);
                 }
@@ -2732,7 +2957,7 @@ function main() {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             if (message.includes('No meta.json found')) {
-                error("No meta.json found. Run 'homegraph spec mine' first.");
+                error("No meta.json found. Run 'homegraph spec build/mine' first.");
             }
             else {
                 error(`Evolve failed: ${message}`);
@@ -2867,6 +3092,7 @@ function main() {
             method,
             resolveLatest: () => up.resolveLatestVersion(),
             run: up.defaultRun,
+            capture: up.defaultCapture,
             hasCommand: up.hasCommand,
             log: (m) => console.log(m),
             warn: (m) => warn(m),