cclaw-cli 7.7.1 → 8.1.1

package/dist/knowledge-store.js

@@ -1,603 +1,69 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "./config.js";
-import { RUNTIME_ROOT } from "./constants.js";
-import { stripBom, withDirectoryLock } from "./fs-utils.js";
-import { FLOW_STAGES } from "./types.js";
-const DEFAULT_COMPOUND_READINESS_MAX_READY = 10;
-/**
- * Single source of truth for the small-project relaxation rule.
- *
- * Kept exported so the inline hook mirror and CLI/runtime paths all agree on
- * the same numbers.
- */
-export const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = 5;
-export const SMALL_PROJECT_RECURRENCE_THRESHOLD = 2;
-export function effectiveCompoundThreshold(baseThreshold, archivedRunsCount) {
-    if (typeof archivedRunsCount === "number" &&
-        Number.isFinite(archivedRunsCount) &&
-        archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
-        baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD) {
-        return {
-            threshold: SMALL_PROJECT_RECURRENCE_THRESHOLD,
-            relaxationApplied: true
-        };
-    }
-    return { threshold: baseThreshold, relaxationApplied: false };
-}
-/**
- * Pure function — no filesystem side effects. Callers pass entries from
- * `readKnowledgeSafely` and get a derived readiness snapshot suitable
- * for persisting to `.cclaw/state/compound-readiness.json`.
- *
- * Clustering key: `(type, normalizeText(trigger), normalizeText(action))`
- * which mirrors the compound readiness clustering in runtime state.
- * The readiness surface intentionally stays simple: no maturity/supersede
- * suppression logic in this pass.
- */
-export function computeCompoundReadiness(entries, options = {}) {
-    const thresholdRaw = options.threshold ?? DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
-    const baseThreshold = Number.isInteger(thresholdRaw) && thresholdRaw >= 1
-        ? thresholdRaw
-        : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
-    const maxReadyRaw = options.maxReady ?? DEFAULT_COMPOUND_READINESS_MAX_READY;
-    const maxReady = Number.isInteger(maxReadyRaw) && maxReadyRaw >= 1
-        ? maxReadyRaw
-        : DEFAULT_COMPOUND_READINESS_MAX_READY;
-    const now = options.now ?? new Date();
-    const archivedRunsCount = typeof options.archivedRunsCount === "number" &&
-        Number.isFinite(options.archivedRunsCount) &&
-        options.archivedRunsCount >= 0
-        ? Math.floor(options.archivedRunsCount)
-        : undefined;
-    const { threshold, relaxationApplied } = effectiveCompoundThreshold(baseThreshold, archivedRunsCount);
-    const buckets = new Map();
-    for (const entry of entries) {
-        const key = [
-            entry.type,
-            normalizeText(entry.trigger),
-            normalizeText(entry.action)
-        ].join("||");
-        const frequency = Math.max(1, Math.floor(entry.frequency));
-        const bucket = buckets.get(key);
-        if (!bucket) {
-            buckets.set(key, {
-                trigger: entry.trigger,
-                action: entry.action,
-                recurrence: frequency,
-                entryCount: 1,
-                severity: entry.severity,
-                lastSeenTs: entry.last_seen_ts,
-                types: new Set([entry.type])
-            });
-            continue;
-        }
-        bucket.recurrence += frequency;
-        bucket.entryCount += 1;
-        bucket.types.add(entry.type);
-        if (entry.severity === "critical") {
-            bucket.severity = "critical";
-        }
-        else if (entry.severity === "important" && bucket.severity !== "critical") {
-            bucket.severity = "important";
-        }
-        if (Date.parse(entry.last_seen_ts) > Date.parse(bucket.lastSeenTs)) {
-            bucket.lastSeenTs = entry.last_seen_ts;
-        }
-    }
-    const ready = [];
-    for (const bucket of buckets.values()) {
-        const criticalOverride = bucket.severity === "critical";
-        const meetsRecurrence = bucket.recurrence >= threshold;
-        if (!criticalOverride && !meetsRecurrence)
-            continue;
-        ready.push({
-            trigger: bucket.trigger,
-            action: bucket.action,
-            recurrence: bucket.recurrence,
-            entryCount: bucket.entryCount,
-            qualification: criticalOverride && !meetsRecurrence ? "critical_override" : "recurrence",
-            ...(bucket.severity ? { severity: bucket.severity } : {}),
-            lastSeenTs: bucket.lastSeenTs,
-            types: Array.from(bucket.types).sort()
-        });
-    }
-    ready.sort((a, b) => {
-        const severityWeight = (sev) => {
-            if (sev === "critical")
-                return 3;
-            if (sev === "important")
-                return 2;
-            if (sev === "suggestion")
-                return 1;
-            return 0;
-        };
-        const severityDiff = severityWeight(b.severity) - severityWeight(a.severity);
-        if (severityDiff !== 0)
-            return severityDiff;
-        if (b.recurrence !== a.recurrence)
-            return b.recurrence - a.recurrence;
-        const recencyDiff = Date.parse(b.lastSeenTs) - Date.parse(a.lastSeenTs);
-        if (!Number.isNaN(recencyDiff) && recencyDiff !== 0)
-            return recencyDiff;
-        return a.trigger.localeCompare(b.trigger);
-    });
-    return {
-        schemaVersion: 2,
-        threshold,
-        baseThreshold,
-        ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
-        smallProjectRelaxationApplied: relaxationApplied,
-        clusterCount: buckets.size,
-        readyCount: ready.length,
-        ready: ready.slice(0, maxReady),
-        lastUpdatedAt: normalizeUtcIso(now.toISOString())
-    };
+import { KNOWLEDGE_LOG_REL_PATH } from "./constants.js";
+import { exists, writeFileSafe } from "./fs-utils.js";
+export class KnowledgeStoreError extends Error {
 }
-const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
-const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
-const KNOWLEDGE_SEVERITY_SET = new Set(["critical", "important", "suggestion"]);
-const LEGACY_KNOWLEDGE_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
-const LEGACY_KNOWLEDGE_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
-const KNOWLEDGE_SOURCE_SET = new Set([
-    "stage",
-    "retro",
-    "compound",
-    "idea",
-    "manual"
-]);
-const FLOW_STAGE_SET = new Set(FLOW_STAGES);
-const KNOWLEDGE_REQUIRED_KEYS = [
-    "type",
-    "trigger",
-    "action",
-    "confidence",
-    "stage",
-    "origin_stage",
-    "frequency",
-    "created",
-    "first_seen_ts",
-    "last_seen_ts",
-    "project"
-];
-const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
-// Legacy keys are accepted for backwards compatibility when reading historical
-// knowledge entries, but no longer required for newly materialized rows.
-KNOWLEDGE_ALLOWED_KEYS.add("domain");
-KNOWLEDGE_ALLOWED_KEYS.add("origin_run");
-KNOWLEDGE_ALLOWED_KEYS.add("universality");
-KNOWLEDGE_ALLOWED_KEYS.add("maturity");
-KNOWLEDGE_ALLOWED_KEYS.add("source");
-KNOWLEDGE_ALLOWED_KEYS.add("severity");
-KNOWLEDGE_ALLOWED_KEYS.add("supersedes");
-KNOWLEDGE_ALLOWED_KEYS.add("superseded_by");
-function keyAllowedInKnowledgeEntry(key) {
-    return KNOWLEDGE_ALLOWED_KEYS.has(key);
+export function knowledgeLogPath(projectRoot) {
+    return path.join(projectRoot, KNOWLEDGE_LOG_REL_PATH);
 }
-function normalizeParsedKnowledgeEntry(obj) {
-    const normalized = {
-        type: obj.type,
-        trigger: obj.trigger,
-        action: obj.action,
-        confidence: obj.confidence,
-        stage: obj.stage,
-        origin_stage: obj.origin_stage,
-        frequency: obj.frequency,
-        created: obj.created,
-        first_seen_ts: obj.first_seen_ts,
-        last_seen_ts: obj.last_seen_ts,
-        project: obj.project
-    };
-    if (obj.severity !== undefined) {
-        normalized.severity = obj.severity;
+function assertEntry(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new KnowledgeStoreError("Knowledge entry must be an object.");
     }
-    if (obj.source !== undefined) {
-        normalized.source = obj.source;
-    }
-    return normalized;
-}
-function knowledgePath(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-}
-function knowledgeLockPath(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "state", ".knowledge.lock");
-}
-function normalizeUtcIso(iso) {
-    return iso.replace(/\.\d{3}Z$/u, "Z");
-}
-function nowUtcIso() {
-    return normalizeUtcIso(new Date().toISOString());
-}
-function normalizeText(value) {
-    return value.trim().replace(/\s+/gu, " ").toLowerCase();
-}
-function dedupeKey(entry) {
-    return [
-        entry.type,
-        normalizeText(entry.trigger),
-        normalizeText(entry.action),
-        entry.stage ?? "null",
-        entry.origin_stage ?? "null",
-        entry.project === null ? "null" : normalizeText(entry.project),
-        entry.source === undefined || entry.source === null ? "null" : entry.source,
-        entry.severity === undefined ? "none" : entry.severity
-    ].join("|");
-}
-function emptyKnowledgeSnapshot() {
-    return {
-        lines: [],
-        entries: [],
-        malformedLines: 0,
-        keyToIndex: new Map(),
-        entryByIndex: new Map()
-    };
-}
-function parseKnowledgeSnapshot(raw) {
-    const lines = stripBom(raw).split(/\r?\n/u);
-    const entries = [];
-    const keyToIndex = new Map();
-    const entryByIndex = new Map();
-    let malformedLines = 0;
-    for (let i = 0; i < lines.length; i += 1) {
-        const trimmed = lines[i].trim();
-        if (trimmed.length === 0)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            const validated = validateKnowledgeEntry(parsed);
-            if (!validated.ok) {
-                malformedLines += 1;
-                continue;
-            }
-            const entry = normalizeParsedKnowledgeEntry(parsed);
-            entries.push(entry);
-            const key = dedupeKey(entry);
-            if (!keyToIndex.has(key)) {
-                keyToIndex.set(key, i);
-            }
-            entryByIndex.set(i, entry);
-        }
-        catch {
-            malformedLines += 1;
+    const entry = value;
+    for (const key of ["slug", "ship_commit", "shipped_at"]) {
+        if (typeof entry[key] !== "string" || entry[key].length === 0) {
+            throw new KnowledgeStoreError(`Knowledge entry must include string ${key}.`);
         }
     }
-    return {
-        lines,
-        entries,
-        malformedLines,
-        keyToIndex,
-        entryByIndex
-    };
-}
-async function readKnowledgeSnapshot(filePath) {
-    try {
-        const raw = await fs.readFile(filePath, "utf8");
-        return parseKnowledgeSnapshot(raw);
-    }
-    catch (error) {
-        const code = error?.code;
-        if (code === "ENOENT") {
-            return emptyKnowledgeSnapshot();
-        }
-        throw error;
+    if (typeof entry.signals !== "object" || entry.signals === null) {
+        throw new KnowledgeStoreError("Knowledge entry must include a `signals` object.");
     }
 }
-function mergeKnowledgeOccurrence(target, incoming) {
-    const mergedFrequency = target.frequency + Math.max(1, incoming.frequency);
-    const mergedLastSeen = target.last_seen_ts >= incoming.last_seen_ts
-        ? target.last_seen_ts
-        : incoming.last_seen_ts;
-    return {
-        ...target,
-        frequency: mergedFrequency,
-        last_seen_ts: mergedLastSeen
-    };
-}
-function isIsoUtcTimestamp(value) {
-    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u.test(value);
-}
-function isNullableString(value) {
-    return value === null || typeof value === "string";
-}
-function isNullableStage(value) {
-    return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
-}
-export function validateKnowledgeEntry(entry) {
-    const errors = [];
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-        return { ok: false, errors: ["Knowledge entry must be a JSON object."] };
-    }
-    const obj = entry;
-    for (const key of Object.keys(obj)) {
-        if (!keyAllowedInKnowledgeEntry(key)) {
-            errors.push(`Unknown key "${key}" in knowledge entry.`);
-        }
-    }
-    for (const key of KNOWLEDGE_REQUIRED_KEYS) {
-        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
-            errors.push(`Missing required key "${key}".`);
-        }
-    }
-    if (!KNOWLEDGE_TYPE_SET.has(obj.type)) {
-        errors.push("type must be one of: rule, pattern, lesson, compound.");
-    }
-    if (typeof obj.trigger !== "string" || obj.trigger.trim().length === 0) {
-        errors.push("trigger must be a non-empty string.");
-    }
-    if (typeof obj.action !== "string" || obj.action.trim().length === 0) {
-        errors.push("action must be a non-empty string.");
-    }
-    if (!KNOWLEDGE_CONFIDENCE_SET.has(obj.confidence)) {
-        errors.push("confidence must be one of: high, medium, low.");
-    }
-    if (obj.severity !== undefined &&
-        (typeof obj.severity !== "string" || !KNOWLEDGE_SEVERITY_SET.has(obj.severity))) {
-        errors.push("severity must be one of: critical, important, suggestion.");
-    }
-    if (obj.domain !== undefined && !isNullableString(obj.domain)) {
-        errors.push("domain must be string or null.");
-    }
-    if (!isNullableStage(obj.stage)) {
-        errors.push(`stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
-    }
-    if (!isNullableStage(obj.origin_stage)) {
-        errors.push(`origin_stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
-    }
-    const originRun = obj.origin_run;
-    if (originRun !== undefined && !isNullableString(originRun)) {
-        errors.push("origin_run must be string or null.");
+export async function appendKnowledgeEntry(projectRoot, entry) {
+    assertEntry(entry);
+    const target = knowledgeLogPath(projectRoot);
+    const line = `${JSON.stringify(entry)}\n`;
+    if (!(await exists(target))) {
+        await writeFileSafe(target, line);
+        return;
     }
-    if (typeof obj.frequency !== "number" ||
-        !Number.isInteger(obj.frequency) ||
-        obj.frequency < 1) {
-        errors.push("frequency must be an integer >= 1.");
-    }
-    if (obj.universality !== undefined &&
-        (typeof obj.universality !== "string" || !LEGACY_KNOWLEDGE_UNIVERSALITY_SET.has(obj.universality))) {
-        errors.push("universality must be one of: project, personal, universal.");
-    }
-    if (obj.maturity !== undefined &&
-        (typeof obj.maturity !== "string" || !LEGACY_KNOWLEDGE_MATURITY_SET.has(obj.maturity))) {
-        errors.push("maturity must be one of: raw, lifted-to-rule, lifted-to-enforcement.");
-    }
-    for (const timestampField of ["created", "first_seen_ts", "last_seen_ts"]) {
-        const value = obj[timestampField];
-        if (typeof value !== "string" || !isIsoUtcTimestamp(value)) {
-            errors.push(`${timestampField} must be ISO UTC (YYYY-MM-DDTHH:MM:SSZ).`);
-        }
-    }
-    if (!isNullableString(obj.project)) {
-        errors.push("project must be string or null.");
-    }
-    if (obj.supersedes !== undefined) {
-        if (!Array.isArray(obj.supersedes) ||
-            obj.supersedes.length === 0 ||
-            obj.supersedes.some((value) => typeof value !== "string" || value.trim().length === 0)) {
-            errors.push("supersedes must be a non-empty array of strings when present.");
-        }
-    }
-    if (obj.superseded_by !== undefined &&
-        (typeof obj.superseded_by !== "string" || obj.superseded_by.trim().length === 0)) {
-        errors.push("superseded_by must be a non-empty string when present.");
-    }
-    const sourceAllowed = obj.source === undefined ||
-        obj.source === null ||
-        (typeof obj.source === "string" &&
-            KNOWLEDGE_SOURCE_SET.has(obj.source));
-    if (!sourceAllowed) {
-        errors.push("source must be one of: stage, retro, compound, idea, manual, or null.");
-    }
-    return { ok: errors.length === 0, errors };
+    await fs.appendFile(target, line, "utf8");
 }
-export function materializeKnowledgeEntry(seed, defaults = {}) {
-    const now = normalizeUtcIso(defaults.nowIso ?? nowUtcIso());
-    const stage = seed.stage ?? defaults.stage ?? null;
-    const originStage = seed.origin_stage ?? defaults.originStage ?? stage ?? null;
-    const source = seed.source ?? defaults.source ?? null;
-    const entry = {
-        type: seed.type,
-        trigger: seed.trigger.trim(),
-        action: seed.action.trim(),
-        confidence: seed.confidence,
-        stage,
-        origin_stage: originStage,
-        frequency: seed.frequency ?? 1,
-        created: normalizeUtcIso(seed.created ?? now),
-        first_seen_ts: normalizeUtcIso(seed.first_seen_ts ?? now),
-        last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
-        project: seed.project ?? defaults.project ?? null
-    };
-    if (seed.severity !== undefined) {
-        entry.severity = seed.severity;
-    }
-    if (source !== null) {
-        entry.source = source;
-    }
-    return entry;
-}
-export async function readKnowledgeSafely(projectRoot, options = {}) {
-    const filePath = knowledgePath(projectRoot);
-    const read = async () => {
-        const snapshot = await readKnowledgeSnapshot(filePath);
-        return {
-            entries: snapshot.entries,
-            malformedLines: snapshot.malformedLines
-        };
-    };
-    if (options.lockAware === false) {
-        return read();
-    }
-    return withDirectoryLock(knowledgeLockPath(projectRoot), read);
-}
-export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
-    if (seeds.length === 0) {
-        return { appended: 0, skippedDuplicates: 0, invalid: 0, errors: [], appendedEntries: [] };
-    }
-    const filePath = knowledgePath(projectRoot);
-    const errors = [];
-    const materialized = [];
-    for (let i = 0; i < seeds.length; i += 1) {
-        const seed = seeds[i];
-        const entry = materializeKnowledgeEntry(seed, defaults);
-        const validated = validateKnowledgeEntry(entry);
-        if (!validated.ok) {
-            errors.push(`entry #${i + 1}: ${validated.errors.join(" ")}`);
-            continue;
-        }
-        materialized.push(entry);
-    }
-    let skippedDuplicates = 0;
-    const appendedEntries = [];
-    await withDirectoryLock(knowledgeLockPath(projectRoot), async () => {
-        await fs.mkdir(path.dirname(filePath), { recursive: true });
-        const snapshot = await readKnowledgeSnapshot(filePath);
-        const updatedByIndex = new Map();
-        const batchEntries = new Map();
-        for (const entry of materialized) {
-            const key = dedupeKey(entry);
-            const existingIndex = snapshot.keyToIndex.get(key);
-            if (existingIndex !== undefined) {
-                skippedDuplicates += 1;
-                const base = updatedByIndex.get(existingIndex) ?? snapshot.entryByIndex.get(existingIndex);
-                if (base) {
-                    updatedByIndex.set(existingIndex, mergeKnowledgeOccurrence(base, entry));
-                }
-                continue;
-            }
-            const existingBatchEntry = batchEntries.get(key);
-            if (existingBatchEntry) {
-                skippedDuplicates += 1;
-                batchEntries.set(key, mergeKnowledgeOccurrence(existingBatchEntry, entry));
-                continue;
-            }
-            batchEntries.set(key, { ...entry });
-        }
-        appendedEntries.push(...batchEntries.values());
-        if (updatedByIndex.size === 0 && batchEntries.size === 0) {
-            return;
-        }
-        const rewrittenLines = snapshot.lines.map((line, index) => {
-            const updated = updatedByIndex.get(index);
-            return updated ? JSON.stringify(updated) : line;
-        }).filter((line) => line.trim().length > 0);
-        const linesToWrite = [
-            ...rewrittenLines,
-            ...Array.from(batchEntries.values(), (entry) => JSON.stringify(entry))
-        ];
-        if (linesToWrite.length > 0) {
-            await fs.writeFile(filePath, `${linesToWrite.join("\n")}\n`, "utf8");
-        }
-    });
-    return {
-        appended: appendedEntries.length,
-        skippedDuplicates,
-        invalid: errors.length,
-        errors,
-        appendedEntries
-    };
-}
-const SHORT_TECHNICAL_TOKEN_SET = new Set(["ci", "db", "ui", "qa", "ux"]);
-function tokenizeText(value) {
-    if (!value)
-        return [];
-    const tokens = [];
-    const matches = value.matchAll(/[A-Za-z0-9]+/gu);
-    for (const match of matches) {
-        const raw = match[0] ?? "";
-        const normalized = raw.toLowerCase();
-        if (normalized.length >= 3) {
-            tokens.push(normalized);
-            continue;
-        }
-        if (/^[A-Z]{2}$/u.test(raw) || SHORT_TECHNICAL_TOKEN_SET.has(normalized)) {
-            tokens.push(normalized);
-        }
-    }
-    return tokens;
-}
-function uniqueTokens(values) {
-    return [...new Set(values)];
-}
-function pathTokens(paths) {
-    if (!Array.isArray(paths) || paths.length === 0)
+export async function readKnowledgeLog(projectRoot) {
+    const target = knowledgeLogPath(projectRoot);
+    if (!(await exists(target)))
         return [];
-    const tokens = [];
-    for (const filePath of paths) {
-        tokens.push(...tokenizeText(filePath));
-    }
-    return uniqueTokens(tokens);
-}
-export async function selectRelevantLearnings(projectRoot, options = {}) {
-    const { entries } = await readKnowledgeSafely(projectRoot);
-    if (entries.length === 0) {
-        return [];
-    }
-    const stage = options.stage ?? null;
-    const branchTokens = tokenizeText(options.branch ?? null);
-    const diffTokens = pathTokens(options.diffFiles);
-    const gateTokens = pathTokens(options.openGates);
-    const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0
-        ? Math.floor(options.limit)
-        : 8;
-    const ranked = entries.map((entry, index) => {
-        let score = 0;
-        let stageScore = 0;
-        if (stage) {
-            if (entry.stage === stage) {
-                stageScore = 4;
-            }
-            else if (entry.origin_stage === stage) {
-                stageScore = 3;
-            }
-            score += stageScore;
-        }
-        if (entry.confidence === "high")
-            score += 2;
-        if (entry.confidence === "medium")
-            score += 1;
-        if (entry.frequency >= 3)
-            score += 1;
-        const searchable = [
-            ...tokenizeText(entry.trigger),
-            ...tokenizeText(entry.action),
-            ...tokenizeText(entry.project)
-        ];
-        const searchSet = new Set(searchable);
-        let contextualScore = 0;
-        for (const token of branchTokens) {
-            if (searchSet.has(token))
-                contextualScore += 2;
-        }
-        for (const token of diffTokens) {
-            if (searchSet.has(token))
-                contextualScore += 2;
-        }
-        for (const token of gateTokens) {
-            if (searchSet.has(token))
-                contextualScore += 2;
-        }
-        score += contextualScore;
-        if (stage && entry.stage === null && stageScore === 0 && contextualScore < 4) {
-            score = 0;
-        }
-        return {
-            index,
-            score,
-            entry
-        };
-    });
-    ranked.sort((a, b) => {
-        if (b.score !== a.score)
-            return b.score - a.score;
-        const bySeen = Date.parse(b.entry.last_seen_ts) - Date.parse(a.entry.last_seen_ts);
-        if (!Number.isNaN(bySeen) && bySeen !== 0)
-            return bySeen;
-        if (b.entry.frequency !== a.entry.frequency)
-            return b.entry.frequency - a.entry.frequency;
-        return b.index - a.index;
-    });
-    return ranked
-        .filter((row) => row.score > 0)
-        .slice(0, limit)
-        .map((row) => row.entry);
+    const raw = await fs.readFile(target, "utf8");
+    const lines = raw.split(/\r?\n/u).filter((line) => line.trim().length > 0);
+    const entries = [];
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            throw new KnowledgeStoreError(`Invalid JSON line in knowledge.jsonl: ${err.message}`);
+        }
+        assertEntry(parsed);
+        entries.push(parsed);
+    }
+    return entries;
+}
+export async function findRefiningChain(projectRoot, slug) {
+    const all = await readKnowledgeLog(projectRoot);
+    const bySlug = new Map();
+    for (const entry of all)
+        bySlug.set(entry.slug, entry);
+    const chain = [];
+    let cursor = slug;
+    const seen = new Set();
+    while (cursor !== null && cursor !== undefined && bySlug.has(cursor) && !seen.has(cursor)) {
+        const found = bySlug.get(cursor);
+        chain.push(found);
+        seen.add(cursor);
+        cursor = found.refines ?? null;
+    }
+    return chain;
 }

package/dist/logger.d.ts

@@ -1,3 +1,8 @@
-import type { CliContext } from "./types.js";
-export declare function info(ctx: CliContext, message: string): void;
-export declare function error(ctx: CliContext, message: string): void;
+type Stream = NodeJS.WriteStream | {
+    write: (chunk: string) => unknown;
+};
+export declare function configureLogger(out: Stream, err: Stream): void;
+export declare function info(message: string): void;
+export declare function warn(message: string): void;
+export declare function error(message: string): void;
+export {};