homegraph 1.2.0 → 1.5.0

package/dist/spec/evolve/pipeline.js

@@ -33,535 +33,514 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runBatchEvolvePipeline = runBatchEvolvePipeline;
+exports.runEvolvePipeline = runEvolvePipeline;
 /**
- * Self-evolve pipeline orchestrator — evaluates new commits against existing
- * specs and rewrites / deprecates them as needed.
+ * Batch spec evolve pipeline — replaces the old per-commit approach with
+ * a unified batch pipeline optimised for the post-commit hook's cumulative
+ * commit threshold trigger.
  *
- * Replaces `commit4spec/self_evolve/pipeline.py` (lines 79-289).
+ * Flow:
+ *   0. Prep (meta, lock, schema, discover specs)
+ *   1a. Batch analysis (scope + metadata + diff, no DB writes)
+ *   1b. Per-commit persistence (independent transactions)
+ *   2. Impact location (find old specs affected by new commits)
+ *   3. LLM evaluation per spec cluster (only if LLM configured)
+ *   ↓ or: mine-style fallback (if phase 1 produced zero matches)
+ *   4. Advance meta.json to last phase-1 success
  *
  * @module spec/evolve/pipeline
  */
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
-const child_process_1 = require("child_process");
 const config_1 = require("../config");
 const utils_1 = require("../utils");
 const schema_1 = require("../db/schema");
 const spec_node_1 = require("../db/spec-node");
-const commit_node_1 = require("../db/commit-node");
-const fragment_node_1 = require("../db/fragment-node");
-const relations_1 = require("../db/relations");
-const git_scanner_1 = require("../mining/git-scanner");
-const scope_resolver_1 = require("../mining/scope-resolver");
-const spec_extractor_1 = require("../mining/spec-extractor");
-const diff_parser_1 = require("../mining/diff-parser");
-const client_1 = require("../llm/client");
-const logic_checker_1 = require("./logic-checker");
+const git_1 = require("../git");
+const factory_1 = require("../llm/factory");
+const commit_spec_analyzer_1 = require("./commit-spec-analyzer");
+const commit_spec_persister_1 = require("./commit-spec-persister");
 const impact_locator_1 = require("./impact-locator");
+const cluster_context_1 = require("./cluster-context");
 const spec_rewriter_1 = require("./spec-rewriter");
+const pipeline_1 = require("../mine/pipeline");
 const errors_1 = require("../../errors");
+const utils_2 = require("../utils");
+// =============================================================================
+// Constants
+// =============================================================================
+const LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 // =============================================================================
 // Helpers
 // =============================================================================
-/**
- * Look up a spec from the DB and return its version and filePath.
- * Falls back to constructing a plan.md path when the spec is not found.
- */
-function getSpecPathInfo(db, specStoragePath, specId) {
-    const node = (0, spec_node_1.findSpecById)(db, specId);
-    if (node) {
-        return { version: node.version, filePath: node.filePath };
+/** Resolve HEAD hash (throws when it cannot be resolved). */
+function resolveHead(repoPath) {
+    const head = (0, git_1.getHeadHash)(repoPath);
+    if (!head) {
+        throw new Error('Failed to resolve HEAD. Not a valid git repository?');
     }
-    return { version: 0, filePath: path.join(specStoragePath, specId, 'plan.md') };
+    return head;
 }
-// =============================================================================
-// runEvolvePipeline  (internal — only called by runBatchEvolvePipeline)
-// =============================================================================
-/**
- * Run the full self-evolve pipeline for a single commit.
- *
- * **Internal.**  Not exported — the public entry point is
- * {@link runBatchEvolvePipeline}, which reads meta.json, initialises the
- * schema, and calls this function for each commit in the range.
- *
- * Flow (ported from pipeline.py:79-289):
- *
- * 1. Load context (commit info, diff, LLM client, config).
- * 2. **Path A (GENERATE):** resolve scope from commit message.
- * 3. **LLM logic check:** determine if the commit is a business-logic change.
- * 4. **Path B (impact + rewrite):** if logic change, find affected active
- *    specs and evaluate each one.
- * 5. If neither Path A nor Path B produced candidates, return early.
- * 6. Persist everything in a single DB transaction.
- *
- * @param repoPath        - Absolute path to the git repository.
- * @param db              - Active SQLite database handle (schema already initialised).
- * @param specStoragePath - Path to the spec storage directory (from meta.json).
- * @param commitHash      - Commit hash to process.
- * @param llmConfig       - Optional LLM config override; falls back to spec config.
- */
-async function runEvolvePipeline(repoPath, db, specStoragePath, commitHash, llmConfig) {
-    // ------------------------------------------------------------------
-    // 1. Context loading
-    // ------------------------------------------------------------------
-    // meta.json and schema already handled by runBatchEvolvePipeline
-    // Resolve commit hash
-    const resolvedHash = commitHash ||
-        (() => {
-            try {
-                return (0, child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], {
-                    cwd: repoPath,
-                    encoding: 'utf8',
-                    stdio: ['ignore', 'pipe', 'ignore'],
-                    windowsHide: true,
-                }).trim();
+/** Validate that lastEvolved is an ancestor of HEAD (detect rebase). */
+function validateAncestry(repoPath, lastEvolved, headHash) {
+    if (!(0, git_1.isAncestor)(repoPath, lastEvolved, headHash)) {
+        throw new Error(`The last evolved commit (${lastEvolved.slice(0, 7)}) is not an ancestor of ` +
+            `HEAD (${headHash.slice(0, 7)}). This usually happens after a rebase ` +
+            `or force-push. Please re-run 'homegraph spec build' to rebuild the ` +
+            `knowledge graph, then run evolve again.`);
+    }
+}
+/** Acquire a file-based advisory lock. */
+function acquireEvolveLock(lockFile) {
+    try {
+        if (fs.existsSync(lockFile)) {
+            const stat = fs.statSync(lockFile);
+            if (Date.now() - stat.mtimeMs > LOCK_TIMEOUT_MS) {
+                fs.unlinkSync(lockFile);
             }
-            catch {
-                return '';
+            else {
+                return false;
             }
-        })();
-    if (!resolvedHash) {
-        throw new Error('No commits found in repository.');
-    }
-    // Get commit info and diff
-    const commitInfo = (0, git_scanner_1.getCommitInfo)(repoPath, resolvedHash);
-    if (!commitInfo) {
-        throw new Error(`Commit ${resolvedHash} not found in repository.`);
-    }
-    const diff = (0, git_scanner_1.getCommitDiff)(repoPath, resolvedHash);
-    // Parse diff into fragments once — reused for file paths and persistence.
-    const diffFragments = (0, diff_parser_1.analyzeCommitDiff)(repoPath, resolvedHash, diff);
-    // Load spec config and optionally create LLM client.
-    // When LLM is not available we still run Path A (scope-based GENERATE).
-    const specConfig = (0, config_1.loadSpecConfig)(repoPath);
-    const resolvedLLMConfig = llmConfig || specConfig.llm;
-    const client = resolvedLLMConfig
-        ? new client_1.OpenAiLlmClient(resolvedLLMConfig)
-        : undefined;
-    // ------------------------------------------------------------------
-    // 2. Path A (GENERATE) — commit message scope resolution
-    // ------------------------------------------------------------------
-    const pathASpecId = (0, scope_resolver_1.resolveScopeToSpec)(commitInfo.message, specStoragePath, specConfig);
-    let pathASpecMetadata = null;
-    if (pathASpecId) {
-        pathASpecMetadata = (0, spec_extractor_1.extractSpecMetadata)(specStoragePath, pathASpecId, specConfig);
+        }
+        fs.writeFileSync(lockFile, String(process.pid));
+        return true;
     }
-    // ------------------------------------------------------------------
-    // 2.5 Early skip: Path A didn't match and no LLM client is available.
-    //     Non-Path-A commits cannot be processed without LLM for logic
-    //     checking and spec evaluation.
-    // ------------------------------------------------------------------
-    if (!pathASpecId && !client) {
-        (0, errors_1.logWarn)('Skipping commit — no LLM configured and commit does not match Path A', {
-            commitHash: resolvedHash.slice(0, 7),
-        });
-        return {
-            commitHash: resolvedHash,
-            generateRelationCreated: false,
-            isLogicChange: false,
-            logicCheckReason: '',
-            affectedSpecCount: 0,
-            evolvedSpecs: [],
-            fragmentsCount: 0,
-            relationsCreated: 0,
-            persisted: false,
-            skipped: true,
-            skipReason: 'LLM not configured — commit message does not contain a spec scope (Path A)',
-        };
+    catch {
+        return false;
     }
-    // ------------------------------------------------------------------
-    // 3. LLM logic check
-    // ------------------------------------------------------------------
-    let logicResult = { isLogic: false, reason: '' };
-    if (client) {
+}
+/** Build an empty BatchEvolveResult for no-op runs. */
+function emptyBatchResult(fromCommit, toCommit, commitsScanned) {
+    return {
+        fromCommit,
+        toCommit,
+        commitsScanned,
+        phaseOneMatched: 0,
+        phaseOneSkipped: 0,
+        phaseOneFailures: 0,
+        historicalSpecsEvaluated: 0,
+        specsUpdated: 0,
+        specsDeprecated: 0,
+        specsUnchanged: 0,
+        perCommitResults: [],
+        metaUpdated: false,
+        skipped: false,
+        mineFallback: false,
+    };
+}
+function runPhaseOne(repoPath, db, specStoragePath, commits, config) {
+    // ---- Stage 1a: Batch analysis ----
+    const analyses = (0, commit_spec_analyzer_1.analyzeIncrementalCommits)(repoPath, specStoragePath, commits, config);
+    // ---- Stage 1b: Per-commit persistence ----
+    const phaseOneResults = new Map();
+    const phaseOneSpecIds = new Set();
+    const commitFilePaths = new Map();
+    let lastPhaseOneSuccess = null;
+    for (const analysis of analyses) {
+        if (!analysis.matched) {
+            phaseOneResults.set(analysis.commit.hash, {
+                skipped: true,
+                reason: analysis.skipReason ?? 'Scope not matched',
+            });
+            continue;
+        }
         try {
-            logicResult = await (0, logic_checker_1.isLogicChange)(commitInfo.message, diff, client);
+            const result = (0, commit_spec_persister_1.persistCommitSpecGraph)(db, analysis);
+            phaseOneResults.set(analysis.commit.hash, result);
+            phaseOneSpecIds.add(result.specId);
+            commitFilePaths.set(analysis.commit.hash, result.filePaths);
+            lastPhaseOneSuccess = analysis.commit.hash;
         }
         catch {
-            (0, errors_1.logWarn)('LLM logic check failed, treating as non-logic change', {
-                commitHash: resolvedHash.slice(0, 7),
+            // Persistence failed — stop advancing but don't roll back prior commits
+            phaseOneResults.set(analysis.commit.hash, {
+                skipped: true,
+                reason: 'Persistence transaction failed',
             });
-            logicResult = { isLogic: false, reason: 'LLM call failed' };
+            break;
         }
     }
-    // ------------------------------------------------------------------
-    // 4. Path B (impact + rewrite) — only when the commit is a logic change
-    // ------------------------------------------------------------------
-    let pathBSpecIds = [];
-    if (logicResult.isLogic) {
-        // Extract file paths from diff fragments
-        const filePaths = diffFragments.map(f => f.filePath);
-        // Locate affected specs
-        const affectedSpecIds = (0, impact_locator_1.locateAffectedSpecs)(db, filePaths);
-        if (affectedSpecIds.length > 0) {
-            // Filter to active specs only
-            const placeholders = affectedSpecIds.map(() => '?').join(',');
-            const activeRows = db
-                .prepare(`SELECT id FROM spec_nodes WHERE status = 'active' AND id IN (${placeholders})`)
-                .all(...affectedSpecIds);
-            pathBSpecIds = activeRows.map((r) => r.id);
-            // Remove Path A spec from Path B list (if present)
-            if (pathASpecId) {
-                pathBSpecIds = pathBSpecIds.filter((id) => id !== pathASpecId);
-            }
-        }
-        (0, errors_1.logDebug)('Path B: affected active specs', {
-            count: pathBSpecIds.length,
-            specIds: pathBSpecIds,
-        });
+    return { phaseOneResults, phaseOneSpecIds, commitFilePaths, lastPhaseOneSuccess, analyses };
+}
+// =============================================================================
+// processSingleCommit — fallback for first-ever evolve (no meta.json anchor)
+// =============================================================================
+async function processSingleCommit(repoPath, db, specStoragePath, headHash, config) {
+    (0, errors_1.logDebug)('runEvolvePipeline: no currentCommitID in meta.json — processing HEAD only', {
+        headHash: headHash.slice(0, 7),
+    });
+    const info = (0, git_1.getCommitInfo)(repoPath, headHash);
+    if (!info) {
+        throw new Error(`Commit ${headHash.slice(0, 7)} not found.`);
     }
-    // ------------------------------------------------------------------
-    // 5. Decide relevance
-    // ------------------------------------------------------------------
-    const hasPathA = pathASpecId !== null;
-    const hasPathB = pathBSpecIds.length > 0;
-    if (!hasPathA && !hasPathB) {
-        (0, errors_1.logDebug)('runEvolvePipeline: no relevant spec found, returning early', {
-            commitHash: resolvedHash.slice(0, 7),
-        });
-        return {
-            commitHash: resolvedHash,
-            generateRelationCreated: false,
-            isLogicChange: logicResult.isLogic,
-            logicCheckReason: logicResult.reason,
-            affectedSpecCount: 0,
-            evolvedSpecs: [],
-            fragmentsCount: 0,
-            relationsCreated: 0,
-            persisted: false,
-            skipped: false,
-        };
+    const { phaseOneResults, phaseOneSpecIds, commitFilePaths, lastPhaseOneSuccess, analyses } = runPhaseOne(repoPath, db, specStoragePath, [info], config);
+    const metaUpdated = !!(lastPhaseOneSuccess);
+    if (metaUpdated) {
+        (0, utils_1.writeMeta)(repoPath, specStoragePath, lastPhaseOneSuccess);
     }
-    const pendingDecisions = [];
-    for (let idx = 0; idx < pathBSpecIds.length; idx++) {
-        const specId = pathBSpecIds[idx];
-        const scheduleNextSpecs = pathBSpecIds.slice(idx + 1);
-        const { version, filePath } = getSpecPathInfo(db, specStoragePath, specId);
-        const decision = await (0, spec_rewriter_1.evaluateSpec)(specId, specStoragePath, filePath, commitInfo.message, diff, scheduleNextSpecs, client);
-        pendingDecisions.push({ specId, decision, version, filePath });
+    // Phase 2 — only if phase 1 matched something
+    let affectedEntries = [];
+    if (phaseOneSpecIds.size > 0) {
+        affectedEntries = (0, impact_locator_1.locateAffectedSpecsWithCommits)(db, commitFilePaths, phaseOneSpecIds);
     }
-    // ------------------------------------------------------------------
-    // 7. Persist (atomic via explicit BEGIN/COMMIT/ROLLBACK)
-    //    All LLM evaluation is complete; only fast DB writes remain.
-    // ------------------------------------------------------------------
-    const evolveResult = {
-        commitHash: resolvedHash,
-        generateSpecId: pathASpecId ?? undefined,
-        generateRelationCreated: false,
-        isLogicChange: logicResult.isLogic,
-        logicCheckReason: logicResult.reason,
-        affectedSpecCount: pathBSpecIds.length,
-        evolvedSpecs: [],
-        fragmentsCount: 0,
-        relationsCreated: 0,
-        persisted: true,
-        skipped: false,
-    };
-    db.exec('BEGIN');
-    try {
-        // ---- Insert CommitNode ----
-        (0, commit_node_1.insertCommitNode)(db, {
-            hash: commitInfo.hash,
-            message: commitInfo.message,
-            author: commitInfo.author,
-            timestamp: commitInfo.timestamp,
-        });
-        // ---- Path A: Insert SpecNode + GENERATE relation ----
-        if (pathASpecId && pathASpecMetadata) {
-            (0, spec_node_1.insertSpecNode)(db, {
-                id: pathASpecMetadata.specId,
-                title: pathASpecMetadata.title,
-                subtitles: pathASpecMetadata.subtitles,
-                status: 'active',
-                version: 1,
-                filePath: pathASpecMetadata.filePath,
-                timestamp: commitInfo.timestamp,
+    // Phase 3
+    const client = (0, factory_1.createSpecLlmClient)(config.llm);
+    const evolvedSpecsByCommit = await evaluateAndApply(db, repoPath, affectedEntries, phaseOneResults, client);
+    return buildBatchResult({
+        fromCommit: null,
+        toCommit: headHash,
+        commitsScanned: 1,
+        analyses,
+        phaseOneResults,
+        affectedEntries,
+        evolvedSpecs: evolvedSpecsByCommit,
+        metaUpdated,
+        mineFallback: false,
+    });
+}
+// =============================================================================
+// evaluateAndApply — phase 3: evaluate each affected spec + apply decisions
+// =============================================================================
+async function evaluateAndApply(db, repoPath, affectedEntries, phaseOneResults, client) {
+    const evolvedSpecsByCommit = new Map();
+    if (!client || affectedEntries.length === 0) {
+        return evolvedSpecsByCommit;
+    }
+    for (const entry of affectedEntries) {
+        // Get spec info from DB
+        const specNode = (0, spec_node_1.findSpecById)(db, entry.specId);
+        if (!specNode)
+            continue;
+        // Collect affecting PersistResults
+        const affectingResults = entry.affectingCommits
+            .map((h) => phaseOneResults.get(h))
+            .filter((r) => r !== undefined && 'filePaths' in r);
+        if (affectingResults.length === 0)
+            continue;
+        // Build CommitContextInput list
+        const commitInputs = [];
+        for (const pr of affectingResults) {
+            let message = pr.commitHash.slice(0, 7);
+            try {
+                const info = (0, git_1.getCommitInfo)(repoPath, pr.commitHash);
+                if (info)
+                    message = info.message;
+            }
+            catch { /* use short hash */ }
+            commitInputs.push({
+                commitHash: pr.commitHash,
+                message,
+                filePaths: pr.filePaths,
             });
-            (0, relations_1.insertSpecCommitRelation)(db, pathASpecMetadata.specId, commitInfo.hash, 'GENERATE');
-            evolveResult.generateRelationCreated = true;
-            evolveResult.relationsCreated++;
         }
-        else if (pathASpecId) {
-            (0, errors_1.logWarn)('Path A: specId resolved but no metadata extracted, skipping insert', {
-                specId: pathASpecId,
-            });
+        // Build cluster context
+        const clusterCtx = (0, cluster_context_1.buildClusterContext)(commitInputs);
+        // Populate actual diffs into cluster context
+        for (const cs of clusterCtx.commitSummaries) {
+            try {
+                const diff = (0, git_1.getCommitDiff)(repoPath, cs.fullHash);
+                cs.truncatedDiff = (0, utils_2.truncateText)(diff, 16000);
+            }
+            catch {
+                cs.truncatedDiff = '(diff unavailable)';
+            }
         }
-        // ---- Path B: Apply pre-evaluated decisions ----
-        const evolvedSpecs = [];
-        for (const pending of pendingDecisions) {
-            const { specId, decision, version, filePath } = pending;
+        // LLM evaluation (outside transaction)
+        let decision;
+        try {
+            decision = await (0, spec_rewriter_1.evaluateSpecWithCluster)(entry.specId, specNode.filePath, clusterCtx, client);
+        }
+        catch {
+            decision = { action: 'UNCHANGED' };
+        }
+        // The last commit in affectingCommits is the one that triggered this evaluation.
+        const lastAffectingCommit = entry.affectingCommits[entry.affectingCommits.length - 1];
+        // Apply decision (inside transaction)
+        db.exec('BEGIN');
+        try {
             if (decision.action === 'UPDATE') {
-                const updateResult = (0, spec_rewriter_1.applyUpdate)(db, specStoragePath, specId, filePath, version, decision, commitInfo.hash);
-                evolvedSpecs.push({
-                    specId,
-                    action: 'UPDATE',
-                    newVersion: updateResult.newVersion,
-                    newSpecId: updateResult.newSpecId,
-                });
-                evolveResult.relationsCreated += 2; // EVOLVED_FROM + GENERATE
+                const result = (0, spec_rewriter_1.applyUpdate)(db, entry.specId, specNode.filePath, specNode.version, decision, lastAffectingCommit);
+                const evolved = {
+                    specId: entry.specId, action: 'UPDATE',
+                    newVersion: result.newVersion, newSpecId: result.newSpecId,
+                };
+                if (!evolvedSpecsByCommit.has(lastAffectingCommit)) {
+                    evolvedSpecsByCommit.set(lastAffectingCommit, []);
+                }
+                evolvedSpecsByCommit.get(lastAffectingCommit).push(evolved);
             }
             else if (decision.action === 'DEPRECATE') {
-                (0, spec_rewriter_1.applyDeprecate)(db, specId);
-                evolvedSpecs.push({
-                    specId,
-                    action: 'DEPRECATE',
-                });
-                // applyDeprecate creates one EVOLVED_FROM relation
-                evolveResult.relationsCreated += 1;
+                (0, spec_rewriter_1.applyDeprecate)(db, entry.specId);
+                const evolved = { specId: entry.specId, action: 'DEPRECATE' };
+                if (!evolvedSpecsByCommit.has(lastAffectingCommit)) {
+                    evolvedSpecsByCommit.set(lastAffectingCommit, []);
+                }
+                evolvedSpecsByCommit.get(lastAffectingCommit).push(evolved);
             }
             else {
-                // UNCHANGED
-                evolvedSpecs.push({
-                    specId,
-                    action: 'UNCHANGED',
-                });
+                const evolved = { specId: entry.specId, action: 'UNCHANGED' };
+                if (!evolvedSpecsByCommit.has(lastAffectingCommit)) {
+                    evolvedSpecsByCommit.set(lastAffectingCommit, []);
+                }
+                evolvedSpecsByCommit.get(lastAffectingCommit).push(evolved);
             }
+            db.exec('COMMIT');
+        }
+        catch (e) {
+            db.exec('ROLLBACK');
+            (0, errors_1.logWarn)('evaluateAndApply: apply failed', {
+                specId: entry.specId,
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    return evolvedSpecsByCommit;
+}
+// =============================================================================
+// mineStyleFallback
+// =============================================================================
+async function mineStyleFallback(repoPath, db, specStoragePath, newCommits, lastEvolved, headHash, llmConfig) {
+    const client = (0, factory_1.createSpecLlmClient)(llmConfig ?? null);
+    if (!client) {
+        (0, errors_1.logWarn)('Phase 1 produced no spec matches and no LLM is available ' +
+            '(no coding agent detected, no LLM configured). ' +
+            'No evolution can be performed. ' +
+            'Consider running "homegraph spec build/mine" first, ' +
+            'or configure an LLM in .homegraph/commit4spec/configs.json.');
+        return {
+            ...emptyBatchResult(lastEvolved, headHash, newCommits.length),
+            phaseOneSkipped: newCommits.length,
+            skipped: true,
+            skipReason: 'Phase 1 produced no matches and no LLM available (no coding agent detected, no LLM configured)',
+        };
+    }
+    // Invoke mine pipeline for the unmatched commit range
+    (0, errors_1.logWarn)('Phase 1 produced no spec matches. Falling back to mine-style spec generation ' +
+        `for ${newCommits.length} commit(s).`);
+    try {
+        const mineConfig = (0, config_1.createMineConfig)({
+            limit: 200,
+            threshold: 0.25,
+            maxCluster: 10,
+            outputDir: specStoragePath,
+            skipLlm: false,
+        }, true);
+        const mineResult = await (0, pipeline_1.runMinePipeline)(repoPath, mineConfig, llmConfig ?? null, db);
+        // runMinePipeline already writes to meta.json and the same DB
+        (0, errors_1.logDebug)('mineStyleFallback: mine pipeline completed', { ...mineResult });
+        const hadResults = mineResult.specsGenerated > 0 || mineResult.specsWritten > 0;
+        return {
+            ...emptyBatchResult(lastEvolved, headHash, newCommits.length),
+            phaseOneSkipped: newCommits.length,
+            metaUpdated: hadResults,
+            skipped: !hadResults,
+            skipReason: hadResults ? undefined : 'Mine pipeline produced no specs',
+            mineFallback: true,
+        };
+    }
+    catch (err) {
+        (0, errors_1.logWarn)('mineStyleFallback: mine pipeline failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return {
+            ...emptyBatchResult(lastEvolved, headHash, newCommits.length),
+            phaseOneSkipped: newCommits.length,
+            skipped: true,
+            skipReason: `Mine pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
+            mineFallback: true,
+        };
+    }
+}
+// =============================================================================
+// buildBatchResult — assemble the final BatchEvolveResult
+// =============================================================================
+function buildBatchResult(params) {
+    const { fromCommit, toCommit, commitsScanned, analyses, phaseOneResults, affectedEntries, evolvedSpecs, metaUpdated, mineFallback } = params;
+    let phaseOneMatched = 0;
+    let phaseOneSkipped = 0;
+    let phaseOneFailures = 0;
+    const perCommitResults = [];
+    for (const analysis of analyses) {
+        const pr = phaseOneResults.get(analysis.commit.hash);
+        if (!pr) {
+            // Should not happen, but defensive
+            perCommitResults.push({
+                commitHash: analysis.commit.hash,
+                matched: false,
+                phaseOneSkipped: true,
+                phaseOneSkipReason: 'Result not found',
+                evolvedSpecs: [],
+                fragmentsInserted: 0,
+                relationsCreated: 0,
+            });
+            phaseOneSkipped++;
+            continue;
         }
-        evolveResult.evolvedSpecs = evolvedSpecs;
-        // ---- Common: Persist pre-parsed fragments and create CONTAINS relations ----
-        for (const frag of diffFragments) {
-            const inserted = (0, fragment_node_1.insertCodeFragment)(db, {
-                id: '',
-                changeType: frag.changeType,
-                filePath: frag.filePath,
-                startLine: frag.startLine,
-                endLine: frag.endLine,
-                codeDiff: frag.codeDiff,
+        if ('skipped' in pr) {
+            perCommitResults.push({
+                commitHash: analysis.commit.hash,
+                matched: false,
+                phaseOneSkipped: true,
+                phaseOneSkipReason: pr.reason,
+                evolvedSpecs: [],
+                fragmentsInserted: 0,
+                relationsCreated: 0,
+            });
+            analysis.matched ? phaseOneFailures++ : phaseOneSkipped++;
+        }
+        else {
+            perCommitResults.push({
+                commitHash: analysis.commit.hash,
+                matched: true,
+                matchedSpecId: pr.specId,
+                phaseOneSkipped: false,
+                evolvedSpecs: evolvedSpecs.get(analysis.commit.hash) || [],
+                fragmentsInserted: pr.stats.fragmentsInserted,
+                relationsCreated: pr.stats.relationsCreated,
             });
-            evolveResult.fragmentsCount++;
-            (0, relations_1.insertCommitFragmentRelation)(db, commitInfo.hash, inserted.id);
-            evolveResult.relationsCreated++;
+            phaseOneMatched++;
         }
-        db.exec('COMMIT');
     }
-    catch (e) {
-        db.exec('ROLLBACK');
-        throw e;
+    // Count phase 3 results
+    let specsUpdated = 0;
+    let specsDeprecated = 0;
+    let specsUnchanged = 0;
+    for (const [, specs] of evolvedSpecs) {
+        for (const es of specs) {
+            if (es.action === 'UPDATE')
+                specsUpdated++;
+            else if (es.action === 'DEPRECATE')
+                specsDeprecated++;
+            else
+                specsUnchanged++;
+        }
     }
-    return evolveResult;
+    return {
+        fromCommit,
+        toCommit,
+        commitsScanned,
+        phaseOneMatched,
+        phaseOneSkipped,
+        phaseOneFailures,
+        historicalSpecsEvaluated: affectedEntries.length,
+        specsUpdated,
+        specsDeprecated,
+        specsUnchanged,
+        perCommitResults,
+        metaUpdated,
+        skipped: !metaUpdated && !mineFallback && phaseOneMatched === 0,
+        skipReason: !metaUpdated && !mineFallback && phaseOneMatched === 0
+            ? 'All phase-1 persistence failed'
+            : undefined,
+        mineFallback,
+    };
 }
 // =============================================================================
-// runBatchEvolvePipeline
+// Public API — runEvolvePipeline
 // =============================================================================
 /**
- * Run the self-evolve pipeline for all NEW commits since the last evolve.
- *
- * Reads `currentCommitID` from `meta.json` and processes every commit between
- * that hash and `HEAD` in chronological order.  Each commit is independently
- * evolved via `runEvolvePipeline`.  On full success, `meta.json` is refreshed
- * with the new HEAD as `currentCommitID` and `updatedAt` set to now.
+ * Run the spec self-evolve pipeline for all new commits since the last evolve.
  *
- * When `currentCommitID` is missing (first evolve after an older mine, or
- * corrupt meta), the function falls back to processing only HEAD.
+ * This is the ONLY public entry point.  It replaces both the old
+ * ``runEvolvePipeline`` (per-commit) and ``runBatchEvolvePipeline`` (batch
+ * wrapper) with a unified batch pipeline that aligns with the post-commit
+ * hook's cumulative commit threshold trigger.
  *
- * **Partial failure:** If any commit fails, the failing commit is logged but
- * processing continues to the next one. `meta.json` is **only** updated when
- * **all** commits succeed — this preserves the invariant that
- * `currentCommitID` always points to the last *successfully* evolved commit.
+ * Flow:
+ *   0. Prep: meta.json → lock → schema → resolve HEAD + range.
+ *   1a. Batch analysis of all incremental commits (no DB writes).
+ *   1b. Per-commit persistence with independent transactions.
+ *   2. Impact location: find old specs affected by new commits.
+ *   3. LLM evaluation per spec cluster (only if LLM configured).
+ *   ↓ or: mine-style fallback (if phase 1 produced zero matches + LLM).
+ *   4. Advance meta.json to last phase-1 success.
  *
- * Edge cases:
- * - `currentCommitID` equals HEAD → 0 new commits, `metaUpdated: false`.
- * - `currentCommitID` is not an ancestor of HEAD (rebase / force-push) →
- *   throws an error asking the user to re-mine.
- */
-const LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
-/**
- * Acquire a file-based advisory lock to prevent concurrent evolve runs.
- * Returns true if the lock was acquired (or the existing lock is stale).
- * Returns false if another evolve instance holds the lock.
+ * @param repoPath  - Absolute path to the git repository.
+ * @param db        - Active SQLite database handle.
+ * @param config     - Spec configuration (loaded from configs.json); when config.llm is absent, phase 3 is skipped
+ *                     (phase 1 graph construction still runs).
  */
-function acquireEvolveLock(lockFile) {
-    try {
-        if (fs.existsSync(lockFile)) {
-            const stat = fs.statSync(lockFile);
-            if (Date.now() - stat.mtimeMs > LOCK_TIMEOUT_MS) {
-                // Stale lock — previous process may have crashed
-                fs.unlinkSync(lockFile);
-            }
-            else {
-                return false;
-            }
-        }
-        fs.writeFileSync(lockFile, String(process.pid));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function runBatchEvolvePipeline(repoPath, db, llmConfig) {
+async function runEvolvePipeline(repoPath, db, config) {
+    // ---- Stage 0: Preparation ----
     const meta = (0, utils_1.readMeta)(repoPath);
     if (!meta) {
-        throw new Error("No meta.json found. Run 'homegraph spec mine' first.");
+        throw new Error("No meta.json found. Run 'homegraph spec build' first.");
     }
-    // Ensure only one evolve instance runs at a time (post-commit hook may
-    // fire multiple times in quick succession).
+    // File lock
     const lockFile = path.join(repoPath, utils_1.SPEC_DATA_DIR, 'logs', 'evolve.lock');
     fs.mkdirSync(path.dirname(lockFile), { recursive: true });
     if (!acquireEvolveLock(lockFile)) {
-        (0, errors_1.logDebug)('runBatchEvolvePipeline: another evolve instance is running, skipping');
-        return {
-            fromCommit: meta.currentCommitID || null,
-            toCommit: '',
-            commitsProcessed: 0,
-            perCommitResults: [],
-            metaUpdated: false,
-            skippedCommits: 0,
-            failures: 0,
-        };
+        (0, errors_1.logDebug)('runEvolvePipeline: another instance is running, skipping');
+        return emptyBatchResult(meta.currentCommitID || null, '', 0);
     }
     (0, schema_1.initSpecSchema)(db);
     try {
-        return await runBatchEvolvePipelineImpl(repoPath, db, meta, llmConfig);
-    }
-    finally {
-        try {
-            fs.unlinkSync(lockFile);
+        // Resolve HEAD and commit range
+        const headHash = resolveHead(repoPath);
+        const lastEvolved = meta.currentCommitID || null;
+        // No currentCommitID → process HEAD only
+        if (!lastEvolved) {
+            return await processSingleCommit(repoPath, db, meta.specStoragePath, headHash, config);
         }
-        catch { /* may already be deleted */ }
-    }
-}
-/**
- * Inner implementation — split out so the lock clean-up in the outer function
- * only needs one try/finally block.
- */
-async function runBatchEvolvePipelineImpl(repoPath, db, meta, llmConfig) {
-    // Resolve HEAD
-    let headHash;
-    try {
-        headHash = (0, child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], {
-            cwd: repoPath,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            windowsHide: true,
-        }).trim();
-    }
-    catch {
-        throw new Error('Failed to resolve HEAD. Not a valid git repository?');
-    }
-    if (!headHash) {
-        throw new Error('No commits found in repository.');
-    }
-    const lastEvolved = meta.currentCommitID || null;
-    // Fallback: no currentCommitID → process just HEAD
-    if (!lastEvolved) {
-        (0, errors_1.logDebug)('runBatchEvolvePipeline: no currentCommitID in meta.json — processing HEAD only', {
-            headHash: headHash.slice(0, 7),
-        });
-        const result = await runEvolvePipeline(repoPath, db, meta.specStoragePath, headHash, llmConfig);
-        // Only refresh meta.json when the commit was actually processed (not skipped).
-        const metaUpdated = !result.skipped;
-        if (metaUpdated) {
-            (0, utils_1.writeMeta)(repoPath, meta.specStoragePath, headHash);
+        // No new commits
+        if (lastEvolved === headHash) {
+            (0, errors_1.logDebug)('runEvolvePipeline: no new commits to evolve', {
+                currentCommitID: lastEvolved.slice(0, 7),
+            });
+            return emptyBatchResult(lastEvolved, headHash, 0);
         }
-        return {
-            fromCommit: null,
-            toCommit: headHash,
-            commitsProcessed: 1,
-            perCommitResults: [result],
-            metaUpdated,
-            skippedCommits: result.skipped ? 1 : 0,
-            failures: 0,
-        };
-    }
-    // No new commits
-    if (lastEvolved === headHash) {
-        (0, errors_1.logDebug)('runBatchEvolvePipeline: no new commits to evolve', {
-            currentCommitID: lastEvolved.slice(0, 7),
-        });
-        return {
-            fromCommit: lastEvolved,
-            toCommit: headHash,
-            commitsProcessed: 0,
-            perCommitResults: [],
-            metaUpdated: false,
-            skippedCommits: 0,
-            failures: 0,
-        };
-    }
-    // Validate ancestry: lastEvolved must be an ancestor of HEAD
-    try {
-        (0, child_process_1.execFileSync)('git', ['merge-base', '--is-ancestor', lastEvolved, headHash], {
-            cwd: repoPath,
-            stdio: 'ignore',
-            windowsHide: true,
-        });
-    }
-    catch {
-        throw new Error(`The last evolved commit (${lastEvolved.slice(0, 7)}) is not an ancestor of ` +
-            `HEAD (${headHash.slice(0, 7)}). This usually happens after a rebase ` +
-            `or force-push. Please re-run 'homegraph spec mine' to rebuild the ` +
-            `knowledge graph, then run 'homegraph spec evolve' again.`);
-    }
-    // Get commit range in chronological order (oldest first)
-    const commits = (0, git_scanner_1.getCommitRange)(repoPath, lastEvolved, headHash);
-    if (commits.length === 0) {
-        (0, errors_1.logDebug)('runBatchEvolvePipeline: range query returned 0 commits', {
+        // Rebase detection
+        validateAncestry(repoPath, lastEvolved, headHash);
+        // Get commit range in chronological order
+        const newCommits = (0, git_1.getCommitRange)(repoPath, lastEvolved, headHash);
+        if (newCommits.length === 0) {
+            return emptyBatchResult(lastEvolved, headHash, 0);
+        }
+        (0, errors_1.logDebug)('runEvolvePipeline: processing commit range', {
+            count: newCommits.length,
             from: lastEvolved.slice(0, 7),
             to: headHash.slice(0, 7),
         });
-        return {
+        // ---- Stage 1a + 1b: Batch analysis + per-commit persistence ----
+        (0, errors_1.logDebug)('runEvolvePipeline: phase 1 — batch analysis + persistence', {
+            commitCount: newCommits.length,
+        });
+        const { phaseOneResults, phaseOneSpecIds, commitFilePaths, lastPhaseOneSuccess, analyses } = runPhaseOne(repoPath, db, meta.specStoragePath, newCommits, config);
+        // ---- Decision: phase 1 produced matches? ----
+        if (phaseOneSpecIds.size === 0) {
+            return await mineStyleFallback(repoPath, db, meta.specStoragePath, newCommits, lastEvolved, headHash, config.llm ?? undefined);
+        }
+        // ---- Stage 2: Impact location ----
+        const affectedEntries = (0, impact_locator_1.locateAffectedSpecsWithCommits)(db, commitFilePaths, phaseOneSpecIds);
+        (0, errors_1.logDebug)('runEvolvePipeline: phase 2 — impact location', {
+            affectedSpecs: affectedEntries.length,
+        });
+        // ---- Stage 3: LLM evaluation + apply ----
+        const client = (0, factory_1.createSpecLlmClient)(config.llm);
+        const evolvedSpecsByCommit = await evaluateAndApply(db, repoPath, affectedEntries, phaseOneResults, client);
+        // ---- Stage 4: Advance meta.json ----
+        const metaUpdated = lastPhaseOneSuccess !== null;
+        if (metaUpdated) {
+            (0, utils_1.writeMeta)(repoPath, meta.specStoragePath, lastPhaseOneSuccess);
+        }
+        const result = buildBatchResult({
             fromCommit: lastEvolved,
-            toCommit: headHash,
-            commitsProcessed: 0,
-            perCommitResults: [],
-            metaUpdated: false,
-            skippedCommits: 0,
-            failures: 0,
-        };
+            toCommit: lastPhaseOneSuccess || headHash,
+            commitsScanned: newCommits.length,
+            analyses,
+            phaseOneResults,
+            affectedEntries,
+            evolvedSpecs: evolvedSpecsByCommit,
+            metaUpdated,
+            mineFallback: false,
+        });
+        return result;
     }
-    (0, errors_1.logDebug)('runBatchEvolvePipeline: processing commit range', {
-        count: commits.length,
-        from: lastEvolved.slice(0, 7),
-        to: headHash.slice(0, 7),
-    });
-    // Process each commit independently
-    const perCommitResults = [];
-    let failures = 0;
-    let skippedCount = 0;
-    for (const commit of commits) {
+    finally {
         try {
-            const result = await runEvolvePipeline(repoPath, db, meta.specStoragePath, commit.hash, llmConfig);
-            perCommitResults.push(result);
-            if (result.skipped)
-                skippedCount++;
-        }
-        catch (err) {
-            failures++;
-            (0, errors_1.logWarn)('runBatchEvolvePipeline: commit evolve failed, continuing', {
-                commitHash: commit.hash.slice(0, 7),
-                error: err instanceof Error ? err.message : String(err),
-            });
-            perCommitResults.push({
-                commitHash: commit.hash,
-                generateRelationCreated: false,
-                isLogicChange: false,
-                logicCheckReason: `Evolve failed: ${err instanceof Error ? err.message : String(err)}`,
-                affectedSpecCount: 0,
-                evolvedSpecs: [],
-                fragmentsCount: 0,
-                relationsCreated: 0,
-                persisted: false,
-                skipped: false,
-            });
+            fs.unlinkSync(lockFile);
         }
+        catch { /* may already be deleted */ }
     }
-    // Refresh meta.json as long as at least one commit was actually
-    // processed (neither skipped nor failed).
-    const processedCount = commits.length - failures - skippedCount;
-    const metaUpdated = processedCount > 0;
-    if (metaUpdated) {
-        (0, utils_1.writeMeta)(repoPath, meta.specStoragePath, headHash);
-    }
-    return {
-        fromCommit: lastEvolved,
-        toCommit: headHash,
-        commitsProcessed: commits.length,
-        perCommitResults,
-        metaUpdated,
-        skippedCommits: skippedCount,
-        failures,
-    };
 }
 //# sourceMappingURL=pipeline.js.map