llm-wiki-kit 0.2.14 → 0.2.16

package/src/evidence.js

@@ -0,0 +1,128 @@
+import { isAbsolute, relative, sep } from 'path';
+import { extractPathsFromText, hasSecretLikeText, isSensitivePath, redactText, summarizeForStorage } from './redaction.js';
+
+export const EVIDENCE_PREFIXES = new Set(['file', 'cmd', 'raw', 'url']);
+export const MAX_CMD_EVIDENCE_CHARS = 500;
+
+export function normalizeEvidenceRefs(value) {
+  if (!Array.isArray(value)) return [];
+  const refs = value
+    .map((item) => summarizeForStorage(String(item || ''), 700))
+    .map((item) => item.replace(/\s+/g, ' ').trim())
+    .filter(Boolean);
+  return [...new Set(refs)];
+}
+
+export function parseEvidenceRef(ref) {
+  const text = String(ref || '').trim();
+  const match = text.match(/^([a-z]+):([\s\S]*)$/i);
+  if (!match) return { raw: text, prefix: '', value: text };
+  return {
+    raw: text,
+    prefix: match[1].toLowerCase(),
+    value: match[2].trim(),
+  };
+}
+
+export function parseEvidenceRefsField(value) {
+  const text = String(value || '').trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) return normalizeEvidenceRefs(parsed);
+  } catch {
+    // Fall through to legacy comma/text parsing.
+  }
+  return normalizeEvidenceRefs(text.split(',').map((item) => item.trim()));
+}
+
+export function frontmatterEvidenceRefs(refs) {
+  const normalized = normalizeEvidenceRefs(refs);
+  if (normalized.length === 0) return 'evidence_refs: []';
+  return ['evidence_refs:', ...normalized.map((ref) => `  - "${ref.replace(/"/g, '\\"')}"`)].join('\n');
+}
+
+function cleanCandidatePath(value) {
+  return String(value || '')
+    .replace(/^[-*]\s+/, '')
+    .replace(/^file:/i, '')
+    .replace(/[),.;:]+$/g, '')
+    .replace(/\\/g, '/')
+    .trim();
+}
+
+function isUsefulFileCandidate(value) {
+  const text = cleanCandidatePath(value);
+  if (!text || text.includes('://') || text.startsWith('cmd:') || text.startsWith('raw:')) return false;
+  if (isSensitivePath(text) || hasSecretLikeText(text)) return false;
+  return (
+    text.startsWith('llm-wiki/') ||
+    text.startsWith('src/') ||
+    text.startsWith('test/') ||
+    text.startsWith('docs/') ||
+    text.startsWith('bin/') ||
+    text.startsWith('examples/') ||
+    /^(?:README|AGENTS|CLAUDE|LICENSE|package(?:-lock)?|install)\.[A-Za-z0-9]+$/i.test(text) ||
+    /\.[A-Za-z0-9]{1,12}$/.test(text)
+  );
+}
+
+function relativeProjectPath(projectRoot, value) {
+  const cleaned = cleanCandidatePath(value);
+  if (!cleaned) return '';
+  if (projectRoot && cleaned.startsWith(projectRoot)) {
+    return relative(projectRoot, cleaned).split(sep).join('/');
+  }
+  return cleaned.replace(/^\.\//, '');
+}
+
+function addFileRefs(refs, projectRoot, text) {
+  for (const candidate of extractPathsFromText(text || '')) {
+    const rel = relativeProjectPath(projectRoot, candidate);
+    if (!isUsefulFileCandidate(rel)) continue;
+    if (isAbsolute(rel) || rel.split('/').includes('..')) continue;
+    refs.push(`file:${rel}`);
+  }
+}
+
+function decodeJsonString(value) {
+  try {
+    return JSON.parse(`"${value}"`);
+  } catch {
+    return value.replace(/\\"/g, '"');
+  }
+}
+
+function addCommandRefs(refs, text) {
+  const body = String(text || '');
+  const cmdRegex = /"cmd"\s*:\s*"((?:\\.|[^"\\])*)"/g;
+  let match = cmdRegex.exec(body);
+  while (match) {
+    const command = summarizeForStorage(decodeJsonString(match[1]).replace(/\s+/g, ' '), MAX_CMD_EVIDENCE_CHARS);
+    if (command && !hasSecretLikeText(command)) refs.push(`cmd:${command}`);
+    match = cmdRegex.exec(body);
+  }
+
+  for (const line of body.split(/\r?\n/)) {
+    const cleaned = line.replace(/^[-*]\s+/, '').trim();
+    const direct = cleaned.match(/^(?:Bash|Shell|Verification|Command):\s*(.+)$/i)?.[1];
+    const command = direct || (/^(?:node|npm|npx|git|llm-wiki|pytest|python|pnpm|yarn|vitest|jest|tsc)\b/.test(cleaned) ? cleaned : '');
+    if (!command) continue;
+    const safe = summarizeForStorage(command.replace(/\s+/g, ' '), MAX_CMD_EVIDENCE_CHARS);
+    if (safe && !hasSecretLikeText(safe)) refs.push(`cmd:${safe}`);
+  }
+}
+
+export function evidenceRefsFromEntry(entry, options = {}) {
+  const refs = [];
+  const projectRoot = options.projectRoot || '';
+  addFileRefs(refs, projectRoot, entry?.changedFiles);
+  addFileRefs(refs, projectRoot, entry?.work);
+  addCommandRefs(refs, entry?.verification);
+  addCommandRefs(refs, entry?.work);
+  return normalizeEvidenceRefs(refs).slice(0, options.limit || 20);
+}
+
+export function redactEvidenceRefs(refs) {
+  return normalizeEvidenceRefs(refs).map((ref) => redactText(ref, 700));
+}

package/src/hook.js

@@ -81,21 +81,35 @@ async function handleLegacyEagerStop(projectRoot, eventName, payload, entry) {
   }
 }
 
+function durableQueueReason(classification) {
+  if (classification.kind === 'explicit-durable') {
+    return 'Explicit durable documentation request did not have a detected durable wiki update.';
+  }
+  return 'Suggested durable wiki candidate did not have a detected durable wiki update.';
+}
+
+function durableFollowUp(entry, classification) {
+  if (!classification.suggestDurable) return entry.followUp;
+  const message = 'This turn is a durable wiki candidate. After the current answer, merge reusable facts into an existing durable wiki page or mark the maintenance item skipped.';
+  const current = String(entry.followUp || '').trim();
+  if (!current || current === '(not captured)') return message;
+  if (current.includes(message)) return current;
+  return `${current}\n${message}`;
+}
+
 async function handleAnswerFirstStop(projectRoot, eventName, payload, entry) {
   const classification = classifyTurn(entry, eventName);
   if (classification.archive) {
     const archiveEntry = {
       ...entry,
-      followUp: classification.suggestDurable
-        ? 'This turn may be worth preserving. If the user approves, merge it into an existing durable wiki page.'
-        : entry.followUp,
+      followUp: durableFollowUp(entry, classification),
     };
     const liveQaPath = await appendLiveQa(projectRoot, archiveEntry);
     if (classification.queueIfMissingDurable && !hasDetectedDurableWikiChange(entry)) {
       await recordMaintenanceForEntry(projectRoot, entry, {
         source: liveQaPath,
         eventName,
-        reason: 'Explicit durable documentation request did not have a detected durable wiki update.',
+        reason: durableQueueReason(classification),
       }).catch(() => {});
     }
     await appendWikiLog(projectRoot, `captured ${eventName}; archive=${relative(projectRoot, liveQaPath)}; classification=${classification.kind}`);

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),
   };
@@ -307,37 +402,55 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
   return output;
 }
 
+function isDurablePromotionCandidate(item) {
+  if (item?.status === 'approved') return true;
+  const text = `${item?.reason || ''} ${item?.fields?.reason || ''}`.toLowerCase();
+  return /suggested durable wiki candidate|precompact durable candidate|explicit durable documentation|durable wiki review/.test(text);
+}
+
+function shouldSurfacePromptMaintenance(summary, query, reviewCandidates) {
+  if (isMaintenanceRelatedQuery(query || '', reviewCandidates)) return true;
+  if ((summary.approvedCount || 0) > 0) return true;
+  if (reviewCandidates.some(isDurablePromotionCandidate)) return true;
+  if ((summary.pendingCount || 0) >= (summary.reviewPendingLimit || DEFAULT_REVIEW_PENDING_LIMIT)) return true;
+  if ((summary.stalePendingCount || 0) > 0) return true;
+  return reviewCandidates.some((item) => item.result_missing);
+}
+
 export function formatMaintenanceContext(summary, options = {}) {
   if (!summary.reviewDue) return '';
   const language = options.language === 'ko' ? 'ko' : 'en';
   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 (!shouldSurfacePromptMaintenance(summary, 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에 병합하거나 skipped로 표시한다.`,
       ]
     : [
         '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; when relevant or before ending the session, merge candidates into durable wiki pages or mark them skipped.`,
       ];
   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 +459,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 +469,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-state.js

@@ -254,7 +254,7 @@ function legacyProcedureSignals(name) {
   const common = [/^# .+ Procedure/m];
   const byName = {
     'ingest.md': [/^# Ingest Procedure/m, /wiki\/memory\.md/, /raw\/inbox|raw\/sources/],
-    'query.md': [/^# Query Procedure/m, /llm-wiki context/, /Save reusable answers|reusable answers/],
+    'query.md': [/^# Query Procedure/m, /llm-wiki context/, /Save reusable answers|reusable answers|Merge reusable facts|reusable facts/],
     'lint.md': [/^# Lint Procedure/m, /llm-wiki lint/, /stale pages|orphan pages/],
     'security.md': [/^# Security Procedure/m, /Redact authentication values|token|private keys/, /raw transcript capture/],
   };
@@ -359,12 +359,19 @@ function hasKitManagedSignal(text, descriptor) {
   return false;
 }
 
+function hasPatchableGeneratedSignal(text, descriptor) {
+  if (!hasLegacyGeneratedSignal(text, descriptor)) return false;
+  if (String(descriptor.id || '').startsWith('procedure-') && /^##\s+/m.test(text)) return false;
+  return true;
+}
+
 function canPatchDescriptor(state, descriptor, currentText, fileExists = true) {
   if (descriptor.mode === 'create-only') return !fileExists;
   if (descriptor.mode === 'marker') return replaceMarkedBlock(currentText, descriptor.content) !== null;
   return isRecordedManaged(state, descriptor, currentText) ||
     isKnownGeneratedContent(currentText, descriptor) ||
-    isLegacyGeneratedContent(currentText, descriptor);
+    isLegacyGeneratedContent(currentText, descriptor) ||
+    hasPatchableGeneratedSignal(currentText, descriptor);
 }
 
 function desiredTextForDescriptor(descriptor, currentText, fileExists = true) {

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

@@ -16,12 +16,21 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - Keep \`llm-wiki/wiki/memory.md\` short. Link to important documents instead of copying long explanations.
 - Use hook-injected context when helpful, but answer the current user request first. Use \`llm-wiki context\`, \`llm-wiki lint\`, and \`llm-wiki consolidate\` only as agent maintenance helpers.
 - Hooks safely store redacted raw envelopes and work/decision-focused live Q&A. Simple answers, status checks, and keyword-only turns should not be promoted to live Q&A or durable wiki by default.
-- Hooks may queue durable cleanup candidates in \`llm-wiki/outputs/maintenance/queue.md\` at stop/start boundaries. Treat maintenance as a soft agent-side reminder; merge pending items only when relevant and mark them \`done\` or \`skipped\`.
+- Hooks may queue durable cleanup candidates in \`llm-wiki/outputs/maintenance/queue.md\` at stop/start boundaries. Treat maintenance as a soft agent-side reminder; merge surfaced candidates when relevant or before ending the session, then mark them \`done\` or \`skipped\`.
 - Before creating new wiki pages, search existing pages and update the right one when possible. Reusable facts should not stay only in chunked \`outputs/questions/\`.
-- Store one-off work or decision records in \`llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md\` when needed. Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` when approved or clearly important.
+- Store one-off work or decision records in \`llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md\` when needed. Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` when approved, hook-suggested, or clearly important.
 - 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 -->
 `;
 }
@@ -55,13 +64,23 @@ These rules replace older OMX/OMC/\`omx_wiki/\` rules for this project.
 - Important claims should include at least one of: \`source_ids\`, file paths, or verification commands.
 - When durable knowledge appears, search existing \`wiki/\` pages before creating a new page.
 - Do not promote simple answers, status checks, keyword-only replies, or one-off chat into live Q&A, \`wiki/queries\`, or maintenance.
-- Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance and user consent flow.
-- Review \`outputs/maintenance/queue.md\` pending items only when related to the current request or when review is due. Merge into existing durable wiki pages, then mark items \`done\` or \`skipped\`.
-- Periodic maintenance is agent review, not automatic editing. Show only short reminders at \`SessionStart\`/\`InstructionsLoaded\`, and only show prompt-time reminders for wiki/maintenance-related user prompts.
+- Hooks may flag work/decision turns as durable wiki candidates when they contain reusable architecture, debugging, policy, procedure, or decision signals. Treat those as review prompts, not automatic page creation.
+- Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance, hook suggestions, and user consent flow.
+- Review \`outputs/maintenance/queue.md\` pending items when surfaced by hook context, related to the current request, or review is due. Merge into existing durable wiki pages, then mark items \`done\` or \`skipped\`.
+- Periodic maintenance is agent review, not automatic editing. Show only short reminders at \`SessionStart\`/\`InstructionsLoaded\`, and compact prompt-time reminders when durable candidates or review thresholds need agent attention.
 - Keep \`wiki/memory.md\` short. Use links to current state and important documents instead of long explanations.
 - 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 +89,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"
@@ -86,7 +106,7 @@ superseded_by: []
 - query: use hook-injected context when useful, but answer the current request first. Manual commands are diagnostics, not required daily workflow.
 - lint: agent helper for user-requested or wiki maintenance work. Do not run it every turn.
 - consolidate: safely refresh generated blocks in \`memory.md\`/\`index.md\`. Do not overwrite handwritten sections or curated document bodies.
-- maintenance: \`outputs/maintenance/queue.md\` stores stop/start cleanup candidates. Review and update it only when it does not delay the current user request.
+- maintenance: \`outputs/maintenance/queue.md\` stores stop/start cleanup candidates. Review surfaced durable candidates without delaying the current user request, then mark them \`done\` or \`skipped\`.
 `;
 }
 
@@ -131,6 +151,7 @@ export function memoryPage() {
 title: "LLM Wiki Memory"
 type: "context"
 source_ids: []
+evidence_refs: []
 status: "draft"
 last_updated: "unknown"
 confidence: "medium"
@@ -178,7 +199,7 @@ export function procedure(name) {
 3. Create or update \`wiki/sources/<slug>.md\` only when a source summary is useful.
 4. Before creating a new page, look for related concept/entity/decision/architecture/debugging/context pages and update those first.
 5. Do not create duplicates. Merge facts into existing pages when they already exist.
-6. Do not promote simple answers or one-off chat into durable wiki.
+6. Do not promote simple answers or one-off chat into durable wiki, but do review hook-suggested durable candidates for reusable facts.
 7. Important claims should record source references, confidence, memory type, importance, and verification status.
 8. When durable entry points change, update \`wiki/memory.md\` briefly or use \`llm-wiki consolidate\`.
 9. Add a short entry to \`wiki/log.md\` for meaningful wiki changes.
@@ -191,8 +212,8 @@ export function procedure(name) {
 4. Inspect raw sources only when exact evidence matters.
 5. Separate verified facts from inference.
 6. Use \`llm-wiki context "<query>"\` only when manual inspection is useful. Add \`--include-episodic\` only for historical query/context pages, and \`--include-archived\` only for archived/superseded pages.
-7. Do not promote one-off answers, status checks, or keyword-only replies to durable wiki or live Q&A. Archive only work turns with tool evidence, changed-file evidence, verification, or structured decision/debugging conclusions.
-8. Merge reusable facts into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance and user consent flow.
+7. Do not promote one-off answers, status checks, or keyword-only replies to durable wiki or live Q&A. Archive only work turns with tool evidence, changed-file evidence, verification, structured decision/debugging conclusions, or hook-suggested durable candidates.
+8. Merge reusable facts into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance, hook suggestions, and user consent flow.
 `,
     'lint.md': `# Lint Procedure
 
@@ -204,7 +225,7 @@ Periodic maintenance is an agent-side task, not a per-turn user command. When ne
 
 1. \`llm-wiki lint --workspace <project>\`
 2. \`llm-wiki maintenance --workspace <project>\`
-3. Merge pending items into existing durable pages, then mark them \`done\` or \`skipped\`.
+3. Merge pending or hook-suggested durable candidates into existing durable pages when appropriate, then mark them \`done\` or \`skipped\`.
 4. \`llm-wiki consolidate --workspace <project> --dry-run\`
 5. Run \`llm-wiki consolidate --workspace <project>\` when the dry run is acceptable.