llm-wiki-kit 0.1.12 → 0.1.14

package/README.md

@@ -58,10 +58,13 @@ llm-wiki/
 │   ├── context/
 │   └── queries/
 ├── outputs/
+│   ├── questions/
+│   ├── reports/
+│   └── maintenance/
 └── procedures/
 ```
 
-`raw/` is the immutable or redacted evidence layer. `wiki/` is the LLM-maintained knowledge layer. `wiki/memory.md` is the short hot index injected into hook context before deeper search results. `outputs/` stores live Q&A and requested reports. `.kit-state.json` records which runtime version last applied managed templates to the project. Text written by the kit is normalized to NFC so Korean filenames and content stay composed.
+`raw/` is the immutable or redacted evidence layer. `wiki/` is the LLM-maintained knowledge layer. `wiki/memory.md` is the short hot index injected into hook context before deeper search results. `outputs/` stores live Q&A, requested reports, and pending wiki maintenance candidates. `.kit-state.json` records which runtime version last applied managed templates to the project. Text written by the kit is normalized to NFC so Korean filenames and content stay composed.
 
 ## Normal Use
 
@@ -76,6 +79,8 @@ The installed hooks:
 - 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
+- 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
 - automatically refresh managed rules/templates for older projects when the current runtime starts a session
 
@@ -87,10 +92,10 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 - Install/update: `llm-wiki install`, `llm-wiki update`, `llm-wiki post-update`, `llm-wiki projects`
 - Diagnostics: `llm-wiki doctor`, `llm-wiki status`, `llm-wiki version`
-- Agent maintenance helpers: `llm-wiki context`, `llm-wiki lint`, `llm-wiki consolidate`
+- Agent maintenance helpers: `llm-wiki context`, `llm-wiki lint`, `llm-wiki consolidate`, `llm-wiki maintenance`
 - Cleanup: `llm-wiki uninstall`
 
-`llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, whether the `llm-wiki` command on `PATH` resolves to the current runtime, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, and how many managed-looking rules need agent cleanup.
+`llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, whether the `llm-wiki` command on `PATH` resolves to the current runtime, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, how many managed-looking rules need agent cleanup, and how many wiki maintenance items are pending.
 
 `llm-wiki update --check [--to <version-or-tag>]` is the online update check. It compares the installed package version with the npm registry target without changing files, and reports an available update only when the target version is newer than the installed version.
 
@@ -104,6 +109,8 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `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 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`.
 
 After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. Clearly generated older `llm-wiki/AGENTS.md` and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.

package/docs/concepts.md

@@ -19,8 +19,9 @@ The important behavior is a loop:
 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. 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.
-7. Future sessions start from the improved wiki instead of relying on long chat history.
+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.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -38,5 +39,6 @@ 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.
 - `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,9 +40,9 @@ 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, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
+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.
 
-`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` 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. `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.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 

package/docs/integrations/codex.md

@@ -29,12 +29,12 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, and any maintenance note for outdated or customized managed rules.
-- `UserPromptSubmit` searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
+- `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.
 - `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.
+- `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.
 - `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.

package/docs/operations.md

@@ -86,6 +86,7 @@ llm-wiki post-update --all --workspace /path/to/search-root
 llm-wiki context "search phrase" --workspace /path/to/project
 llm-wiki lint --workspace /path/to/project
 llm-wiki consolidate --workspace /path/to/project
+llm-wiki maintenance --workspace /path/to/project
 ```
 
 `status` is offline and answers whether the local installation is internally consistent:
@@ -96,6 +97,7 @@ llm-wiki consolidate --workspace /path/to/project
 - project template state from `llm-wiki/.kit-state.json`
 - current managed file hashes
 - auto-updateable managed rules and managed-looking rules that need agent cleanup
+- pending wiki maintenance count
 
 `update --check [--to <version-or-tag>]` is online and asks npm for the target version. It reports `update available` only when that registry target is newer than the installed version, so it does not suggest downgrades.
 
@@ -120,6 +122,8 @@ 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 the context automatically, and the active agent is expected to update durable wiki pages when reusable project knowledge appears.
 
+`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.
+
 `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
@@ -148,6 +152,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no
 - duplicate aliases or titles
 - stale pages and orphan candidates
 - outdated managed rules/templates from earlier `llm-wiki-kit` versions
+- stale or oversized maintenance queues
 
 Broken links, invalid source IDs, and secret-like content are errors and return exit code 1. Metadata and discoverability gaps are warnings.
 
@@ -163,6 +168,8 @@ 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`.
+
 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.
 
 ## Updating User-Local Or nvm Installs

package/docs/troubleshooting.md

@@ -177,6 +177,19 @@ Check:
 - project `CLAUDE.md` exists or imports `@AGENTS.md`
 - the session was restarted after install
 
+## 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.
+
+Check the queue and health warnings:
+
+```bash
+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`.
+
 ## Authentication Values Were Redacted
 
 The hook does not block tool calls only because inputs look sensitive. Durable summaries redact authentication values before writing, while ordinary work context such as dates, phone numbers, emails, and business identifiers is preserved by default.

package/package.json

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

package/src/cli.js

@@ -2,6 +2,7 @@ import { resolve } from 'path';
 import { formatConsolidateResult, runConsolidate } from './consolidate.js';
 import { handleHook } from './hook.js';
 import { install, status, uninstall } from './install.js';
+import { formatMaintenanceResult, maintenanceSummary } from './maintenance.js';
 import { bootstrapProject } from './project.js';
 import { inspectProjectState } from './project-state.js';
 import { commandForProject, knownProjectRoots, recordProject } from './projects.js';
@@ -98,6 +99,7 @@ Usage:
   llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand]
   llm-wiki lint --workspace <project>
   llm-wiki consolidate --workspace <project> [--dry-run]
+  llm-wiki maintenance --workspace <project> [--json]
 `);
     return;
   }
@@ -195,6 +197,12 @@ Usage:
     return;
   }
 
+  if (command === 'maintenance') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    printJsonOrText(await maintenanceSummary(projectRoot, options), options, formatMaintenanceResult);
+    return;
+  }
+
   if (command === 'hook') {
     const provider = rest[0] || 'codex';
     const eventName = rest[1];
@@ -250,6 +258,7 @@ function formatStatus(value) {
     `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
     `- project auto-updateable rules: ${autoUpdateCount}`,
     `- project rules needing agent cleanup: ${attentionCount}`,
+    `- project maintenance pending: ${value.maintenance?.pendingCount ?? 0}`,
   ].join('\n');
 }
 

package/src/constants.js

@@ -52,6 +52,7 @@ export const LLM_WIKI_DIRS = [
   'wiki/queries',
   'outputs/questions',
   'outputs/reports',
+  'outputs/maintenance',
   'procedures',
 ];
 

package/src/hook.js

@@ -1,5 +1,6 @@
 import { findProjectRoot } from './fs-utils.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';
 import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
@@ -61,6 +62,9 @@ export async function handleHook(provider, explicitEvent) {
   await recordProject(projectRoot, 'hook').catch(() => {});
   await autoUpdateManagedProject(projectRoot, eventName).catch(() => {});
   await appendSessionEnvelope(projectRoot, eventName, payload).catch(() => {});
+  if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded' || eventName === 'UserPromptSubmit') {
+    await recoverStaleTurnStates(projectRoot).catch(() => []);
+  }
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
     const context = await buildContextBrief(projectRoot, 'SessionStart');
@@ -96,9 +100,16 @@ export async function handleHook(provider, explicitEvent) {
     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)') {
-      await appendLiveQa(projectRoot, entry);
+      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') {

package/src/install.js

@@ -4,6 +4,7 @@ import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
 import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
 import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
+import { maintenanceSummary } from './maintenance.js';
 import { inspectProjectState } from './project-state.js';
 import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
@@ -121,7 +122,10 @@ async function reconcileLocalBin(localBinPath) {
 
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
-  const already = JSON.stringify(hooks[eventName]).includes(command);
+  const already = hooks[eventName].some((entry) => (
+    Array.isArray(entry?.hooks) &&
+    entry.hooks.some((hook) => hook?.type === 'command' && hook?.command === command)
+  ));
   if (already) return false;
   const entry = {
     hooks: [
@@ -280,5 +284,6 @@ export async function status(options = {}) {
     codexHooksPath,
     claudeSettingsPath,
     project: await inspectProjectState(workspace),
+    maintenance: await maintenanceSummary(workspace),
   };
 }

package/src/maintenance.js

@@ -0,0 +1,253 @@
+import { readdir, unlink } from 'fs/promises';
+import { join, relative } from 'path';
+import { appendText, exists, kitDataDir, readJson, readText, sha256, writeTextIfMissing } from './fs-utils.js';
+import { redactText, summarizeForStorage } from './redaction.js';
+import { buildEntryFromTurnState, hasRecoverableTurnState } from './state.js';
+
+export const MAINTENANCE_QUEUE_REL = 'llm-wiki/outputs/maintenance/queue.md';
+const DEFAULT_STALE_TURN_MS = 10 * 60 * 1000;
+const DEFAULT_STALE_PENDING_DAYS = 7;
+const DEFAULT_PENDING_LIMIT = 20;
+
+function queuePath(projectRoot) {
+  return join(projectRoot, MAINTENANCE_QUEUE_REL);
+}
+
+function queueHeader() {
+  return [
+    '# LLM Wiki Maintenance Queue',
+    '',
+    '정식 wiki 문서에 합칠 후보를 보관한다. Hook은 후보만 만들고, agent가 기존 durable wiki 문서를 찾아 병합한다.',
+    '',
+    'Status values: pending, done, skipped.',
+    '',
+  ].join('\n');
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function staleTurnMs() {
+  const value = Number(process.env.LLM_WIKI_KIT_STALE_TURN_MS || DEFAULT_STALE_TURN_MS);
+  return Number.isFinite(value) && value >= 0 ? value : DEFAULT_STALE_TURN_MS;
+}
+
+function normalizeSource(projectRoot, source) {
+  if (!source) return '';
+  const text = String(source);
+  if (text.startsWith('state:')) return text;
+  if (text.startsWith(projectRoot)) return relative(projectRoot, text).split('\\').join('/');
+  return text.split('\\').join('/');
+}
+
+function relativeSource(projectRoot, path) {
+  return normalizeSource(projectRoot, path);
+}
+
+function sanitizeField(value, maxLength = 500) {
+  return summarizeForStorage(String(value || '').replace(/\s+/g, ' ').trim(), maxLength);
+}
+
+function inferSuggestedTarget(entry, source) {
+  const text = `${entry?.question || ''}\n${entry?.result || ''}\n${entry?.work || ''}\n${source || ''}`.toLowerCase();
+  if (String(source || '').includes('wiki/decisions/') || /decision|decided|결정|선택|채택|확정/.test(text)) return 'wiki/decisions/';
+  if (/error|bug|fix|debug|failure|failed|실패|오류|버그|수정|원인/.test(text)) return 'wiki/debugging/';
+  if (/architecture|flow|runtime|hook|update|install|context|memory|구조|아키텍처|흐름|설치|업데이트/.test(text)) return 'wiki/architecture/';
+  if (/procedure|process|policy|rule|운영|절차|규칙|정책/.test(text)) return 'procedures/';
+  return 'wiki/concepts/';
+}
+
+function itemId(projectRoot, source, entry) {
+  const question = entry?.question || entry?.topic || '';
+  const firstInput = entry?.firstTimestamp || entry?.createdAt || source || '';
+  return sha256(`${projectRoot}\n${source}\n${question}\n${firstInput}`).slice(0, 24);
+}
+
+function itemBlock(item) {
+  return [
+    `## ${item.status || 'pending'} - ${item.topic || 'maintenance item'}`,
+    '',
+    `- id: ${item.id}`,
+    `- created_at: ${item.created_at}`,
+    `- last_seen_at: ${item.last_seen_at}`,
+    `- source: ${item.source}`,
+    `- suggested_target: ${item.suggested_target}`,
+    `- reason: ${item.reason}`,
+    `- result_missing: ${item.result_missing ? 'true' : 'false'}`,
+    '',
+  ].join('\n');
+}
+
+export async function readMaintenanceQueue(projectRoot) {
+  const path = queuePath(projectRoot);
+  const text = await readText(path, '');
+  const items = [];
+  let current = null;
+
+  const pushCurrent = () => {
+    if (current) items.push(current);
+    current = null;
+  };
+
+  for (const line of text.split(/\r?\n/)) {
+    const header = line.match(/^##\s+(pending|done|skipped)\s+-\s*(.*)$/);
+    if (header) {
+      pushCurrent();
+      current = {
+        status: header[1],
+        topic: header[2].trim(),
+        fields: {},
+      };
+      continue;
+    }
+    if (!current) continue;
+    const field = line.match(/^-\s+([a-z_]+):\s*(.*)$/);
+    if (field) {
+      current.fields[field[1]] = field[2].trim();
+    }
+  }
+  pushCurrent();
+
+  return {
+    path,
+    exists: await exists(path),
+    items: items.map((item) => ({
+      ...item.fields,
+      status: item.status,
+      topic: item.topic,
+      result_missing: String(item.fields.result_missing || '').toLowerCase() === 'true',
+    })),
+  };
+}
+
+export function summarizeMaintenanceQueue(queue, options = {}) {
+  const staleDays = options.staleDays ?? DEFAULT_STALE_PENDING_DAYS;
+  const pendingLimit = options.pendingLimit ?? DEFAULT_PENDING_LIMIT;
+  const pending = queue.items.filter((item) => item.status === 'pending');
+  const staleCutoff = Date.now() - staleDays * 24 * 60 * 60 * 1000;
+  const stalePending = pending.filter((item) => {
+    const time = Date.parse(item.created_at || item.last_seen_at || '');
+    return Number.isFinite(time) && time < staleCutoff;
+  });
+  return {
+    path: queue.path,
+    exists: queue.exists,
+    items: queue.items,
+    pending,
+    done: queue.items.filter((item) => item.status === 'done'),
+    skipped: queue.items.filter((item) => item.status === 'skipped'),
+    pendingCount: pending.length,
+    doneCount: queue.items.filter((item) => item.status === 'done').length,
+    skippedCount: queue.items.filter((item) => item.status === 'skipped').length,
+    stalePending,
+    stalePendingDays: staleDays,
+    pendingLimit,
+    tooManyPending: pending.length > pendingLimit,
+  };
+}
+
+export async function maintenanceSummary(projectRoot, options = {}) {
+  return summarizeMaintenanceQueue(await readMaintenanceQueue(projectRoot), options);
+}
+
+export async function appendMaintenanceItem(projectRoot, item) {
+  const path = queuePath(projectRoot);
+  await writeTextIfMissing(path, queueHeader());
+  const queue = await readMaintenanceQueue(projectRoot);
+  if (queue.items.some((existing) => existing.id === item.id)) {
+    return { created: false, path, id: item.id };
+  }
+  await appendText(path, redactText(`\n${itemBlock(item)}`, 6000));
+  return { created: true, path, id: item.id };
+}
+
+export async function recordMaintenanceForEntry(projectRoot, entry, options = {}) {
+  const source = relativeSource(projectRoot, options.source || options.queryPath || options.decisionPath || options.liveQaPath || '');
+  if (!source && !options.resultMissing) return { created: false, reason: 'missing-source' };
+  if (!entry?.question || entry.question === '(not captured)') return { created: false, reason: 'missing-question' };
+  const created = nowIso();
+  const item = {
+    id: itemId(projectRoot, source, entry),
+    status: 'pending',
+    topic: sanitizeField(entry.topic || entry.question, 120),
+    created_at: created,
+    last_seen_at: created,
+    source,
+    suggested_target: options.suggestedTarget || inferSuggestedTarget(entry, source),
+    reason: sanitizeField(options.reason || `Captured ${options.eventName || 'turn'} needs durable wiki review.`, 300),
+    result_missing: Boolean(options.resultMissing),
+  };
+  return appendMaintenanceItem(projectRoot, item);
+}
+
+function stateDir() {
+  return join(kitDataDir(), 'state');
+}
+
+async function stateFiles() {
+  try {
+    return (await readdir(stateDir()))
+      .filter((file) => file.endsWith('.json'))
+      .map((file) => join(stateDir(), file));
+  } catch {
+    return [];
+  }
+}
+
+export async function recoverStaleTurnStates(projectRoot, options = {}) {
+  const output = [];
+  const cutoffMs = options.staleMs ?? staleTurnMs();
+  const now = Date.now();
+  for (const path of await stateFiles()) {
+    const state = await readJson(path, null);
+    if (!state || state.projectRoot !== projectRoot) continue;
+    const updated = Date.parse(state.updated_at || '');
+    if (Number.isFinite(updated) && now - updated < cutoffMs) continue;
+    if (!hasRecoverableTurnState(state)) continue;
+    const entry = buildEntryFromTurnState(state, '');
+    const result = await recordMaintenanceForEntry(projectRoot, entry, {
+      source: `state:${state.session || path.split('/').pop()?.replace(/\.json$/, '')}`,
+      eventName: 'recovered stale turn state',
+      reason: 'Recovered from stale turn state because Stop/SessionEnd did not complete.',
+      resultMissing: true,
+    });
+    await unlink(path).catch(() => {});
+    output.push({ ...result, statePath: path, session: state.session });
+  }
+  return output;
+}
+
+export function formatMaintenanceContext(summary, options = {}) {
+  const limit = options.limit || 5;
+  const pending = summary.pending.slice(0, limit);
+  if (pending.length === 0) 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.',
+  ];
+  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' : ''}`);
+  }
+  if (summary.pending.length > pending.length) {
+    lines.push(`- ${summary.pending.length - pending.length} more pending item(s) hidden from context.`);
+  }
+  return lines.join('\n');
+}
+
+export function formatMaintenanceResult(summary) {
+  const lines = [
+    'llm-wiki maintenance',
+    `- queue: ${summary.path}`,
+    `- pending: ${summary.pendingCount}`,
+    `- done: ${summary.doneCount}`,
+    `- skipped: ${summary.skippedCount}`,
+  ];
+  if (summary.pending.length > 0) {
+    lines.push('', 'Pending:');
+    for (const item of summary.pending.slice(0, 10)) {
+      lines.push(`- ${item.topic || item.id}: ${item.source} -> ${item.suggested_target}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/project.js

@@ -9,6 +9,7 @@ import {
   writeTextIfMissing,
 } from './fs-utils.js';
 import { LLM_WIKI_DIRS } from './constants.js';
+import { formatMaintenanceContext, maintenanceSummary } from './maintenance.js';
 import { normalizeForStorage, redactText, summarizeForStorage } from './redaction.js';
 import { gitignore, indexPage, llmWikiAgents, logPage, memoryPage, procedure, rootAgentsPolicy } from './templates.js';
 import { formatProjectMaintenanceContext, inspectProjectState, recordManagedTemplates } from './project-state.js';
@@ -121,6 +122,7 @@ export async function appendLiveQa(projectRoot, entry) {
     '',
   ].join('\n');
   await appendText(path, redactText(block, 12000));
+  return path;
 }
 
 export async function writeQueryPage(projectRoot, entry) {
@@ -166,5 +168,8 @@ export async function buildContextBrief(projectRoot, eventName, query = '') {
   const maintenance = await inspectProjectState(projectRoot)
     .then(formatProjectMaintenanceContext)
     .catch(() => '');
-  return [formatContextPack(pack), maintenance].filter(Boolean).join('\n\n');
+  const wikiMaintenance = await maintenanceSummary(projectRoot)
+    .then(formatMaintenanceContext)
+    .catch(() => '');
+  return [formatContextPack(pack), maintenance, wikiMaintenance].filter(Boolean).join('\n\n');
 }

package/src/state.js

@@ -63,16 +63,38 @@ export async function rememberTool(projectRoot, payload, summary) {
 
 export async function buildEntryFromState(projectRoot, payload, assistantText) {
   const state = await readTurnState(projectRoot, payload);
-  const question = state.questions.at(-1)?.text || summarizeForStorage(payload.prompt || payload.user_prompt || '', 2000);
-  const result = summarizeForStorage(assistantText || payload.last_assistant_message || payload.response || '', 4000);
+  return buildEntryFromTurnState(state, assistantText || payload.last_assistant_message || payload.response || '');
+}
+
+export function hasRecoverableTurnState(state) {
+  return Boolean(
+    state &&
+    (
+      (Array.isArray(state.questions) && state.questions.length > 0) ||
+      (Array.isArray(state.tools) && state.tools.length > 0) ||
+      (Array.isArray(state.files) && state.files.length > 0) ||
+      (Array.isArray(state.verification) && state.verification.length > 0)
+    )
+  );
+}
+
+export function buildEntryFromTurnState(state, assistantText = '') {
+  const questions = Array.isArray(state.questions) ? state.questions : [];
+  const tools = Array.isArray(state.tools) ? state.tools : [];
+  const files = Array.isArray(state.files) ? state.files : [];
+  const verification = Array.isArray(state.verification) ? state.verification : [];
+  const question = questions.at(-1)?.text || '';
+  const result = summarizeForStorage(assistantText || '', 4000);
   const topic = question ? question.replace(/\s+/g, ' ').slice(0, 80) : 'session turn';
   return {
     topic,
     question: question || '(not captured)',
-    work: state.tools.map((item) => `- ${item.text}`).join('\n') || '(not captured)',
+    work: tools.map((item) => `- ${item.text}`).join('\n') || '(not captured)',
     result: result || '(not captured)',
-    changedFiles: [...new Set(state.files)].map((item) => `- ${item}`).join('\n') || '(not captured)',
-    verification: state.verification.map((item) => `- ${item}`).join('\n') || '(not captured)',
+    changedFiles: [...new Set(files)].map((item) => `- ${item}`).join('\n') || '(not captured)',
+    verification: verification.map((item) => `- ${item}`).join('\n') || '(not captured)',
     followUp: '',
+    firstTimestamp: questions[0]?.at || tools[0]?.at || state.updated_at,
+    session: state.session,
   };
 }

package/src/templates.js

@@ -15,6 +15,7 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
 - hook이 주입한 context를 우선 사용한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
 - hook은 redacted live Q&A와 query/decision 후보를 기록한다. 재사용 가능한 지식은 agent가 기존 정식 wiki 문서에 합친다.
+- hook은 종료/시작 경계에서 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 agent가 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
 - 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
 - 일회성 작업 기록은 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
@@ -47,6 +48,7 @@ Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wik
 - 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
 - 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
 - 반복해서 쓸 지식은 \`outputs/questions/\`에만 두지 말고 \`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에 저장하지 않는다.
@@ -75,6 +77,7 @@ superseded_by: []
 - query: hook이 주입한 context를 우선 사용한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
 - lint: agent가 필요할 때 wiki 건강 상태를 점검하는 보조 도구다. 사용자가 매번 직접 실행해야 하는 명령이 아니다.
 - consolidate: agent가 \`memory.md\`/\`index.md\` generated block을 안전하게 갱신할 때 쓰는 보조 도구다. 손글씨 영역과 정식 문서 본문은 덮어쓰지 않는다.
+- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
 `;
 }
 

package/src/wiki-lint.js

@@ -1,6 +1,7 @@
 import { readdir } from 'fs/promises';
 import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'path';
 import { exists, readText } from './fs-utils.js';
+import { maintenanceSummary } from './maintenance.js';
 import { inspectProjectState } from './project-state.js';
 import { hasSecretLikeText } from './redaction.js';
 import {
@@ -244,6 +245,14 @@ export async function runLint(projectRoot, options = {}) {
     }
   }
 
+  const maintenance = await maintenanceSummary(projectRoot).catch(() => null);
+  if (maintenance?.tooManyPending) {
+    issues.push(issue('warning', 'maintenance-too-many-pending', 'outputs/maintenance/queue.md', `maintenance queue has ${maintenance.pendingCount} pending items; review and merge durable items into wiki pages`));
+  }
+  if ((maintenance?.stalePending || []).length > 0) {
+    issues.push(issue('warning', 'maintenance-stale-pending', 'outputs/maintenance/queue.md', `${maintenance.stalePending.length} pending maintenance item(s) are older than ${maintenance.stalePendingDays} days`));
+  }
+
   return lintResult(projectRoot, pages, issues);
 }