llm-wiki-kit 0.1.6 → 0.1.8

package/src/doctor.js

@@ -9,27 +9,27 @@ function nodeMajor() {
   return Number.parseInt(process.versions.node.split('.')[0], 10);
 }
 
-export async function runDoctor() {
+export async function runDoctor(options = {}) {
   const checks = [];
-  const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
-  const stat = await status();
+  const add = (id, name, ok, detail = '') => checks.push({ id, name, ok, detail });
+  const stat = await status(options);
 
-  add('node >= 20', nodeMajor() >= 20, process.version);
-  add('runtime version detected', Boolean(stat.runtimeVersion), stat.runtimeVersion || 'unknown');
-  add('llm-wiki bin exists', await exists(stat.binPath), stat.binPath);
-  add('runtime installed from npm', stat.installSource === 'npm', `${stat.installSource}; npm install -g does not update source checkouts`);
-  add('llm-wiki command resolves to current runtime', stat.commandMatchesRuntime, stat.commandPath ? `command=${stat.commandPath}; runtime=${stat.binPath}` : 'command not found on PATH');
-  add('Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
-  add('Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
-  add('project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
-  add('codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
-  add('claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
-  add('state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
-  add('docs present', await docsPresent(), 'README.md and docs/');
-  add('sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
+  add('node', 'node >= 20', nodeMajor() >= 20, process.version);
+  add('runtime-version', 'runtime version detected', Boolean(stat.runtimeVersion), stat.runtimeVersion || 'unknown');
+  add('runtime-bin', 'llm-wiki bin exists', await exists(stat.binPath), stat.binPath);
+  add('install-source', 'runtime installed from npm', stat.installSource === 'npm', `${stat.installSource}; npm install -g does not update source checkouts`);
+  add('command-path', 'llm-wiki command resolves to current runtime', stat.commandMatchesRuntime, stat.commandPath ? `command=${stat.commandPath}; runtime=${stat.binPath}` : 'command not found on PATH');
+  add('codex-hook', 'Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
+  add('claude-hook', 'Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
+  add('project-templates', 'project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
+  add('codex-command', 'codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
+  add('claude-command', 'claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
+  add('state-writable', 'state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
+  add('docs', 'docs present', await docsPresent(), 'README.md and docs/');
+  add('sample-hook', 'sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
 
   const allOk = checks.every((check) => check.ok);
-  return { ok: allOk, checks };
+  return { ok: allOk, checks, workspace: stat.workspace, status: stat };
 }
 
 async function docsPresent() {
@@ -84,8 +84,38 @@ export function formatDoctor(result) {
     lines.push(`- ${check.ok ? 'PASS' : 'WARN'} ${check.name}${check.detail ? ` (${check.detail})` : ''}`);
   }
   if (!result.ok) {
-    lines.push('');
-    lines.push('Run ./install.sh --workspace /apps --profile standard to install hooks, then restart Codex/Claude Code sessions.');
+    const remediation = doctorRemediation(result);
+    if (remediation.length > 0) {
+      lines.push('', 'Suggested fix:');
+      for (const item of remediation) lines.push(`- ${item}`);
+    }
   }
   return lines.join('\n');
 }
+
+function failed(result, id) {
+  return (result.checks || []).some((check) => check.id === id && !check.ok);
+}
+
+function doctorRemediation(result) {
+  const workspace = result.workspace || process.cwd();
+  const suggestions = [];
+  if (failed(result, 'install-source')) {
+    suggestions.push(`normal install: npm install -g llm-wiki-kit@latest && llm-wiki install --workspace ${workspace} --profile standard`);
+    suggestions.push(`source checkout development: ./install.sh --workspace ${workspace} --profile standard`);
+  }
+  if (failed(result, 'command-path')) {
+    const local = result.status?.localBin;
+    if (result.status?.installSource === 'npm' && local?.exists && local.managed) {
+      suggestions.push(`remove stale managed local shim if it still shadows npm: rm -f ${local.path} && hash -r`);
+    }
+    suggestions.push(`reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
+  }
+  if (failed(result, 'codex-hook') || failed(result, 'claude-hook')) {
+    suggestions.push(`install hooks: llm-wiki install --workspace ${workspace} --profile standard, then restart Codex/Claude Code sessions`);
+  }
+  if (failed(result, 'project-templates')) {
+    suggestions.push(`refresh managed project templates: llm-wiki post-update --workspace ${workspace}`);
+  }
+  return [...new Set(suggestions)];
+}

package/src/hook.js

@@ -3,7 +3,8 @@ import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelop
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
-import { buildEntryFromState, rememberQuestion, rememberTool } from './state.js';
+import { buildEntryFromState, clearTurnState, rememberQuestion, rememberTool } from './state.js';
+import { relative } from 'path';
 
 async function readStdinJson() {
   const chunks = [];
@@ -45,7 +46,9 @@ async function autoUpdateManagedProject(projectRoot, eventName) {
   const state = await inspectProjectState(projectRoot);
   if (state.runtimeUpToDateWithProject && state.managedFilesCurrent) return;
   const result = await applyProjectTemplateUpdate(projectRoot);
-  await appendWikiLog(projectRoot, `llm-wiki-kit auto-update applied runtime ${result.runtimeVersion}; changed templates: ${result.changed.length}; skipped templates: ${result.skipped.length}`);
+  if (result.changed.length > 0) {
+    await appendWikiLog(projectRoot, `llm-wiki-kit auto-update applied runtime ${result.runtimeVersion}; changed templates: ${result.changed.length}; skipped templates: ${result.skipped.length}`);
+  }
 }
 
 export async function handleHook(provider, explicitEvent) {
@@ -96,7 +99,10 @@ export async function handleHook(provider, explicitEvent) {
       await appendLiveQa(projectRoot, entry);
       const queryPath = await writeQueryPage(projectRoot, entry);
       const decisionPath = await writeDecisionPage(projectRoot, entry);
-      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${queryPath}` : ''}${decisionPath ? `; decision=${decisionPath}` : ''}`);
+      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(() => {});
     }
     return {};
   }

package/src/install.js

@@ -1,9 +1,9 @@
 import { realpathSync } from 'fs';
-import { chmod } from 'fs/promises';
+import { chmod, lstat, readlink, unlink } from 'fs/promises';
 import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
 import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
-import { backupFile, ensureDir, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
+import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { inspectProjectState } from './project-state.js';
 import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
@@ -34,6 +34,91 @@ function realpathOrOriginal(path) {
   }
 }
 
+function sameResolvedPath(left, right) {
+  const resolvedLeft = realpathOrOriginal(left);
+  const resolvedRight = realpathOrOriginal(right);
+  return Boolean(resolvedLeft && resolvedRight && resolvedLeft === resolvedRight);
+}
+
+function samePath(left, right) {
+  if (!left || !right) return false;
+  return resolve(left) === resolve(right);
+}
+
+function isKitPath(path) {
+  return String(path || '').replace(/\\/g, '/').includes('/llm-wiki-kit/');
+}
+
+async function inspectLocalBin(localBinPath) {
+  try {
+    const stat = await lstat(localBinPath);
+    const symlink = stat.isSymbolicLink();
+    const target = symlink ? await readlink(localBinPath).catch(() => null) : null;
+    const resolved = realpathOrOriginal(localBinPath);
+    return {
+      path: localBinPath,
+      exists: true,
+      symlink,
+      target,
+      resolved,
+      managed: symlink && (isKitPath(target) || isKitPath(resolved)),
+      matchesRuntime: sameResolvedPath(localBinPath, binPath),
+    };
+  } catch {
+    return {
+      path: localBinPath,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+}
+
+async function reconcileLocalBin(localBinPath) {
+  const commandPathsBefore = llmWikiCommandPaths();
+  const localBefore = await inspectLocalBin(localBinPath);
+  const alternateRuntimeCommand = commandPathsBefore.some((path) => (
+    !samePath(path, localBinPath) && sameResolvedPath(path, binPath)
+  ));
+  let action = 'kept';
+
+  if (alternateRuntimeCommand) {
+    if (localBefore.exists && localBefore.managed) {
+      await backupFile(localBinPath, 'local-bin-llm-wiki');
+      await unlink(localBinPath).catch(() => {});
+      action = 'removed-shadowing-shim';
+    } else if (localBefore.exists) {
+      action = 'left-unmanaged-local-bin';
+    } else {
+      action = 'skipped-npm-command-available';
+    }
+  } else if (localBefore.matchesRuntime) {
+    action = 'kept-current-shim';
+  } else {
+    if (localBefore.exists) {
+      await backupFile(localBinPath, 'local-bin-llm-wiki');
+      action = 'replaced-local-shim';
+    } else {
+      action = 'created-local-shim';
+    }
+    await safeSymlink(binPath, localBinPath);
+  }
+
+  const commandPathsAfter = llmWikiCommandPaths();
+  const localAfter = await inspectLocalBin(localBinPath);
+  return {
+    ...localAfter,
+    action,
+    alternateRuntimeCommand,
+    commandPathsBefore,
+    commandPathsAfter,
+    commandPath: commandPathsAfter[0] || null,
+  };
+}
+
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
   const already = JSON.stringify(hooks[eventName]).includes(command);
@@ -72,12 +157,8 @@ export async function install(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
   await chmod(binPath, 0o755).catch(() => {});
   const localBin = join(homeDir(), '.local', 'bin');
-  await ensureDir(localBin);
   const localBinPath = join(localBin, 'llm-wiki');
-  if (await exists(localBinPath)) {
-    await backupFile(localBinPath, 'local-bin-llm-wiki');
-  }
-  await safeSymlink(binPath, localBinPath);
+  const localBinResult = await reconcileLocalBin(localBinPath);
   if (!options.noProject) {
     await bootstrapProject(workspace, { profile: options.profile || 'standard', recordState: true });
     await recordProject(workspace, 'install');
@@ -133,7 +214,12 @@ export async function install(options = {}) {
     workspace,
     runtimeVersion: runtimeVersion(),
     binPath,
-    localBin: join(localBin, 'llm-wiki'),
+    localBin: localBinPath,
+    localBinAction: localBinResult.action,
+    localBinManaged: localBinResult.managed,
+    localBinMatchesRuntime: localBinResult.matchesRuntime,
+    commandPath: localBinResult.commandPath,
+    commandPaths: localBinResult.commandPathsAfter,
     changed,
   };
 }
@@ -176,7 +262,10 @@ export async function status(options = {}) {
   const commandPath = commandPaths[0] || null;
   const resolvedCommandPath = realpathOrOriginal(commandPath);
   const resolvedBinPath = realpathOrOriginal(binPath);
+  const localBinPath = join(homeDir(), '.local', 'bin', 'llm-wiki');
+  const localBin = await inspectLocalBin(localBinPath);
   return {
+    workspace,
     runtimeVersion: runtimeVersion(),
     packageRoot,
     installSource: detectInstallSource(),
@@ -184,6 +273,7 @@ export async function status(options = {}) {
     commandPath,
     commandPaths,
     commandMatchesRuntime: Boolean(resolvedCommandPath && resolvedBinPath && resolvedCommandPath === resolvedBinPath),
+    localBin,
     codexInstalled,
     claudeInstalled,
     hooksCurrent: codexInstalled && claudeInstalled,

package/src/project-state.js

@@ -27,6 +27,14 @@ function templateDescriptors() {
       path: join('llm-wiki', 'AGENTS.md'),
       content: llmWikiAgents(),
       mode: 'generated-file',
+      legacyContents: legacyLlmWikiAgentsContents(),
+      legacySignals: [
+        /^# LLM Wiki Agent Rules/m,
+        /Generated by llm-wiki-kit/m,
+        /## Purpose/m,
+        /## Core Rules/m,
+        /## Operations/m,
+      ],
     },
     {
       id: 'wiki-memory',
@@ -39,10 +47,179 @@ function templateDescriptors() {
       path: join('llm-wiki', 'procedures', name),
       content: procedure(name),
       mode: 'generated-file',
+      legacyContents: legacyProcedureContents(name),
+      legacySignals: legacyProcedureSignals(name),
     })),
   ];
 }
 
+function legacyLlmWikiAgentsContents() {
+  return [
+    `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit <version>.
+
+## Purpose
+Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
+These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+
+## Directories
+- \`raw/\`: immutable or redacted source material. Never edit original source captures.
+- \`wiki/\`: AI-maintained knowledge pages.
+- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
+- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+
+## Core Rules
+- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
+- Do not state unsupported claims as facts.
+- Mark inference explicitly.
+- Add \`source_ids\` or file references for important claims.
+- Update \`wiki/index.md\` and \`wiki/log.md\` whenever new durable knowledge is created.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
+- Preserve useful work context and redact authentication values before writing durable notes.
+
+## Page Format
+Use YAML frontmatter when creating wiki pages:
+
+\`\`\`yaml
+---
+title: ""
+type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
+source_ids: []
+status: "draft | reviewed | stale"
+last_updated: "YYYY-MM-DD"
+confidence: "high | medium | low"
+---
+\`\`\`
+
+## Operations
+- ingest: read new raw files, create or update wiki pages, then update \`wiki/index.md\` and \`wiki/log.md\`.
+- query: start from \`wiki/index.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
+- lint: find stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, contradictions, and missing links.`,
+    `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit <version>.
+
+## Purpose
+Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
+These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+
+## Directories
+- \`raw/\`: immutable or redacted source material. Never edit original source captures.
+- \`wiki/\`: AI-maintained knowledge pages. \`wiki/memory.md\` is the short hot index injected into hook context.
+- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
+- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+
+## Core Rules
+- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
+- Do not state unsupported claims as facts.
+- Mark inference explicitly.
+- Add \`source_ids\` or file references for important claims.
+- Update \`wiki/memory.md\`, \`wiki/index.md\`, and \`wiki/log.md\` whenever new durable knowledge changes the active project map.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
+- Preserve useful work context and redact authentication values before writing durable notes.
+
+## Page Format
+Use YAML frontmatter when creating wiki pages:
+
+\`\`\`yaml
+---
+title: ""
+type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
+source_ids: []
+status: "draft | reviewed | stale"
+last_updated: "YYYY-MM-DD"
+confidence: "high | medium | low"
+memory_type: "semantic | episodic | procedural"
+importance: 1
+last_verified: "YYYY-MM-DD | unknown"
+supersedes: []
+superseded_by: []
+---
+\`\`\`
+
+## Operations
+- ingest: read \`wiki/memory.md\` and \`wiki/index.md\`, ingest new raw files, create or update wiki pages, then update the active map and \`wiki/log.md\`.
+- query: start from \`llm-wiki context "<query>"\` or \`wiki/memory.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
+- lint: run \`llm-wiki lint --workspace <project>\` to find stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, contradictions, and missing links.
+- consolidate: run \`llm-wiki consolidate --workspace <project>\` after meaningful wiki growth to refresh generated memory/index blocks without overwriting hand-written notes. Default query/context/session-log pages are excluded unless explicitly durable.`,
+  ];
+}
+
+function legacyProcedureContents(name) {
+  const early = {
+    'ingest.md': `# Ingest Procedure
+
+1. Read \`wiki/index.md\` first.
+2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.
+3. Create or update \`wiki/sources/<slug>.md\` for each source.
+4. Update related concept, entity, decision, architecture, debugging, or context pages.
+5. Prefer updating existing pages over creating duplicates.
+6. Add source references and confidence.
+7. Update \`wiki/index.md\` and append to \`wiki/log.md\`.`,
+    'query.md': `# Query Procedure
+
+1. Start from \`wiki/index.md\`.
+2. Search \`wiki/\` for relevant pages.
+3. Read the smallest useful set of pages first.
+4. Use raw sources only when exact evidence matters.
+5. Separate verified facts from inference.
+6. Save reusable answers into \`wiki/queries/\` and link them from related pages.`,
+    'lint.md': `# Lint Procedure
+
+Check for stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.`,
+    'security.md': `# Security Procedure
+
+- Never store credentials, tokens, private keys, \`.env\` contents, customer identifiers, or private personal data.
+- Redact before writing hook payloads or summaries.
+- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.
+- If a file or prompt looks secret-bearing, do not persist it and ask for confirmation before reading further.`,
+  };
+  const layered = {
+    'ingest.md': `# Ingest Procedure
+
+1. Read \`wiki/memory.md\` and \`wiki/index.md\` first.
+2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.
+3. Create or update \`wiki/sources/<slug>.md\` for each source.
+4. Update related concept, entity, decision, architecture, debugging, or context pages.
+5. Prefer updating existing pages over creating duplicates.
+6. Add source references, confidence, memory type, importance, and verification status.
+7. Update \`wiki/memory.md\` or run \`llm-wiki consolidate\` when durable entry points change.
+8. Update \`wiki/index.md\` and append to \`wiki/log.md\`.`,
+    'query.md': `# Query Procedure
+
+1. Start from \`llm-wiki context "<query>"\` or read \`wiki/memory.md\` and \`wiki/index.md\`.
+2. Use \`--limit\` or \`--no-expand\` when you need a narrower context pack.
+3. Search \`wiki/\` for relevant pages.
+4. Read the smallest useful set of pages first.
+5. Use raw sources only when exact evidence matters.
+6. Separate verified facts from inference.
+7. Save reusable answers into \`wiki/queries/\` and link them from related pages.`,
+    'lint.md': `# Lint Procedure
+
+Run \`llm-wiki lint --workspace <project>\` to check for stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.`,
+    'security.md': `# Security Procedure
+
+- Preserve useful work context for the local project wiki.
+- Do not block reads or tool calls only because they look sensitive.
+- Redact authentication values such as tokens, passwords, bearer credentials, and private keys before writing hook payloads, summaries, or context packs.
+- Run \`llm-wiki lint --workspace <project>\` when sensitive material might have entered wiki pages; secret-like content is reported as an error.
+- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.`,
+  };
+  return [early[name], layered[name]].filter(Boolean);
+}
+
+function legacyProcedureSignals(name) {
+  const common = [/^# .+ Procedure/m];
+  const byName = {
+    'ingest.md': [/^# Ingest Procedure/m, /wiki\/memory\.md/, /raw\/inbox|raw\/sources/],
+    'query.md': [/^# Query Procedure/m, /llm-wiki context/, /Save reusable answers|reusable answers/],
+    'lint.md': [/^# Lint Procedure/m, /llm-wiki lint/, /stale pages|orphan pages/],
+    'security.md': [/^# Security Procedure/m, /Redact authentication values|token|private keys/, /raw transcript capture/],
+  };
+  return byName[name] || common;
+}
+
 function emptyState() {
   return {
     schemaVersion: PROJECT_STATE_SCHEMA_VERSION,
@@ -79,18 +256,24 @@ export async function writeProjectState(projectRoot, state) {
 }
 
 function replaceMarkedBlock(current, replacement) {
+  if (markerStatus(current) !== 'complete') return null;
   const start = current.indexOf(ROOT_POLICY_START);
   const end = current.indexOf(ROOT_POLICY_END);
-  if (start === -1 || end === -1 || end < start) return null;
   const afterEnd = end + ROOT_POLICY_END.length;
   return `${current.slice(0, start)}${replacement.trimStart().trimEnd()}${current.slice(afterEnd)}`;
 }
 
+function markerCount(current, marker) {
+  return current.split(marker).length - 1;
+}
+
 function markerStatus(current) {
   const start = current.indexOf(ROOT_POLICY_START);
   const end = current.indexOf(ROOT_POLICY_END);
-  if (start === -1 && end === -1) return 'missing';
-  if (start === -1 || end === -1 || end < start) return 'malformed';
+  const starts = markerCount(current, ROOT_POLICY_START);
+  const ends = markerCount(current, ROOT_POLICY_END);
+  if (starts === 0 && ends === 0) return 'missing';
+  if (starts !== 1 || ends !== 1 || end < start) return 'malformed';
   return 'complete';
 }
 
@@ -108,10 +291,39 @@ function isKnownGeneratedContent(text, descriptor) {
   return templateHash(text) === templateHash(descriptor.content);
 }
 
+function normalizeGeneratedText(text) {
+  return String(text || '')
+    .replace(/\r\n/g, '\n')
+    .replace(/Generated by llm-wiki-kit [^\n]+/g, 'Generated by llm-wiki-kit <version>.')
+    .trim();
+}
+
+function isLegacyGeneratedContent(text, descriptor) {
+  if (descriptor.mode !== 'generated-file') return false;
+  if (!Array.isArray(descriptor.legacyContents) || descriptor.legacyContents.length === 0) return false;
+  const normalized = normalizeGeneratedText(text);
+  return descriptor.legacyContents.some((content) => normalizeGeneratedText(content) === normalized);
+}
+
+function hasLegacyGeneratedSignal(text, descriptor) {
+  if (!Array.isArray(descriptor.legacySignals) || descriptor.legacySignals.length === 0) return false;
+  return descriptor.legacySignals.every((pattern) => pattern.test(text));
+}
+
+function hasKitManagedSignal(text, descriptor) {
+  if (descriptor.mode === 'marker') return markerStatus(text) !== 'missing';
+  if (descriptor.mode === 'generated-file') {
+    return isLegacyGeneratedContent(text, descriptor) || hasLegacyGeneratedSignal(text, descriptor) || /Generated by llm-wiki-kit/.test(text);
+  }
+  return false;
+}
+
 function canPatchDescriptor(state, descriptor, currentText, fileExists = true) {
   if (descriptor.mode === 'create-only') return !fileExists;
   if (descriptor.mode === 'marker') return replaceMarkedBlock(currentText, descriptor.content) !== null;
-  return isRecordedManaged(state, descriptor, currentText) || isKnownGeneratedContent(currentText, descriptor);
+  return isRecordedManaged(state, descriptor, currentText) ||
+    isKnownGeneratedContent(currentText, descriptor) ||
+    isLegacyGeneratedContent(currentText, descriptor);
 }
 
 function desiredTextForDescriptor(descriptor, currentText, fileExists = true) {
@@ -125,6 +337,10 @@ async function createOnlyParentExists(projectRoot, descriptor) {
   return exists(dirname(join(projectRoot, descriptor.path)));
 }
 
+async function descriptorParentExists(projectRoot, descriptor) {
+  return exists(dirname(join(projectRoot, descriptor.path)));
+}
+
 export async function inspectProjectState(projectRoot) {
   const state = await readProjectState(projectRoot);
   const runtime = runtimeVersion();
@@ -139,10 +355,16 @@ export async function inspectProjectState(projectRoot) {
     const currentHash = fileExists ? templateHash(currentText) : null;
     const recorded = state.managedTemplates[descriptor.id] || null;
     const markerState = descriptor.mode === 'marker' && fileExists ? markerStatus(currentText) : null;
-    const parentExists = await createOnlyParentExists(projectRoot, descriptor);
+    const parentExists = await descriptorParentExists(projectRoot, descriptor);
     const patchable = descriptor.mode === 'create-only' && !fileExists && !parentExists
       ? false
-      : (markerState === 'malformed' || canPatchDescriptor(state, descriptor, currentText, fileExists));
+      : (!fileExists && descriptor.mode === 'generated-file'
+        ? parentExists
+        : (markerState === 'malformed' ? false : canPatchDescriptor(state, descriptor, currentText, fileExists)));
+    const needsAttention = (fileExists || recorded) &&
+      !patchable &&
+      currentText !== (desiredText || '') &&
+      (fileExists ? hasKitManagedSignal(currentText, descriptor) : descriptor.mode !== 'create-only');
     const current = descriptor.mode === 'create-only'
       ? fileExists
       : fileExists && desiredText !== null && currentHash === templateHash(desiredText);
@@ -153,11 +375,12 @@ export async function inspectProjectState(projectRoot) {
       exists: fileExists,
       patchable,
       current,
+      needsAttention,
       currentHash,
       desiredHash,
       recordedHash: recorded?.hash || null,
       recordedVersion: recorded?.version || null,
-      reason: markerState === 'malformed' ? 'malformed-marker' : null,
+      reason: markerState === 'malformed' ? 'malformed-marker' : (!fileExists ? 'missing' : null),
     });
   }
 
@@ -167,11 +390,31 @@ export async function inspectProjectState(projectRoot) {
     schemaVersion: state.schemaVersion,
     lastRuntimeVersionApplied: state.lastRuntimeVersionApplied,
     runtimeUpToDateWithProject: state.lastRuntimeVersionApplied === runtime,
-    managedFilesCurrent: files.every((file) => file.current || !file.patchable),
+    managedFilesCurrent: files.every((file) => file.current || (!file.patchable && !file.needsAttention)),
     managedFiles: files,
   };
 }
 
+export function formatProjectMaintenanceContext(inspection) {
+  const files = inspection?.managedFiles || [];
+  const attention = files.filter((file) => file.needsAttention);
+  const outdated = files.filter((file) => !file.current && file.patchable);
+  if (attention.length === 0 && outdated.length === 0) return '';
+
+  const lines = [
+    'LLM Wiki maintenance note:',
+    '- 이전 버전의 llm-wiki-kit 규칙/문서가 남아 있을 수 있다.',
+    '- 확실히 kit가 관리하는 영역은 자동 갱신된다. 사용자 편집 가능성이 있는 문서는 덮어쓰지 말고 기존 내용을 보존한 채 현재 규칙에 맞게 자연스럽게 정리한다.',
+  ];
+  if (outdated.length > 0) {
+    lines.push(`- 자동 갱신 대상: ${outdated.map((file) => file.path).join(', ')}`);
+  }
+  if (attention.length > 0) {
+    lines.push(`- agent 확인 필요: ${attention.map((file) => file.path).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
 export async function recordManagedTemplates(projectRoot) {
   const state = await readProjectState(projectRoot);
   const runtime = runtimeVersion();
@@ -211,7 +454,7 @@ export async function applyProjectTemplateUpdate(projectRoot, options = {}) {
     const absolutePath = join(projectRoot, descriptor.path);
     if (!(await exists(absolutePath))) {
       if (descriptor.mode === 'create-only') {
-        if (!(await createOnlyParentExists(projectRoot, descriptor))) {
+        if (!(await descriptorParentExists(projectRoot, descriptor))) {
           skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing-wiki' });
           continue;
         }
@@ -227,6 +470,19 @@ export async function applyProjectTemplateUpdate(projectRoot, options = {}) {
         };
         continue;
       }
+      if (descriptor.mode === 'generated-file' && await descriptorParentExists(projectRoot, descriptor)) {
+        if (!options.dryRun) {
+          await ensureDir(dirname(absolutePath));
+          await writeText(absolutePath, descriptor.content, 'utf8');
+        }
+        changed.push({ id: descriptor.id, path: descriptor.path });
+        state.managedTemplates[descriptor.id] = {
+          path: descriptor.path,
+          version: runtime,
+          hash: templateHash(descriptor.content),
+        };
+        continue;
+      }
       skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing' });
       continue;
     }

package/src/project.js

@@ -11,7 +11,7 @@ import {
 import { LLM_WIKI_DIRS } from './constants.js';
 import { normalizeForStorage, redactText, summarizeForStorage } from './redaction.js';
 import { gitignore, indexPage, llmWikiAgents, logPage, memoryPage, procedure, rootAgentsPolicy } from './templates.js';
-import { recordManagedTemplates } from './project-state.js';
+import { formatProjectMaintenanceContext, inspectProjectState, recordManagedTemplates } from './project-state.js';
 import { buildContextPack, formatContextPack, searchWiki as searchWikiWithIndex } from './wiki-search.js';
 
 export async function bootstrapProject(projectRoot, options = {}) {
@@ -117,7 +117,7 @@ export async function appendLiveQa(projectRoot, entry) {
     entry.verification || '(not captured)',
     '',
     '### Follow-up',
-    entry.followUp || '(none captured)',
+    entry.followUp || '다음 작업에서 이 turn의 reusable fact가 있으면 기존 wiki 문서에 합치고, 일회성 기록은 이 Q&A에만 보존한다.',
     '',
   ].join('\n');
   await appendText(path, redactText(block, 12000));
@@ -163,5 +163,8 @@ export async function buildContextBrief(projectRoot, eventName, query = '') {
     includeLog: eventName === 'SessionStart',
     limit: 5,
   });
-  return formatContextPack(pack);
+  const maintenance = await inspectProjectState(projectRoot)
+    .then(formatProjectMaintenanceContext)
+    .catch(() => '');
+  return [formatContextPack(pack), maintenance].filter(Boolean).join('\n\n');
 }