llm-wiki-kit 0.2.8 → 0.2.10

package/README.md

@@ -86,11 +86,12 @@ Use Claude Code or Codex normally.
 
 The installed hooks:
 
-- inject functional compact context at session start, instructions loaded, prompt submit, and post-compact time. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, and update status; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
+- inject functional compact context at session start, instructions loaded, and prompt submit. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, update status, and any compact recovery packet; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
 - remove Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces at session start so `llm-wiki/` remains the active wiki implementation
 - record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
 - before compaction, classify the current turn and save a redacted checkpoint for meaningful or durable work; durable candidates also get a maintenance queue item
+- after compaction, store the redacted compact summary only; if pre-compact preservation failed, prepare a recovery packet for the next legal model-visible context hook
 - allow tool calls to proceed without secret/PII-based hook blocking
 - update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md` only for meaningful work turns
 - avoid automatic `wiki/queries/` and `wiki/decisions/` promotion in the default answer-first mode
@@ -101,7 +102,7 @@ The installed hooks:
 
 If you need to think about saving every answer manually, the setup has failed.
 If wiki maintenance delays the actual answer, the setup is being used wrong. The default capture mode is `LLM_WIKI_KIT_CAPTURE_MODE=answer-first`; the old eager query/decision capture path remains only as deprecated compatibility mode via `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager`.
-Pre-compact preservation uses `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` with default `limited`. It reads only a bounded transcript tail controlled by `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`; the raw transcript path and authentication values are redacted before any checkpoint is written.
+Pre-compact preservation always lets compaction proceed. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` suppresses failure warnings; `limited` and `soft` both emit a non-blocking warning if checkpoint storage fails. The hook reads only a bounded transcript tail controlled by `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`; the raw transcript path and authentication values are redacted before any checkpoint or recovery packet is written.
 
 ## Operational Commands
 
@@ -125,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/integrations/claude-code.md

@@ -44,12 +44,12 @@ The hook records redacted turn summaries but does not deny tool calls only becau
 
 At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects functional compact context. The context still uses `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, relevant wiki/search state, operating rules, maintenance signals, passive runtime update status, and managed-template cleanup notes; the hook formats those signals so they are usable if shown in the Claude Code UI. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 
-`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` classifies the current turn before compaction: simple turns record only a context note, meaningful work writes a live Q&A checkpoint, and durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. `PostCompact` stores the redacted compact summary as a context note and returns fresh wiki context. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
+`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` classifies the current turn before compaction: simple turns record only a context note, meaningful work writes a live Q&A checkpoint, and durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event. `PostCompact` stores the redacted compact summary as a context note and prepares any pending recovery packet without returning model-visible context directly. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
-Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` to tune pre-compact failure handling; default `limited` blocks only when checkpoint/queue preservation fails on providers with block support. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -33,8 +33,8 @@ Expected behavior:
 - `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
-- `PreCompact` classifies the current turn before compaction. Simple turns record only a context note; meaningful work writes a live Q&A checkpoint; durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`.
-- `PostCompact` stores the redacted compact summary as a context note and returns fresh wiki context.
+- `PreCompact` classifies the current turn before compaction. Simple turns record only a context note; meaningful work writes a live Q&A checkpoint; durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event.
+- `PostCompact` stores the redacted compact summary as a context note and prepares any pending compact recovery packet. It does not return `hookSpecificOutput.additionalContext`, because Codex `PostCompact` only supports common output fields.
 - In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` appends live Q&A only for meaningful work turns and does not auto-create `wiki/queries/` or `wiki/decisions/`.
 - If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop` queues a pending maintenance item for agent review.
 - `Stop` clears the per-session turn buffer after recording. `SubagentStop` leaves the parent turn buffer available for the final stop event.
@@ -44,7 +44,7 @@ Hook payloads are stored as small redacted event envelopes rather than full tran
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
-Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` to tune pre-compact failure handling; default `limited` blocks only on supported providers when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 Run these after install:
 

package/docs/manual.md

@@ -62,8 +62,8 @@ llm-wiki/
 
 설치된 hook은 다음 일을 자동으로 수행한다.
 
-- session start, prompt submit, post compact 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status는 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
-- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, meaningful/durable turn은 redacted live Q&A checkpoint와 필요한 maintenance queue 후보를 남긴다.
+- session start, instructions loaded, prompt submit 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status, compact recovery packet은 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
+- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, meaningful/durable turn은 redacted live Q&A checkpoint와 필요한 maintenance queue 후보를 남긴다. 저장 실패 시에도 compact는 진행시키고, 중요한 내용만 recovery packet으로 준비한다.
 - prompt/tool/result summary를 redaction한 뒤 turn buffer에 기록한다.
 - 의미 있는 작업 turn만 `outputs/questions/YYYY-MM-DD-live-qa.md`에 live Q&A로 남긴다.
 - 기본 answer-first mode에서는 `wiki/queries/`와 `wiki/decisions/`를 매 turn 자동 생성하지 않는다.
@@ -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`
 
@@ -387,9 +403,9 @@ Claude Code handled events:
 
 Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다. `PreCompact`는 checkpoint 생성을 위해 작은 bounded transcript tail만 읽을 수 있고, 저장 전 인증값과 raw `transcript_path`를 redaction한다.
 
-Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status를 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
+Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status, compact recovery packet을 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `PostCompact`는 compact summary 저장과 recovery packet 준비만 수행하고 model-visible context를 직접 반환하지 않는다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
 
-Pre-compact 보존은 기본 `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`로 동작한다. `limited`는 checkpoint/queue 저장 실패 시 block을 지원하는 provider에서만 compact block을 시도하고, 그 외에는 failure context를 남긴다. `soft`는 block하지 않고, `off`는 실패 output을 억제한다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
+Pre-compact 보존은 compact를 block하지 않는다. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off`는 실패 warning을 억제하고, `limited`/`soft`는 checkpoint/queue 저장 실패 시 non-blocking warning만 남긴다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
 
 ## Security Defaults
 

package/docs/operations.md

@@ -143,9 +143,9 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working
 
 Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject context automatically, but the current user answer takes priority over wiki cleanup. The active agent updates durable wiki pages when reusable project knowledge appears and the turn's importance or user consent justifies persistence. Hook context policy is function-first: memory, search, maintenance, and update signals remain available, while user-visible context is formatted as functional compact context instead of a raw dump.
 
-In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `PreCompact` performs the same answer-first classification before context compaction: simple turns get only a context note, archive-worthy turns get a live Q&A checkpoint, and durable candidates get a checkpoint plus queue item. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `PreCompact` performs the same answer-first classification before context compaction: simple turns get only a context note, archive-worthy turns get a live Q&A checkpoint, and durable candidates get a checkpoint plus queue item. If checkpoint storage fails, compaction still proceeds and the hook prepares an important-only compact recovery packet for the next legal context-injection event. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
 
-Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`. In that mode, checkpoint/queue write failures can block compact only on providers that support hook blocking; otherwise the hook returns best-effort failure context. `soft` never blocks, and `off` suppresses failure output. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the small bounded transcript tail used for checkpoint context. Authentication values and the raw transcript path are redacted before storage.
+Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`, but compaction is never blocked by llm-wiki-kit. `limited` and `soft` emit non-blocking failure warnings, and `off` suppresses failure output. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the small bounded transcript tail used for checkpoint context. Authentication values and the raw transcript path are redacted before storage.
 
 `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` keeps the old eager live Q&A/query/decision/maintenance behavior for compatibility only. New projects should rely on the answer-first default.
 
@@ -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.8",
+  "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/compact-capture.js

@@ -4,26 +4,12 @@ import { classifyTurn } from './capture-policy.js';
 import { recordMaintenanceForEntry } from './maintenance.js';
 import { appendContextNote, appendLiveQa, appendWikiLog } from './project.js';
 import { redactText, summarizeForStorage } from './redaction.js';
-import { buildEntryFromState } from './state.js';
+import { buildEntryFromState, clearCompactRecovery, readCompactRecovery, writeCompactRecovery } from './state.js';
 
 const DEFAULT_PRECOMPACT_TAIL_BYTES = 32 * 1024;
 const MAX_PRECOMPACT_TAIL_BYTES = 256 * 1024;
 const ENFORCEMENT_MODES = new Set(['limited', 'soft', 'off']);
 
-function contextOutput(eventName, context) {
-  if (!context) return {};
-  return {
-    hookSpecificOutput: {
-      hookEventName: eventName,
-      additionalContext: context,
-    },
-  };
-}
-
-function providerSupportsBlock(provider) {
-  return String(provider || '').toLowerCase() === 'claude';
-}
-
 export function preCompactEnforcementMode(env = process.env) {
   const value = String(env.LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT || 'limited').toLowerCase();
   return ENFORCEMENT_MODES.has(value) ? value : 'limited';
@@ -118,16 +104,77 @@ function entryWithTranscriptTail(entry, tail) {
   return next;
 }
 
-function failureOutput(provider, eventName, message, mode) {
+function captured(value) {
+  const text = String(value || '').trim();
+  return text && text !== '(not captured)' ? text : '';
+}
+
+function sanitizeFailureText(projectRoot, value) {
+  let text = String(value || '');
+  if (projectRoot) text = text.split(projectRoot).join('[REDACTED:project-root]');
+  return summarizeForStorage(text, 1200);
+}
+
+function sanitizeFailures(projectRoot, failures) {
+  return failures.map((failure) => sanitizeFailureText(projectRoot, failure));
+}
+
+function formatRecoveryContext(recovery) {
+  const entry = recovery?.entry || {};
+  const lines = [
+    'LLM Wiki compact recovery:',
+    '- PreCompact preservation could not finish before compaction. Use this fallback context only for important lost details.',
+    `- classification: ${recovery?.classification || 'unknown'}`,
+  ];
+  if (recovery?.postCompactSummary) {
+    lines.push(`- compact summary: ${summarizeForStorage(recovery.postCompactSummary, 600)}`);
+  }
+  if (recovery?.failures) {
+    lines.push(`- preservation failure: ${summarizeForStorage(recovery.failures, 600)}`);
+  }
+  const fields = [
+    ['question', 'question', 900],
+    ['work', 'work', 1200],
+    ['result', 'result', 1400],
+    ['changedFiles', 'changed files', 700],
+    ['verification', 'verification', 700],
+    ['followUp', 'follow-up', 700],
+  ];
+  for (const [key, label, limit] of fields) {
+    const value = captured(entry[key]);
+    if (value) lines.push(`\n${label}:\n${summarizeForStorage(value, limit)}`);
+  }
+  return summarizeForStorage(lines.join('\n'), 5000);
+}
+
+async function recordCompactRecoveryFailure(projectRoot, payload, entry, classification, failures) {
+  const recovery = {
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    classification: classification.kind,
+    failures: summarizeForStorage(failures.join('; '), 1200),
+    entry: {
+      topic: summarizeForStorage(entry.topic, 300),
+      question: summarizeForStorage(entry.question, 1000),
+      work: summarizeForStorage(entry.work, 1600),
+      result: summarizeForStorage(entry.result, 1800),
+      changedFiles: summarizeForStorage(entry.changedFiles, 900),
+      verification: summarizeForStorage(entry.verification, 900),
+      followUp: summarizeForStorage(entry.followUp, 900),
+      firstTimestamp: entry.firstTimestamp,
+      session: entry.session,
+    },
+  };
+  recovery.context = formatRecoveryContext(recovery);
+  await writeCompactRecovery(projectRoot, payload, recovery);
+}
+
+function failureOutput(message, mode) {
   if (mode === 'off') return {};
   const reason = summarizeForStorage(message, 1200);
-  if (mode === 'limited' && providerSupportsBlock(provider)) {
-    return {
-      decision: 'block',
-      reason,
-    };
-  }
-  return contextOutput(eventName, `LLM Wiki PreCompact preservation warning:\n${reason}`);
+  return {
+    systemMessage: `LLM Wiki PreCompact preservation warning: ${reason}`,
+  };
 }
 
 export async function handlePreCompactCapture(projectRoot, provider, eventName, payload) {
@@ -193,12 +240,16 @@ export async function handlePreCompactCapture(projectRoot, provider, eventName,
   }
 
   if (failures.length > 0) {
-    return failureOutput(
-      provider,
-      eventName,
-      `LLM Wiki PreCompact preservation did not complete. ${failures.join('; ')}`,
-      mode
-    );
+    let safeFailures = sanitizeFailures(projectRoot, failures);
+    if (classification.archive) {
+      try {
+        await recordCompactRecoveryFailure(projectRoot, payload, entry, classification, safeFailures);
+      } catch (error) {
+        failures.push(`compact recovery marker failed: ${error?.message || error}`);
+        safeFailures = sanitizeFailures(projectRoot, failures);
+      }
+    }
+    return failureOutput(`LLM Wiki PreCompact preservation did not complete. ${safeFailures.join('; ')}`, mode);
   }
 
   return {};
@@ -212,3 +263,30 @@ export async function recordPostCompactSummary(projectRoot, eventName, payload)
     summary ? `Compact summary:\n${redactText(summary, 4000)}` : 'Compact summary was not provided.'
   );
 }
+
+export async function finalizeCompactRecovery(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return null;
+  const summary = compactSummaryText(payload);
+  const next = {
+    ...recovery,
+    updated_at: new Date().toISOString(),
+    postCompactSummary: summary || recovery.postCompactSummary || '',
+    ready: true,
+  };
+  next.context = formatRecoveryContext(next);
+  await writeCompactRecovery(projectRoot, payload, next);
+  await appendContextNote(
+    projectRoot,
+    'PostCompact',
+    'Prepared compact recovery packet for the next legal model-visible hook context.'
+  ).catch(() => {});
+  return next;
+}
+
+export async function consumeCompactRecoveryContext(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return '';
+  await clearCompactRecovery(projectRoot, payload);
+  return recovery.context || formatRecoveryContext(recovery);
+}