llm-wiki-kit 0.2.13 → 0.2.15

package/src/maintenance.js

@@ -1,6 +1,7 @@
 import { readdir, unlink } from 'fs/promises';
 import { join, relative } from 'path';
-import { appendText, exists, kitDataDir, readJson, readText, sha256, writeTextIfMissing } from './fs-utils.js';
+import { evidenceRefsFromEntry, normalizeEvidenceRefs, parseEvidenceRefsField } from './evidence.js';
+import { appendText, exists, kitDataDir, readJson, readText, sha256, writeText, writeTextIfMissing } from './fs-utils.js';
 import { classifyTurn, isMaintenanceRelatedQuery } from './capture-policy.js';
 import { redactText, summarizeForStorage } from './redaction.js';
 import { buildEntryFromTurnState, hasRecoverableTurnState } from './state.js';
@@ -24,7 +25,7 @@ function queueHeader() {
     '',
     'Candidates to merge into durable wiki pages. Hooks only create candidates; the active agent reviews and merges them into existing durable wiki documents.',
     '',
-    'Status values: pending, done, skipped.',
+    'Status values: pending, approved, done, skipped.',
     '',
   ].join('\n');
 }
@@ -70,18 +71,51 @@ function itemId(projectRoot, source, entry) {
 }
 
 function itemBlock(item) {
-  return [
+  const fields = {
+    ...(item.fields || {}),
+    id: item.id,
+    created_at: item.created_at,
+    last_seen_at: item.last_seen_at,
+    source: item.source,
+    suggested_target: item.suggested_target,
+    target: item.target,
+    reviewed_at: item.reviewed_at,
+    review_note: item.review_note,
+    evidence_refs: normalizeEvidenceRefs(item.evidence_refs).length > 0
+      ? JSON.stringify(normalizeEvidenceRefs(item.evidence_refs))
+      : item.fields?.evidence_refs,
+    reason: item.reason,
+    result_missing: item.result_missing ? 'true' : 'false',
+  };
+  const order = [
+    'id',
+    'created_at',
+    'last_seen_at',
+    'source',
+    'suggested_target',
+    'target',
+    'reviewed_at',
+    'review_note',
+    'evidence_refs',
+    'reason',
+    'result_missing',
+  ];
+  const lines = [
     `## ${item.status || 'pending'} - ${item.topic || 'maintenance item'}`,
     '',
-    `- id: ${item.id}`,
-    `- created_at: ${item.created_at}`,
-    `- last_seen_at: ${item.last_seen_at}`,
-    `- source: ${item.source}`,
-    `- suggested_target: ${item.suggested_target}`,
-    `- reason: ${item.reason}`,
-    `- result_missing: ${item.result_missing ? 'true' : 'false'}`,
-    '',
-  ].join('\n');
+  ];
+  const emitted = new Set();
+  for (const key of order) {
+    if (fields[key] === undefined || fields[key] === '') continue;
+    lines.push(`- ${key}: ${fields[key]}`);
+    emitted.add(key);
+  }
+  for (const key of Object.keys(fields).sort()) {
+    if (emitted.has(key) || fields[key] === undefined || fields[key] === '') continue;
+    lines.push(`- ${key}: ${fields[key]}`);
+  }
+  lines.push('');
+  return lines.join('\n');
 }
 
 export async function readMaintenanceQueue(projectRoot) {
@@ -96,7 +130,7 @@ export async function readMaintenanceQueue(projectRoot) {
   };
 
   for (const line of text.split(/\r?\n/)) {
-    const header = line.match(/^##\s+(pending|done|skipped)\s+-\s*(.*)$/);
+    const header = line.match(/^##\s+(pending|approved|done|skipped)\s+-\s*(.*)$/);
     if (header) {
       pushCurrent();
       current = {
@@ -107,7 +141,7 @@ export async function readMaintenanceQueue(projectRoot) {
       continue;
     }
     if (!current) continue;
-    const field = line.match(/^-\s+([a-z_]+):\s*(.*)$/);
+    const field = line.match(/^-\s+([A-Za-z0-9_-]+):\s*(.*)$/);
     if (field) {
       current.fields[field[1]] = field[2].trim();
     }
@@ -119,19 +153,35 @@ export async function readMaintenanceQueue(projectRoot) {
     exists: await exists(path),
     items: items.map((item) => ({
       ...item.fields,
+      fields: item.fields,
       status: item.status,
       topic: item.topic,
+      evidence_refs: parseEvidenceRefsField(item.fields.evidence_refs),
+      evidenceRefs: parseEvidenceRefsField(item.fields.evidence_refs),
       result_missing: String(item.fields.result_missing || '').toLowerCase() === 'true',
     })),
   };
 }
 
+async function writeMaintenanceQueue(projectRoot, items) {
+  const content = [
+    queueHeader().trimEnd(),
+    '',
+    ...items.map((item) => itemBlock(item).trimEnd()),
+    '',
+  ].join('\n');
+  const path = queuePath(projectRoot);
+  await writeText(path, content);
+  return path;
+}
+
 export function summarizeMaintenanceQueue(queue, options = {}) {
   const staleDays = options.staleDays ?? DEFAULT_STALE_PENDING_DAYS;
   const pendingLimit = options.pendingLimit ?? DEFAULT_PENDING_LIMIT;
   const reviewPendingLimit = options.reviewPendingLimit ?? DEFAULT_REVIEW_PENDING_LIMIT;
   const reviewIntervalDays = options.reviewIntervalDays ?? DEFAULT_REVIEW_INTERVAL_DAYS;
   const pending = queue.items.filter((item) => item.status === 'pending');
+  const approved = queue.items.filter((item) => item.status === 'approved');
   const staleCutoff = Date.now() - staleDays * 24 * 60 * 60 * 1000;
   const stalePending = pending.filter((item) => {
     const time = Date.parse(item.created_at || item.last_seen_at || '');
@@ -143,6 +193,7 @@ export function summarizeMaintenanceQueue(queue, options = {}) {
     .filter(Number.isFinite);
   const lastReviewMs = reviewTimes.length > 0 ? Math.max(...reviewTimes) : null;
   const reviewReasons = [];
+  if (approved.length > 0) reviewReasons.push(`approved queue has ${approved.length} item(s) ready for durable wiki merge`);
   if (pending.length >= reviewPendingLimit) reviewReasons.push(`pending queue has ${pending.length} items (threshold ${reviewPendingLimit})`);
   if (stalePending.length > 0) reviewReasons.push(`${stalePending.length} pending item(s) older than ${staleDays} days`);
   if (pending.some((item) => item.result_missing)) reviewReasons.push('pending recovered turn state needs review');
@@ -153,9 +204,11 @@ export function summarizeMaintenanceQueue(queue, options = {}) {
     path: queue.path,
     exists: queue.exists,
     items: queue.items,
+    approved,
     pending,
     done: queue.items.filter((item) => item.status === 'done'),
     skipped: queue.items.filter((item) => item.status === 'skipped'),
+    approvedCount: approved.length,
     pendingCount: pending.length,
     doneCount: queue.items.filter((item) => item.status === 'done').length,
     skippedCount: queue.items.filter((item) => item.status === 'skipped').length,
@@ -246,6 +299,47 @@ export async function appendMaintenanceItem(projectRoot, item) {
   return { created: true, path, id: item.id };
 }
 
+export async function updateMaintenanceItem(projectRoot, id, action, options = {}) {
+  const allowed = new Set(['approve', 'done', 'skip']);
+  if (!allowed.has(action)) throw new Error(`unsupported maintenance action: ${action}`);
+  const queue = await readMaintenanceQueue(projectRoot);
+  const index = queue.items.findIndex((item) => item.id === id);
+  if (index === -1) throw new Error(`maintenance item not found: ${id}`);
+  if ((action === 'approve' || action === 'done') && !options.target && !queue.items[index].target) {
+    throw new Error(`--target is required for maintenance --${action}`);
+  }
+  const now = nowIso();
+  const current = queue.items[index];
+  const next = {
+    ...current,
+    fields: { ...(current.fields || {}) },
+    status: action === 'approve' ? 'approved' : (action === 'done' ? 'done' : 'skipped'),
+    last_seen_at: now,
+    reviewed_at: now,
+    target: options.target || current.target || '',
+    review_note: sanitizeField(options.note || current.review_note || '', 500),
+  };
+  if (next.target) next.fields.target = next.target;
+  next.fields.last_seen_at = next.last_seen_at;
+  next.fields.reviewed_at = next.reviewed_at;
+  if (next.review_note) next.fields.review_note = next.review_note;
+  const refs = normalizeEvidenceRefs(options.evidence_refs || current.evidence_refs || current.evidenceRefs || []);
+  if (refs.length > 0) {
+    next.evidence_refs = refs;
+    next.fields.evidence_refs = JSON.stringify(refs);
+  }
+  queue.items[index] = next;
+  await writeMaintenanceQueue(projectRoot, queue.items);
+  return {
+    workspace: projectRoot,
+    path: queue.path,
+    id,
+    status: next.status,
+    target: next.target || null,
+    reviewed_at: next.reviewed_at,
+  };
+}
+
 export async function recordMaintenanceForEntry(projectRoot, entry, options = {}) {
   const source = relativeSource(projectRoot, options.source || options.queryPath || options.decisionPath || options.liveQaPath || '');
   if (!source && !options.resultMissing) return { created: false, reason: 'missing-source' };
@@ -259,6 +353,7 @@ export async function recordMaintenanceForEntry(projectRoot, entry, options = {}
     last_seen_at: created,
     source,
     suggested_target: options.suggestedTarget || inferSuggestedTarget(entry, source),
+    evidence_refs: evidenceRefsFromEntry(entry, { projectRoot }),
     reason: sanitizeField(options.reason || `Captured ${options.eventName || 'turn'} needs durable wiki review.`, 300),
     result_missing: Boolean(options.resultMissing),
   };
@@ -313,31 +408,34 @@ export function formatMaintenanceContext(summary, options = {}) {
   const eventName = options.eventName || '';
   const defaultLimit = eventName === 'SessionStart' || eventName === 'InstructionsLoaded' ? 1 : 5;
   const limit = options.limit || defaultLimit;
-  let pending = summary.pending.slice(0, limit);
+  const reviewCandidates = [...(summary.approved || []), ...(summary.pending || [])];
+  let pending = reviewCandidates.slice(0, limit);
 
   if (eventName === 'UserPromptSubmit') {
-    if (!isMaintenanceRelatedQuery(options.query || '', summary.pending)) return '';
-    pending = summary.pending.slice(0, 1);
+    if (!isMaintenanceRelatedQuery(options.query || '', reviewCandidates)) return '';
+    pending = reviewCandidates.slice(0, 1);
   } else if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') {
     return '';
   }
 
+  const reviewCount = (summary.approvedCount || 0) + (summary.pendingCount || 0);
   const lines = language === 'ko'
     ? [
         'LLM Wiki maintenance status:',
         `- review due: yes (${(summary.reviewReasons || []).slice(0, 2).join('; ') || 'periodic review threshold met'}).`,
-        `- pending review items: ${summary.pendingCount}. 현재 요청이 우선이며, 관련 있을 때만 durable wiki 정리에 사용한다.`,
+        `- approved/pending review items: ${reviewCount}. 현재 요청이 우선이며, 관련 있을 때만 durable wiki 정리에 사용한다.`,
       ]
     : [
         'LLM Wiki maintenance status:',
         `- review due: yes (${(summary.reviewReasons || []).slice(0, 2).join('; ') || 'periodic review threshold met'}).`,
-        `- pending review items: ${summary.pendingCount}. The current request comes first; use this only when it is relevant to durable wiki cleanup.`,
+        `- approved/pending review items: ${reviewCount}. The current request comes first; use this only when it is relevant to durable wiki cleanup.`,
       ];
   for (const item of pending) {
-    lines.push(`- ${item.topic || item.id}: ${item.suggested_target}; source=${item.source}${item.result_missing ? '; result missing' : ''}`);
+    const target = item.target || item.suggested_target;
+    lines.push(`- ${item.status}: ${item.topic || item.id}: ${target}; source=${item.source}${item.result_missing ? '; result missing' : ''}`);
   }
-  if (summary.pending.length > pending.length) {
-    lines.push(`- ${summary.pending.length - pending.length} more pending item(s) available in llm-wiki/outputs/maintenance/queue.md.`);
+  if (reviewCandidates.length > pending.length) {
+    lines.push(`- ${reviewCandidates.length - pending.length} more review item(s) available in llm-wiki/outputs/maintenance/queue.md.`);
   }
   return lines.join('\n');
 }
@@ -346,6 +444,7 @@ export function formatMaintenanceResult(summary) {
   const lines = [
     'llm-wiki maintenance',
     `- queue: ${summary.path}`,
+    `- approved: ${summary.approvedCount || 0}`,
     `- pending: ${summary.pendingCount}`,
     `- stale pending: ${summary.stalePendingCount || 0}`,
     `- done: ${summary.doneCount}`,
@@ -355,6 +454,12 @@ export function formatMaintenanceResult(summary) {
   if ((summary.reviewReasons || []).length > 0) {
     lines.push(`- review reasons: ${summary.reviewReasons.join('; ')}`);
   }
+  if ((summary.approved || []).length > 0) {
+    lines.push('', 'Approved:');
+    for (const item of summary.approved.slice(0, 10)) {
+      lines.push(`- ${item.topic || item.id}: ${item.source} -> ${item.target || item.suggested_target}`);
+    }
+  }
   if (summary.pending.length > 0) {
     lines.push('', 'Pending:');
     for (const item of summary.pending.slice(0, 10)) {

package/src/project.js

@@ -9,6 +9,7 @@ import {
   writeTextIfMissing,
 } from './fs-utils.js';
 import { LLM_WIKI_DIRS } from './constants.js';
+import { evidenceRefsFromEntry, frontmatterEvidenceRefs } from './evidence.js';
 import { formatMaintenanceContext, maintenanceSummary } from './maintenance.js';
 import { normalizeForStorage, redactText, summarizeForStorage } from './redaction.js';
 import { gitignore, indexPage, llmWikiAgents, logPage, memoryPage, procedure, rootAgentsPolicy } from './templates.js';
@@ -107,7 +108,8 @@ export async function writeQueryPage(projectRoot, entry) {
   const slug = slugify(entry.question, 'query');
   const path = join(projectRoot, 'llm-wiki', 'wiki', 'queries', `${day}-${slug}.md`);
   if (await exists(path)) return path;
-  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "query"\nsource_ids: []\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\nmemory_type: "episodic"\nimportance: 2\nlast_verified: "unknown"\nsupersedes: []\nsuperseded_by: []\n---\n\n# ${entry.topic || entry.question.slice(0, 80)}\n\n## Question\n${entry.question}\n\n## Answer Summary\n${entry.result || '(not captured)'}\n\n## Work Notes\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Related Pages\n- [[index]]\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
+  const evidenceRefs = frontmatterEvidenceRefs(evidenceRefsFromEntry(entry, { projectRoot }));
+  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "query"\nsource_ids: []\n${evidenceRefs}\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\nmemory_type: "episodic"\nimportance: 2\nlast_verified: "unknown"\nsupersedes: []\nsuperseded_by: []\n---\n\n# ${entry.topic || entry.question.slice(0, 80)}\n\n## Question\n${entry.question}\n\n## Answer Summary\n${entry.result || '(not captured)'}\n\n## Work Notes\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Related Pages\n- [[index]]\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
   await writeTextIfMissing(path, redactText(content, 12000));
   return path;
 }
@@ -120,7 +122,8 @@ export async function writeDecisionPage(projectRoot, entry) {
   const slug = slugify(entry.topic || entry.question || 'decision', 'decision');
   const path = join(projectRoot, 'llm-wiki', 'wiki', 'decisions', `${day}-${slug}.md`);
   if (await exists(path)) return path;
-  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "decision"\nsource_ids: []\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\nmemory_type: "semantic"\nimportance: 4\nlast_verified: "unknown"\nsupersedes: []\nsuperseded_by: []\n---\n\n# ${entry.topic || 'Decision'}\n\n## Decision\n${entry.result || '(captured from assistant response; review needed)'}\n\n## Context\n${entry.question || '(not captured)'}\n\n## Evidence\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Open Questions\n${entry.followUp || '(none captured)'}\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
+  const evidenceRefs = frontmatterEvidenceRefs(evidenceRefsFromEntry(entry, { projectRoot }));
+  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "decision"\nsource_ids: []\n${evidenceRefs}\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\nmemory_type: "semantic"\nimportance: 4\nlast_verified: "unknown"\nsupersedes: []\nsuperseded_by: []\n---\n\n# ${entry.topic || 'Decision'}\n\n## Decision\n${entry.result || '(captured from assistant response; review needed)'}\n\n## Context\n${entry.question || '(not captured)'}\n\n## Evidence\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Open Questions\n${entry.followUp || '(none captured)'}\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
   await writeTextIfMissing(path, redactText(content, 12000));
   return path;
 }

package/src/templates.js

@@ -22,6 +22,15 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - Record verification commands, evidence files, and uncertainty. Mark inference explicitly and preserve contradictions in Open Questions or Contradictions.
 - Never store credentials, tokens, passwords, private keys, or raw \`.env\` contents. Store only redacted summaries when needed.
 
+### llm-wiki-kit Implementation Plans
+
+- When implementing an approved llm-wiki-kit plan, read the complete plan first and treat it as the implementation source of truth.
+- A valid plan must include history/context, lifecycle intent, exact source paths, test strategy, release verification, and commit/push requirements.
+- Do not implement feature lists in isolation. Each feature must be integrated into the hook-first, answer-first, local Markdown knowledge lifecycle.
+- \`llms.txt\`/exports are not passive artifacts; they are agent onboarding, handoff, retrieval-eval, and external-consumption manifests.
+- \`evidence_refs\`, maintenance review, context ranking explanations, export, and eval must share the same durable wiki visibility policy.
+- Never store npm tokens, WinRM credentials, private keys, raw \`.env\`, or full raw transcripts in wiki, logs, generated exports, or commits.
+
 <!-- llm-wiki-kit:end -->
 `;
 }
@@ -62,6 +71,15 @@ These rules replace older OMX/OMC/\`omx_wiki/\` rules for this project.
 - Preserve contradictions in \`Contradictions\` or \`Open Questions\`; do not overwrite them silently.
 - Do not store credentials, tokens, passwords, private keys, or raw \`.env\` contents in wiki.
 
+### llm-wiki-kit Implementation Plans
+
+- When implementing an approved llm-wiki-kit plan, read the complete plan first and treat it as the implementation source of truth.
+- A valid plan must include history/context, lifecycle intent, exact source paths, test strategy, release verification, and commit/push requirements.
+- Do not implement feature lists in isolation. Each feature must be integrated into the hook-first, answer-first, local Markdown knowledge lifecycle.
+- \`llms.txt\`/exports are not passive artifacts; they are agent onboarding, handoff, retrieval-eval, and external-consumption manifests.
+- \`evidence_refs\`, maintenance review, context ranking explanations, export, and eval must share the same durable wiki visibility policy.
+- Never store npm tokens, WinRM credentials, private keys, raw \`.env\`, or full raw transcripts in wiki, logs, generated exports, or commits.
+
 ## Page Format
 Use YAML frontmatter when creating wiki pages:
 
@@ -70,6 +88,7 @@ Use YAML frontmatter when creating wiki pages:
 title: ""
 type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
 source_ids: []
+evidence_refs: []
 status: "draft | reviewed | stale | archived"
 last_updated: "YYYY-MM-DD"
 confidence: "high | medium | low"
@@ -131,6 +150,7 @@ export function memoryPage() {
 title: "LLM Wiki Memory"
 type: "context"
 source_ids: []
+evidence_refs: []
 status: "draft"
 last_updated: "unknown"
 confidence: "medium"

package/src/update.js

@@ -26,6 +26,7 @@ async function runCommand(command, args, options = {}) {
   const label = options.label || commandLine(command, args);
   const startedAt = Date.now();
   const windows = isWindows(options);
+  const useShell = options.shell !== undefined ? options.shell : windows;
   const detached = !windows;
   let stdout = '';
   let stderr = '';
@@ -69,7 +70,7 @@ async function runCommand(command, args, options = {}) {
       child = spawn(command, args, {
         detached,
         env: options.env || process.env,
-        shell: windows,
+        shell: useShell,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
     } catch (error) {
@@ -455,6 +456,7 @@ export async function update(options = {}) {
       LLM_WIKI_KIT_PROGRESS: process.env.LLM_WIKI_KIT_PROGRESS || '1',
     },
     label: 'post-update',
+    shell: false,
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');

package/src/wiki-eval.js

@@ -0,0 +1,110 @@
+import { join } from 'path';
+import { exists, readJson } from './fs-utils.js';
+import { buildContextPack } from './wiki-search.js';
+import { DURABLE_VISIBILITY_POLICY } from './wiki-visibility.js';
+
+export const DEFAULT_EVAL_FIXTURE_REL = 'llm-wiki/evals/retrieval.json';
+
+function normalizePath(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function fixturePath(projectRoot, options = {}) {
+  return options.fixture || join(projectRoot, DEFAULT_EVAL_FIXTURE_REL);
+}
+
+function normalizeFixture(raw) {
+  const queries = Array.isArray(raw?.queries) ? raw.queries : [];
+  return queries.map((item) => ({
+    query: String(item?.query || '').trim(),
+    expected: Array.isArray(item?.expected) ? item.expected.map(normalizePath).filter(Boolean) : [],
+    unexpected: Array.isArray(item?.unexpected) ? item.unexpected.map(normalizePath).filter(Boolean) : [],
+  })).filter((item) => item.query);
+}
+
+export async function runEval(projectRoot, options = {}) {
+  const path = fixturePath(projectRoot, options);
+  if (!(await exists(path))) {
+    return {
+      workspace: projectRoot,
+      fixture: path,
+      ok: true,
+      status: 'missing-fixture',
+      message: 'no fixture found',
+      visibilityPolicy: DURABLE_VISIBILITY_POLICY,
+      warnings: [],
+      queries: [],
+    };
+  }
+  const fixture = await readJson(path, null);
+  if (!fixture) throw new Error(`invalid eval fixture JSON: ${path}`);
+  const limit = Number(options.limit || 5);
+  const rows = [];
+  for (const item of normalizeFixture(fixture)) {
+    const pack = await buildContextPack(projectRoot, item.query, {
+      ...options,
+      limit,
+      expand: options.expand !== false,
+    });
+    const topHits = pack.hits.map((hit) => hit.path);
+    const hitSet = new Set(topHits);
+    const expectedHits = item.expected.filter((expected) => hitSet.has(expected));
+    const missedExpected = item.expected.filter((expected) => !hitSet.has(expected));
+    const unexpectedHits = item.unexpected.filter((unexpected) => hitSet.has(unexpected));
+    rows.push({
+      query: item.query,
+      ok: missedExpected.length === 0 && unexpectedHits.length === 0,
+      recall: item.expected.length === 0 ? 1 : expectedHits.length / item.expected.length,
+      expected: item.expected,
+      expectedHits,
+      missedExpected,
+      unexpected: item.unexpected,
+      unexpectedHits,
+      topHits,
+      search: pack.search,
+    });
+  }
+  const warnings = [];
+  if (fixture.visibilityPolicy && fixture.visibilityPolicy !== DURABLE_VISIBILITY_POLICY) {
+    warnings.push(`fixture visibility policy ${fixture.visibilityPolicy} differs from export/eval policy ${DURABLE_VISIBILITY_POLICY}`);
+  }
+  return {
+    workspace: projectRoot,
+    fixture: path,
+    ok: rows.every((row) => row.ok),
+    status: 'evaluated',
+    visibilityPolicy: DURABLE_VISIBILITY_POLICY,
+    warnings,
+    queries: rows,
+  };
+}
+
+export function formatEvalResult(result) {
+  if (result.status === 'missing-fixture') {
+    return [
+      'llm-wiki eval',
+      `- workspace: ${result.workspace}`,
+      `- fixture: ${result.fixture}`,
+      '- result: no fixture found',
+    ].join('\n');
+  }
+  const lines = [
+    'llm-wiki eval',
+    `- workspace: ${result.workspace}`,
+    `- fixture: ${result.fixture}`,
+    `- result: ${result.ok ? 'ok' : 'failed'}`,
+    `- visibility policy: ${result.visibilityPolicy}`,
+    `- queries: ${result.queries.length}`,
+  ];
+  for (const warning of result.warnings || []) {
+    lines.push(`- warning: ${warning}`);
+  }
+  for (const row of result.queries) {
+    lines.push('', `## ${row.query}`);
+    lines.push(`- recall: ${row.expectedHits.length}/${row.expected.length}`);
+    lines.push(`- missed expected: ${row.missedExpected.join(', ') || 'none'}`);
+    lines.push(`- unexpected hits: ${row.unexpectedHits.join(', ') || 'none'}`);
+    lines.push(`- top hits: ${row.topHits.join(', ') || 'none'}`);
+  }
+  return lines.join('\n');
+}