llm-wiki-kit 0.1.14 → 0.2.0

package/README.md

@@ -73,18 +73,18 @@ Use Claude Code or Codex normally.
 The installed hooks:
 
 - inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start, instructions loaded, prompt submit, and post-compact time
-- record redacted turn summaries
+- record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
-- update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md`
-- capture reusable-answer candidates into `llm-wiki/wiki/queries/`
-- promote decision-like turns into `llm-wiki/wiki/decisions/`
-- queue durable cleanup candidates in `llm-wiki/outputs/maintenance/queue.md` at stop/session-end time
+- 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
+- queue durable cleanup candidates only for explicit documentation requests that were not reflected in durable wiki files, or when stale turn state is recovered
 - recover stale per-turn state into that queue on the next session start or prompt submit when the previous stop hook did not complete
-- nudge the active LLM to fold reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
+- nudge the active LLM to fold approved reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
 - automatically refresh managed rules/templates for older projects when the current runtime starts a session
 
 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`.
 
 ## Operational Commands
 
@@ -103,13 +103,13 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `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 same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; daily use should rely on hook injection.
+`llm-wiki context "<query>"` prints the same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; 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 lint` checks wiki health and detects outdated managed rules from older kit versions. 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 maintenance` prints the pending queue from `llm-wiki/outputs/maintenance/queue.md`. Hooks create candidates; the active agent should merge reusable items into existing durable wiki pages and mark queue items `done` or `skipped`.
+`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 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

@@ -15,13 +15,14 @@ raw sources -> wiki -> schema/rules
 The important behavior is a loop:
 
 1. A Claude Code or Codex session starts.
-2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
+2. `memory.md`, `index.md`, and relevant wiki context are injected automatically with an answer-first instruction.
 3. The user works normally; no extra command loop is required.
 4. Hooks gather redacted prompt/tool/result summaries.
-5. At stop/session end, hooks append redacted live Q&A and create query or decision candidates when the turn has enough captured context.
-6. At stop/session-end or the next start/prompt after an abrupt shutdown, hooks queue durable cleanup candidates in `outputs/maintenance/queue.md`.
-7. When reusable knowledge appears, the active Claude Code/Codex agent folds it into existing durable wiki pages instead of leaving everything as one-off Q&A.
-8. Future sessions start from the improved wiki instead of relying on long chat history.
+5. At stop/session end, hooks append redacted live Q&A only for meaningful work turns.
+6. Durable wiki promotion is selective: explicit record/document requests should be handled by the active agent in existing wiki pages; the hook queues review only when such a request was not reflected in durable files.
+7. At the next start/prompt after an abrupt shutdown, hooks can recover stale turn state into `outputs/maintenance/queue.md`.
+8. When reusable knowledge appears, the active Claude Code/Codex agent folds approved facts into existing durable wiki pages instead of leaving everything as one-off Q&A.
+9. Future sessions start from the improved wiki instead of relying on long chat history.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -38,7 +39,7 @@ The maintenance loop is intentionally layered:
 
 - `memory.md`: short hot index for current durable facts.
 - `index.md`: broad navigation map.
-- MiniSearch + wikilinks: retrieval over the rest of `wiki/**/*.md`, with substring fallback when MiniSearch is not installed in a source checkout.
-- `outputs/maintenance/queue.md`: pending reminders for turns that need durable wiki review.
+- MiniSearch + wikilinks: retrieval over durable `wiki/**/*.md`, with episodic `wiki/queries/` hidden by default unless `--include-episodic` 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.

package/docs/integrations/claude-code.md

@@ -40,11 +40,12 @@ when no project `CLAUDE.md` exists. Existing `CLAUDE.md` files are not overwritt
 
 The hook records redacted turn summaries but does not deny tool calls only because an input looks sensitive. Hook payloads are stored as small redacted event envelopes rather than full transcripts, and context output is redacted field by field before it is returned to Claude Code.
 
-At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, pending queue items, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set plus pending queue reminders.
+At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set. 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` records a compaction note, and `PostCompact` records the note and returns fresh wiki context. `SubagentStop`, `Stop`, and `SessionEnd` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like. `Stop` and `SessionEnd` also queue pending maintenance items for durable wiki review, then clear the per-session turn buffer after recording; `SubagentStop` does not.
+`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` records a compaction note, and `PostCompact` records the 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.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -29,17 +29,19 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, pending queue items, and any maintenance note for outdated or customized managed rules.
-- `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set plus pending queue reminders.
+- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, and any maintenance note for outdated or customized managed rules.
+- `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set. 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` records a compaction note; `PostCompact` records the note and returns fresh wiki context.
-- `SubagentStop` and `Stop` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like. `Stop` also queues a pending maintenance item for durable wiki review.
+- 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.
 
 Hook payloads are stored as small redacted event envelopes rather than full transcripts. Context output is also redacted field by field before it is returned to Codex.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 Run these after install:
 

package/docs/operations.md

@@ -120,24 +120,29 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working
 
 ## Context And Wiki Maintenance
 
-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 the context automatically, and the active agent is expected to update durable wiki pages when reusable project knowledge appears.
+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.
 
-`Stop` and `SessionEnd` write pending cleanup candidates to `llm-wiki/outputs/maintenance/queue.md` after live Q&A/query/decision capture. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete, then inject up to five pending items into context. 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`. `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.
+
+`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.
 
 `llm-wiki context "<query>"` is the manual debug form of hook context injection. It reads:
 
 - `llm-wiki/wiki/memory.md` as the short hot index
 - `llm-wiki/wiki/index.md` as the navigation map
-- MiniSearch results from `llm-wiki/wiki/**/*.md`, with substring fallback when MiniSearch is unavailable
+- MiniSearch results from durable `llm-wiki/wiki/**/*.md`, with substring fallback when MiniSearch is unavailable
 - 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:
+
 Use it only when you want to inspect what the next agent turn should see:
 
 ```bash
 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 lint` checks Markdown wiki health without modifying files:

package/docs/troubleshooting.md

@@ -179,7 +179,7 @@ Check:
 
 ## Maintenance Queue Is Empty Or Stale
 
-`llm-wiki/outputs/maintenance/queue.md` is created only after a captured `Stop`/`SessionEnd` turn, or when `SessionStart`/`UserPromptSubmit` recovers stale per-turn state from a session that did not stop cleanly.
+In the default answer-first mode, `llm-wiki/outputs/maintenance/queue.md` is created only when a user explicitly asked for durable recording/documentation but no durable wiki update was detected, or when `SessionStart`/`UserPromptSubmit` recovers stale per-turn state from a session that did not stop cleanly. It is not expected to grow after every normal `Stop`.
 
 Check the queue and health warnings:
 
@@ -188,7 +188,7 @@ llm-wiki maintenance --workspace /path/to/project
 llm-wiki lint --workspace /path/to/project
 ```
 
-If the queue is always empty, confirm hooks run and that the turn had a captured `UserPromptSubmit`. If pending items stay around, the active agent should merge reusable content into existing durable wiki pages and mark each queue item `done` or `skipped`.
+If the queue is always empty during ordinary Q&A, that is normal. If you expected an explicit documentation request to queue, confirm hooks run and that the turn had a captured `UserPromptSubmit`. If pending items stay around, the active agent should merge reusable content into existing durable wiki pages and mark each item `done` or `skipped` without delaying unrelated answers.
 
 ## Authentication Values Were Redacted
 

package/package.json

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

package/src/capture-policy.js

@@ -0,0 +1,163 @@
+const NOT_CAPTURED = '(not captured)';
+
+const EXPLICIT_DURABLE_RE = /(?:기록해|기록해줘|문서화|문서화해|wiki에\s*남겨|위키에\s*남겨|wiki[^.\n]{0,40}(?:남겨|저장|기록)|위키[^.\n]{0,40}(?:남겨|저장|기록)|remember\s+this|save\s+this|document\s+this|record\s+this|persist\s+this)/i;
+
+const DURABLE_KEYWORD_RE = /(?:debug|bug|fix|failure|failed|error|root cause|architecture|runtime|hook|install|update|deploy|release|publish|migration|security|policy|procedure|decision|decided|verification|test|lint|build|doctor|디버깅|버그|오류|에러|실패|수정|원인|아키텍처|구조|런타임|훅|설치|업데이트|배포|릴리스|마이그레이션|보안|정책|절차|결정|선택|채택|확정|검증|테스트|문서|위키|wiki)/i;
+
+const MAINTENANCE_QUERY_RE = /(?:llm-wiki|wiki|위키|maintenance|maintain|문서|문서화|기록|정리|consolidate|lint|queue|AGENTS\.md)/i;
+
+export function captureMode(env = process.env) {
+  return env.LLM_WIKI_KIT_CAPTURE_MODE === 'legacy-eager' ? 'legacy-eager' : 'answer-first';
+}
+
+export function isLegacyEagerCaptureMode(env = process.env) {
+  return captureMode(env) === 'legacy-eager';
+}
+
+export function capturedText(value) {
+  const text = String(value || '').trim();
+  if (!text || text === NOT_CAPTURED) return '';
+  return text;
+}
+
+export function hasCapturedQuestion(entry) {
+  return capturedText(entry?.question).length >= 8;
+}
+
+export function entrySearchText(entry) {
+  return [
+    entry?.question,
+    entry?.result,
+    entry?.work,
+    entry?.changedFiles,
+    entry?.verification,
+  ].map(capturedText).filter(Boolean).join('\n');
+}
+
+export function explicitDurableRequested(value) {
+  const text = typeof value === 'string' ? value : entrySearchText(value);
+  return EXPLICIT_DURABLE_RE.test(text);
+}
+
+export function hasDurableKeyword(value) {
+  const text = typeof value === 'string' ? value : entrySearchText(value);
+  return DURABLE_KEYWORD_RE.test(text);
+}
+
+export function isMaintenanceRelatedQuery(query, pendingItems = []) {
+  const text = capturedText(query);
+  if (!text) return false;
+  if (MAINTENANCE_QUERY_RE.test(text)) return true;
+  const terms = text
+    .normalize('NFC')
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+    .split(/\s+/)
+    .filter((term) => term.length >= 3);
+  if (terms.length === 0) return false;
+  return pendingItems.some((item) => {
+    const topic = `${item.topic || ''} ${item.source || ''}`.normalize('NFC').toLowerCase();
+    return terms.some((term) => topic.includes(term));
+  });
+}
+
+export function hasDetectedDurableWikiChange(entry) {
+  const text = [
+    entry?.changedFiles,
+    entry?.work,
+  ].map(capturedText).filter(Boolean).join('\n');
+  return /(?:^|[\s"'`])(?:llm-wiki\/)?(?:wiki\/(?!queries\/)(?:architecture|debugging|decisions|concepts|entities|sources|context)\/|procedures\/|llm-wiki\/wiki\/(?!queries\/)(?:architecture|debugging|decisions|concepts|entities|sources|context)\/|llm-wiki\/procedures\/)[^\s"'`]+\.md\b/i.test(text);
+}
+
+export function classifyTurn(entry, eventName = '') {
+  if (eventName === 'SubagentStop') {
+    return {
+      kind: 'subagent',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  const question = capturedText(entry?.question);
+  const result = capturedText(entry?.result);
+  const work = capturedText(entry?.work);
+  const changedFiles = capturedText(entry?.changedFiles);
+  const verification = capturedText(entry?.verification);
+  const text = entrySearchText(entry);
+
+  if (!question && !result) {
+    return {
+      kind: 'empty',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  if (explicitDurableRequested(text)) {
+    return {
+      kind: 'explicit-durable',
+      archive: true,
+      suggestDurable: false,
+      queueIfMissingDurable: true,
+    };
+  }
+
+  const hasWork = Boolean(work);
+  const hasFiles = Boolean(changedFiles);
+  const hasVerification = Boolean(verification);
+  const longWork = work.length > 800;
+  const durableKeyword = hasDurableKeyword(text);
+  const simple =
+    !hasWork &&
+    !hasFiles &&
+    !hasVerification &&
+    question.length <= 120 &&
+    result.length <= 800 &&
+    !durableKeyword;
+
+  if (simple) {
+    return {
+      kind: 'simple',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  if (durableKeyword) {
+    return {
+      kind: 'suggest-durable',
+      archive: true,
+      suggestDurable: true,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  return {
+    kind: hasWork || hasFiles || hasVerification || longWork || result.length > 800 ? 'archive-only' : 'simple',
+    archive: hasWork || hasFiles || hasVerification || longWork || result.length > 800,
+    suggestDurable: false,
+    queueIfMissingDurable: false,
+  };
+}
+
+export function formatDurableCaptureGuidance(query) {
+  const text = capturedText(query);
+  if (!text) return '';
+  if (explicitDurableRequested(text)) {
+    return [
+      'LLM Wiki durable documentation request detected:',
+      '- 현재 사용자 요청을 먼저 처리하되, 사용자가 기록/문서화를 요청했으므로 기존 durable wiki 문서를 찾아 갱신한다.',
+      '- 새 문서는 관련 기존 문서가 없을 때만 만들고, credentials/private data는 저장하지 않는다.',
+    ].join('\n');
+  }
+  if (hasDurableKeyword(text)) {
+    return [
+      'LLM Wiki durable knowledge note:',
+      '- 현재 답변을 먼저 한다. 다음 세션에도 쓸 결론이면 답변 끝에서 짧게 wiki 문서화 여부를 물어본다.',
+    ].join('\n');
+  }
+  return '';
+}

package/src/cli.js

@@ -51,6 +51,8 @@ function parseOptions(args) {
       i += 1;
     } else if (arg === '--no-expand') {
       options.expand = false;
+    } else if (arg === '--include-episodic') {
+      options.includeEpisodic = true;
     } else if (arg === '--replace-hooks') {
       options.replaceHooks = true;
     } else if (arg === '--all') {
@@ -96,7 +98,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]
+  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand] [--include-episodic]
   llm-wiki lint --workspace <project>
   llm-wiki consolidate --workspace <project> [--dry-run]
   llm-wiki maintenance --workspace <project> [--json]

package/src/hook.js

@@ -1,4 +1,5 @@
 import { findProjectRoot } from './fs-utils.js';
+import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
 import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
@@ -41,6 +42,49 @@ function contextOutput(eventName, context) {
   };
 }
 
+async function handleLegacyEagerStop(projectRoot, eventName, payload, entry) {
+  if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
+    const liveQaPath = await appendLiveQa(projectRoot, entry);
+    const queryPath = await writeQueryPage(projectRoot, entry);
+    const decisionPath = await writeDecisionPage(projectRoot, entry);
+    if (eventName === 'Stop' || eventName === 'SessionEnd') {
+      await recordMaintenanceForEntry(projectRoot, entry, {
+        source: decisionPath || queryPath || liveQaPath,
+        eventName,
+        reason: 'Captured turn needs durable wiki review.',
+      }).catch(() => {});
+    }
+    await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${relative(projectRoot, queryPath)}` : ''}${decisionPath ? `; decision=${relative(projectRoot, decisionPath)}` : ''}`);
+  }
+  if (eventName === 'Stop' || eventName === 'SessionEnd') {
+    await clearTurnState(projectRoot, payload).catch(() => {});
+  }
+}
+
+async function handleAnswerFirstStop(projectRoot, eventName, payload, entry) {
+  const classification = classifyTurn(entry, eventName);
+  if (classification.archive) {
+    const archiveEntry = {
+      ...entry,
+      followUp: classification.suggestDurable
+        ? '이 결론은 다음 세션에도 쓸 수 있어 보입니다. 사용자가 승인하면 기존 durable wiki 문서에 합친다.'
+        : entry.followUp,
+    };
+    const liveQaPath = await appendLiveQa(projectRoot, archiveEntry);
+    if (classification.queueIfMissingDurable && !hasDetectedDurableWikiChange(entry)) {
+      await recordMaintenanceForEntry(projectRoot, entry, {
+        source: liveQaPath,
+        eventName,
+        reason: 'Explicit durable documentation request did not have a detected durable wiki update.',
+      }).catch(() => {});
+    }
+    await appendWikiLog(projectRoot, `captured ${eventName}; archive=${relative(projectRoot, liveQaPath)}; classification=${classification.kind}`);
+  }
+  if (eventName === 'Stop' || eventName === 'SessionEnd') {
+    await clearTurnState(projectRoot, payload).catch(() => {});
+  }
+}
+
 async function autoUpdateManagedProject(projectRoot, eventName) {
   if (process.env.LLM_WIKI_KIT_AUTO_PROJECT_UPDATE === '0') return;
   if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') return;
@@ -74,7 +118,8 @@ export async function handleHook(provider, explicitEvent) {
   if (eventName === 'UserPromptSubmit') {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
-    const context = await buildContextBrief(projectRoot, eventName, prompt);
+    const guidance = formatDurableCaptureGuidance(prompt);
+    const context = [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n');
     return contextOutput(eventName, context);
   }
 
@@ -99,21 +144,10 @@ export async function handleHook(provider, explicitEvent) {
   if (eventName === 'Stop' || eventName === 'SubagentStop' || eventName === 'SessionEnd') {
     const assistantText = payload.last_assistant_message || payload.response || payload.assistant_response || '';
     const entry = await buildEntryFromState(projectRoot, payload, assistantText);
-    if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
-      const liveQaPath = await appendLiveQa(projectRoot, entry);
-      const queryPath = await writeQueryPage(projectRoot, entry);
-      const decisionPath = await writeDecisionPage(projectRoot, entry);
-      if (eventName === 'Stop' || eventName === 'SessionEnd') {
-        await recordMaintenanceForEntry(projectRoot, entry, {
-          source: decisionPath || queryPath || liveQaPath,
-          eventName,
-          reason: 'Captured turn needs durable wiki review.',
-        }).catch(() => {});
-      }
-      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${relative(projectRoot, queryPath)}` : ''}${decisionPath ? `; decision=${relative(projectRoot, decisionPath)}` : ''}`);
-    }
-    if (eventName === 'Stop' || eventName === 'SessionEnd') {
-      await clearTurnState(projectRoot, payload).catch(() => {});
+    if (isLegacyEagerCaptureMode()) {
+      await handleLegacyEagerStop(projectRoot, eventName, payload, entry);
+    } else {
+      await handleAnswerFirstStop(projectRoot, eventName, payload, entry);
     }
     return {};
   }

package/src/maintenance.js

@@ -1,6 +1,7 @@
 import { readdir, unlink } from 'fs/promises';
 import { join, relative } from 'path';
 import { appendText, exists, kitDataDir, readJson, readText, sha256, writeTextIfMissing } from './fs-utils.js';
+import { classifyTurn, isMaintenanceRelatedQuery } from './capture-policy.js';
 import { redactText, summarizeForStorage } from './redaction.js';
 import { buildEntryFromTurnState, hasRecoverableTurnState } from './state.js';
 
@@ -206,6 +207,11 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
     if (Number.isFinite(updated) && now - updated < cutoffMs) continue;
     if (!hasRecoverableTurnState(state)) continue;
     const entry = buildEntryFromTurnState(state, '');
+    if (!classifyTurn(entry, 'recovered stale turn state').archive) {
+      await unlink(path).catch(() => {});
+      output.push({ created: false, reason: 'simple-stale-turn', statePath: path, session: state.session });
+      continue;
+    }
     const result = await recordMaintenanceForEntry(projectRoot, entry, {
       source: `state:${state.session || path.split('/').pop()?.replace(/\.json$/, '')}`,
       eventName: 'recovered stale turn state',
@@ -219,12 +225,24 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
 }
 
 export function formatMaintenanceContext(summary, options = {}) {
-  const limit = options.limit || 5;
-  const pending = summary.pending.slice(0, limit);
+  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 '';
+    pending = summary.pending.slice(0, 1);
+  } else if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') {
+    return '';
+  }
+
   const lines = [
-    'LLM Wiki maintenance queue:',
-    '- Pending items should be merged into existing durable wiki pages when relevant; update queue status to done or skipped after review.',
+    eventName === 'UserPromptSubmit'
+      ? 'LLM Wiki maintenance queue soft reminder:'
+      : 'LLM Wiki maintenance queue summary:',
+    `- pending: ${summary.pendingCount}. 현재 사용자 요청을 지연시키지 말고, 관련 있을 때만 기존 durable wiki 문서에 병합한다.`,
   ];
   for (const item of pending) {
     lines.push(`- ${item.topic || item.id}: source=${item.source}; target=${item.suggested_target}; reason=${item.reason}${item.result_missing ? '; result_missing=true' : ''}`);

package/src/project.js

@@ -169,7 +169,7 @@ export async function buildContextBrief(projectRoot, eventName, query = '') {
     .then(formatProjectMaintenanceContext)
     .catch(() => '');
   const wikiMaintenance = await maintenanceSummary(projectRoot)
-    .then(formatMaintenanceContext)
+    .then((summary) => formatMaintenanceContext(summary, { eventName, query }))
     .catch(() => '');
   return [formatContextPack(pack), maintenance, wikiMaintenance].filter(Boolean).join('\n\n');
 }

package/src/templates.js

@@ -13,11 +13,11 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`llm-wiki/raw/\`는 원본 또는 redacted 근거 저장소다. hook envelope append 외에는 원본 capture를 수정하지 않는다.
 - \`llm-wiki/wiki/\`는 agent가 관리하는 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 여기에 정리한다.
 - \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
-- hook이 주입한 context를 우선 사용한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
-- hook은 redacted live Q&A와 query/decision 후보를 기록한다. 재사용 가능한 지식은 agent가 기존 정식 wiki 문서에 합친다.
-- hook은 종료/시작 경계에서 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 agent가 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- hook이 주입한 context를 참고하되, 현재 사용자 답변을 먼저 처리한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
+- hook은 redacted raw envelope와 필요한 live Q&A를 안전하게 남긴다. \`wiki/queries\`/\`wiki/decisions\` 자동 승격은 기본값이 아니며, durable 지식은 중요도와 동의 흐름에 따라 agent가 기존 정식 wiki 문서에 합친다.
+- hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
 - 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
-- 일회성 작업 기록은 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
+- 일회성 작업 기록은 필요할 때 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
 - 인증값, token, password, private key, \`.env\` 원문은 저장하지 않는다. 필요한 경우 redacted summary만 남긴다.
 
@@ -32,7 +32,7 @@ Generated by llm-wiki-kit ${runtimeVersion()}.
 
 ## Purpose
 Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wiki를 자연스럽게 유지한다.
-사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하는 것이 기본이다.
+사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하되 현재 사용자 답변을 지연시키지 않는 것이 기본이다.
 이 규칙은 오래된 OMX/OMC/\`omx_wiki/\` 규칙을 대체한다.
 
 ## Directories
@@ -42,13 +42,14 @@ Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wik
 - \`procedures/\`: ingest, query, lint, security 같은 운영 규칙.
 
 ## Core Rules
-- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행한다.
+- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행하되, 현재 사용자 요청에 대한 답변을 먼저 끝낸다.
 - \`raw/\` 원본은 수정하지 않는다. 안전한 hook envelope append만 예외다.
 - 근거 없는 내용을 사실처럼 쓰지 않는다. 추론은 명시한다.
 - 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
 - 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
-- 반복해서 쓸 지식은 \`outputs/questions/\`에만 두지 말고 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
-- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 다음 작업 시작 시 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- 단순 답변, 상태 확인, 일회성 대화는 과도하게 \`wiki/queries\`나 maintenance로 승격하지 않는다.
+- 반복해서 쓸 지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 현재 요청과 관련 있을 때 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
 - \`wiki/memory.md\`는 짧게 유지한다. 긴 설명 대신 현재 상태와 중요한 문서 링크를 둔다.
 - 모순은 덮어쓰지 말고 \`Contradictions\` 또는 \`Open Questions\`에 보존한다.
 - 인증값, token, password, private key, \`.env\` 원문은 wiki에 저장하지 않는다.
@@ -74,10 +75,10 @@ superseded_by: []
 
 ## Operations
 - ingest: \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽고, 새 근거를 확인한 뒤 기존 wiki 문서를 우선 갱신한다.
-- query: hook이 주입한 context를 우선 사용한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
-- lint: agent가 필요할 때 wiki 건강 상태를 점검하는 보조 도구다. 사용자가 매번 직접 실행해야 하는 명령이 아니다.
+- query: hook이 주입한 context를 참고하되 현재 답변을 먼저 한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
+- lint: 사용자가 요청했거나 wiki 유지보수 작업일 때 agent가 쓰는 보조 도구다. 매 turn 실행하지 않는다.
 - consolidate: agent가 \`memory.md\`/\`index.md\` generated block을 안전하게 갱신할 때 쓰는 보조 도구다. 손글씨 영역과 정식 문서 본문은 덮어쓰지 않는다.
-- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
+- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. 현재 요청을 지연시키지 않는 범위에서 agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
 `;
 }
 
@@ -169,19 +170,21 @@ export function procedure(name) {
 3. source별 요약이 필요하면 \`wiki/sources/<slug>.md\`를 만들거나 갱신한다.
 4. 새 문서부터 만들지 말고 관련 concept/entity/decision/architecture/debugging/context 문서를 먼저 찾아 갱신한다.
 5. 중복 문서를 만들지 않는다. 같은 사실이 이미 있으면 기존 문서에 합친다.
-6. 중요한 주장에는 source reference, confidence, memory type, importance, verification status를 남긴다.
-7. durable entry point가 바뀌면 \`wiki/memory.md\`를 짧게 갱신하거나 agent가 \`llm-wiki consolidate\`를 사용한다.
-8. 의미 있는 변화는 \`wiki/log.md\`에 짧게 남긴다.
+6. 단순 답변과 일회성 대화는 durable wiki로 승격하지 않는다.
+7. 중요한 주장에는 source reference, confidence, memory type, importance, verification status를 남긴다.
+8. durable entry point가 바뀌면 \`wiki/memory.md\`를 짧게 갱신하거나 agent가 \`llm-wiki consolidate\`를 사용한다.
+9. 의미 있는 변화는 \`wiki/log.md\`에 짧게 남긴다.
 `,
     'query.md': `# Query Procedure
 
-1. hook이 주입한 context를 먼저 사용한다. 수동으로 확인할 때만 \`llm-wiki context "<query>"\`를 쓴다.
+1. 현재 사용자 질문에 먼저 답한다. hook이 주입한 context는 필요한 만큼만 참고한다.
 2. \`wiki/memory.md\`와 \`wiki/index.md\`에서 시작한다.
 3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
 4. 정확한 근거가 필요할 때만 raw source를 확인한다.
 5. 검증된 사실과 추론을 분리한다.
-6. 일회성 답변은 \`outputs/questions/\`에 남기고, 재사용 가능한 답변은 기존 \`wiki/queries/\` 또는 관련 정식 문서에 연결한다.
-7. 반복해서 쓸 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query까지 봐야 할 때는 \`--include-episodic\`을 붙인다.
+7. 일회성 답변은 durable wiki로 승격하지 않는다. 필요한 작업 turn만 \`outputs/questions/\`에 남긴다.
+8. 반복해서 쓸 결론은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
 `,
     'lint.md': `# Lint Procedure
 

package/src/wiki-search.js

@@ -79,6 +79,20 @@ 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;
+}
+
+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;
+  }
+  return true;
+}
+
 export async function searchWiki(projectRoot, query, options = {}) {
   return (await performSearch(projectRoot, query, options)).hits;
 }
@@ -94,7 +108,7 @@ async function performSearch(projectRoot, query, options = {}) {
 
   let pages = [];
   try {
-    pages = await collectWikiPages(projectRoot, opts);
+    pages = (await collectWikiPages(projectRoot, opts)).filter((page) => isDefaultSearchCandidate(page, opts));
   } catch {
     return { hits: [], search: 'missing-wiki' };
   }
@@ -212,12 +226,12 @@ export async function buildContextPack(projectRoot, query, options = {}) {
 
 export function formatContextPack(pack) {
   const lines = [
-    'LLM Wiki context from llm-wiki-kit:',
+    'LLM Wiki context from llm-wiki-kit: answer the current user request first; use wiki context only when it helps.',
     '- Treat chat memory as temporary; update project Markdown when knowledge should persist.',
     '- Preserve raw/wiki separation. Do not store secrets, tokens, .env contents, private keys, or personal/customer identifiers.',
     '- Prefer updating existing wiki pages over creating duplicate pages.',
-    '- Claude Code/Codex를 평소처럼 사용한다. 사용자가 별도 명령을 실행하지 않아도 agent가 필요한 wiki 조회와 정리를 수행한다.',
-    '- 오래 쓸 지식은 outputs/questions에만 두지 말고 기존 wiki/architecture, wiki/debugging, wiki/decisions, wiki/concepts, procedures 문서에 합친다.',
+    '- Claude Code/Codex를 평소처럼 사용한다. 사용자가 별도 명령을 실행하지 않아도 agent가 필요한 wiki 조회와 정리를 수행하되, 현재 사용자 답변을 지연시키지 않는다.',
+    '- durable 기록은 중요도와 동의 흐름에 따라 선택적으로 승격한다. 오래 쓸 지식은 승인된 경우 기존 wiki/architecture, wiki/debugging, wiki/decisions, wiki/concepts, procedures 문서에 합친다.',
     '- wiki/memory.md는 짧은 핵심 기억으로 유지하고, 긴 설명 대신 관련 정식 문서 링크를 둔다.',
   ];
   if (pack.query) {