llm-wiki-kit 0.2.8 → 0.2.10

package/src/consolidate.js

@@ -5,6 +5,14 @@ import { hasSecretLikeText, isSensitivePath, normalizeForStorage } from './redac
 import { indexPage, memoryPage } from './templates.js';
 import { collectWikiPages } from './wiki-model.js';
 import { runLint } from './wiki-lint.js';
+import {
+  isArchivedPage,
+  isEpisodicLayerPage,
+  isPromotedDurablePage,
+  isStalePage,
+  isSupersededPage,
+  pageImportance,
+} from './wiki-visibility.js';
 
 export const MEMORY_START = '<!-- llm-wiki-kit:memory-start -->';
 export const MEMORY_END = '<!-- llm-wiki-kit:memory-end -->';
@@ -37,37 +45,53 @@ function pageReference(page) {
   return `[[${pageTarget(page)}|${page.title}]]`;
 }
 
-function importance(page) {
-  const value = Number(page.frontmatter.importance || 0);
-  return Number.isFinite(value) ? value : 0;
-}
-
 function isPromotableEpisodicPage(page) {
-  return ['semantic', 'procedural'].includes(page.memoryType) && importance(page) >= 4;
+  return isPromotedDurablePage(page);
 }
 
-function isGeneratedBlockCandidate(page) {
-  if (['wiki/index.md', 'wiki/log.md', 'wiki/memory.md'].includes(page.rel)) return false;
-  if (isSensitivePath(page.rel) || isSensitivePath(page.title)) return false;
-  if (hasSecretLikeText(`${page.rel}\n${page.title}\n${page.content}`)) return false;
-  const type = String(page.type || '').toLowerCase();
-  if (
-    type === 'query' ||
-    type === 'context' ||
-    type === 'session-log' ||
-    page.rel.startsWith('wiki/queries/') ||
-    page.rel.startsWith('wiki/context/')
-  ) {
-    return isPromotableEpisodicPage(page);
+function classifyGeneratedPages(pages) {
+  const stats = {
+    durablePages: 0,
+    memoryPages: 0,
+    hiddenEpisodicPages: 0,
+    archivedSkippedPages: 0,
+    staleSkippedPages: 0,
+    supersededSkippedPages: 0,
+    sensitiveSkippedPages: 0,
+  };
+  const candidates = [];
+  for (const page of pages) {
+    if (['wiki/index.md', 'wiki/log.md', 'wiki/memory.md'].includes(page.rel)) continue;
+    if (isSensitivePath(page.rel) || isSensitivePath(page.title) || hasSecretLikeText(`${page.rel}\n${page.title}\n${page.content}`)) {
+      stats.sensitiveSkippedPages += 1;
+      continue;
+    }
+    if (isArchivedPage(page)) {
+      stats.archivedSkippedPages += 1;
+      continue;
+    }
+    if (isSupersededPage(page)) {
+      stats.supersededSkippedPages += 1;
+      continue;
+    }
+    if (isStalePage(page)) {
+      stats.staleSkippedPages += 1;
+      continue;
+    }
+    if (isEpisodicLayerPage(page) && !isPromotableEpisodicPage(page)) {
+      stats.hiddenEpisodicPages += 1;
+      continue;
+    }
+    candidates.push(page);
   }
-  return true;
+  stats.durablePages = candidates.length;
+  return { candidates, stats };
 }
 
 function sortedPages(pages) {
   return pages
-    .filter(isGeneratedBlockCandidate)
     .sort((a, b) => {
-      const importanceDiff = importance(b) - importance(a);
+      const importanceDiff = pageImportance(b) - pageImportance(a);
       if (importanceDiff !== 0) return importanceDiff;
       const typeDiff = String(a.type || '').localeCompare(String(b.type || ''));
       if (typeDiff !== 0) return typeDiff;
@@ -75,12 +99,16 @@ function sortedPages(pages) {
     });
 }
 
-function buildGeneratedMemoryBlock(pages) {
-  const candidates = sortedPages(pages).slice(0, 25);
+function buildGeneratedMemoryBlock(pages, stats) {
+  const allCandidates = sortedPages(pages);
+  const candidates = allCandidates.slice(0, 25);
+  stats.memoryPages = candidates.length;
   const lines = [
     '## Generated Memory Map',
     '',
-    `- Pages indexed: ${sortedPages(pages).length}`,
+    `- Durable pages indexed: ${allCandidates.length}`,
+    `- Hidden episodic pages: ${stats.hiddenEpisodicPages}`,
+    `- Skipped archived/stale/superseded pages: ${stats.archivedSkippedPages}/${stats.staleSkippedPages}/${stats.supersededSkippedPages}`,
   ];
   if (candidates.length === 0) {
     lines.push('- No durable pages found yet.');
@@ -91,7 +119,7 @@ function buildGeneratedMemoryBlock(pages) {
     const metadata = [
       page.type || 'unknown',
       page.memoryType ? `memory:${page.memoryType}` : '',
-      importance(page) > 0 ? `importance:${importance(page)}` : '',
+      pageImportance(page) > 0 ? `importance:${pageImportance(page)}` : '',
       page.confidence ? `confidence:${page.confidence}` : '',
     ].filter(Boolean).join(', ');
     lines.push(`- ${pageReference(page)}${metadata ? ` - ${metadata}` : ''}`);
@@ -111,7 +139,7 @@ function buildGeneratedIndexBlock(pages) {
   const lines = [
     '## Generated Page Map',
     '',
-    `- Pages indexed: ${candidates.length}`,
+    `- Durable pages indexed: ${candidates.length}`,
   ];
   if (groups.size === 0) {
     lines.push('- No durable pages found yet.');
@@ -142,6 +170,7 @@ async function updateMarkedFile(projectRoot, rel, initialContent, startMarker, e
 export async function runConsolidate(projectRoot, options = {}) {
   const lintResult = await runLint(projectRoot, { maxFiles: options.maxFiles || 1000 });
   const pages = await collectWikiPages(projectRoot, { maxFiles: options.maxFiles || 1000 });
+  const { candidates, stats } = classifyGeneratedPages(pages);
   const changed = [];
   const skipped = [];
 
@@ -151,7 +180,7 @@ export async function runConsolidate(projectRoot, options = {}) {
     memoryPage(),
     MEMORY_START,
     MEMORY_END,
-    buildGeneratedMemoryBlock(pages),
+    buildGeneratedMemoryBlock(candidates, stats),
     options,
   );
   if (memoryChange?.changed) changed.push(memoryChange.changed);
@@ -163,7 +192,7 @@ export async function runConsolidate(projectRoot, options = {}) {
     indexPage(),
     INDEX_START,
     INDEX_END,
-    buildGeneratedIndexBlock(pages),
+    buildGeneratedIndexBlock(candidates),
     options,
   );
   if (indexChange?.changed) changed.push(indexChange.changed);
@@ -182,6 +211,7 @@ export async function runConsolidate(projectRoot, options = {}) {
     dryRun: Boolean(options.dryRun),
     changed,
     skipped,
+    counts: stats,
     lint: {
       ok: finalLintResult.ok,
       errorCount: finalLintResult.errorCount,
@@ -197,6 +227,9 @@ export function formatConsolidateResult(result) {
     `- dry run: ${result.dryRun ? 'yes' : 'no'}`,
     `- changed: ${result.changed.length ? result.changed.map((item) => item.path).join(', ') : 'none'}`,
     `- skipped: ${result.skipped?.length ? result.skipped.map((item) => `${item.path} (${item.reason})`).join(', ') : 'none'}`,
+    `- durable pages indexed: ${result.counts?.durablePages ?? 0}`,
+    `- hidden episodic pages: ${result.counts?.hiddenEpisodicPages ?? 0}`,
+    `- skipped archived/stale/superseded: ${result.counts?.archivedSkippedPages ?? 0}/${result.counts?.staleSkippedPages ?? 0}/${result.counts?.supersededSkippedPages ?? 0}`,
     `- lint errors: ${result.lint.errorCount}`,
     `- lint warnings: ${result.lint.warningCount}`,
   ].join('\n');

package/src/hook.js

@@ -1,7 +1,7 @@
 import { findProjectRoot } from './fs-utils.js';
 import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
 import { bootstrapProject, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
-import { compactSummaryText, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
+import { consumeCompactRecoveryContext, finalizeCompactRecovery, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
@@ -35,8 +35,16 @@ function toolSummary(payload) {
   return `${toolName}: ${summarizeForStorage(input, 1200)}`;
 }
 
-function contextOutput(eventName, context) {
+function supportsAdditionalContext(provider, eventName) {
+  const normalized = String(provider || '').toLowerCase();
+  if (normalized === 'codex') return ['SessionStart', 'UserPromptSubmit'].includes(eventName);
+  if (normalized === 'claude') return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+  return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+}
+
+function contextOutput(provider, eventName, context) {
   if (!context) return {};
+  if (!supportsAdditionalContext(provider, eventName)) return {};
   return {
     hookSpecificOutput: {
       hookEventName: eventName,
@@ -129,21 +137,30 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
-    const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, 'SessionStart'), payload);
-    return contextOutput(eventName, context);
+    const recovery = supportsAdditionalContext(provider, eventName)
+      ? await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '')
+      : '';
+    const context = await hookContext(
+      projectRoot,
+      eventName,
+      [recovery, await buildContextBrief(projectRoot, 'SessionStart')].filter(Boolean).join('\n\n'),
+      payload
+    );
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'UserPromptSubmit') {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
     const guidance = formatDurableCaptureGuidance(prompt);
+    const recovery = await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '');
     const context = await hookContext(
       projectRoot,
       eventName,
-      [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
+      [recovery, await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
       payload
     );
-    return contextOutput(eventName, context);
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'PreToolUse') {
@@ -158,10 +175,9 @@ export async function handleHook(provider, explicitEvent) {
 
   if (eventName === 'PreCompact' || eventName === 'PostCompact') {
     if (eventName === 'PostCompact') {
-      const summary = compactSummaryText(payload);
       await recordPostCompactSummary(projectRoot, eventName, payload);
-      const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, eventName, summary), payload);
-      return contextOutput(eventName, context);
+      await finalizeCompactRecovery(projectRoot, payload).catch(() => {});
+      return {};
     }
     return handlePreCompactCapture(projectRoot, provider, eventName, payload);
   }

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/state.js

@@ -38,6 +38,22 @@ export async function clearTurnState(projectRoot, payload) {
   await unlink(statePath(projectRoot, payload)).catch(() => {});
 }
 
+export function compactRecoveryPath(projectRoot, payload) {
+  return join(kitDataDir(), 'compact-recovery', `${sessionKey(projectRoot, payload)}.json`);
+}
+
+export async function readCompactRecovery(projectRoot, payload) {
+  return readJson(compactRecoveryPath(projectRoot, payload), null);
+}
+
+export async function writeCompactRecovery(projectRoot, payload, recovery) {
+  await writeJson(compactRecoveryPath(projectRoot, payload), recovery);
+}
+
+export async function clearCompactRecovery(projectRoot, payload) {
+  await unlink(compactRecoveryPath(projectRoot, payload)).catch(() => {});
+}
+
 export async function rememberQuestion(projectRoot, payload, prompt) {
   const state = await readTurnState(projectRoot, payload);
   const clean = summarizeForStorage(prompt, 3000);

package/src/templates.js

@@ -15,7 +15,7 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`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로 표시한다.
+- hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. 정기 maintenance는 agent-side soft reminder이며, pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
 - 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
 - 일회성 작업 기록은 필요할 때 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 사실/지식은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
@@ -49,7 +49,8 @@ Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wik
 - 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
 - 단순 답변, 상태 확인, 일회성 대화는 과도하게 \`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에 저장하지 않는다.
@@ -182,7 +183,7 @@ export function procedure(name) {
 3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
 4. 정확한 근거가 필요할 때만 raw source를 확인한다.
 5. 검증된 사실과 추론을 분리한다.
-6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query까지 봐야 할 때는 \`--include-episodic\`을 붙인다.
+6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query/context까지 봐야 할 때는 \`--include-episodic\`을 붙이고, archived/superseded page까지 봐야 할 때만 \`--include-archived\`를 붙인다.
 7. 일회성 답변은 durable wiki로 승격하지 않는다. 필요한 작업 turn만 \`outputs/questions/\`에 남긴다.
 8. 반복해서 쓸 사실/지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
 `,
@@ -190,7 +191,15 @@ export function procedure(name) {
 
 \`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.
+
+정기 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에 정리 필요성을 올린다.
 `,

package/src/wiki-lint.js

@@ -8,10 +8,19 @@ import {
   buildAliasMap,
   buildWikiGraph,
   collectWikiPages,
+  DEFAULT_MAX_WIKI_FILES,
+  MEMORY_BYTE_LIMIT,
   normalizeTarget,
   resolveWikiLink,
   wikiRoot,
 } from './wiki-model.js';
+import {
+  hasSupersession,
+  isArchivedPage,
+  isEpisodicLayerPage,
+  isPromotedDurablePage,
+  isStalePage,
+} from './wiki-visibility.js';
 
 const VALID_TYPES = new Set([
   'source',
@@ -29,6 +38,9 @@ const VALID_STATUS = new Set(['draft', 'reviewed', 'stale', 'archived']);
 const VALID_CONFIDENCE = new Set(['high', 'medium', 'low']);
 const VALID_MEMORY_TYPES = new Set(['semantic', 'episodic', 'procedural']);
 const CORE_PAGES = new Set(['wiki/index.md', 'wiki/log.md', 'wiki/memory.md']);
+const MEMORY_NEAR_BUDGET_BYTES = 20 * 1024;
+const HIDDEN_PAGE_WARNING_THRESHOLD = 50;
+const SEARCH_CAP_WARNING_RATIO = 0.8;
 
 function issue(severity, code, path, message) {
   return { severity, code, path, message };
@@ -125,8 +137,9 @@ export async function runLint(projectRoot, options = {}) {
     return lintResult(projectRoot, [], issues);
   }
 
+  const maxFiles = options.maxFiles || 1000;
   const pages = await collectWikiPages(projectRoot, {
-    maxFiles: options.maxFiles || 1000,
+    maxFiles,
     maxChars: options.maxChars || 75000,
   });
   const byRel = new Map(pages.map((page) => [page.rel, page]));
@@ -226,9 +239,23 @@ export async function runLint(projectRoot, options = {}) {
   }
 
   const memoryText = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'memory.md'), '');
-  if (Buffer.byteLength(memoryText, 'utf8') > 25000) {
-    issues.push(issue('warning', 'memory-too-large', 'wiki/memory.md', 'memory.md is larger than the hook excerpt budget'));
+  const memoryBytes = Buffer.byteLength(memoryText, 'utf8');
+  if (memoryBytes > MEMORY_BYTE_LIMIT) {
+    issues.push(issue('warning', 'memory-too-large', 'wiki/memory.md', `memory.md is oversized (${memoryBytes} bytes) and larger than the hook excerpt budget`));
+  } else if (memoryBytes >= MEMORY_NEAR_BUDGET_BYTES) {
+    issues.push(issue('warning', 'memory-near-budget', 'wiki/memory.md', `memory.md is near the hook excerpt budget (${memoryBytes} bytes)`));
+  }
+
+  const searchCap = options.maxFiles || DEFAULT_MAX_WIKI_FILES;
+  if (pages.length >= Math.floor(searchCap * SEARCH_CAP_WARNING_RATIO)) {
+    issues.push(issue('warning', 'wiki-page-count-near-search-cap', 'llm-wiki/wiki', `wiki page count ${pages.length} is near the default search cap ${searchCap}`));
   }
+
+  const hiddenEpisodicPages = pages.filter((page) => isEpisodicLayerPage(page) && !isPromotedDurablePage(page));
+  if (hiddenEpisodicPages.length >= HIDDEN_PAGE_WARNING_THRESHOLD) {
+    issues.push(issue('warning', 'hidden-episodic-growth', 'llm-wiki/wiki', `${hiddenEpisodicPages.length} default-hidden episodic/context/session pages may add wiki growth and search noise`));
+  }
+
   for (const page of pages.filter(isOrphanCandidate)) {
     const backlinks = graph.backlinks.get(page.rel);
     if (!backlinks || backlinks.size === 0) {
@@ -236,6 +263,15 @@ export async function runLint(projectRoot, options = {}) {
     }
   }
 
+  for (const page of pages) {
+    if (!isArchivedPage(page) && !isStalePage(page)) continue;
+    const backlinks = graph.backlinks.get(page.rel);
+    const outlinks = graph.outlinks.get(page.rel);
+    if (!hasSupersession(page) && (!backlinks || backlinks.size === 0) && (!outlinks || outlinks.size === 0)) {
+      issues.push(issue('warning', 'stale-archived-discoverability', page.rel, 'stale/archived page has no supersession metadata or wiki links for discoverability'));
+    }
+  }
+
   const projectState = await inspectProjectState(projectRoot).catch(() => null);
   for (const file of projectState?.managedFiles || []) {
     if (file.needsAttention) {
@@ -245,12 +281,14 @@ export async function runLint(projectRoot, options = {}) {
     }
   }
 
-  const maintenance = await maintenanceSummary(projectRoot).catch(() => null);
-  if (maintenance?.tooManyPending) {
-    issues.push(issue('warning', 'maintenance-too-many-pending', 'outputs/maintenance/queue.md', `maintenance queue has ${maintenance.pendingCount} pending items; review and merge durable items into wiki pages`));
-  }
-  if ((maintenance?.stalePending || []).length > 0) {
-    issues.push(issue('warning', 'maintenance-stale-pending', 'outputs/maintenance/queue.md', `${maintenance.stalePending.length} pending maintenance item(s) are older than ${maintenance.stalePendingDays} days`));
+  if (!options.skipMaintenance) {
+    const maintenance = await maintenanceSummary(projectRoot, { skipLint: true }).catch(() => null);
+    if (maintenance?.tooManyPending) {
+      issues.push(issue('warning', 'maintenance-too-many-pending', 'outputs/maintenance/queue.md', `maintenance queue has ${maintenance.pendingCount} pending items; review and merge durable items into wiki pages`));
+    }
+    if ((maintenance?.stalePending || []).length > 0) {
+      issues.push(issue('warning', 'maintenance-stale-pending', 'outputs/maintenance/queue.md', `${maintenance.stalePending.length} pending maintenance item(s) are older than ${maintenance.stalePendingDays} days`));
+    }
   }
 
   return lintResult(projectRoot, pages, issues);