llm-wiki-kit 0.2.11 → 0.2.13

package/src/templates.js

@@ -8,18 +8,19 @@ export function rootAgentsPolicy() {
 This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex and Claude Code.
 
 - This block supersedes older OMX/OMC/\`omx_wiki/\` LLM Wiki instructions for this repository.
-- 평소처럼 Codex 또는 Claude Code를 사용한다. 사용자가 별도 \`llm-wiki\` 명령을 외워서 실행해야 하는 흐름을 만들지 않는다.
-- 채팅 기억은 임시로 본다. 오래 남길 프로젝트 지식은 \`llm-wiki/\` Markdown에 남긴다.
-- \`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 raw envelope와 작업/결정 중심 live Q&A만 안전하게 남긴다. 단순 답변, 상태 확인, 키워드만 포함된 응답은 live Q&A나 durable wiki로 승격하지 않는다. \`wiki/queries\`/\`wiki/decisions\` 자동 승격은 기본값이 아니며, durable 지식은 중요도와 동의 흐름에 따라 agent가 기존 정식 wiki 문서에 합친다.
-- hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. 정기 maintenance는 agent-side soft reminder이며, pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
-- 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 chunked \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
-- 일회성 작업/결정 기록은 필요할 때 \`llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md\` style chunk에 보존하고, 재사용 가능한 사실/지식은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
-- 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
-- 인증값, token, password, private key, \`.env\` 원문은 저장하지 않는다. 필요한 경우 redacted summary만 남긴다.
+- Use Codex or Claude Code normally. Do not create a workflow where users must remember extra \`llm-wiki\` commands during ordinary work.
+- Language: respond in the user's current prompt language when it is clearly Korean or English. Keep technical identifiers, commands, paths, code, and original error text unchanged. If no prompt language is clear, follow local \`CLAUDE.md\`/\`AGENTS.md\` guidance, then fall back to English.
+- Treat chat memory as temporary. Durable project knowledge belongs in repository Markdown under \`llm-wiki/\`.
+- \`llm-wiki/raw/\` is the immutable or redacted evidence layer. Do not modify raw captures except safe hook envelope append.
+- \`llm-wiki/wiki/\` is the curated knowledge layer managed by the agent. Put decisions, architecture, debugging findings, concepts, procedures, and context there.
+- Keep \`llm-wiki/wiki/memory.md\` short. Link to important documents instead of copying long explanations.
+- Use hook-injected context when helpful, but answer the current user request first. Use \`llm-wiki context\`, \`llm-wiki lint\`, and \`llm-wiki consolidate\` only as agent maintenance helpers.
+- Hooks safely store redacted raw envelopes and work/decision-focused live Q&A. Simple answers, status checks, and keyword-only turns should not be promoted to live Q&A or durable wiki by default.
+- Hooks may queue durable cleanup candidates in \`llm-wiki/outputs/maintenance/queue.md\` at stop/start boundaries. Treat maintenance as a soft agent-side reminder; merge pending items only when relevant and mark them \`done\` or \`skipped\`.
+- Before creating new wiki pages, search existing pages and update the right one when possible. Reusable facts should not stay only in chunked \`outputs/questions/\`.
+- Store one-off work or decision records in \`llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md\` when needed. Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` when approved or clearly important.
+- Record verification commands, evidence files, and uncertainty. Mark inference explicitly and preserve contradictions in Open Questions or Contradictions.
+- Never store credentials, tokens, passwords, private keys, or raw \`.env\` contents. Store only redacted summaries when needed.
 
 <!-- llm-wiki-kit:end -->
 `;
@@ -31,29 +32,35 @@ export function llmWikiAgents() {
 Generated by llm-wiki-kit ${runtimeVersion()}.
 
 ## Purpose
-Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wiki를 자연스럽게 유지한다.
-사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하되 현재 사용자 답변을 지연시키지 않는 것이 기본이다.
-이 규칙은 오래된 OMX/OMC/\`omx_wiki/\` 규칙을 대체한다.
+Maintain a living Markdown LLM Wiki while users work normally in Codex or Claude Code.
+The user should not need to run many \`llm-wiki\` commands manually. The agent checks and maintains wiki context when useful, but the current user answer comes first.
+These rules replace older OMX/OMC/\`omx_wiki/\` rules for this project.
+
+## Language
+- Follow the user's current prompt language when it is clearly Korean or English.
+- If no current prompt language is clear, follow local \`CLAUDE.md\`/\`AGENTS.md\` guidance, then fall back to English.
+- Keep commands, paths, code identifiers, API names, package names, logs, and original error text unchanged.
+- Korean and English users should both be able to use Codex/Claude Code naturally without changing \`llm-wiki\` commands.
 
 ## Directories
-- \`raw/\`: 원본 또는 redacted 근거 저장소. hook이 redacted envelope를 append하는 경우 외에는 원본 capture를 수정하지 않는다.
-- \`wiki/\`: agent가 관리하는 정식 지식 문서. \`wiki/memory.md\`는 hook context에 들어가는 짧은 핵심 기억이다.
-- \`outputs/\`: live Q&A, 보고서, 긴 생성물 저장소. 일회성 기록은 여기에 둔다.
-- \`procedures/\`: ingest, query, lint, security 같은 운영 규칙.
+- \`raw/\`: immutable or redacted evidence. Do not edit raw captures except safe hook envelope append.
+- \`wiki/\`: curated knowledge pages maintained by the agent. \`wiki/memory.md\` is the short hot index injected into hook context.
+- \`outputs/\`: live Q&A, reports, maintenance candidates, and long generated artifacts. One-off records belong here.
+- \`procedures/\`: operating rules for ingest, query, lint, and security.
 
 ## Core Rules
-- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행하되, 현재 사용자 요청에 대한 답변을 먼저 끝낸다.
-- \`raw/\` 원본은 수정하지 않는다. 안전한 hook envelope append만 예외다.
-- 근거 없는 내용을 사실처럼 쓰지 않는다. 추론은 명시한다.
-- 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
-- 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
-- 단순 답변, 상태 확인, 키워드만 포함된 응답, 일회성 대화는 live Q&A, \`wiki/queries\`, maintenance로 승격하지 않는다.
-- 반복해서 쓸 지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
-- 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에 저장하지 않는다.
+- Users work normally in Claude Code/Codex. The agent performs wiki lookup and maintenance naturally, but answers the current request first.
+- Do not modify \`raw/\` source material except safe hook envelope append.
+- Do not state unsupported claims as facts. Mark inference explicitly.
+- Important claims should include at least one of: \`source_ids\`, file paths, or verification commands.
+- When durable knowledge appears, search existing \`wiki/\` pages before creating a new page.
+- Do not promote simple answers, status checks, keyword-only replies, or one-off chat into live Q&A, \`wiki/queries\`, or maintenance.
+- Merge reusable knowledge into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance and user consent flow.
+- Review \`outputs/maintenance/queue.md\` pending items only when related to the current request or when review is due. Merge into existing durable wiki pages, then mark items \`done\` or \`skipped\`.
+- Periodic maintenance is agent review, not automatic editing. Show only short reminders at \`SessionStart\`/\`InstructionsLoaded\`, and only show prompt-time reminders for wiki/maintenance-related user prompts.
+- Keep \`wiki/memory.md\` short. Use links to current state and important documents instead of long explanations.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\`; do not overwrite them silently.
+- Do not store credentials, tokens, passwords, private keys, or raw \`.env\` contents in wiki.
 
 ## Page Format
 Use YAML frontmatter when creating wiki pages:
@@ -75,11 +82,11 @@ superseded_by: []
 \`\`\`
 
 ## Operations
-- ingest: \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽고, 새 근거를 확인한 뒤 기존 wiki 문서를 우선 갱신한다.
-- query: hook이 주입한 context를 참고하되 현재 답변을 먼저 한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
-- lint: 사용자가 요청했거나 wiki 유지보수 작업일 때 agent가 쓰는 보조 도구다. 매 turn 실행하지 않는다.
-- consolidate: agent가 \`memory.md\`/\`index.md\` generated block을 안전하게 갱신할 때 쓰는 보조 도구다. 손글씨 영역과 정식 문서 본문은 덮어쓰지 않는다.
-- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. 현재 요청을 지연시키지 않는 범위에서 agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
+- ingest: read \`wiki/memory.md\` and \`wiki/index.md\` first, verify new evidence, then prefer updating existing wiki pages.
+- query: use hook-injected context when useful, but answer the current request first. Manual commands are diagnostics, not required daily workflow.
+- lint: agent helper for user-requested or wiki maintenance work. Do not run it every turn.
+- consolidate: safely refresh generated blocks in \`memory.md\`/\`index.md\`. Do not overwrite handwritten sections or curated document bodies.
+- maintenance: \`outputs/maintenance/queue.md\` stores stop/start cleanup candidates. Review and update it only when it does not delay the current user request.
 `;
 }
 
@@ -90,31 +97,31 @@ Generated by llm-wiki-kit.
 
 ## Overview
 
-이 파일은 living wiki의 짧은 지도다. 자세한 설명을 길게 쓰기보다, agent가 다음 작업에서 빠르게 찾아갈 entry point를 유지한다.
+This file is the short navigation map for the living wiki. Keep entry points easy to scan instead of adding long explanations here.
 
 ## Main Areas
 
-- [Memory](memory.md) - 짧은 핵심 기억과 주요 entry point.
-- [Sources](sources/) - source summary와 source id.
-- [Concepts](concepts/) - 재사용 가능한 개념과 용어.
-- [Entities](entities/) - 시스템, 모듈, 도구, 서비스, 주요 객체.
-- [Decisions](decisions/) - 결정과 근거.
-- [Architecture](architecture/) - 구조와 데이터/제어 흐름.
-- [Debugging](debugging/) - 원인, 수정, 검증 evidence.
-- [Context](context/) - 세션 연속성과 프로젝트 맥락.
-- [Queries](queries/) - 재사용 가능한 질문 답변. 일회성 기록은 outputs/questions에 둔다.
+- [Memory](memory.md) - short active memory and durable entry points.
+- [Sources](sources/) - source summaries and source IDs.
+- [Concepts](concepts/) - reusable concepts and terminology.
+- [Entities](entities/) - systems, modules, tools, services, and important objects.
+- [Decisions](decisions/) - decisions and rationale.
+- [Architecture](architecture/) - structure, data flow, and control flow.
+- [Debugging](debugging/) - causes, fixes, and verification evidence.
+- [Context](context/) - session continuity and project context.
+- [Queries](queries/) - reusable question answers. One-off records belong in outputs/questions.
 
 ## Operating Notes
 
-- 넓은 질문은 memory와 이 index에서 시작한다.
-- 새 문서를 만들기 전에 관련 기존 문서 3-7개를 먼저 확인한다.
-- 오래 쓸 사실/지식은 기존 정식 문서에 합치고, 작업/결정 중심 일회성 기록은 chunked outputs/questions에 둔다.
-- 관련 페이지가 생기면 \`[[page-or-topic]]\` 링크를 추가한다.
+- Start broad questions from memory and this index.
+- Before creating a new page, check 3-7 relevant existing pages.
+- Merge durable facts into existing curated pages. Keep one-off work/decision records in chunked outputs/questions.
+- Add \`[[page-or-topic]]\` links when related pages become useful.
 
 <!-- llm-wiki-kit:index-start -->
 ## Generated Page Map
 
-Agent가 필요할 때 \`llm-wiki consolidate --workspace <project>\`로 이 generated block을 갱신한다.
+The agent may refresh this generated block with \`llm-wiki consolidate --workspace <project>\`.
 <!-- llm-wiki-kit:index-end -->
 `;
 }
@@ -136,11 +143,11 @@ superseded_by: []
 
 # LLM Wiki Memory
 
-짧은 핵심 기억이다. hook context에 들어갈 만큼 작게 유지하고, 긴 설명을 복사하지 말고 깊은 문서로 링크한다.
+Short active memory for hook context. Keep it small and link to deeper documents instead of copying long explanations.
 
 ## Current Focus
 
-- 오래 남길 현재 프로젝트 초점을 여기에 짧게 추가한다.
+- Add the current durable project focus here in a few short bullets.
 
 ## Durable Entry Points
 
@@ -150,7 +157,7 @@ superseded_by: []
 <!-- llm-wiki-kit:memory-start -->
 ## Generated Memory Map
 
-Agent가 필요할 때 \`llm-wiki consolidate --workspace <project>\`로 이 generated block을 갱신한다.
+The agent may refresh this generated block with \`llm-wiki consolidate --workspace <project>\`.
 <!-- llm-wiki-kit:memory-end -->
 `;
 }
@@ -166,50 +173,50 @@ export function procedure(name) {
   const procedures = {
     'ingest.md': `# Ingest Procedure
 
-1. \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽는다.
-2. 새 근거가 있으면 \`raw/inbox/\` 또는 \`raw/sources/\`를 확인한다.
-3. source별 요약이 필요하면 \`wiki/sources/<slug>.md\`를 만들거나 갱신한다.
-4. 새 문서부터 만들지 말고 관련 concept/entity/decision/architecture/debugging/context 문서를 먼저 찾아 갱신한다.
-5. 중복 문서를 만들지 않는다. 같은 사실이 이미 있으면 기존 문서에 합친다.
-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\`에 짧게 남긴다.
+1. Read \`wiki/memory.md\` and \`wiki/index.md\` first.
+2. If new evidence exists, inspect \`raw/inbox/\` or \`raw/sources/\`.
+3. Create or update \`wiki/sources/<slug>.md\` only when a source summary is useful.
+4. Before creating a new page, look for related concept/entity/decision/architecture/debugging/context pages and update those first.
+5. Do not create duplicates. Merge facts into existing pages when they already exist.
+6. Do not promote simple answers or one-off chat into durable wiki.
+7. Important claims should record source references, confidence, memory type, importance, and verification status.
+8. When durable entry points change, update \`wiki/memory.md\` briefly or use \`llm-wiki consolidate\`.
+9. Add a short entry to \`wiki/log.md\` for meaningful wiki changes.
 `,
     'query.md': `# Query Procedure
 
-1. 현재 사용자 질문에 먼저 답한다. hook이 주입한 context는 필요한 만큼만 참고한다.
-2. \`wiki/memory.md\`와 \`wiki/index.md\`에서 시작한다.
-3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
-4. 정확한 근거가 필요할 때만 raw source를 확인한다.
-5. 검증된 사실과 추론을 분리한다.
-6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query/context까지 봐야 할 때는 \`--include-episodic\`을 붙이고, archived/superseded page까지 봐야 할 때만 \`--include-archived\`를 붙인다.
-7. 일회성 답변, 상태 확인, 키워드만 포함된 응답은 durable wiki나 live Q&A로 승격하지 않는다. tool evidence, changed-file evidence, verification, 구조화된 decision/debugging 결론이 있는 작업 turn만 \`outputs/questions/YYYY-MM-DD/live-qa-001.md\` style chunk에 남긴다.
-8. 반복해서 쓸 사실/지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+1. Answer the current user question first. Use hook-injected context only as needed.
+2. Start from \`wiki/memory.md\` and \`wiki/index.md\`.
+3. Read the smallest relevant set of \`wiki/\` documents.
+4. Inspect raw sources only when exact evidence matters.
+5. Separate verified facts from inference.
+6. Use \`llm-wiki context "<query>"\` only when manual inspection is useful. Add \`--include-episodic\` only for historical query/context pages, and \`--include-archived\` only for archived/superseded pages.
+7. Do not promote one-off answers, status checks, or keyword-only replies to durable wiki or live Q&A. Archive only work turns with tool evidence, changed-file evidence, verification, or structured decision/debugging conclusions.
+8. Merge reusable facts into \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, or \`procedures/\` based on importance and user consent flow.
 `,
     'lint.md': `# Lint Procedure
 
-\`llm-wiki lint --workspace <project>\`는 agent가 필요할 때 쓰는 wiki 건강 점검 도구다. 사용자가 매번 실행해야 하는 명령이 아니다.
+\`llm-wiki lint --workspace <project>\` is an agent-side wiki health check. Users should not need to run it every turn.
 
-점검 대상: stale page, orphan page, broken wiki/Markdown link, unsafe source id, secret-like content, missing source, duplicate concept/title, unsupported claim, unresolved contradiction, outdated managed rule, memory budget, page count growth, hidden episodic/context growth, stale/archived discoverability, maintenance review due, oversized legacy live Q&A, oversized live Q&A chunk.
+Checks include stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts/titles, unsupported claims, unresolved contradictions, outdated managed rules, memory budget pressure, page-count growth, hidden episodic/context growth, stale/archived discoverability, maintenance review due, oversized legacy live Q&A, and oversized live Q&A chunks.
 
-정기 maintenance는 사용자가 매 turn 실행할 필요가 없는 agent-side task다. 필요할 때 agent가 다음 순서로 확인한다:
+Periodic maintenance is an agent-side task, not a per-turn user command. When needed, the agent checks:
 
 1. \`llm-wiki lint --workspace <project>\`
 2. \`llm-wiki maintenance --workspace <project>\`
-3. pending item을 기존 durable page에 병합한 뒤 \`done\` 또는 \`skipped\`로 표시한다.
+3. Merge pending items into existing durable pages, then mark them \`done\` or \`skipped\`.
 4. \`llm-wiki consolidate --workspace <project> --dry-run\`
-5. 필요할 때 \`llm-wiki consolidate --workspace <project>\`
+5. Run \`llm-wiki consolidate --workspace <project>\` when the dry run is acceptable.
 
-자동 수정은 확실히 kit가 관리하는 영역에만 적용한다. 사용자 편집 가능성이 있는 문서는 덮어쓰지 말고 다음 작업 context에 정리 필요성을 올린다.
+Apply automatic fixes only to clearly managed kit areas. Do not overwrite user-editable documents; surface cleanup needs in the next work context.
 `,
     'security.md': `# Security Procedure
 
-- 로컬 프로젝트 wiki에 유용한 작업 맥락은 보존한다.
-- 입력이 민감해 보인다는 이유만으로 read/tool call을 막지 않는다.
-- token, password, bearer credential, private key, \`.env\` 원문 같은 인증값은 hook payload, summary, context pack, wiki page에 저장하기 전에 redaction한다.
-- 민감정보가 wiki에 들어갔을 가능성이 있으면 agent가 \`llm-wiki lint --workspace <project>\`를 사용해 점검한다.
-- full raw transcript capture는 기본 비활성이다. 프로젝트가 명시적으로 opt-in하고 redaction 경로가 있을 때만 허용한다.
+- Preserve useful local project work context.
+- Do not block reads or tool calls only because input looks sensitive.
+- Redact authentication values such as tokens, passwords, bearer credentials, private keys, and raw \`.env\` contents before writing hook payloads, summaries, context packs, or wiki pages.
+- If sensitive material may have entered the wiki, use \`llm-wiki lint --workspace <project>\`.
+- Full raw transcript capture is disabled by default. Allow it only when a project explicitly opts in and has a redaction path.
 `,
   };
   return procedures[name] || '';

package/src/update-notice.js

@@ -113,12 +113,22 @@ export async function updateNoticeContext(projectRoot, eventName, options = {})
 
   const workspace = resolve(projectRoot || process.cwd());
   const updateCommand = commandForProject('update', workspace);
+  if (options.language === 'ko') {
+    return [
+      'LLM Wiki runtime update status:',
+      `- current hook runtime: ${notice.installedVersion}; npm registry: ${notice.latestVersion}`,
+      '- 현재 요청 처리가 우선이며, 현재 runtime 기능은 계속 동작한다.',
+      `- 업데이트/정비를 수행할 때 사용할 명령: \`${updateCommand}\``,
+      '- npm 전역 설치 권한 오류가 나면 환경에 맞게 `npm install -g llm-wiki-kit@latest` 또는 `sudo npm install -g llm-wiki-kit@latest` 후 같은 update 명령을 다시 실행한다.',
+      '- 이 status만으로 설치나 업데이트를 실행하지 않는다.',
+    ].join('\n');
+  }
   return [
     'LLM Wiki runtime update status:',
     `- current hook runtime: ${notice.installedVersion}; npm registry: ${notice.latestVersion}`,
-    '- 현재 요청 처리가 우선이며, 현재 runtime 기능은 계속 동작한다.',
-    `- 업데이트/정비를 수행할 때 사용할 명령: \`${updateCommand}\``,
-    '- npm 전역 설치 권한 오류가 나면 환경에 맞게 `npm install -g llm-wiki-kit@latest` 또는 `sudo npm install -g llm-wiki-kit@latest` 후 같은 update 명령을 다시 실행한다.',
-    '- 이 status만으로 설치나 업데이트를 실행하지 않는다.',
+    '- The current request comes first, and the current runtime continues to work.',
+    `- Use this command only when performing update or maintenance work: \`${updateCommand}\``,
+    '- If global npm install hits a permission error, run `npm install -g llm-wiki-kit@latest` or `sudo npm install -g llm-wiki-kit@latest` as appropriate, then rerun the same update command.',
+    '- Do not install or update only because this status is present.',
   ].join('\n');
 }

package/src/update.js

@@ -3,10 +3,10 @@ import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
 import { install } from './install.js';
-import { isWindows } from './platform.js';
+import { commandMatchesRuntime, commandPaths, isWindows, sameResolvedPath } from './platform.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { knownProjectRoots, recordProject } from './projects.js';
-import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
+import { binPath, detectInstallSource, packageName, packageRoot, runtimeVersion } from './version.js';
 
 function commandLine(command, args) {
   return [command, ...args].join(' ');
@@ -115,6 +115,10 @@ function binCommand() {
   return process.env.LLM_WIKI_KIT_BIN || binPath;
 }
 
+function packageSpec(target) {
+  return `${packageName()}@${target}`;
+}
+
 function assertCommandOk(result, label) {
   if (result.status === 0 && !result.error) return;
   const detail = result.stderr.trim() ||
@@ -125,6 +129,45 @@ function assertCommandOk(result, label) {
   throw new Error(`${label} failed: ${detail}`);
 }
 
+function postUpdateCommand(workspace, options = {}) {
+  const command = ['llm-wiki', 'post-update'];
+  if (shouldUpdateAllProjects(options)) command.push('--all');
+  command.push('--workspace', workspace);
+  return command.join(' ');
+}
+
+function formatRemediation(workspace, target, options = {}) {
+  const install = isWindows(options)
+    ? `npm install -g ${packageSpec(target)}`
+    : `sudo npm install -g ${packageSpec(target)}`;
+  return [
+    'Run the npm install command that owns the active runtime, then reapply hooks/templates:',
+    `  ${install}`,
+    `  ${postUpdateCommand(workspace, options)}`,
+    'Then verify:',
+    `  llm-wiki status --workspace ${workspace}`,
+  ].join('\n');
+}
+
+function createUpdateVerificationError(message, diagnostics = {}, workspace, target, options = {}) {
+  const lines = [
+    'llm-wiki-kit update did not update the active runtime.',
+    message,
+  ];
+  if (diagnostics.registryTarget) lines.push(`- registry target: ${diagnostics.registryTarget}`);
+  if (diagnostics.runtimeBefore) lines.push(`- runtime before: ${diagnostics.runtimeBefore}`);
+  if (diagnostics.runtimeAfter) lines.push(`- runtime after: ${diagnostics.runtimeAfter}`);
+  if (diagnostics.activePackageRoot) lines.push(`- active runtime root: ${diagnostics.activePackageRoot}`);
+  if (diagnostics.npmRoot) lines.push(`- npm global root: ${diagnostics.npmRoot}`);
+  if (diagnostics.npmPackageRoot) lines.push(`- npm target package root: ${diagnostics.npmPackageRoot}`);
+  if (diagnostics.commandPath) lines.push(`- command on PATH: ${diagnostics.commandPath}`);
+  if (diagnostics.commandMatchesRuntime !== undefined) {
+    lines.push(`- command matches runtime: ${diagnostics.commandMatchesRuntime ? 'yes' : 'no'}`);
+  }
+  lines.push(formatRemediation(workspace, target, options));
+  return Object.assign(new Error(lines.join('\n')), { diagnostics });
+}
+
 async function hasProjectWiki(projectRoot) {
   return exists(join(projectRoot, 'llm-wiki', 'wiki'));
 }
@@ -190,6 +233,74 @@ export function compareVersions(a, b) {
   return left.prerelease > right.prerelease ? 1 : -1;
 }
 
+async function npmGlobalInfo(options = {}) {
+  const rootResult = await runCommand(npmCommand(), ['root', '-g'], {
+    ...options,
+    label: 'npm root -g',
+    timeout: options.timeout || 30000,
+  });
+  assertCommandOk(rootResult, 'npm root -g');
+  const prefixResult = await runCommand(npmCommand(), ['prefix', '-g'], {
+    ...options,
+    label: 'npm prefix -g',
+    timeout: options.timeout || 30000,
+  });
+  assertCommandOk(prefixResult, 'npm prefix -g');
+  const root = rootResult.stdout.trim().split(/\r?\n/).at(-1) || '';
+  const prefix = prefixResult.stdout.trim().split(/\r?\n/).at(-1) || '';
+  return {
+    root,
+    prefix,
+    packageRoot: root ? join(root, packageName()) : '',
+  };
+}
+
+async function commandInfo(options = {}) {
+  const paths = await commandPaths('llm-wiki', options);
+  const commandPath = paths[0] || null;
+  const matchesRuntime = await commandMatchesRuntime(commandPath, binPath, {
+    ...options,
+    installSource: detectInstallSource(),
+  });
+  return {
+    path: commandPath,
+    paths,
+    matchesRuntime: Boolean(matchesRuntime),
+  };
+}
+
+function runtimeSatisfiesTarget(runtime, targetVersion) {
+  return compareVersions(runtime, targetVersion) >= 0;
+}
+
+function rootMatchesActiveRuntime(npmPackageRoot) {
+  return sameResolvedPath(npmPackageRoot, packageRoot) ||
+    resolve(npmPackageRoot || '') === resolve(packageRoot);
+}
+
+async function preflightRuntimeUpdate(check, workspace, target, options = {}) {
+  const npmGlobal = await npmGlobalInfo(options);
+  const command = await commandInfo(options);
+  if (check.updateAvailable && detectInstallSource() === 'npm' && !rootMatchesActiveRuntime(npmGlobal.packageRoot)) {
+    throw createUpdateVerificationError(
+      'The active llm-wiki runtime is not under the npm global root that this update command would modify.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        activePackageRoot: packageRoot,
+        npmRoot: npmGlobal.root,
+        npmPackageRoot: npmGlobal.packageRoot,
+        commandPath: command.path,
+        commandMatchesRuntime: command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
+  return { npmGlobal, command };
+}
+
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
@@ -297,9 +408,10 @@ export async function update(options = {}) {
   }
 
   const target = options.to || 'latest';
+  const beforeDiagnostics = await preflightRuntimeUpdate(check, workspace, target, options);
   const shouldRunNpmInstall = check.updateAvailable;
   const installResult = shouldRunNpmInstall
-    ? await runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+    ? await runCommand(npmCommand(), ['install', '-g', packageSpec(target)], {
       ...options,
       label: 'npm install -g',
       timeout: options.timeout || 120000,
@@ -310,6 +422,25 @@ export async function update(options = {}) {
       stderr: '',
     };
   assertCommandOk(installResult, 'npm install -g');
+  const runtimeAfterInstall = runtimeVersion();
+  if (shouldRunNpmInstall && !runtimeSatisfiesTarget(runtimeAfterInstall, check.latestVersion)) {
+    throw createUpdateVerificationError(
+      'npm install -g exited successfully, but the active runtime version did not change to the registry target.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        runtimeAfter: runtimeAfterInstall,
+        activePackageRoot: packageRoot,
+        npmRoot: beforeDiagnostics.npmGlobal.root,
+        npmPackageRoot: beforeDiagnostics.npmGlobal.packageRoot,
+        commandPath: beforeDiagnostics.command.path,
+        commandMatchesRuntime: beforeDiagnostics.command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
 
   const postArgs = [binCommand(), 'post-update', '--workspace', workspace, '--json'];
   if (shouldUpdateAllProjects(options)) postArgs.push('--all');
@@ -328,13 +459,47 @@ export async function update(options = {}) {
   });
   assertCommandOk(postResult, 'post-update');
   const parsedPostUpdate = parseJsonOutput(postResult.stdout);
+  const postRuntimeVersion = parsedPostUpdate?.runtimeVersion || null;
+  if (shouldRunNpmInstall && postRuntimeVersion && !runtimeSatisfiesTarget(postRuntimeVersion, check.latestVersion)) {
+    throw createUpdateVerificationError(
+      'post-update ran, but it did not run from the registry target runtime.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        runtimeAfter: postRuntimeVersion,
+        activePackageRoot: packageRoot,
+        npmRoot: beforeDiagnostics.npmGlobal.root,
+        npmPackageRoot: beforeDiagnostics.npmGlobal.packageRoot,
+        commandPath: beforeDiagnostics.command.path,
+        commandMatchesRuntime: beforeDiagnostics.command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
+  const afterCommand = await commandInfo(options);
+  const warnings = [];
+  if (!afterCommand.matchesRuntime) {
+    warnings.push(`llm-wiki command on PATH does not resolve to the active runtime: ${afterCommand.path || 'not found'}`);
+  }
 
   return {
     mode: 'update',
     workspace,
     before: check.installedVersion,
     target,
+    latest: check.latestVersion,
+    runtimeBefore: check.installedVersion,
+    runtimeAfter: runtimeAfterInstall,
+    postUpdateRuntime: postRuntimeVersion,
+    updateApplied: shouldRunNpmInstall,
+    runtimeVerified: runtimeSatisfiesTarget(runtimeAfterInstall, check.latestVersion),
     scope: shouldUpdateAllProjects(options) ? 'all' : 'current',
+    activePackageRoot: packageRoot,
+    npmGlobal: beforeDiagnostics.npmGlobal,
+    command: afterCommand,
+    warnings,
     npmInstall: {
       skipped: !shouldRunNpmInstall,
       stdout: installResult.stdout.trim(),