homegraph 1.1.2 → 1.2.0

package/dist/spec/graph/queries.js

@@ -0,0 +1,440 @@
+"use strict";
+/**
+ * Graph traversal queries for the Spec→Commit→CodeFragment knowledge graph.
+ *
+ * Replaces `commit4spec/graph/queries.py`. Provides spec context retrieval,
+ * stats, and search+traverse functionality.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSpecContext = getSpecContext;
+exports.findSpecsByFragmentPath = findSpecsByFragmentPath;
+exports.findSpecsByFilePath = findSpecsByFilePath;
+exports.getSpecStats = getSpecStats;
+exports.searchAndGetContext = searchAndGetContext;
+exports.findSpecsByCodeSymbol = findSpecsByCodeSymbol;
+const fts_1 = require("../db/fts");
+// ===========================================================================
+// Private helpers
+// ===========================================================================
+/**
+ * Parse a JSON string into a string array, returning [] on any failure.
+ */
+function _parseSubtitles(raw) {
+    try {
+        return JSON.parse(raw || '[]');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Convert a DB row (snake_case keys) to a SpecNode (camelCase).
+ */
+function _rowToSpecNode(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        subtitles: _parseSubtitles(row.subtitles),
+        status: row.status,
+        version: row.version,
+        filePath: row.file_path,
+        timestamp: row.timestamp,
+    };
+}
+// ===========================================================================
+// Public API
+// ===========================================================================
+/**
+ * Retrieve full context for a Spec — the spec node itself, all linked
+ * commits (with their relation types), and optionally the code fragments
+ * each commit touched.
+ *
+ * Commits are ordered by relation-type priority (GENERATE first, then
+ * SUMMARIZED_FROM, then others) and then by timestamp descending within
+ * each priority tier.
+ *
+ * @param db           Active SQLite database handle.
+ * @param specId       Spec identifier to look up.
+ * @param maxCommits   Maximum number of linked commits to return (default 5).
+ * @param includeFragments  Whether to load code fragments for each commit (default true).
+ * @returns SpecContext on success, or null when the spec is not found.
+ */
+function getSpecContext(db, specId, maxCommits = 5, includeFragments = true) {
+    // 1. Look up the spec by id
+    const specRow = db
+        .prepare(`SELECT id, title, subtitles, status, version, file_path, timestamp
+       FROM spec_nodes
+       WHERE id = ?`)
+        .get(specId);
+    if (!specRow)
+        return null;
+    const spec = _rowToSpecNode(specRow);
+    // 2. Query linked commits with priority ordering
+    const commitRows = db
+        .prepare(`SELECT c.hash, c.message, c.author, c.timestamp, r.relation_type
+       FROM spec_commit_relations r
+       JOIN commit_nodes c ON c.hash = r.commit_hash
+       WHERE r.spec_id = ?
+       ORDER BY
+         CASE r.relation_type
+           WHEN 'GENERATE' THEN 0
+           WHEN 'SUMMARIZED_FROM' THEN 1
+           ELSE 2
+         END,
+         c.timestamp DESC
+       LIMIT ?`)
+        .all(specId, maxCommits);
+    // 3. Build commit contexts (with optional fragments)
+    const commits = [];
+    for (const crow of commitRows) {
+        const commit = {
+            hash: crow.hash,
+            message: crow.message,
+            author: crow.author,
+            timestamp: crow.timestamp,
+        };
+        let fragments = [];
+        if (includeFragments) {
+            const fragRows = db
+                .prepare(`SELECT f.id, f.change_type, f.file_path, f.start_line,
+                  f.end_line, f.code_diff
+           FROM commit_fragment_relations r
+           JOIN code_fragment_nodes f ON f.id = r.fragment_id
+           WHERE r.commit_hash = ?
+           ORDER BY f.file_path, f.start_line`)
+                .all(crow.hash);
+            fragments = fragRows.map((fr) => ({
+                id: fr.id,
+                changeType: fr.change_type,
+                filePath: fr.file_path,
+                startLine: fr.start_line,
+                endLine: fr.end_line,
+                codeDiff: fr.code_diff,
+            }));
+        }
+        commits.push({
+            commit,
+            relationType: crow.relation_type,
+            fragments,
+        });
+    }
+    return { spec, commits };
+}
+/**
+ * Find all spec IDs related to code fragments whose file path matches
+ * the given substring.
+ *
+ * @param db       Active SQLite database handle.
+ * @param filePath  File path substring to search for (LIKE-wrapped).
+ * @returns Array of distinct spec IDs.
+ */
+function findSpecsByFragmentPath(db, filePath) {
+    const pattern = `%${filePath}%`;
+    const rows = db
+        .prepare(`SELECT DISTINCT r.spec_id
+       FROM spec_commit_relations r
+       JOIN commit_fragment_relations cfr ON cfr.commit_hash = r.commit_hash
+       JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
+       WHERE cf.file_path LIKE ?`)
+        .all(pattern);
+    return rows.map((r) => r.spec_id);
+}
+// ===========================================================================
+// findSpecsByFilePath
+// ===========================================================================
+/** Default max results returned by findSpecsByFilePath. */
+const DEFAULT_MAX_SPEC_FIND_RESULTS = 100;
+/**
+ * Find specs whose code fragments reference the given file path.
+ *
+ * Traverses: filePath -> code_fragment_nodes -> commit_fragment_relations
+ * -> commit_nodes -> spec_commit_relations -> spec_nodes.
+ *
+ * Uses LIKE matching against code_fragment_nodes.file_path, so partial
+ * paths work (e.g. `src/auth.ts` matches `src/auth/login.ts` and
+ * `app/src/auth.ts`).  LIKE metacharacters (`%`, `_`, `\`) in the
+ * filePath are automatically escaped.
+ *
+ * An empty or whitespace-only filePath is rejected with an error
+ * (it would match every spec in the graph).
+ *
+ * @param db         Active SQLite database handle.
+ * @param filePath   File path to search for (substring LIKE match).
+ * @param maxResults Maximum number of results to return (default 100).
+ * @returns FindSpecsByFilePathResult with .results, .matched_count, and .truncated.
+ */
+function findSpecsByFilePath(db, filePath, maxResults = DEFAULT_MAX_SPEC_FIND_RESULTS) {
+    // Guard against empty input that would match every spec
+    if (!filePath || filePath.trim().length === 0) {
+        throw new Error('Empty file path is not allowed -- it would match every spec in the knowledge graph. ' +
+            'Provide a concrete file path (e.g. "src/auth.ts") or a partial path (e.g. "src/auth").');
+    }
+    // Escape LIKE metacharacters (SQLite ESCAPE '\' is used in the query)
+    const escaped = filePath
+        .replace(/\\/g, '\\\\') // literal backslash
+        .replace(/%/g, '\\%') // percent wildcard
+        .replace(/_/g, '\\_'); // underscore wildcard
+    const pattern = `%${escaped}%`;
+    const rows = db
+        .prepare(`SELECT DISTINCT s.id, s.title, s.status, s.version, s.file_path
+       FROM spec_nodes s
+       JOIN spec_commit_relations scr ON scr.spec_id = s.id
+       JOIN commit_fragment_relations cfr ON cfr.commit_hash = scr.commit_hash
+       JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
+       WHERE cf.file_path LIKE ? ESCAPE '\\'
+       ORDER BY s.id
+       LIMIT ?`)
+        .all(pattern, maxResults + 1);
+    const truncated = rows.length > maxResults;
+    const slice = truncated ? rows.slice(0, maxResults) : rows;
+    return {
+        results: slice.map((r) => ({
+            id: r.id,
+            title: r.title,
+            status: r.status,
+            version: r.version,
+            filePath: r.file_path,
+        })),
+        matched_count: slice.length,
+        truncated,
+    };
+}
+/**
+ * Compute statistics about the Spec knowledge graph.
+ *
+ * @param db  Active SQLite database handle.
+ * @returns SpecStats with entity counts and relation totals.
+ */
+function getSpecStats(db) {
+    const specCount = db.prepare('SELECT COUNT(*) as cnt FROM spec_nodes').get().cnt;
+    const commitCount = db.prepare('SELECT COUNT(*) as cnt FROM commit_nodes').get().cnt;
+    const fragmentCount = db
+        .prepare('SELECT COUNT(*) as cnt FROM code_fragment_nodes')
+        .get().cnt;
+    const scrCount = db
+        .prepare('SELECT COUNT(*) as cnt FROM spec_commit_relations')
+        .get().cnt;
+    const cfrCount = db
+        .prepare('SELECT COUNT(*) as cnt FROM commit_fragment_relations')
+        .get().cnt;
+    const ssrCount = db
+        .prepare('SELECT COUNT(*) as cnt FROM spec_spec_relations')
+        .get().cnt;
+    const activeSpecCount = db
+        .prepare("SELECT COUNT(*) as cnt FROM spec_nodes WHERE status = 'active'")
+        .get().cnt;
+    const deprecatedSpecCount = db
+        .prepare("SELECT COUNT(*) as cnt FROM spec_nodes WHERE status = 'deprecated'")
+        .get().cnt;
+    return {
+        specCount,
+        commitCount,
+        fragmentCount,
+        relationCount: scrCount + cfrCount + ssrCount,
+        activeSpecCount,
+        deprecatedSpecCount,
+    };
+}
+/**
+ * Full-text search for specs and return full context for each match.
+ *
+ * Combines FTS5 + LIKE fallback search with graph traversal so callers
+ * get everything in one call: spec metadata, linked commits, and
+ * optionally code fragments.
+ *
+ * Results are sorted by `_score` descending, then by spec timestamp
+ * descending as a tiebreaker.
+ *
+ * @param db                Active SQLite database handle.
+ * @param query             Search query string.
+ * @param topK              Maximum number of results to return (default 10).
+ * @param includeFragments  Whether to load code fragments per commit (default true).
+ * @returns Array of SpecContext (null results filtered out).
+ */
+function searchAndGetContext(db, query, topK = 10, includeFragments = true) {
+    // 1. Search specs via FTS5 + LIKE fallback
+    const results = (0, fts_1.searchSpecs)(db, query, topK);
+    // 2. Get full context for each result
+    const scored = [];
+    for (const result of results) {
+        const context = getSpecContext(db, result.id, 5, includeFragments);
+        if (context !== null) {
+            scored.push({
+                score: result._score ?? 0,
+                timestamp: context.spec.timestamp,
+                context,
+            });
+        }
+    }
+    // 3. Sort by _score descending, then by spec timestamp descending
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return b.timestamp - a.timestamp;
+    });
+    return scored.map((c) => c.context);
+}
+/** Weight constants for the five scoring dimensions. */
+const WEIGHTS = {
+    filePath: 0.30,
+    content: 0.25,
+    name: 0.15,
+    recency: 0.20,
+    overlap: 0.10,
+};
+/** Maximum candidates to consider from the initial file-path JOIN. */
+const MAX_CANDIDATES = 200;
+/**
+ * Escape LIKE metacharacters in a string, also escaping the escape character.
+ */
+function escapeLike(str) {
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/%/g, '\\%')
+        .replace(/_/g, '\\_');
+}
+/**
+ * Find Specs associated with a code entity by multi-dimensional scoring:
+ *
+ * 1. File path match (weight 0.30) — most stable anchor; function rarely changes file
+ * 2. Code-diff content match via FTS5 (weight 0.25) — catches entity names in diff text
+ *    that never appear in Spec titles
+ * 3. Spec title/subtitle name match via FTS5 (weight 0.15) — semantic alignment
+ * 4. Recency (weight 0.20) — newer Specs are more likely to describe current code
+ * 5. Line-range overlap (weight 0.10) — soft signal; code drifts over time
+ *
+ * All five dimensions contribute even when some are zero — a spec without line
+ * overlap can still rank first if its content/name/recency scores are high.
+ *
+ * @param specDb       commit4spec.db connection
+ * @param entity       Code entity info (from homegraph.db nodes)
+ * @param topK         Maximum matches to return (default 10)
+ * @returns Ranked, scored matches with score breakdowns
+ */
+function findSpecsByCodeSymbol(specDb, entity, topK = 10) {
+    const pathEscaped = escapeLike(entity.filePath);
+    const likePattern = `%${pathEscaped}%`;
+    const suffixLikePattern = `%${pathEscaped}`; // cf.file_path ends with entity's path
+    // -----------------------------------------------------------------------
+    // 1. Gather candidates: all specs whose fragments touch the entity's file
+    // -----------------------------------------------------------------------
+    const candidateRows = specDb
+        .prepare(`
+      SELECT
+          s.id, s.title, s.status, s.version, s.file_path, s.timestamp,
+          MAX(
+            MIN(cf.end_line, @entityEnd) - MAX(cf.start_line, @entityStart) + 1,
+            0
+          ) AS overlap_lines,
+          COUNT(DISTINCT cf.id) AS fragment_count,
+          COUNT(DISTINCT scr.commit_hash) AS commit_count,
+          MAX(CASE
+            WHEN cf.file_path = @exactFilePath THEN 3
+            WHEN cf.file_path LIKE @suffixLikePattern ESCAPE '\\' THEN 2
+            ELSE 1
+          END) AS file_path_match_level
+      FROM spec_nodes s
+      JOIN spec_commit_relations scr ON scr.spec_id = s.id
+      JOIN commit_fragment_relations cfr ON cfr.commit_hash = scr.commit_hash
+      JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
+      WHERE s.status = 'active'
+        AND cf.file_path LIKE @likePattern ESCAPE '\\'
+      GROUP BY s.id
+      ORDER BY s.timestamp DESC
+      LIMIT @maxCandidates
+    `)
+        .all({
+        entityEnd: entity.endLine,
+        entityStart: entity.startLine,
+        exactFilePath: entity.filePath,
+        suffixLikePattern,
+        likePattern,
+        maxCandidates: MAX_CANDIDATES,
+    });
+    // -----------------------------------------------------------------------
+    // 2. Content-match signal: search code_fragments_fts for the entity name
+    // -----------------------------------------------------------------------
+    const contentFragmentIds = new Set((0, fts_1.searchCodeFragments)(specDb, entity.name, 50));
+    // Map from spec_id → whether any of its fragments matched in content search
+    const contentSpecIds = new Set();
+    if (contentFragmentIds.size > 0) {
+        const fragsIn = [...contentFragmentIds].map(() => '?').join(',');
+        const contentSpecRows = specDb
+            .prepare(`
+        SELECT DISTINCT scr.spec_id
+        FROM commit_fragment_relations cfr
+        JOIN spec_commit_relations scr ON scr.commit_hash = cfr.commit_hash
+        WHERE cfr.fragment_id IN (${fragsIn})
+      `)
+            .all(...contentFragmentIds);
+        for (const r of contentSpecRows) {
+            contentSpecIds.add(r.spec_id);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 3. Name-match signal: search specs_fts for the entity name
+    // -----------------------------------------------------------------------
+    const nameResults = (0, fts_1.searchSpecs)(specDb, entity.name, topK * 3);
+    const nameScoreMap = new Map();
+    const nameMaxScore = Math.max(1, ...nameResults.map((r) => r._score ?? 0));
+    for (const r of nameResults) {
+        nameScoreMap.set(r.id, (r._score ?? 0) / nameMaxScore); // normalize to [0, 1]
+    }
+    // -----------------------------------------------------------------------
+    // 4. Compute weighted score for each candidate
+    // -----------------------------------------------------------------------
+    const now = Date.now();
+    const entityLength = Math.max(1, entity.endLine - entity.startLine + 1);
+    const scored = candidateRows.map((row) => {
+        // 4a. File-path score — derived from the best-matching fragment's file_path
+        // (computed in SQL as file_path_match_level: 3=exact, 2=suffix, 1=LIKE)
+        const filePathScore = row.file_path_match_level === 3 ? 1.0
+            : row.file_path_match_level === 2 ? 0.8
+                : 0.6;
+        // 4b. Content score
+        const contentScore = contentSpecIds.has(row.id) ? 1.0 : 0;
+        // 4c. Name score
+        const nameScore = nameScoreMap.get(row.id) ?? 0;
+        // 4d. Recency score: MapSpec(timestamp, 0, maxTs)MapSpec => [0, 1]
+        const daysSinceUpdate = (now - row.timestamp) / (1000 * 60 * 60 * 24);
+        const recencyScore = 1 / (1 + Math.max(0, daysSinceUpdate) / 180);
+        // 4e. Overlap score
+        const overlapRatio = Math.min(1.0, row.overlap_lines / entityLength);
+        const overlapScore = overlapRatio;
+        const score = filePathScore * WEIGHTS.filePath +
+            contentScore * WEIGHTS.content +
+            nameScore * WEIGHTS.name +
+            recencyScore * WEIGHTS.recency +
+            overlapScore * WEIGHTS.overlap;
+        return {
+            spec: {
+                id: row.id,
+                title: row.title,
+                status: row.status,
+                version: row.version,
+                filePath: row.file_path,
+                timestamp: row.timestamp,
+            },
+            score,
+            scoreDetail: {
+                filePathScore,
+                contentScore,
+                nameScore,
+                recencyScore,
+                overlapScore,
+            },
+            fragmentCount: row.fragment_count,
+            commitCount: row.commit_count,
+        };
+    });
+    // -----------------------------------------------------------------------
+    // 5. Sort and trim
+    // -----------------------------------------------------------------------
+    scored.sort((a, b) => b.score - a.score);
+    return {
+        entity,
+        matches: scored.slice(0, topK),
+        totalCandidates: candidateRows.length,
+    };
+}
+//# sourceMappingURL=queries.js.map

package/dist/spec/graph/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../../src/spec/graph/queries.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AA6FH,wCA8EC;AAUD,0DAgBC;AA4CD,kDAsDC;AASD,oCAqDC;AAkBD,kDA6BC;AA4FD,sDA8JC;AAnoBD,mCAA6D;AAiC7D,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;GAEG;AACH,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,GAAgB;IACtC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC;QACzC,MAAM,EAAE,GAAG,CAAC,MAA4B;QACxC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,SAAgB,cAAc,CAC5B,EAAkB,EAClB,MAAc,EACd,aAAqB,CAAC,EACtB,mBAA4B,IAAI;IAEhC,4BAA4B;IAC5B,MAAM,OAAO,GAAG,EAAE;SACf,OAAO,CACN;;oBAEc,CACf;SACA,GAAG,CAAC,MAAM,CAA4B,CAAC;IAE1C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAErC,iDAAiD;IACjD,MAAM,UAAU,GAAG,EAAE;SAClB,OAAO,CACN;;;;;;;;;;;eAWS,CACV;SACA,GAAG,CAAC,MAAM,EAAE,UAAU,CAAgB,CAAC;IAE1C,qDAAqD;IACrD,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAe;YACzB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QAEF,IAAI,SAAS,GAAuB,EAAE,CAAC;QACvC,IAAI,gBAAgB,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,EAAE;iBAChB,OAAO,CACN;;;;;8CAKoC,CACrC;iBACA,GAAG,CAAC,IAAI,CAAC,IAAI,CAAkB,CAAC;YAEnC,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;gBAChC,EAAE,EAAE,EAAE,CAAC,EAAE;gBACT,UAAU,EAAE,EAAE,CAAC,WAA6C;gBAC5D,QAAQ,EAAE,EAAE,CAAC,SAAS;gBACtB,SAAS,EAAE,EAAE,CAAC,UAAU;gBACxB,OAAO,EAAE,EAAE,CAAC,QAAQ;gBACpB,QAAQ,EAAE,EAAE,CAAC,SAAS;aACvB,CAAC,CAAC,CAAC;QACN,CAAC;QAED,OAAO,CAAC,IAAI,CAAC;YACX,MAAM;YACN,YAAY,EAAE,IAAI,CAAC,aAAkD;YACrE,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CACrC,EAAkB,EAClB,QAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,QAAQ,GAAG,CAAC;IAChC,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN;;;;iCAI2B,CAC5B;SACA,GAAG,CAAC,OAAO,CAA+B,CAAC;IAE9C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,2DAA2D;AAC3D,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAkB1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,mBAAmB,CACjC,EAAkB,EAClB,QAAgB,EAChB,aAAqB,6BAA6B;IAElD,wDAAwD;IACxD,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,sFAAsF;YACtF,wFAAwF,CACzF,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,MAAM,OAAO,GAAG,QAAQ;SACrB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,oBAAoB;SAC3C,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAG,mBAAmB;SAC1C,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,sBAAsB;IAEhD,MAAM,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC;IAE/B,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN;;;;;;;eAOS,CACV;SACA,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,CAAC,CAM1B,CAAC;IAEL,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;IAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE3D,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,QAAQ,EAAE,CAAC,CAAC,SAAS;SACtB,CAAC,CAAC;QACH,aAAa,EAAE,KAAK,CAAC,MAAM;QAC3B,SAAS;KACV,CAAC;AACJ,CAAC;AAGD;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,EAAkB;IAC7C,MAAM,SAAS,GACb,EAAE,CAAC,OAAO,CAAC,wCAAwC,CAAC,CAAC,GAAG,EACzD,CAAC,GAAG,CAAC;IAEN,MAAM,WAAW,GACf,EAAE,CAAC,OAAO,CAAC,0CAA0C,CAAC,CAAC,GAAG,EAC3D,CAAC,GAAG,CAAC;IAEN,MAAM,aAAa,GACjB,EAAE;SACC,OAAO,CAAC,iDAAiD,CAAC;SAC1D,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,MAAM,QAAQ,GACZ,EAAE;SACC,OAAO,CAAC,mDAAmD,CAAC;SAC5D,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,MAAM,QAAQ,GACZ,EAAE;SACC,OAAO,CAAC,uDAAuD,CAAC;SAChE,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,MAAM,QAAQ,GACZ,EAAE;SACC,OAAO,CAAC,iDAAiD,CAAC;SAC1D,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,MAAM,eAAe,GACnB,EAAE;SACC,OAAO,CAAC,gEAAgE,CAAC;SACzE,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,MAAM,mBAAmB,GACvB,EAAE;SACC,OAAO,CAAC,oEAAoE,CAAC;SAC7E,GAAG,EACP,CAAC,GAAG,CAAC;IAEN,OAAO;QACL,SAAS;QACT,WAAW;QACX,aAAa;QACb,aAAa,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ;QAC7C,eAAe;QACf,mBAAmB;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,mBAAmB,CACjC,EAAkB,EAClB,KAAa,EACb,OAAe,EAAE,EACjB,mBAA4B,IAAI;IAEhC,2CAA2C;IAC3C,MAAM,OAAO,GAAG,IAAA,iBAAW,EAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAE7C,sCAAsC;IACtC,MAAM,MAAM,GAAsE,EAAE,CAAC;IACrF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACnE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC;gBACzB,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS;gBACjC,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC;AAoDD,wDAAwD;AACxD,MAAM,OAAO,GAAG;IACd,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;IACb,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,sEAAsE;AACtE,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;GAEG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,GAAG;SACP,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,qBAAqB,CACnC,MAAsB,EACtB,MAAsB,EACtB,OAAe,EAAE;IAEjB,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,IAAI,WAAW,GAAG,CAAC;IACvC,MAAM,iBAAiB,GAAG,IAAI,WAAW,EAAE,CAAC,CAAC,uCAAuC;IAEpF,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAE1E,MAAM,aAAa,GAAG,MAAM;SACzB,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;KAuBR,CAAC;SACD,GAAG,CAAC;QACH,SAAS,EAAE,MAAM,CAAC,OAAO;QACzB,WAAW,EAAE,MAAM,CAAC,SAAS;QAC7B,aAAa,EAAE,MAAM,CAAC,QAAQ;QAC9B,iBAAiB;QACjB,WAAW;QACX,aAAa,EAAE,cAAc;KAC9B,CAWC,CAAC;IAEL,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,IAAA,yBAAmB,EAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAC7C,CAAC;IAEF,4EAA4E;IAC5E,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACzC,IAAI,kBAAkB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,CAAC,GAAG,kBAAkB,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,eAAe,GAAG,MAAM;aAC3B,OAAO,CAAC;;;;oCAIqB,OAAO;OACpC,CAAC;aACD,GAAG,CAAC,GAAG,kBAAkB,CAA+B,CAAC;QAC5D,KAAK,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;YAChC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,6DAA6D;IAC7D,0EAA0E;IAC1E,MAAM,WAAW,GAAG,IAAA,iBAAW,EAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;IAC/D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,sBAAsB;IAChF,CAAC;IAED,0EAA0E;IAC1E,+CAA+C;IAC/C,0EAA0E;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAExE,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACvC,4EAA4E;QAC5E,wEAAwE;QACxE,MAAM,aAAa,GAAG,GAAG,CAAC,qBAAqB,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;YACzD,CAAC,CAAC,GAAG,CAAC,qBAAqB,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;gBACvC,CAAC,CAAC,GAAG,CAAC;QAER,oBAAoB;QACpB,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1D,iBAAiB;QACjB,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAEhD,mEAAmE;QACnE,MAAM,eAAe,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACtE,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,GAAG,GAAG,CAAC,CAAC;QAElE,oBAAoB;QACpB,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,aAAa,GAAG,YAAY,CAAC,CAAC;QACrE,MAAM,YAAY,GAAG,YAAY,CAAC;QAElC,MAAM,KAAK,GACT,aAAa,GAAG,OAAO,CAAC,QAAQ;YAChC,YAAY,GAAG,OAAO,CAAC,OAAO;YAC9B,SAAS,GAAG,OAAO,CAAC,IAAI;YACxB,YAAY,GAAG,OAAO,CAAC,OAAO;YAC9B,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;QAEjC,OAAO;YACL,IAAI,EAAE;gBACJ,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,QAAQ,EAAE,GAAG,CAAC,SAAS;gBACvB,SAAS,EAAE,GAAG,CAAC,SAAS;aACzB;YACD,KAAK;YACL,WAAW,EAAE;gBACX,aAAa;gBACb,YAAY;gBACZ,SAAS;gBACT,YAAY;gBACZ,YAAY;aACb;YACD,aAAa,EAAE,GAAG,CAAC,cAAc;YACjC,WAAW,EAAE,GAAG,CAAC,YAAY;SAC9B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAC1E,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEzC,OAAO;QACL,MAAM;QACN,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;QAC9B,eAAe,EAAE,aAAa,CAAC,MAAM;KACtC,CAAC;AACJ,CAAC"}

package/dist/spec/llm/client.d.ts

@@ -0,0 +1,29 @@
+import { LLMConfig } from '../config';
+export interface LlmClient {
+    chat(systemPrompt: string, userPrompt: string): Promise<string>;
+    chatJson(systemPrompt: string, userPrompt: string): Promise<Record<string, unknown>>;
+}
+export declare class OpenAiLlmClient implements LlmClient {
+    private config;
+    constructor(config: LLMConfig);
+    /**
+     * Send a chat completion request and return the message content string.
+     *
+     * Calls the OpenAI-compatible chat completions API and returns
+     * `choices[0].message.content`. On any error, returns an empty string.
+     */
+    chat(systemPrompt: string, userPrompt: string): Promise<string>;
+    /**
+     * Same as `chat()`, but parses the response as JSON.
+     *
+     * Parsing strategy (tried in order):
+     * 1. Direct `JSON.parse(content)`.
+     * 2. Extract from `` ```json ... ``` `` fenced block.
+     * 3. Extract from `` ``` ... ``` `` fenced block.
+     * 4. Fallback: log a debug warning and return `{}`.
+     *
+     * Empty or null content from `chat()` also returns `{}`.
+     */
+    chatJson(systemPrompt: string, userPrompt: string): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/spec/llm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/client.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAOtC,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtF;AAMD,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,EAAE,SAAS;IAQ7B;;;;;OAKG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCrE;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CA+CpC"}

package/dist/spec/llm/client.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAiLlmClient = void 0;
+/**
+ * Provider-agnostic LLM client for spec self-evolution.
+ *
+ * Supports OpenAI-compatible chat completions API. No mock mode — callers
+ * that need test doubles inject their own stubs implementing the interface.
+ *
+ * @module spec/llm/client
+ */
+const openai_1 = __importDefault(require("openai"));
+const errors_1 = require("../../errors");
+// =============================================================================
+// OpenAiLlmClient
+// =============================================================================
+class OpenAiLlmClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // ===========================================================================
+    // chat
+    // ===========================================================================
+    /**
+     * Send a chat completion request and return the message content string.
+     *
+     * Calls the OpenAI-compatible chat completions API and returns
+     * `choices[0].message.content`. On any error, returns an empty string.
+     */
+    async chat(systemPrompt, userPrompt) {
+        const baseURL = this.config.baseUrl
+            ? this.config.baseUrl
+            : this.config.provider === 'anthropic'
+                ? 'https://api.anthropic.com/v1'
+                : undefined;
+        const client = new openai_1.default({
+            apiKey: this.config.apiKey,
+            baseURL,
+        });
+        try {
+            const completion = await client.chat.completions.create({
+                model: this.config.model,
+                temperature: this.config.temperature,
+                max_tokens: this.config.maxTokens,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userPrompt },
+                ],
+            });
+            const content = completion.choices[0]?.message?.content;
+            return content ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    // ===========================================================================
+    // chatJson
+    // ===========================================================================
+    /**
+     * Same as `chat()`, but parses the response as JSON.
+     *
+     * Parsing strategy (tried in order):
+     * 1. Direct `JSON.parse(content)`.
+     * 2. Extract from `` ```json ... ``` `` fenced block.
+     * 3. Extract from `` ``` ... ``` `` fenced block.
+     * 4. Fallback: log a debug warning and return `{}`.
+     *
+     * Empty or null content from `chat()` also returns `{}`.
+     */
+    async chatJson(systemPrompt, userPrompt) {
+        const raw = await this.chat(systemPrompt, userPrompt);
+        if (!raw)
+            return {};
+        // 1. Direct parse
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Fall through to fence extraction
+        }
+        // 2. ```json ... ``` fence
+        const jsonFenceMatch = /```json\s*([\s\S]*?)```/.exec(raw);
+        if (jsonFenceMatch) {
+            try {
+                const parsed = JSON.parse(jsonFenceMatch[1].trim());
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // 3. ``` ... ``` fence
+        const fenceMatch = /```\s*([\s\S]*?)```/.exec(raw);
+        if (fenceMatch) {
+            try {
+                const parsed = JSON.parse(fenceMatch[1].trim());
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // 4. Fallback
+        (0, errors_1.logDebug)('chatJson: could not parse response as JSON', {
+            raw: raw.length > 200 ? raw.slice(0, 200) + '…' : raw,
+        });
+        return {};
+    }
+}
+exports.OpenAiLlmClient = OpenAiLlmClient;
+//# sourceMappingURL=client.js.map

package/dist/spec/llm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/spec/llm/client.ts"],"names":[],"mappings":"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"}

package/dist/spec/llm/index.d.ts

@@ -0,0 +1,3 @@
+export { LlmClient, OpenAiLlmClient } from './client';
+export { LOGIC_CHECK_SYSTEM_PROMPT, buildLogicCheckUserPrompt, SPEC_EVALUATION_SYSTEM_PROMPT, buildSpecEvaluationUserPrompt, } from './prompts';
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/llm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,WAAW,CAAC"}

package/dist/spec/llm/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSpecEvaluationUserPrompt = exports.SPEC_EVALUATION_SYSTEM_PROMPT = exports.buildLogicCheckUserPrompt = exports.LOGIC_CHECK_SYSTEM_PROMPT = exports.OpenAiLlmClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "OpenAiLlmClient", { enumerable: true, get: function () { return client_1.OpenAiLlmClient; } });
+var prompts_1 = require("./prompts");
+Object.defineProperty(exports, "LOGIC_CHECK_SYSTEM_PROMPT", { enumerable: true, get: function () { return prompts_1.LOGIC_CHECK_SYSTEM_PROMPT; } });
+Object.defineProperty(exports, "buildLogicCheckUserPrompt", { enumerable: true, get: function () { return prompts_1.buildLogicCheckUserPrompt; } });
+Object.defineProperty(exports, "SPEC_EVALUATION_SYSTEM_PROMPT", { enumerable: true, get: function () { return prompts_1.SPEC_EVALUATION_SYSTEM_PROMPT; } });
+Object.defineProperty(exports, "buildSpecEvaluationUserPrompt", { enumerable: true, get: function () { return prompts_1.buildSpecEvaluationUserPrompt; } });
+//# sourceMappingURL=index.js.map

package/dist/spec/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spec/llm/index.ts"],"names":[],"mappings":";;;AAAA,mCAAsD;AAAlC,yGAAA,eAAe,OAAA;AACnC,qCAKmB;AAJjB,oHAAA,yBAAyB,OAAA;AACzB,oHAAA,yBAAyB,OAAA;AACzB,wHAAA,6BAA6B,OAAA;AAC7B,wHAAA,6BAA6B,OAAA"}

package/dist/spec/llm/prompts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * LLM prompt templates for spec self-evolution.
+ *
+ * Extracted from logic-checker.ts and spec-rewriter.ts so evolve modules
+ * don't contain prompt strings directly.
+ *
+ * @module spec/llm/prompts
+ */
+export declare const LOGIC_CHECK_SYSTEM_PROMPT = "You are a code review assistant. Your task is to determine whether a git commit represents a business-logic change (as opposed to purely cosmetic, formatting, comment-only, or test-only changes).\n\nA business-logic change includes:\n- Changes to algorithms, data structures, or control flow\n- Changes to business rules, validation logic, or domain behavior\n- Adding or removing functionality\n- Bug fixes that change behavior\n\nNOT business-logic changes:\n- Whitespace, formatting, or code style changes\n- Comment-only changes\n- Test-only changes (adding tests without changing production code)\n- Configuration changes that don't alter behavior\n- Package/dependency version bumps\n\nRespond with a JSON object:\n{\n  \"is_logic_change\": true/false,\n  \"reason\": \"Brief explanation of why this is or is not a logic change\"\n}";
+export declare function buildLogicCheckUserPrompt(commitMessage: string, truncatedDiff: string): string;
+export declare const SPEC_EVALUATION_SYSTEM_PROMPT = "You are a technical documentation maintainer. Your task is to evaluate whether a git commit requires updating a software design specification (plan.md).\n\nGiven the current plan content, the commit message, and the code diff, determine:\n1. Whether the plan needs to be updated (UPDATE), deprecated (DEPRECATE), or left unchanged (UNCHANGED).\n2. If UPDATE: provide the new title, subtitles (as an array of heading-preview strings), and full rewritten plan_content.\n3. If DEPRECATE: provide a brief explanation in the plan_content field.\n\nResponse format (JSON):\n{\n  \"action\": \"UPDATE\" | \"DEPRECATE\" | \"UNCHANGED\",\n  \"title\": \"New spec title (for UPDATE)\",\n  \"subtitles\": [\"heading1 \u2192 heading2 - preview\", ...],\n  \"plan_content\": \"Full rewritten markdown content (for UPDATE) or deprecation reason (for DEPRECATE)\"\n}";
+export declare function buildSpecEvaluationUserPrompt(planContent: string, commitMessage: string, truncatedDiff: string, scheduleNextSpecs: string[]): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/spec/llm/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,yBAAyB,20BAmBpC,CAAC;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,MAAM,CAOR;AAMD,eAAO,MAAM,6BAA6B,w1BAaxC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,MAAM,CAcR"}