@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/audit/knowledge-audit-llm.d.ts

@@ -0,0 +1,19 @@
+import { type IAiMessage, type IAiProvider } from '@shrkcrft/ai';
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IKnowledgeAuditEntry, IKnowledgeAuditReport, ILlmKnowledgeAuditFinding } from './knowledge-audit.js';
+export interface IEnrichKnowledgeAuditOptions {
+    provider: IAiProvider;
+    inspection: ISharkcraftInspection;
+    maxTokensPerEntry?: number;
+    onPerEntryError?: (entryId: string, error: Error) => void;
+}
+export declare function enrichKnowledgeAuditWithLlm(report: IKnowledgeAuditReport, options: IEnrichKnowledgeAuditOptions): Promise<IKnowledgeAuditReport>;
+declare function buildEnrichmentMessages(entry: IKnowledgeEntry, peers: readonly IKnowledgeEntry[], auditEntry: IKnowledgeAuditEntry): IAiMessage[];
+declare function parseLlmFindings(raw: string): readonly ILlmKnowledgeAuditFinding[];
+export declare const __internals: {
+    buildEnrichmentMessages: typeof buildEnrichmentMessages;
+    parseLlmFindings: typeof parseLlmFindings;
+};
+export {};
+//# sourceMappingURL=knowledge-audit-llm.d.ts.map

package/dist/audit/knowledge-audit-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-audit-llm.d.ts","sourceRoot":"","sources":["../../src/audit/knowledge-audit-llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EAE1B,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,qBAAqB,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC3D;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAoChC;AAED,iBAAS,uBAAuB,CAC9B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,UAAU,EAAE,oBAAoB,GAC/B,UAAU,EAAE,CAyEd;AAOD,iBAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,yBAAyB,EAAE,CAoC3E;AAQD,eAAO,MAAM,WAAW;;;CAAgD,CAAC"}

package/dist/audit/knowledge-audit-llm.js

@@ -0,0 +1,164 @@
+import { AiMessageRole } from '@shrkcrft/ai';
+export async function enrichKnowledgeAuditWithLlm(report, options) {
+    const enriched = [];
+    for (const entry of report.entries) {
+        const ke = options.inspection.knowledgeEntries.find((e) => e.id === entry.entryId);
+        if (!ke) {
+            enriched.push(entry);
+            continue;
+        }
+        const peers = options.inspection.knowledgeEntries
+            .filter((e) => e.id !== ke.id && String(e.type) === String(ke.type))
+            .slice(0, 4);
+        const messages = buildEnrichmentMessages(ke, peers, entry);
+        try {
+            const res = await options.provider.send({
+                messages,
+                maxTokens: options.maxTokensPerEntry ?? 1024,
+            });
+            if (!res.ok) {
+                options.onPerEntryError?.(entry.entryId, res.error);
+                enriched.push(entry);
+                continue;
+            }
+            const parsed = parseLlmFindings(res.value.content);
+            enriched.push({ ...entry, llmFindings: parsed });
+        }
+        catch (e) {
+            options.onPerEntryError?.(entry.entryId, e);
+            enriched.push(entry);
+        }
+    }
+    return {
+        ...report,
+        llmEnriched: true,
+        llmProviderId: options.provider.id,
+        entries: enriched,
+    };
+}
+function buildEnrichmentMessages(entry, peers, auditEntry) {
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            'You are a critic auditing a SharkCraft knowledge entry for staleness, content quality, and silent drift from sibling entries.',
+            'A knowledge entry is a structured piece of project knowledge (a rule, a path convention, a generic knowledge fact) that AI coding agents read when working on the project.',
+            '',
+            'CRITICAL DISTINCTION — read carefully before flagging anything:',
+            '- You are auditing the ENTRY itself, NOT the domain it describes. An entry about "deprecated APIs" is fine even if the APIs it discusses are deprecated; you would only flag it if the entry now teaches the wrong thing about those APIs.',
+            '- "References stale" means a file/symbol named in the entry no longer exists. Do not invent stale references — only flag what you can ground in the entry text or supplied deterministic findings.',
+            '- A short summary is not automatically a bug. Only flag thin wording when the surrounding context makes the brevity misleading.',
+            '',
+            'STRICT silence bias: emit a finding only if a senior maintainer would change something on the strength of it. If the deterministic layer already caught it, do not restate. Better silence than ceremony.',
+            '',
+            'Your job: surface issues the deterministic layer (knowledge lint + knowledge stale-reference check) CANNOT see. Look explicitly for:',
+            '  1. **content-drift**         — the entry teaches a pattern that the rest of the corpus has moved past.',
+            '  2. **internal-contradiction**— the entry contradicts a peer entry in the same scope.',
+            '  3. **doc-content-mismatch**  — `summary`/`description` and the long-form `body` say different things.',
+            '  4. **vague-claim**           — the entry uses "always/never/should" without a concrete why or example.',
+            '  5. **missing-action-hint**   — actionable rule with no command or MCP-tool reference, where similar peers have them.',
+            '  6. **stale-phrasing**        — references a tool/command/workflow that has been renamed or removed.',
+            '  7. **other**                 — only if none of the above fit.',
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no fences:',
+            '{',
+            '  "findings": [',
+            '    {',
+            '      "severity": "info" | "warn" | "error",',
+            '      "category": "content-drift" | "internal-contradiction" | "doc-content-mismatch" | "vague-claim" | "missing-action-hint" | "stale-phrasing" | "other",',
+            '      "message": "<one sentence — name specific symbols, commands, or peers when possible>",',
+            '      "confidence": 0.0',
+            '    }',
+            '  ]',
+            '}',
+            'If nothing new is worth flagging, return {"findings": []}. Never invent symbols, paths, or peer ids not present in the supplied data.',
+        ].join('\n'),
+    };
+    const user = {
+        role: AiMessageRole.User,
+        content: [
+            `# Knowledge entry under audit`,
+            `id: ${entry.id}`,
+            `type: ${String(entry.type)}`,
+            `title: ${entry.title ?? '(none)'}`,
+            `summary: ${entry.summary ?? '(none)'}`,
+            `tags: ${(entry.tags ?? []).join(', ') || '(none)'}`,
+            ``,
+            `## Content (truncated to ~4 KB)`,
+            '```',
+            truncate(String(entry.content ?? '(no content)'), 4096),
+            '```',
+            ``,
+            `## Deterministic findings already produced`,
+            auditEntry.deterministicFindings.length === 0
+                ? '(none)'
+                : auditEntry.deterministicFindings
+                    .map((f) => `- [${f.severity}] ${f.category} (${f.field}): ${f.message} (sources: ${f.sources.join(', ')})`)
+                    .join('\n'),
+            ``,
+            `## Sibling entries (same type)`,
+            peers.length === 0
+                ? '(no peers in this workspace)'
+                : peers
+                    .map((p) => `- ${p.id}: ${p.title ?? '(no title)'} — ${p.summary ?? '(no summary)'}`)
+                    .join('\n'),
+        ].join('\n'),
+    };
+    return [system, user];
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n… [truncated ${s.length - max} chars]`;
+}
+function parseLlmFindings(raw) {
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const first = jsonText.indexOf('{');
+        const last = jsonText.lastIndexOf('}');
+        if (first < 0 || last <= first)
+            return [];
+        try {
+            parsed = JSON.parse(jsonText.slice(first, last + 1));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const list = parsed.findings;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const severity = coerceSeverity(obj.severity);
+        const category = typeof obj.category === 'string' && obj.category.trim() ? obj.category.trim() : 'other';
+        const message = typeof obj.message === 'string' ? obj.message.trim() : '';
+        const confidence = typeof obj.confidence === 'number' && obj.confidence >= 0 && obj.confidence <= 1
+            ? obj.confidence
+            : 0.5;
+        if (!message)
+            continue;
+        out.push({ severity, category, message, confidence });
+    }
+    return out;
+}
+function coerceSeverity(value) {
+    if (value === 'error' || value === 'warn' || value === 'info')
+        return value;
+    if (value === 'warning')
+        return 'warn';
+    return 'info';
+}
+export const __internals = { buildEnrichmentMessages, parseLlmFindings };

package/dist/audit/knowledge-audit.d.ts

@@ -0,0 +1,61 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IAiBlock } from '@shrkcrft/ai';
+export type KnowledgeAuditFindingSeverity = 'info' | 'warn' | 'error';
+export interface IKnowledgeAuditFinding {
+    severity: KnowledgeAuditFindingSeverity;
+    category: string;
+    field: string;
+    message: string;
+    sources: readonly string[];
+    stubSuggestion?: string;
+    fixSuggestion?: string;
+}
+export interface ILlmKnowledgeAuditFinding {
+    severity: KnowledgeAuditFindingSeverity;
+    category: string;
+    message: string;
+    confidence: number;
+}
+export type KnowledgeAuditVerdict = 'ok' | 'minor' | 'stale' | 'broken';
+export interface IKnowledgeAuditSuggestedAction {
+    kind: 'edit' | 'rewrite' | 'retire' | 'investigate';
+    target: string;
+    note: string;
+}
+export interface IKnowledgeAuditEntry {
+    entryId: string;
+    entryType: string;
+    title: string;
+    verdict: KnowledgeAuditVerdict;
+    deterministicFindings: readonly IKnowledgeAuditFinding[];
+    llmFindings: readonly ILlmKnowledgeAuditFinding[];
+    suggestedActions: readonly IKnowledgeAuditSuggestedAction[];
+}
+export interface IKnowledgeAuditSkipped {
+    entryId: string;
+    reason: string;
+}
+export interface IKnowledgeAuditReport {
+    auditId: string;
+    generatedAt: string;
+    llmEnriched: boolean;
+    llmProviderId: string | null;
+    entries: readonly IKnowledgeAuditEntry[];
+    skipped: readonly IKnowledgeAuditSkipped[];
+    summary: {
+        ok: number;
+        minor: number;
+        stale: number;
+        broken: number;
+        total: number;
+    };
+    ai?: IAiBlock;
+}
+export interface IBuildKnowledgeAuditOptions {
+    /** Restrict to one entry id. */
+    entryId?: string;
+    /** Skip the stale-reference walk (slower; touches the filesystem). Defaults false. */
+    skipStaleCheck?: boolean;
+}
+export declare function buildKnowledgeAudit(inspection: ISharkcraftInspection, options?: IBuildKnowledgeAuditOptions): IKnowledgeAuditReport;
+//# sourceMappingURL=knowledge-audit.d.ts.map

package/dist/audit/knowledge-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-audit.d.ts","sourceRoot":"","sources":["../../src/audit/knowledge-audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,MAAM,6BAA6B,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,6BAA6B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,6BAA6B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,CAAC;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,qBAAqB,CAAC;IAC/B,qBAAqB,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACzD,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAClD,gBAAgB,EAAE,SAAS,8BAA8B,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC3C,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC1C,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,2BAAgC,GACxC,qBAAqB,CAyGvB"}

package/dist/audit/knowledge-audit.js

@@ -0,0 +1,203 @@
+import { buildKnowledgeStaleReport, KnowledgeLintSeverity, lintKnowledge, ReferenceCheckOutcome, } from '@shrkcrft/inspector';
+export function buildKnowledgeAudit(inspection, options = {}) {
+    const all = inspection.knowledgeEntries;
+    // User-source only: skip pack-contributed entries (they're signed; not our place to audit).
+    const userEntries = all.filter((e) => {
+        const src = inspection.entrySources?.get(e.id);
+        return !src || src.type === 'local';
+    });
+    const skipped = all
+        .filter((e) => !userEntries.includes(e))
+        .map((e) => ({
+        entryId: e.id,
+        reason: 'pack-contributed (out of scope for v1 audit)',
+    }));
+    const targets = options.entryId
+        ? userEntries.filter((e) => e.id === options.entryId)
+        : userEntries;
+    const targetIds = new Set(targets.map((t) => t.id));
+    const lint = lintKnowledge(targets, {});
+    const stale = options.skipStaleCheck ? null : safeBuildStaleReport(inspection);
+    // Group lint findings by entryId.
+    const lintByEntry = new Map();
+    for (const f of lint.findings) {
+        if (!targetIds.has(f.entryId))
+            continue;
+        const list = lintByEntry.get(f.entryId) ?? [];
+        list.push(f);
+        lintByEntry.set(f.entryId, list);
+    }
+    // Group stale reference findings by entryId. Only stale/missing outcomes
+    // (the deterministic engine already filters `ok`); promote to findings.
+    const staleByEntry = new Map();
+    for (const check of stale?.referenceChecks ?? []) {
+        if (!targetIds.has(check.entryId))
+            continue;
+        if (check.outcome === ReferenceCheckOutcome.Ok ||
+            check.outcome === ReferenceCheckOutcome.Unknown) {
+            continue;
+        }
+        const list = staleByEntry.get(check.entryId) ?? [];
+        list.push(check);
+        staleByEntry.set(check.entryId, list);
+    }
+    const entries = [];
+    for (const e of targets) {
+        const lintFindings = lintByEntry.get(e.id) ?? [];
+        const staleFindings = staleByEntry.get(e.id) ?? [];
+        const raw = [];
+        for (const f of lintFindings) {
+            raw.push({
+                severity: normaliseLintSeverity(f.severity),
+                category: f.code,
+                field: f.field,
+                message: f.message,
+                sources: ['knowledge lint'],
+                ...(f.stubSuggestion ? { stubSuggestion: f.stubSuggestion } : {}),
+            });
+        }
+        for (const f of staleFindings) {
+            raw.push({
+                severity: outcomeToSeverity(f.outcome),
+                category: `knowledge-stale.${f.outcome}`,
+                field: f.reference.kind ?? 'reference',
+                message: f.message,
+                sources: ['knowledge stale'],
+                ...(f.suggestion ? { fixSuggestion: f.suggestion } : {}),
+            });
+        }
+        const deterministicFindings = dedupeFindings(raw);
+        entries.push({
+            entryId: e.id,
+            entryType: String(e.type),
+            title: e.title ?? e.id,
+            verdict: deriveVerdict(deterministicFindings),
+            deterministicFindings,
+            llmFindings: [],
+            suggestedActions: deriveSuggestedActions(e.id, deterministicFindings),
+        });
+    }
+    const summary = entries.reduce((acc, e) => {
+        acc[e.verdict] += 1;
+        acc.total += 1;
+        return acc;
+    }, { ok: 0, minor: 0, stale: 0, broken: 0, total: 0 });
+    const generatedAt = new Date().toISOString();
+    return {
+        auditId: `audit-${generatedAt.replace(/[:.]/g, '-')}`,
+        generatedAt,
+        llmEnriched: false,
+        llmProviderId: null,
+        entries,
+        skipped,
+        summary,
+    };
+}
+function safeBuildStaleReport(inspection) {
+    try {
+        return buildKnowledgeStaleReport(inspection);
+    }
+    catch {
+        // The stale walker touches the filesystem; degrade to no-stale rather than
+        // failing the audit when index access throws.
+        return null;
+    }
+}
+function normaliseLintSeverity(s) {
+    if (s === KnowledgeLintSeverity.Warning)
+        return 'warn';
+    return 'info';
+}
+function outcomeToSeverity(o) {
+    if (o === ReferenceCheckOutcome.Missing)
+        return 'error';
+    if (o === ReferenceCheckOutcome.Stale)
+        return 'warn';
+    return 'info';
+}
+function dedupeFindings(raw) {
+    const byKey = new Map();
+    for (const f of raw) {
+        const key = `${f.category}::${f.field}::${f.message}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, { ...f, sources: [...f.sources] });
+            continue;
+        }
+        const sources = Array.from(new Set([...existing.sources, ...f.sources]));
+        byKey.set(key, {
+            ...existing,
+            sources,
+            severity: maxSeverity(existing.severity, f.severity),
+        });
+    }
+    return Array.from(byKey.values()).sort((a, b) => {
+        const order = { error: 0, warn: 1, info: 2 };
+        return order[a.severity] - order[b.severity] || a.category.localeCompare(b.category);
+    });
+}
+function maxSeverity(a, b) {
+    const rank = { info: 0, warn: 1, error: 2 };
+    return rank[a] >= rank[b] ? a : b;
+}
+function deriveVerdict(findings) {
+    if (findings.some((f) => f.severity === 'error'))
+        return 'broken';
+    if (findings.some((f) => f.severity === 'warn'))
+        return 'stale';
+    if (findings.some((f) => f.severity === 'info'))
+        return 'minor';
+    return 'ok';
+}
+function deriveSuggestedActions(entryId, findings) {
+    const actions = [];
+    const missingRef = findings.find((f) => f.category === `knowledge-stale.${ReferenceCheckOutcome.Missing}`);
+    const staleRef = findings.find((f) => f.category === `knowledge-stale.${ReferenceCheckOutcome.Stale}`);
+    const obsolete = findings.find((f) => f.category.includes('obsolete-entry'));
+    const summaryMissing = findings.find((f) => f.category === 'knowledge.summary-missing');
+    const hasError = findings.some((f) => f.severity === 'error');
+    const hasWarn = findings.some((f) => f.severity === 'warn');
+    if (missingRef) {
+        actions.push({
+            kind: 'edit',
+            target: entryId,
+            note: 'A referenced symbol/file no longer exists — update the reference or remove it.',
+        });
+    }
+    if (staleRef) {
+        actions.push({
+            kind: 'edit',
+            target: entryId,
+            note: 'A referenced symbol moved or was renamed — update the reference to point at the new location.',
+        });
+    }
+    if (obsolete) {
+        actions.push({
+            kind: 'retire',
+            target: entryId,
+            note: 'Entry classified as obsolete — confirm and remove, or refresh and re-tag.',
+        });
+    }
+    if (summaryMissing) {
+        actions.push({
+            kind: 'edit',
+            target: entryId,
+            note: 'Add a one-sentence summary so consumers can grok the entry without opening it.',
+        });
+    }
+    if (hasError && actions.length === 0) {
+        actions.push({
+            kind: 'investigate',
+            target: entryId,
+            note: 'Entry has error-level findings; review and fix before next consumption.',
+        });
+    }
+    if (!hasError && hasWarn && actions.length === 0) {
+        actions.push({
+            kind: 'edit',
+            target: entryId,
+            note: 'Address warning-level findings to keep the entry aligned with current code.',
+        });
+    }
+    return actions;
+}

package/dist/audit/knowledge-fix-plan-llm.d.ts

@@ -0,0 +1,11 @@
+import { type IAiProvider } from '@shrkcrft/ai';
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IKnowledgeFixPlan } from './knowledge-fix-plan.js';
+export interface IEnrichKnowledgeFixPlanOptions {
+    provider: IAiProvider;
+    inspection: ISharkcraftInspection;
+    maxTokensPerEntry?: number;
+    onPerEntryError?: (entryId: string, error: Error) => void;
+}
+export declare function enrichKnowledgeFixPlanWithLlm(plan: IKnowledgeFixPlan, options: IEnrichKnowledgeFixPlanOptions): Promise<IKnowledgeFixPlan>;
+//# sourceMappingURL=knowledge-fix-plan-llm.d.ts.map

package/dist/audit/knowledge-fix-plan-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-fix-plan-llm.d.ts","sourceRoot":"","sources":["../../src/audit/knowledge-fix-plan-llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA4B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE3F,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,qBAAqB,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC3D;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAuC5B"}

package/dist/audit/knowledge-fix-plan-llm.js

@@ -0,0 +1,141 @@
+import { AiMessageRole } from '@shrkcrft/ai';
+export async function enrichKnowledgeFixPlanWithLlm(plan, options) {
+    const byEntry = new Map();
+    for (const fix of plan.fixes) {
+        const list = byEntry.get(fix.entryId) ?? [];
+        list.push(fix);
+        byEntry.set(fix.entryId, list);
+    }
+    const enriched = [];
+    for (const [entryId, fixes] of byEntry.entries()) {
+        const entry = options.inspection.knowledgeEntries.find((e) => e.id === entryId);
+        if (!entry) {
+            enriched.push(...fixes);
+            continue;
+        }
+        try {
+            const messages = buildFixSuggestionMessages(entry, fixes);
+            const res = await options.provider.send({
+                messages,
+                maxTokens: options.maxTokensPerEntry ?? 1024,
+            });
+            if (!res.ok) {
+                options.onPerEntryError?.(entryId, res.error);
+                enriched.push(...fixes);
+                continue;
+            }
+            const suggestions = parseSuggestionMap(res.value.content);
+            for (const fix of fixes) {
+                const key = suggestionKey(fix.findingCategory, fix.finding);
+                const suggestion = suggestions.get(key) ?? suggestions.get(fix.findingCategory) ?? null;
+                enriched.push(suggestion ? { ...fix, llmSuggestion: suggestion } : fix);
+            }
+        }
+        catch (e) {
+            options.onPerEntryError?.(entryId, e);
+            enriched.push(...fixes);
+        }
+    }
+    return { ...plan, fixes: enriched };
+}
+function suggestionKey(category, finding) {
+    return `${category}::${finding.slice(0, 80)}`;
+}
+function buildFixSuggestionMessages(entry, fixes) {
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            'You are a senior maintainer sharpening fix recommendations for a SharkCraft knowledge entry.',
+            'For each finding listed, the deterministic layer has already produced a sound agent prompt with a generic placeholder.',
+            'Replace those placeholders with a CONCRETE recommendation grounded in the supplied entry.',
+            '',
+            'Per finding category, prefer to emit:',
+            '  - knowledge.summary-missing   → a concrete one-sentence summary in single quotes.',
+            '  - knowledge.tags-missing      → 1–3 concrete kebab-case tags as an array.',
+            '  - knowledge.title-missing     → a concrete short title in single quotes.',
+            '  - knowledge-stale.stale       → name the likely replacement symbol/path if you can ground it.',
+            '  - knowledge-stale.missing     → confirm removal or name a likely replacement.',
+            '  - any other category          → a one-sentence concrete suggestion.',
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no fences:',
+            '{',
+            '  "suggestions": [',
+            '    {',
+            '      "findingCategory": "<exact category>",',
+            '      "finding": "<first 80 chars of the original finding message>",',
+            '      "suggestion": "<one to three sentences, concrete>"',
+            '    }',
+            '  ]',
+            '}',
+            'Omit entries you cannot meaningfully sharpen — better silence than ceremony.',
+        ].join('\n'),
+    };
+    const user = {
+        role: AiMessageRole.User,
+        content: [
+            `# Knowledge entry: ${entry.id}`,
+            `type: ${String(entry.type)}`,
+            `title: ${entry.title ?? '(none)'}`,
+            `summary: ${entry.summary ?? '(none)'}`,
+            `tags: ${(entry.tags ?? []).join(', ') || '(none)'}`,
+            ``,
+            `## Content (truncated)`,
+            '```',
+            truncate(String(entry.content ?? '(no content)'), 3072),
+            '```',
+            ``,
+            `## Fixes needing sharpening`,
+            fixes
+                .map((f, i) => `### Fix ${i + 1}: ${f.findingCategory}\nfinding: ${f.finding}\ncurrent agent prompt:\n${f.agentPrompt}`)
+                .join('\n\n'),
+        ].join('\n'),
+    };
+    return [system, user];
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n… [truncated ${s.length - max} chars]`;
+}
+function parseSuggestionMap(raw) {
+    const out = new Map();
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const first = jsonText.indexOf('{');
+        const last = jsonText.lastIndexOf('}');
+        if (first < 0 || last <= first)
+            return out;
+        try {
+            parsed = JSON.parse(jsonText.slice(first, last + 1));
+        }
+        catch {
+            return out;
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return out;
+    const list = parsed.suggestions;
+    if (!Array.isArray(list))
+        return out;
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const category = typeof obj.findingCategory === 'string' ? obj.findingCategory.trim() : '';
+        const finding = typeof obj.finding === 'string' ? obj.finding.trim() : '';
+        const suggestion = typeof obj.suggestion === 'string' ? obj.suggestion.trim() : '';
+        if (!category || !suggestion)
+            continue;
+        const key = finding ? suggestionKey(category, finding) : category;
+        out.set(key, suggestion);
+    }
+    return out;
+}

package/dist/audit/knowledge-fix-plan.d.ts

@@ -0,0 +1,41 @@
+import type { IKnowledgeAuditReport, KnowledgeAuditFindingSeverity } from './knowledge-audit.js';
+export type KnowledgeFixConfidence = 'high' | 'medium' | 'low';
+export interface IKnowledgeFixInstruction {
+    entryId: string;
+    findingCategory: string;
+    finding: string;
+    severity: KnowledgeAuditFindingSeverity;
+    intent: string;
+    agentPrompt: string;
+    confidence: KnowledgeFixConfidence;
+    source: 'deterministic' | 'llm';
+    llmSuggestion?: string;
+}
+export interface IKnowledgeSkippedFinding {
+    entryId: string;
+    findingCategory: string;
+    finding: string;
+    reason: string;
+}
+export interface IKnowledgeFixPlan {
+    fixPlanId: string;
+    generatedAt: string;
+    auditId: string;
+    /**
+     * Knowledge entries are sourced from many files (config-driven). The plan
+     * points the agent to the registered config so they can find each entry's
+     * literal source by id.
+     */
+    sourceHint: string;
+    fixes: readonly IKnowledgeFixInstruction[];
+    skipped: readonly IKnowledgeSkippedFinding[];
+    summary: {
+        fixCount: number;
+        highConfidence: number;
+        mediumConfidence: number;
+        lowConfidence: number;
+        skipped: number;
+    };
+}
+export declare function buildKnowledgeFixPlan(report: IKnowledgeAuditReport): IKnowledgeFixPlan;
+//# sourceMappingURL=knowledge-fix-plan.d.ts.map

package/dist/audit/knowledge-fix-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-fix-plan.d.ts","sourceRoot":"","sources":["../../src/audit/knowledge-fix-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,qBAAqB,EAErB,6BAA6B,EAC9B,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE/D,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,6BAA6B,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3C,OAAO,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC7C,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAKD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,iBAAiB,CAiCtF"}