llm-wiki-kit 0.2.9 → 0.2.10

package/README.md

@@ -126,13 +126,13 @@ Installed npm runtimes also perform a cached update notice check from hooks whil
 
 `llm-wiki post-update --workspace <project>` reapplies the current runtime's hook entries and safe managed template updates without running `npm install -g`. Use `post-update --all --workspace <search-root>` to reapply templates across discovered project roots.
 
-`llm-wiki context "<query>"` prints the full debug view of the layered context sources used by hooks. Hook injection may render those sources as functional compact context for Codex and Claude, but this CLI stays verbose so maintainers can inspect retrieval, snippets, memory, index, and expansion behavior. Daily use should rely on hook injection. By default, episodic `wiki/queries/` pages are excluded from search unless they were promoted with `memory_type: semantic` or `procedural` and `importance >= 4`; use `--include-episodic` only when debugging old automatic query records.
+`llm-wiki context "<query>"` prints the full debug view of the layered context sources used by hooks. Hook injection may render those sources as functional compact context for Codex and Claude, but this CLI stays verbose so maintainers can inspect retrieval, snippets, memory, index, expansion behavior, and context budget metadata. Daily use should rely on hook injection. By default, episodic `wiki/queries/`, `wiki/context/`, and `session-log` pages are excluded from search unless they were promoted with `memory_type: semantic` or `procedural` and `importance >= 4`; use `--include-episodic` only when debugging old automatic records. Archived or superseded pages are hidden unless `--include-archived` is requested, while stale pages remain searchable with lower score.
 
-`llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. Agents may use it before/after meaningful wiki maintenance.
+`llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. It also warns when `memory.md` is near budget, wiki page count nears the search cap, hidden episodic/context pages accumulate, or stale/archived pages lack supersession/link discoverability. Agents may use it before/after meaningful wiki maintenance.
 
-`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. It is an agent maintenance helper, not a command users should run after every turn.
+`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. Generated maps keep durable non-archived pages, hide default episodic records, skip stale/archived/superseded pages, and report those counts in dry-run output. It is an agent maintenance helper, not a command users should run after every turn.
 
-`llm-wiki maintenance` prints the pending queue from `llm-wiki/outputs/maintenance/queue.md`. Hooks create only selective candidates; the active agent should merge reusable items into existing durable wiki pages and mark queue items `done` or `skipped` without delaying unrelated user answers.
+`llm-wiki maintenance` prints the pending queue and review due status from `llm-wiki/outputs/maintenance/queue.md`. Hooks create only selective candidates; the active agent should merge reusable items into existing durable wiki pages and mark queue items `done` or `skipped` without delaying unrelated user answers. Periodic maintenance is a soft agent-side reminder, not a user command loop.
 
 `llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state or an older `llm-wiki/wiki/index.md`, and shows the update commands to run. `llm-wiki update --workspace /apps` updates the global runtime once, then reapplies managed templates across every known or discovered project root under `/apps`.
 

package/docs/concepts.md

@@ -39,7 +39,8 @@ The maintenance loop is intentionally layered:
 
 - `memory.md`: short hot index for current durable facts.
 - `index.md`: broad navigation map.
-- MiniSearch + wikilinks: retrieval over durable `wiki/**/*.md`, with episodic `wiki/queries/` hidden by default unless `--include-episodic` is requested.
+- MiniSearch + wikilinks: retrieval over durable `wiki/**/*.md`, with episodic `wiki/queries/`, `wiki/context/`, and `session-log` pages hidden by default unless promoted or `--include-episodic` is requested; archived/superseded pages stay preserved but hidden unless `--include-archived` is requested.
 - `outputs/maintenance/queue.md`: selective reminders for explicit durable requests that need review, plus stale turn recovery.
-- `lint`: finds broken links, stale pages, duplicates, metadata gaps, secret-like content, and outdated managed rules.
-- `consolidate`: agent helper that refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.
+- `lint`: finds broken links, stale pages, duplicates, metadata gaps, secret-like content, outdated managed rules, memory/page-count budget pressure, hidden episodic growth, and stale/archived discoverability gaps.
+- `maintenance`: reports `reviewDue` only when periodic thresholds are met; hook reminders are soft and limited to session start/instructions loaded or maintenance-related prompts.
+- `consolidate`: agent helper that refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes, keeping default query/context/session pages out of the durable generated maps, and skipping stale/archived/superseded pages.

package/docs/manual.md

@@ -271,6 +271,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project --json
 llm-wiki context "auth architecture" --workspace /path/to/project --limit 8
 llm-wiki context "auth architecture" --workspace /path/to/project --no-expand
 llm-wiki context "auth architecture" --workspace /path/to/project --include-episodic
+llm-wiki context "auth architecture" --workspace /path/to/project --include-archived
 ```
 
 읽는 자료:
@@ -281,7 +282,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project --include-epis
 - MiniSearch 또는 substring fallback 결과
 - strong match의 one-hop wikilink neighbors
 
-기본 검색은 episodic `wiki/queries/`를 제외한다. 오래된 automatic query record까지 보고 싶을 때만 `--include-episodic`을 쓴다.
+기본 검색은 durable semantic/procedural page를 우선하고, episodic `wiki/queries/`, `wiki/context/`, `session-log` 계열은 숨긴다. 해당 page가 `memory_type: semantic|procedural`이고 `importance >= 4`이면 promoted durable page로 취급한다. `status: archived` 또는 `superseded_by`가 있는 page도 기본 검색에서 제외하며, 필요한 조사 때만 `--include-archived`로 복구한다. `status: stale` page는 보존하고 검색할 수 있지만 score를 낮춘다. JSON 출력에는 memory/index/hit/snippet budget metadata가 포함된다.
 
 ### `llm-wiki lint`
 
@@ -302,6 +303,10 @@ llm-wiki lint --workspace /path/to/project
 - secret-like content
 - duplicate aliases/titles
 - stale pages and orphan candidates
+- `memory.md` near-budget/oversized 상태
+- wiki page count가 search cap에 근접했는지
+- default-hidden episodic/context/session page 성장
+- stale/archived page의 supersession/link discoverability
 - outdated managed rules/templates
 - stale or oversized maintenance queue
 
@@ -321,7 +326,7 @@ llm-wiki consolidate --workspace /path/to/project --dry-run
 - `wiki/memory.md`의 generated memory map
 - `wiki/index.md`의 generated page map
 
-handwritten content는 보존한다. malformed marker block은 덮어쓰지 않고 건너뛴다. 기본 `query`, `context`, `session-log` page는 explicit durable metadata가 없으면 generated map에서 제외한다.
+handwritten content는 보존한다. malformed marker block은 덮어쓰지 않고 건너뛴다. generated map에는 durable non-archived page만 넣는다. `stale`, `archived`, `superseded_by` page는 보존하지만 generated map에서는 제외한다. 기본 `query`, `context`, `session-log` page는 explicit durable metadata가 없으면 generated map에서 제외한다. `--dry-run` 결과는 indexed durable pages, hidden episodic pages, archived/stale/superseded skipped counts를 보고한다.
 
 ### `llm-wiki maintenance`
 
@@ -332,7 +337,18 @@ llm-wiki maintenance --workspace /path/to/project
 llm-wiki maintenance --workspace /path/to/project --json
 ```
 
-이 명령은 page merge를 자동 수행하지 않는다. active agent가 pending item을 읽고, 가장 가까운 durable wiki 문서에 병합한 뒤 queue item을 `done` 또는 `skipped`로 표시한다.
+이 명령은 page merge를 자동 수행하지 않는다. 정기 maintenance는 agent-side task이며 사용자가 매 turn 실행할 필요가 없다. active agent가 pending item을 읽고, 가장 가까운 durable wiki 문서에 병합한 뒤 queue item을 `done` 또는 `skipped`로 표시한다.
+
+JSON 출력에는 `reviewDue`, `reviewReasons`, `pendingCount`, `stalePendingCount`, `health`, `recommendedCommands`가 포함된다. Review due 조건은 마지막 review 후 14일 경과, pending 5개 이상, stale/result-missing pending item, lint warning/error, `memory.md` near-budget 이상, wiki page count가 search cap의 80% 이상인 경우다. Hook은 due 상태를 `SessionStart`/`InstructionsLoaded`에서만 짧게 보여주고, `UserPromptSubmit`에서는 사용자가 wiki/maintenance/정리 관련 질문을 했을 때만 보여준다. 현재 답변을 중단하거나 정리를 강제하지 않는다.
+
+Agent checklist:
+
+```bash
+llm-wiki lint --workspace /path/to/project
+llm-wiki maintenance --workspace /path/to/project
+llm-wiki consolidate --workspace /path/to/project --dry-run
+llm-wiki consolidate --workspace /path/to/project
+```
 
 ### `llm-wiki uninstall`
 

package/docs/operations.md

@@ -157,7 +157,7 @@ Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limite
 - one-hop wikilink neighbors for the strongest matches
 - redacted output fields for query text, memory/index/log excerpts, hit paths, titles, snippets, matched terms, and link expansion metadata
 
-Default context search excludes episodic `wiki/queries/` pages unless they were explicitly promoted with `memory_type: semantic` or `procedural` and `importance >= 4`. Use `--include-episodic` only when debugging historical automatic query pages:
+Default context search prioritizes durable semantic/procedural pages. It hides episodic `wiki/queries/`, `wiki/context/`, and `session-log` pages unless they were explicitly promoted with `memory_type: semantic` or `procedural` and `importance >= 4`. It also hides `status: archived` and `superseded_by` pages unless `--include-archived` is requested. `status: stale` pages remain searchable but receive a lower score. JSON output includes memory/index/hit/snippet budget metadata so maintainers can see how much context each layer consumed. Use `--include-episodic` only when debugging historical automatic query pages:
 
 Use it only when you want to inspect what the next agent turn should see:
 
@@ -166,6 +166,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project
 llm-wiki context "auth architecture" --workspace /path/to/project --json
 llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no-expand
 llm-wiki context "auth architecture" --workspace /path/to/project --include-episodic
+llm-wiki context "auth architecture" --workspace /path/to/project --include-archived
 ```
 
 `llm-wiki lint` checks Markdown wiki health without modifying files:
@@ -179,6 +180,10 @@ llm-wiki context "auth architecture" --workspace /path/to/project --include-epis
 - secret-like content patterns such as tokens, password assignments, bearer credentials, and private keys
 - duplicate aliases or titles
 - stale pages and orphan candidates
+- `memory.md` near-budget or oversized state
+- wiki page count near the default search cap
+- default-hidden episodic/context/session page growth
+- stale/archived pages without supersession metadata or links
 - outdated managed rules/templates from earlier `llm-wiki-kit` versions
 - stale or oversized maintenance queues
 
@@ -188,7 +193,10 @@ Broken links, invalid source IDs, and secret-like content are errors and return
 
 - refreshes the generated block inside `wiki/memory.md`
 - refreshes the generated block inside `wiki/index.md`
+- keeps only durable non-archived pages in generated maps
+- skips `stale`, `archived`, and `superseded_by` pages from generated maps while preserving them on disk
 - excludes default `query`, `context`, and `session-log` pages from generated maps unless they are explicitly durable (`memory_type: semantic` or `procedural`, `importance >= 4`)
+- reports indexed durable pages, hidden episodic pages, and archived/stale/superseded skipped counts, including in `--dry-run`
 - skips malformed generated marker blocks instead of overwriting them
 - preserves handwritten content outside marker blocks
 - appends a log entry when files change
@@ -196,7 +204,18 @@ Broken links, invalid source IDs, and secret-like content are errors and return
 
 Agents may run `consolidate` after meaningful wiki growth. Users should not need to run it after every turn.
 
-`llm-wiki maintenance --workspace <project>` prints queue counts and the first pending items. It does not merge wiki pages by itself; the active agent should review pending items, update the closest existing durable wiki document, then mark the queue item `done` or `skipped`.
+`llm-wiki maintenance --workspace <project>` prints queue counts, review due status, and the first pending items. It does not merge wiki pages by itself; the active agent should review pending items, update the closest existing durable wiki document, then mark the queue item `done` or `skipped`. Periodic maintenance is an agent-side task, not something users need to run after every turn.
+
+`llm-wiki maintenance --workspace <project> --json` includes `reviewDue`, `reviewReasons`, `pendingCount`, `stalePendingCount`, `health`, and `recommendedCommands`. Review is due when the last review is older than 14 days, pending queue size reaches 5, stale or result-missing pending items exist, lint has warnings/errors, `memory.md` is near budget, or wiki page count reaches 80% of the search cap. Hook reminders are soft: `SessionStart`/`InstructionsLoaded` may show a short due note, while `UserPromptSubmit` shows it only for wiki/maintenance/cleanup-related prompts. The reminder never blocks the current answer.
+
+Recommended agent checklist:
+
+```bash
+llm-wiki lint --workspace /path/to/project
+llm-wiki maintenance --workspace /path/to/project
+llm-wiki consolidate --workspace /path/to/project --dry-run
+llm-wiki consolidate --workspace /path/to/project
+```
 
 When a new runtime sees an older project, `SessionStart`/`InstructionsLoaded` automatically reapplies safe managed template updates. Files that are clearly generated by older kit versions are refreshed. Files that look user-edited are preserved and surfaced to the active agent as cleanup context instead of being overwritten. Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic template refresh behavior.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -70,6 +70,8 @@ function parseOptions(args) {
       options.expand = false;
     } else if (arg === '--include-episodic') {
       options.includeEpisodic = true;
+    } else if (arg === '--include-archived') {
+      options.includeArchived = true;
     } else if (arg === '--replace-hooks') {
       options.replaceHooks = true;
     } else if (arg === '--all') {
@@ -116,7 +118,7 @@ Usage:
   llm-wiki hook claude <EventName>
   llm-wiki bootstrap --workspace <project>
   llm-wiki migrate --workspace <project>
-  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand] [--include-episodic]
+  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand] [--include-episodic] [--include-archived]
   llm-wiki lint --workspace <project>
   llm-wiki consolidate --workspace <project> [--dry-run]
   llm-wiki maintenance --workspace <project> [--json]
@@ -234,7 +236,7 @@ Usage:
 
   if (command === 'maintenance') {
     const projectRoot = resolve(options.workspace || process.cwd());
-    printJsonOrText(await maintenanceSummary(projectRoot, options), options, formatMaintenanceResult);
+    printJsonOrText(await maintenanceSummary(projectRoot, { ...options, includeLint: true }), options, formatMaintenanceResult);
     return;
   }
 

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/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/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);

package/src/wiki-search.js

@@ -4,10 +4,20 @@ import { redactText } from './redaction.js';
 import {
   buildWikiGraph,
   collectWikiPages,
+  MEMORY_BYTE_LIMIT,
+  MEMORY_LINE_LIMIT,
   pageLookup,
   parseFrontmatter,
   readMemoryExcerpt,
 } from './wiki-model.js';
+import {
+  isArchivedPage,
+  isDefaultSearchCandidate,
+  isEpisodicLayerPage,
+  isStalePage,
+  isSupersededPage,
+  searchWeight,
+} from './wiki-visibility.js';
 
 const DEFAULT_LIMIT = 5;
 const SNIPPET_CHARS = 350;
@@ -65,6 +75,7 @@ function resultRecord(page, score, fields = {}) {
     title: page.title,
     type: page.type || '',
     memoryType: page.memoryType || '',
+    status: page.status || '',
     score,
     directScore: fields.directScore || 0,
     linkScore: fields.linkScore || 0,
@@ -81,22 +92,35 @@ function sortHits(a, b) {
   return a.path.localeCompare(b.path);
 }
 
-function importance(page) {
-  const value = Number(page?.frontmatter?.importance || 0);
-  return Number.isFinite(value) ? value : 0;
+export async function searchWiki(projectRoot, query, options = {}) {
+  return (await performSearch(projectRoot, query, options)).hits;
 }
 
-function isDefaultSearchCandidate(page, options = {}) {
-  if (options.includeEpisodic) return true;
-  const type = String(page.type || '').toLowerCase();
-  if (type === 'query' || page.rel.startsWith('wiki/queries/')) {
-    return ['semantic', 'procedural'].includes(page.memoryType) && importance(page) >= 4;
+function searchVisibility(pages, options = {}) {
+  const metadata = {
+    totalPages: pages.length,
+    searchedPages: 0,
+    hiddenEpisodicPages: 0,
+    hiddenArchivedPages: 0,
+    hiddenSupersededPages: 0,
+    stalePagesSearched: 0,
+    includeEpisodic: Boolean(options.includeEpisodic),
+    includeArchived: Boolean(options.includeArchived),
+  };
+  const visible = [];
+  for (const page of pages) {
+    const hiddenArchived = !options.includeArchived && isArchivedPage(page);
+    const hiddenSuperseded = !options.includeArchived && isSupersededPage(page);
+    const hiddenEpisodic = !options.includeEpisodic && isEpisodicLayerPage(page) && !isDefaultSearchCandidate(page, options);
+    if (hiddenArchived) metadata.hiddenArchivedPages += 1;
+    if (hiddenSuperseded) metadata.hiddenSupersededPages += 1;
+    if (hiddenEpisodic) metadata.hiddenEpisodicPages += 1;
+    if (!isDefaultSearchCandidate(page, options)) continue;
+    if (isStalePage(page)) metadata.stalePagesSearched += 1;
+    visible.push(page);
   }
-  return true;
-}
-
-export async function searchWiki(projectRoot, query, options = {}) {
-  return (await performSearch(projectRoot, query, options)).hits;
+  metadata.searchedPages = visible.length;
+  return { visible, metadata };
 }
 
 async function performSearch(projectRoot, query, options = {}) {
@@ -109,8 +133,21 @@ async function performSearch(projectRoot, query, options = {}) {
   }
 
   let pages = [];
+  let metadata = {
+    totalPages: 0,
+    searchedPages: 0,
+    hiddenEpisodicPages: 0,
+    hiddenArchivedPages: 0,
+    hiddenSupersededPages: 0,
+    stalePagesSearched: 0,
+    includeEpisodic: Boolean(opts.includeEpisodic),
+    includeArchived: Boolean(opts.includeArchived),
+  };
   try {
-    pages = (await collectWikiPages(projectRoot, opts)).filter((page) => isDefaultSearchCandidate(page, opts));
+    const collected = await collectWikiPages(projectRoot, opts);
+    const visibility = searchVisibility(collected, opts);
+    pages = visibility.visible;
+    metadata = visibility.metadata;
   } catch {
     return { hits: [], search: 'missing-wiki' };
   }
@@ -144,7 +181,7 @@ async function performSearch(projectRoot, query, options = {}) {
       const page = byPath.get(item.id);
       if (!page) continue;
       const subScore = substringScore(page, terms);
-      const score = item.score + subScore;
+      const score = (item.score + subScore) * searchWeight(page);
       hits.set(page.rel, resultRecord(page, score, {
         directScore: score,
         matchedTerms: item.terms || terms,
@@ -154,7 +191,7 @@ async function performSearch(projectRoot, query, options = {}) {
   }
 
   for (const page of pages) {
-    const score = substringScore(page, terms);
+    const score = substringScore(page, terms) * searchWeight(page);
     if (score <= 0 || hits.has(page.rel)) continue;
     hits.set(page.rel, resultRecord(page, score, {
       directScore: score,
@@ -175,7 +212,7 @@ async function performSearch(projectRoot, query, options = {}) {
         if (hits.has(neighborPath)) continue;
         const page = byPath.get(neighborPath);
         if (!page) continue;
-        const linkScore = seed.score * 0.2;
+        const linkScore = seed.score * 0.2 * searchWeight(page);
         hits.set(neighborPath, resultRecord(page, linkScore, {
           linkScore,
           source: 'linked',
@@ -190,6 +227,7 @@ async function performSearch(projectRoot, query, options = {}) {
   return {
     hits: [...hits.values()].sort(sortHits).slice(0, limit),
     search,
+    metadata,
   };
 }
 
@@ -282,11 +320,12 @@ export async function buildContextPack(projectRoot, query, options = {}) {
   const limit = Number(options.limit || DEFAULT_LIMIT);
   const expand = options.expand !== false;
   const memoryExcerpt = await readMemoryExcerpt(projectRoot);
-  const indexExcerpt = (await readText(join(projectRoot, 'llm-wiki', 'wiki', 'index.md'))).slice(0, 1200).trim();
+  const rawIndexExcerpt = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'index.md'));
+  const indexExcerpt = rawIndexExcerpt.slice(0, 1200).trim();
   const logExcerpt = options.includeLog
     ? (await readText(join(projectRoot, 'llm-wiki', 'wiki', 'log.md'))).slice(-1000).trim()
     : '';
-  const result = query ? await performSearch(projectRoot, query, { ...options, limit, expand }) : { hits: [], search: 'none' };
+  const result = query ? await performSearch(projectRoot, query, { ...options, limit, expand }) : { hits: [], search: 'none', metadata: null };
   return {
     workspace: projectRoot,
     query: redactText(query || '', 1000),
@@ -297,6 +336,32 @@ export async function buildContextPack(projectRoot, query, options = {}) {
     indexExcerpt: redactText(indexExcerpt, 2000),
     logExcerpt: redactText(logExcerpt, 2000),
     hits: result.hits.map(redactHit),
+    metadata: {
+      search: result.metadata,
+      budgets: {
+        memory: {
+          maxLines: MEMORY_LINE_LIMIT,
+          maxBytes: MEMORY_BYTE_LIMIT,
+          returnedBytes: Buffer.byteLength(memoryExcerpt.trim(), 'utf8'),
+          redactionMaxChars: 30000,
+        },
+        index: {
+          maxChars: 1200,
+          sourceChars: rawIndexExcerpt.length,
+          returnedChars: indexExcerpt.length,
+          redactionMaxChars: 2000,
+        },
+        hits: {
+          requestedLimit: limit,
+          returned: result.hits.length,
+          snippetChars: SNIPPET_CHARS,
+          hookSnippetChars: HOOK_SNIPPET_CHARS,
+          expand,
+          includeEpisodic: Boolean(options.includeEpisodic),
+          includeArchived: Boolean(options.includeArchived),
+        },
+      },
+    },
   };
 }
 

package/src/wiki-visibility.js

@@ -0,0 +1,76 @@
+export const DURABLE_MEMORY_TYPES = new Set(['semantic', 'procedural']);
+
+export function frontmatterValues(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '').trim()).filter(Boolean);
+  const text = String(value || '').trim();
+  if (!text || text === '[]') return [];
+  return [text];
+}
+
+export function pageImportance(page) {
+  const value = Number(page?.frontmatter?.importance || 0);
+  return Number.isFinite(value) ? value : 0;
+}
+
+export function isArchivedPage(page) {
+  return String(page?.status || '').toLowerCase() === 'archived';
+}
+
+export function isStalePage(page) {
+  return String(page?.status || '').toLowerCase() === 'stale';
+}
+
+export function supersededBy(page) {
+  return frontmatterValues(page?.frontmatter?.superseded_by);
+}
+
+export function supersedes(page) {
+  return frontmatterValues(page?.frontmatter?.supersedes);
+}
+
+export function isSupersededPage(page) {
+  return supersededBy(page).length > 0;
+}
+
+export function hasSupersession(page) {
+  return supersededBy(page).length > 0 || supersedes(page).length > 0;
+}
+
+export function isEpisodicLayerPage(page) {
+  const type = String(page?.type || '').toLowerCase();
+  const rel = String(page?.rel || '');
+  return (
+    type === 'query' ||
+    type === 'context' ||
+    type === 'session-log' ||
+    rel.startsWith('wiki/queries/') ||
+    rel.startsWith('wiki/context/')
+  );
+}
+
+export function isPromotedDurablePage(page) {
+  return DURABLE_MEMORY_TYPES.has(String(page?.memoryType || '').toLowerCase()) && pageImportance(page) >= 4;
+}
+
+export function includeArchivedPages(options = {}) {
+  return Boolean(options.includeArchived);
+}
+
+export function includeEpisodicPages(options = {}) {
+  return Boolean(options.includeEpisodic);
+}
+
+export function isDefaultSearchCandidate(page, options = {}) {
+  if (!includeArchivedPages(options) && (isArchivedPage(page) || isSupersededPage(page))) return false;
+  if (includeEpisodicPages(options)) return true;
+  if (isEpisodicLayerPage(page)) return isPromotedDurablePage(page);
+  return true;
+}
+
+export function searchWeight(page) {
+  let weight = 1;
+  if (DURABLE_MEMORY_TYPES.has(String(page?.memoryType || '').toLowerCase())) weight *= 1.2;
+  if (pageImportance(page) >= 4) weight *= 1.1;
+  if (isStalePage(page)) weight *= 0.35;
+  return weight;
+}