llm-wiki-kit 0.2.9 → 0.2.11

package/src/live-qa.js

@@ -0,0 +1,321 @@
+import { copyFile, readdir } from 'fs/promises';
+import { basename, dirname, join, relative } from 'path';
+import {
+  appendText,
+  ensureDir,
+  exists,
+  readText,
+  sha256,
+  timeKst,
+  todayKst,
+  writeText,
+} from './fs-utils.js';
+import { redactText } from './redaction.js';
+
+export const DEFAULT_LIVE_QA_MAX_LINES = 500;
+export const DEFAULT_LIVE_QA_MAX_BYTES = 80 * 1024;
+
+const ARCHIVE_STUB_MARKER = '<!-- llm-wiki-kit:archived-live-qa -->';
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) return fallback;
+  return parsed;
+}
+
+export function liveQaMaxLines(env = process.env) {
+  return positiveInteger(env.LLM_WIKI_KIT_LIVE_QA_MAX_LINES, DEFAULT_LIVE_QA_MAX_LINES);
+}
+
+export function liveQaMaxBytes(env = process.env) {
+  return positiveInteger(env.LLM_WIKI_KIT_LIVE_QA_MAX_BYTES, DEFAULT_LIVE_QA_MAX_BYTES);
+}
+
+export function liveQaDayDir(projectRoot, day = todayKst()) {
+  return join(projectRoot, 'llm-wiki', 'outputs', 'questions', day);
+}
+
+function liveQaLegacyPath(projectRoot, day) {
+  return join(projectRoot, 'llm-wiki', 'outputs', 'questions', `${day}-live-qa.md`);
+}
+
+function chunkName(number) {
+  return `live-qa-${String(number).padStart(3, '0')}.md`;
+}
+
+function chunkNumber(file) {
+  const match = file.match(/^live-qa-(\d+)\.md$/);
+  return match ? Number(match[1]) : null;
+}
+
+function countLines(text) {
+  if (!text) return 0;
+  return String(text).split(/\r?\n/).length;
+}
+
+function countBlocks(text) {
+  return (String(text || '').match(/^## \d{2}:\d{2} KST - /gm) || []).length;
+}
+
+async function listChunkFiles(dayDir) {
+  let entries = [];
+  try {
+    entries = await readdir(dayDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && chunkNumber(entry.name) !== null)
+    .map((entry) => entry.name)
+    .sort((a, b) => chunkNumber(a) - chunkNumber(b));
+}
+
+function exceedsLimit(existing, addition, options = {}) {
+  if (!existing) return false;
+  const maxLines = options.maxLines ?? liveQaMaxLines();
+  const maxBytes = options.maxBytes ?? liveQaMaxBytes();
+  return (
+    countLines(existing) + countLines(addition) > maxLines ||
+    Buffer.byteLength(existing, 'utf8') + Buffer.byteLength(addition, 'utf8') > maxBytes
+  );
+}
+
+async function targetChunkPath(projectRoot, day, block, options = {}) {
+  const dayDir = liveQaDayDir(projectRoot, day);
+  await ensureDir(dayDir);
+  const files = await listChunkFiles(dayDir);
+  let number = files.length > 0 ? chunkNumber(files.at(-1)) : 1;
+  let path = join(dayDir, chunkName(number));
+  const existing = await readText(path, '');
+  if (exceedsLimit(existing, block, options)) {
+    number += 1;
+    path = join(dayDir, chunkName(number));
+  }
+  return path;
+}
+
+export function formatLiveQaBlock(entry) {
+  return [
+    `\n## ${timeKst()} KST - ${entry.topic || 'session turn'}`,
+    '',
+    '### Question',
+    entry.question || '(not captured)',
+    '',
+    '### Work',
+    entry.work || '(not captured)',
+    '',
+    '### Result',
+    entry.result || '(not captured)',
+    '',
+    '### Changed files',
+    entry.changedFiles || '(not captured)',
+    '',
+    '### Verification',
+    entry.verification || '(not captured)',
+    '',
+    '### Follow-up',
+    entry.followUp || '작업/결정 중심으로 저장된 live Q&A 기록이다. 재사용 가능한 사실은 사용자가 원하거나 명확히 중요할 때만 기존 durable wiki 문서에 합친다.',
+    '',
+  ].join('\n');
+}
+
+export async function refreshLiveQaIndex(projectRoot, day = todayKst()) {
+  const dayDir = liveQaDayDir(projectRoot, day);
+  const files = await listChunkFiles(dayDir);
+  const rows = [];
+  let totalBlocks = 0;
+  for (const file of files) {
+    const rel = file;
+    const text = await readText(join(dayDir, file), '');
+    const blocks = countBlocks(text);
+    totalBlocks += blocks;
+    rows.push(`- [${rel}](${rel}) - ${blocks} turn(s), ${countLines(text)} line(s)`);
+  }
+  const content = [
+    `# Live Q&A ${day}`,
+    '',
+    'Chunked live Q&A archive for meaningful work and decision turns.',
+    '',
+    `- chunks: ${files.length}`,
+    `- turns: ${totalBlocks}`,
+    `- updated_at: ${new Date().toISOString()}`,
+    '',
+    '## Chunks',
+    '',
+    rows.length > 0 ? rows.join('\n') : '(none)',
+    '',
+  ].join('\n');
+  await writeText(join(dayDir, 'index.md'), content);
+}
+
+export async function appendLiveQa(projectRoot, entry, options = {}) {
+  const day = todayKst();
+  const block = redactText(formatLiveQaBlock(entry), 12000);
+  const path = await targetChunkPath(projectRoot, day, block, options);
+  await appendText(path, block);
+  await refreshLiveQaIndex(projectRoot, day);
+  return path;
+}
+
+function splitLiveQaBlocks(text) {
+  const blocks = [];
+  let current = [];
+  for (const line of String(text || '').replace(/\r\n/g, '\n').split('\n')) {
+    if (/^## \d{2}:\d{2} KST - /.test(line) && current.some((item) => item.trim())) {
+      blocks.push(`\n${current.join('\n').trim()}\n`);
+      current = [line];
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.some((item) => item.trim())) {
+    blocks.push(`\n${current.join('\n').trim()}\n`);
+  }
+  return blocks;
+}
+
+function packBlocks(blocks, options = {}) {
+  const chunks = [];
+  let current = '';
+  for (const block of blocks) {
+    if (current && exceedsLimit(current, block, options)) {
+      chunks.push(current);
+      current = block;
+    } else {
+      current += block;
+    }
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+async function writeGeneratedFile(path, content) {
+  const current = await readText(path, null);
+  if (current !== null && current !== content) {
+    throw new Error(`refusing to overwrite existing generated target with different content: ${path}`);
+  }
+  if (current === content) return false;
+  await writeText(path, content);
+  return true;
+}
+
+async function backupTarget(projectRoot, sourcePath, checksum) {
+  const base = join(projectRoot, 'llm-wiki', 'outputs', 'questions', 'archive', 'originals', basename(sourcePath));
+  if (!(await exists(base))) return base;
+  const currentChecksum = await readText(`${base}.sha256`, '');
+  if (currentChecksum.includes(checksum)) return base;
+  const parsed = basename(sourcePath, '.md');
+  return join(projectRoot, 'llm-wiki', 'outputs', 'questions', 'archive', 'originals', `${parsed}-${checksum.slice(0, 12)}.md`);
+}
+
+async function archiveOne(projectRoot, day, options = {}) {
+  const sourcePath = liveQaLegacyPath(projectRoot, day);
+  const sourceRel = relative(projectRoot, sourcePath).split('\\').join('/');
+  if (!(await exists(sourcePath))) {
+    return { date: day, status: 'missing', source: sourceRel, chunks: [] };
+  }
+
+  const text = await readText(sourcePath, '');
+  if (text.includes(ARCHIVE_STUB_MARKER)) {
+    return { date: day, status: 'already-archived', source: sourceRel, chunks: [] };
+  }
+
+  const blocks = splitLiveQaBlocks(text);
+  if (blocks.length === 0) {
+    return { date: day, status: 'empty', source: sourceRel, chunks: [] };
+  }
+
+  const checksum = sha256(text);
+  const backupPath = await backupTarget(projectRoot, sourcePath, checksum);
+  const backupRel = relative(projectRoot, backupPath).split('\\').join('/');
+  const chunks = packBlocks(blocks, options);
+  const dayDir = liveQaDayDir(projectRoot, day);
+  const existingChunks = await listChunkFiles(dayDir);
+  const firstChunkNumber = existingChunks.length > 0 ? chunkNumber(existingChunks.at(-1)) + 1 : 1;
+  const chunkTargets = chunks.map((content, index) => ({
+    path: join(dayDir, chunkName(firstChunkNumber + index)),
+    rel: relative(projectRoot, join(dayDir, chunkName(firstChunkNumber + index))).split('\\').join('/'),
+    content,
+    blocks: countBlocks(content),
+    lines: countLines(content),
+  }));
+
+  const result = {
+    date: day,
+    status: options.dryRun ? 'planned' : 'archived',
+    source: sourceRel,
+    original: backupRel,
+    checksum,
+    blocks: blocks.length,
+    chunks: chunkTargets.map(({ rel, blocks: blockCount, lines }) => ({ path: rel, blocks: blockCount, lines })),
+  };
+  if (options.dryRun) return result;
+
+  await ensureDir(dirname(backupPath));
+  if (!(await exists(backupPath))) await copyFile(sourcePath, backupPath);
+  await writeText(`${backupPath}.sha256`, `${checksum}  ${basename(sourcePath)}\n`);
+  await ensureDir(dayDir);
+  for (const target of chunkTargets) {
+    await writeGeneratedFile(target.path, target.content);
+  }
+  await refreshLiveQaIndex(projectRoot, day);
+  const stub = [
+    '# Live Q&A Archived',
+    ARCHIVE_STUB_MARKER,
+    '',
+    'This legacy daily live Q&A file was archived into chunked files.',
+    '',
+    `- original: ${backupRel}`,
+    `- sha256: ${checksum}`,
+    `- index: llm-wiki/outputs/questions/${day}/index.md`,
+    '',
+  ].join('\n');
+  await writeText(sourcePath, stub);
+  return result;
+}
+
+async function datesToArchive(projectRoot, options = {}) {
+  if (options.date) return [options.date];
+  const questionsDir = join(projectRoot, 'llm-wiki', 'outputs', 'questions');
+  let entries = [];
+  try {
+    entries = await readdir(questionsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name.match(/^(\d{4}-\d{2}-\d{2})-live-qa\.md$/)?.[1])
+    .filter(Boolean)
+    .sort();
+}
+
+export async function archiveQuestions(projectRoot, options = {}) {
+  const dates = await datesToArchive(projectRoot, options);
+  const files = [];
+  for (const day of dates) {
+    files.push(await archiveOne(projectRoot, day, options));
+  }
+  return {
+    workspace: projectRoot,
+    dryRun: Boolean(options.dryRun),
+    date: options.date || null,
+    files,
+  };
+}
+
+export function formatArchiveQuestionsResult(result) {
+  const lines = [
+    'llm-wiki archive-questions',
+    `- workspace: ${result.workspace}`,
+    `- dry-run: ${result.dryRun ? 'yes' : 'no'}`,
+    `- files: ${result.files.length}`,
+  ];
+  for (const file of result.files) {
+    lines.push(`- ${file.date}: ${file.status}; blocks=${file.blocks || 0}; chunks=${file.chunks.length}`);
+    for (const chunk of file.chunks) {
+      lines.push(`  - ${chunk.path} (${chunk.blocks} turn(s), ${chunk.lines} line(s))`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/maintenance.js

@@ -4,11 +4,15 @@ import { appendText, exists, kitDataDir, readJson, readText, sha256, writeTextIf
 import { classifyTurn, isMaintenanceRelatedQuery } from './capture-policy.js';
 import { redactText, summarizeForStorage } from './redaction.js';
 import { buildEntryFromTurnState, hasRecoverableTurnState } from './state.js';
+import { collectWikiPages, DEFAULT_MAX_WIKI_FILES, MEMORY_BYTE_LIMIT } from './wiki-model.js';
 
 export const MAINTENANCE_QUEUE_REL = 'llm-wiki/outputs/maintenance/queue.md';
 const DEFAULT_STALE_TURN_MS = 10 * 60 * 1000;
 const DEFAULT_STALE_PENDING_DAYS = 7;
 const DEFAULT_PENDING_LIMIT = 20;
+const DEFAULT_REVIEW_PENDING_LIMIT = 5;
+const DEFAULT_REVIEW_INTERVAL_DAYS = 14;
+const MEMORY_NEAR_BUDGET_BYTES = 20 * 1024;
 
 function queuePath(projectRoot) {
   return join(projectRoot, MAINTENANCE_QUEUE_REL);
@@ -125,12 +129,26 @@ export async function readMaintenanceQueue(projectRoot) {
 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 staleCutoff = Date.now() - staleDays * 24 * 60 * 60 * 1000;
   const stalePending = pending.filter((item) => {
     const time = Date.parse(item.created_at || item.last_seen_at || '');
     return Number.isFinite(time) && time < staleCutoff;
   });
+  const reviewItems = queue.items.filter((item) => item.status === 'done' || item.status === 'skipped');
+  const reviewTimes = reviewItems
+    .map((item) => Date.parse(item.last_seen_at || item.created_at || ''))
+    .filter(Number.isFinite);
+  const lastReviewMs = reviewTimes.length > 0 ? Math.max(...reviewTimes) : null;
+  const reviewReasons = [];
+  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');
+  if (lastReviewMs && Date.now() - lastReviewMs >= reviewIntervalDays * 24 * 60 * 60 * 1000) {
+    reviewReasons.push(`last maintenance review is older than ${reviewIntervalDays} days`);
+  }
   return {
     path: queue.path,
     exists: queue.exists,
@@ -142,14 +160,79 @@ export function summarizeMaintenanceQueue(queue, options = {}) {
     doneCount: queue.items.filter((item) => item.status === 'done').length,
     skippedCount: queue.items.filter((item) => item.status === 'skipped').length,
     stalePending,
+    stalePendingCount: stalePending.length,
     stalePendingDays: staleDays,
     pendingLimit,
+    reviewPendingLimit,
+    reviewIntervalDays,
+    lastReviewAt: lastReviewMs ? new Date(lastReviewMs).toISOString() : null,
+    reviewDue: reviewReasons.length > 0,
+    reviewReasons,
     tooManyPending: pending.length > pendingLimit,
   };
 }
 
 export async function maintenanceSummary(projectRoot, options = {}) {
-  return summarizeMaintenanceQueue(await readMaintenanceQueue(projectRoot), options);
+  const summary = summarizeMaintenanceQueue(await readMaintenanceQueue(projectRoot), options);
+  const health = await maintenanceHealthSignals(projectRoot, options);
+  const reviewReasons = [...summary.reviewReasons];
+  if (health.memoryNearBudget) reviewReasons.push(`memory.md is near budget (${health.memoryBytes} bytes)`);
+  if (health.pageCountNearSearchCap) reviewReasons.push(`wiki page count ${health.pageCount} is near search cap ${health.searchCap}`);
+  if (health.lint && health.lint.issueCount > 0) {
+    reviewReasons.push(`lint has ${health.lint.errorCount} error(s) and ${health.lint.warningCount} warning(s)`);
+  }
+  return {
+    ...summary,
+    reviewDue: reviewReasons.length > 0,
+    reviewReasons,
+    health,
+    recommendedCommands: recommendedMaintenanceCommands(projectRoot),
+  };
+}
+
+function recommendedMaintenanceCommands(projectRoot) {
+  return [
+    `llm-wiki lint --workspace ${projectRoot}`,
+    `llm-wiki maintenance --workspace ${projectRoot}`,
+    `llm-wiki consolidate --workspace ${projectRoot} --dry-run`,
+    `llm-wiki consolidate --workspace ${projectRoot}`,
+  ];
+}
+
+async function maintenanceHealthSignals(projectRoot, options = {}) {
+  const memoryText = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'memory.md'), '');
+  const memoryBytes = Buffer.byteLength(memoryText, 'utf8');
+  let pageCount = 0;
+  const searchCap = options.searchCap || DEFAULT_MAX_WIKI_FILES;
+  try {
+    pageCount = (await collectWikiPages(projectRoot, { maxFiles: searchCap })).length;
+  } catch {
+    pageCount = 0;
+  }
+  let lint = null;
+  if (options.includeLint && !options.skipLint) {
+    try {
+      const module = await import('./wiki-lint.js');
+      const result = await module.runLint(projectRoot, { maxFiles: options.maxFiles || 1000, skipMaintenance: true });
+      lint = {
+        ok: result.ok,
+        issueCount: result.issueCount,
+        errorCount: result.errorCount,
+        warningCount: result.warningCount,
+      };
+    } catch {
+      lint = null;
+    }
+  }
+  return {
+    memoryBytes,
+    memoryNearBudget: memoryBytes >= MEMORY_NEAR_BUDGET_BYTES,
+    memoryOversized: memoryBytes > MEMORY_BYTE_LIMIT,
+    pageCount,
+    searchCap,
+    pageCountNearSearchCap: pageCount >= Math.floor(searchCap * 0.8),
+    lint,
+  };
 }
 
 export async function appendMaintenanceItem(projectRoot, item) {
@@ -225,11 +308,11 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
 }
 
 export function formatMaintenanceContext(summary, options = {}) {
+  if (!summary.reviewDue) return '';
   const eventName = options.eventName || '';
   const defaultLimit = eventName === 'SessionStart' || eventName === 'InstructionsLoaded' ? 1 : 5;
   const limit = options.limit || defaultLimit;
   let pending = summary.pending.slice(0, limit);
-  if (pending.length === 0) return '';
 
   if (eventName === 'UserPromptSubmit') {
     if (!isMaintenanceRelatedQuery(options.query || '', summary.pending)) return '';
@@ -242,6 +325,7 @@ export function formatMaintenanceContext(summary, options = {}) {
     eventName === 'UserPromptSubmit'
       ? 'LLM Wiki maintenance status:'
       : 'LLM Wiki maintenance status:',
+    `- review due: yes (${(summary.reviewReasons || []).slice(0, 2).join('; ') || 'periodic review threshold met'}).`,
     `- pending review items: ${summary.pendingCount}. 현재 요청이 우선이며, 관련 있을 때만 durable wiki 정리에 사용한다.`,
   ];
   for (const item of pending) {
@@ -258,14 +342,25 @@ export function formatMaintenanceResult(summary) {
     'llm-wiki maintenance',
     `- queue: ${summary.path}`,
     `- pending: ${summary.pendingCount}`,
+    `- stale pending: ${summary.stalePendingCount || 0}`,
     `- done: ${summary.doneCount}`,
     `- skipped: ${summary.skippedCount}`,
+    `- review due: ${summary.reviewDue ? 'yes' : 'no'}`,
   ];
+  if ((summary.reviewReasons || []).length > 0) {
+    lines.push(`- review reasons: ${summary.reviewReasons.join('; ')}`);
+  }
   if (summary.pending.length > 0) {
     lines.push('', 'Pending:');
     for (const item of summary.pending.slice(0, 10)) {
       lines.push(`- ${item.topic || item.id}: ${item.source} -> ${item.suggested_target}`);
     }
   }
+  if ((summary.recommendedCommands || []).length > 0) {
+    lines.push('', 'Recommended commands:');
+    for (const command of summary.recommendedCommands) {
+      lines.push(`- ${command}`);
+    }
+  }
   return lines.join('\n');
 }

package/src/project.js

@@ -14,6 +14,7 @@ import { normalizeForStorage, redactText, summarizeForStorage } from './redactio
 import { gitignore, indexPage, llmWikiAgents, logPage, memoryPage, procedure, rootAgentsPolicy } from './templates.js';
 import { formatProjectMaintenanceContext, inspectProjectState, recordManagedTemplates } from './project-state.js';
 import { buildContextPack, formatHookContextPack, searchWiki as searchWikiWithIndex } from './wiki-search.js';
+import { appendLiveQa as appendChunkedLiveQa } from './live-qa.js';
 
 export async function bootstrapProject(projectRoot, options = {}) {
   if (process.env.LLM_WIKI_KIT_DISABLE_BOOTSTRAP === '1') return { created: false };
@@ -97,32 +98,7 @@ function hasCapturedQuestion(entry) {
 }
 
 export async function appendLiveQa(projectRoot, entry) {
-  const day = todayKst();
-  const path = join(projectRoot, 'llm-wiki', 'outputs', 'questions', `${day}-live-qa.md`);
-  const block = [
-    `\n## ${timeKst()} KST - ${entry.topic || 'session turn'}`,
-    '',
-    '### Question',
-    entry.question || '(not captured)',
-    '',
-    '### Work',
-    entry.work || '(not captured)',
-    '',
-    '### Result',
-    entry.result || '(not captured)',
-    '',
-    '### Changed files',
-    entry.changedFiles || '(not captured)',
-    '',
-    '### Verification',
-    entry.verification || '(not captured)',
-    '',
-    '### Follow-up',
-    entry.followUp || '다음 작업에서 이 turn의 reusable fact가 있으면 기존 wiki 문서에 합치고, 일회성 기록은 이 Q&A에만 보존한다.',
-    '',
-  ].join('\n');
-  await appendText(path, redactText(block, 12000));
-  return path;
+  return appendChunkedLiveQa(projectRoot, entry);
 }
 
 export async function writeQueryPage(projectRoot, entry) {

package/src/templates.js

@@ -14,10 +14,10 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`llm-wiki/wiki/\`는 agent가 관리하는 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 여기에 정리한다.
 - \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
 - hook이 주입한 context를 참고하되, 현재 사용자 답변을 먼저 처리한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
-- hook은 redacted raw envelope와 필요한 live Q&A를 안전하게 남긴다. \`wiki/queries\`/\`wiki/decisions\` 자동 승격은 기본값이 아니며, durable 지식은 중요도와 동의 흐름에 따라 agent가 기존 정식 wiki 문서에 합친다.
-- hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
-- 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
-- 일회성 작업 기록은 필요할 때 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 사실/지식은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
+- hook은 redacted raw envelope와 작업/결정 중심 live Q&A만 안전하게 남긴다. 단순 답변, 상태 확인, 키워드만 포함된 응답은 live Q&A나 durable wiki로 승격하지 않는다. \`wiki/queries\`/\`wiki/decisions\` 자동 승격은 기본값이 아니며, durable 지식은 중요도와 동의 흐름에 따라 agent가 기존 정식 wiki 문서에 합친다.
+- hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. 정기 maintenance는 agent-side soft reminder이며, pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
+- 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 chunked \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
+- 일회성 작업/결정 기록은 필요할 때 \`llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md\` style chunk에 보존하고, 재사용 가능한 사실/지식은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
 - 인증값, token, password, private key, \`.env\` 원문은 저장하지 않는다. 필요한 경우 redacted summary만 남긴다.
 
@@ -47,9 +47,10 @@ Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wik
 - 근거 없는 내용을 사실처럼 쓰지 않는다. 추론은 명시한다.
 - 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
 - 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
-- 단순 답변, 상태 확인, 일회성 대화는 과도하게 \`wiki/queries\`나 maintenance로 승격하지 않는다.
+- 단순 답변, 상태 확인, 키워드만 포함된 응답, 일회성 대화는 live Q&A, \`wiki/queries\`, maintenance로 승격하지 않는다.
 - 반복해서 쓸 지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
-- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 현재 요청과 관련 있을 때 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 현재 요청과 관련 있거나 review due 안내가 있을 때 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- 정기 maintenance는 자동 수정이 아니라 agent review다. \`SessionStart\`/\`InstructionsLoaded\`에서만 짧게 안내되고, \`UserPromptSubmit\`에서는 사용자가 wiki/maintenance/정리 관련 질문을 한 경우에만 안내된다.
 - \`wiki/memory.md\`는 짧게 유지한다. 긴 설명 대신 현재 상태와 중요한 문서 링크를 둔다.
 - 모순은 덮어쓰지 말고 \`Contradictions\` 또는 \`Open Questions\`에 보존한다.
 - 인증값, token, password, private key, \`.env\` 원문은 wiki에 저장하지 않는다.
@@ -107,7 +108,7 @@ Generated by llm-wiki-kit.
 
 - 넓은 질문은 memory와 이 index에서 시작한다.
 - 새 문서를 만들기 전에 관련 기존 문서 3-7개를 먼저 확인한다.
-- 오래 쓸 사실/지식은 기존 정식 문서에 합치고, 일회성 기록은 outputs/questions에 둔다.
+- 오래 쓸 사실/지식은 기존 정식 문서에 합치고, 작업/결정 중심 일회성 기록은 chunked outputs/questions에 둔다.
 - 관련 페이지가 생기면 \`[[page-or-topic]]\` 링크를 추가한다.
 
 <!-- llm-wiki-kit:index-start -->
@@ -182,15 +183,23 @@ export function procedure(name) {
 3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
 4. 정확한 근거가 필요할 때만 raw source를 확인한다.
 5. 검증된 사실과 추론을 분리한다.
-6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query까지 봐야 할 때는 \`--include-episodic\`을 붙인다.
-7. 일회성 답변은 durable wiki로 승격하지 않는다. 필요한 작업 turn만 \`outputs/questions/\`에 남긴다.
+6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query/context까지 봐야 할 때는 \`--include-episodic\`을 붙이고, archived/superseded page까지 봐야 할 때만 \`--include-archived\`를 붙인다.
+7. 일회성 답변, 상태 확인, 키워드만 포함된 응답은 durable wiki나 live Q&A로 승격하지 않는다. tool evidence, changed-file evidence, verification, 구조화된 decision/debugging 결론이 있는 작업 turn만 \`outputs/questions/YYYY-MM-DD/live-qa-001.md\` style chunk에 남긴다.
 8. 반복해서 쓸 사실/지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
 `,
     'lint.md': `# Lint Procedure
 
 \`llm-wiki lint --workspace <project>\`는 agent가 필요할 때 쓰는 wiki 건강 점검 도구다. 사용자가 매번 실행해야 하는 명령이 아니다.
 
-점검 대상: stale page, orphan page, broken wiki/Markdown link, unsafe source id, secret-like content, missing source, duplicate concept/title, unsupported claim, unresolved contradiction, outdated managed rule.
+점검 대상: stale page, orphan page, broken wiki/Markdown link, unsafe source id, secret-like content, missing source, duplicate concept/title, unsupported claim, unresolved contradiction, outdated managed rule, memory budget, page count growth, hidden episodic/context growth, stale/archived discoverability, maintenance review due, oversized legacy live Q&A, oversized live Q&A chunk.
+
+정기 maintenance는 사용자가 매 turn 실행할 필요가 없는 agent-side task다. 필요할 때 agent가 다음 순서로 확인한다:
+
+1. \`llm-wiki lint --workspace <project>\`
+2. \`llm-wiki maintenance --workspace <project>\`
+3. pending item을 기존 durable page에 병합한 뒤 \`done\` 또는 \`skipped\`로 표시한다.
+4. \`llm-wiki consolidate --workspace <project> --dry-run\`
+5. 필요할 때 \`llm-wiki consolidate --workspace <project>\`
 
 자동 수정은 확실히 kit가 관리하는 영역에만 적용한다. 사용자 편집 가능성이 있는 문서는 덮어쓰지 말고 다음 작업 context에 정리 필요성을 올린다.
 `,