@kybird/llm-wiki 0.2.1 → 0.3.0

package/lib/wiki-search.js

@@ -2,7 +2,6 @@
 // 원본: TTSTextViewer/.agents/skills/wiki-search/scripts/search.js
 // 변경점:
 //   - __dirname '../../../../' 4단 종속 제거 → findDocRoot(), findQmd() 사용.
-//   - findstr(Windows 전용) → process.platform 분기 (win32=findstr, else=grep).
 //   - 2026-08-29 (개선계획 0-1): "QMD 성공 시 grep 건너뛰기" 분기 제거. QMD가 유사도로
 //     뭐라도 물어오면 정확 문자열 매칭이 묻히는 구조라 색인이 싱싱할수록 재현율이
 //     떨어졌다(plan.md 5.1(1)). 시맨틱은 대체재가 아니라 보완재 — 둘 다 항상 돌린다.
@@ -14,7 +13,10 @@
 //   - 2026-08-29 (개선계획 1-6): 수집(collect)과 렌더(render)를 분리. --json이면
 //     {schemaVersion: 1, kind: 'search-results', ...} 봉투로 출력 — 스킬 프롬프트가
 //     사람용 출력 문자열에 깨지지 않게 하는 계약.
-const { execSync } = require('child_process');
+//   - 2026-09-09 (개선계획 5-1-1): qmd 호출을 execFileSync 인자 배열로 — 검색어의
+//     메타문자가 셸로 새는 것을 원천 차단.
+//   - 2026-09-09 (개선계획 5-1-6): findstr/grep 외부 호출을 제거하고 프로세스 안
+//     라인 스캐너로. findstr은 ACP 의존이라 CP949 머신에서 한국어 검색어가 0건.
 const path = require('path');
 const fs = require('fs');
 const { findDocRoot, loadConfig } = require('./find-doc-root');
@@ -52,7 +54,7 @@ function search(query, options = {}) {
 }
 
 function collectGrepResults(query, wikiPath, rawPath) {
-  // 따옴표는 findstr/grep 인용 규칙을 깨므로 키워드에서 제거.
+  // 따옴표는 문서 본문에 잘 안 나오는 캐럭터라 키워드에서 제외(회수율).
   const keywords = query.split(/\s+/)
     .map(k => k.replace(/"/g, ''))
     .filter(k => k.length > 1);
@@ -61,34 +63,30 @@ function collectGrepResults(query, wikiPath, rawPath) {
 
   const found = new Map(); // absPath → { keywords: Set, snippets: Map<lineText, true> }
   const searchDirs = [wikiPath, rawPath];
-  const isWindows = process.platform === 'win32';
 
+  // 외부 grep/findstr을 쓰지 않는다 — findstr은 코드페이지(ACP) 의존이라 한국어
+  // Windows(CP949)에서 UTF-8 문서의 한국어 검색어가 비트 불일치로 조용히 0건이었다
+  // (2026-09-09 리뷰 5-1-6). 프로세스 안 라인 스캐너는 인코딩·플랫폼 무관하고
+  // 메타문자가 셸로 새는 경로도 원천히 없다. 코퍼스는 doc/ 규모라 속도 문제 없다.
   for (const dir of searchDirs) {
     if (!fs.existsSync(dir)) continue;
-    for (const kw of keywords) {
+    for (const filePath of listMarkdownFiles(dir)) {
+      let lines;
       try {
-        let grepCmd;
-        if (isWindows) {
-          // /C: 통짜 문자열 매칭(정규식 아님) — 에러 메시지의 . : ( 등이 그대로 걸린다.
-          // /M(files-only)을 쓰지 않는다 — 매칭 줄 자체가 스니펫이 된다.
-          grepCmd = `findstr /S /I /C:"${kw}" "${path.join(dir, '*.md')}"`;
-        } else {
-          // -F 고정 문자열(정규식 메타문자 무력화), -n 줄번호, -i 대소문자무시
-          grepCmd = `grep -rniF --include="*.md" -e "${kw}" "${dir}"`;
+        lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+      } catch { continue; }
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        const lower = line.toLowerCase();
+        for (const kw of keywords) {
+          if (lower.includes(kw.toLowerCase())) {
+            if (!found.has(filePath)) found.set(filePath, { keywords: new Set(), snippets: new Map() });
+            const entry = found.get(filePath);
+            entry.keywords.add(kw);
+            const snippet = line.trim();
+            if (!entry.snippets.has(snippet)) entry.snippets.set(snippet, true);
+          }
         }
-        const output = execSync(grepCmd, { encoding: 'utf8' });
-        for (const line of output.split(/\r?\n/)) {
-          if (!line.trim()) continue;
-          const { file, snippet } = splitGrepLine(line);
-          if (!file) continue;
-          const abs = path.resolve(file);
-          if (!found.has(abs)) found.set(abs, { keywords: new Set(), snippets: new Map() });
-          const entry = found.get(abs);
-          entry.keywords.add(kw);
-          if (snippet && !entry.snippets.has(snippet)) entry.snippets.set(snippet, true);
-        }
-      } catch (e) {
-        // findstr/grep returns exit code 1 if no matches
       }
     }
   }
@@ -111,6 +109,19 @@ function collectGrepResults(query, wikiPath, rawPath) {
   return { keywords, files };
 }
 
+// .md 재귀 수집 — grep -r / findstr /S 대응.
+function listMarkdownFiles(dir) {
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const abs = path.join(dir, name);
+    let stat;
+    try { stat = fs.statSync(abs); } catch { continue; }
+    if (stat.isDirectory()) out.push(...listMarkdownFiles(abs));
+    else if (name.toLowerCase().endsWith('.md')) out.push(abs);
+  }
+  return out;
+}
+
 function collectQmdResults(query, config) {
   const qmdPath = findQmd();
   if (!qmdPath) return { available: false, collections: [] };
@@ -120,7 +131,10 @@ function collectQmdResults(query, config) {
   const results = [];
   for (const coll of collections) {
     try {
-      const output = execSync(`node "${qmdPath}" search "${query}" -c ${coll}`, { encoding: 'utf8', timeout: 30000 });
+      // 검색어를 셸 문자열에 끼워 넣지 않는다 — 인자 배열은 메타문자를 데이터로만
+      // 전달한다(따옴표·$()·백틱 포함 질의가 에러 메시지 붙여넣기의 일상이다).
+      const output = execFileSync(process.execPath, [qmdPath, 'search', query, '-c', coll],
+        { encoding: 'utf8', timeout: 30000 });
       if (!isQmdEmpty(output)) results.push({ collection: coll, output: output.trim() });
     } catch (error) {
       // collection missing or QMD error for this collection — try next
@@ -171,16 +185,4 @@ function isQmdEmpty(output) {
   return /^no\s+results\s+found\.\s*$/i.test(output.trim());
 }
 
-// findstr/grep 출력 행에서 경로와 매칭 줄을 분리한다.
-//   findstr:  <경로>.md:<내용>
-//   grep -n:  <경로>.md:<줄번호>:<내용>
-// 경계는 첫 `.md:`로 판정 — 윈도우 절대경로의 드라이브 콜론(`D:`)과 충돌을 피한다.
-function splitGrepLine(line) {
-  const idx = line.indexOf('.md:');
-  if (idx === -1) return { file: null, snippet: null };
-  const file = line.slice(0, idx + 3);
-  const snippet = line.slice(idx + 4).replace(/^\d+:/, ''); // POSIX grep 줄번호 제거
-  return { file, snippet: snippet.trim() };
-}
-
 module.exports = { search };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybird/llm-wiki",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "LLM-friendly knowledge graph + kanban for AI coding agents. Raw daily logs → compiled wiki → merged semantic+grep search, and a card-per-file kanban the work-loop skill consumes unattended. Drop-in for any repo.",
   "license": "MIT",
   "author": "kybird",
@@ -36,5 +36,8 @@
     "agentic-memory",
     "claude-code",
     "work-loop"
-  ]
+  ],
+  "scripts": {
+    "test": "node --test test/roundtrip.test.js test/kanban-write.test.js test/kanban-pick-guards.test.js test/kanban-wait.test.js test/find-doc-root-worktree.test.js test/auto-update.test.js"
+  }
 }

package/skills/work-loop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: work-loop
 description: Unattended kanban loop — pick a card, resolve it with objective evidence, park judgment calls and move on. Board is the only task list; converge, don't diverge.
-skill-version: 4
+skill-version: 5
 ---
 # When to use
 
@@ -27,7 +27,7 @@ pick → work → 판정 ─ done / handoff / abandon / supersede
 집을 카드 없음 → review(대기) 큐 점검 → 전부 대기면 질문을 모아 정지 (반스래시)
 ```
 
-# Rules (all six are load-bearing)
+# Rules (all seven are load-bearing)
 
 0. **Condition-gated cards.** Some cards must not start yet:
    - `not_before: YYYY-MM-DD` in frontmatter (future date) — `pick` skips them
@@ -70,6 +70,14 @@ pick → work → 판정 ─ done / handoff / abandon / supersede
    On a long card, `llm-wiki card edit <제목> --renew-claim` before the timeout, or
    another loop instance will reclaim the card under you.
 
+7. **Worktrees share one board.** The board is a project resource, not a branch resource:
+   from a linked worktree, every `pick`/`done`/`card` writes the **primary worktree's**
+   `doc/kanban/`. If this loop runs in a linked worktree, its card changes appear as
+   uncommitted changes in the primary worktree — leave them there (the primary's next
+   commit picks them up); do not chase them into this worktree's commits, and do not
+   commit in the primary from here. `LLM_WIKI_WORKTREE_LOCAL=1` restores per-worktree
+   boards.
+
 # Splitting (supersede) — divergence guard
 
 Supersede only when each child is **strictly smaller** than the parent in context needed.

package/templates/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+<!-- Seeded by `llm-wiki init`. This file is YOURS — edit freely; init never overwrites it. -->
+
+This repo uses **llm-wiki**: `doc/` is the knowledge base, `doc/kanban/` is the work board.
+Files are the source of truth. Kanban card files are written ONLY via the CLI — people read them.
+
+## Skill usage — when to use what
+
+| Moment | Skill / command |
+|---|---|
+| Before starting any task | `llm-wiki search "<keywords>"` — paste the verbatim error string when debugging |
+| After fixing a bug / making a decision / discovering something | `wiki-log` skill → a Case in `doc/raw/YYYY-MM-DD.md` with verbatim error + `hash:` grounding |
+| When raw logs have accumulated | `wiki-compile` skill → promote to `doc/wiki/` pages, then `llm-wiki compile index` |
+| Sanity check of the knowledge base | `wiki-lint` skill or `llm-wiki lint` |
+| Planning work (person present) | `kanban-plan` skill → cards via `llm-wiki card new "<title>"` |
+| Unattended execution | `work-loop` skill → `llm-wiki pick --claim <name>`, park judgment calls with `handoff` |
+
+## Rules
+
+- Quote error messages **character-for-character** in logs and wiki pages — `llm-wiki lint`
+  back-checks every quote and `hash:` against `doc/raw/`.
+- Follow `status: deprecated` → `superseded_by` when reading wiki pages.
+- The board is a **project** resource, not a branch resource: from any git linked worktree,
+  `llm-wiki` reads and writes the **primary worktree's** `doc/kanban/`. `pick`/`done` run in
+  a secondary worktree leave uncommitted changes in the primary worktree — intended, commit
+  them there. Opt out with `LLM_WIKI_WORKTREE_LOCAL=1`.
+- Expand this file with this repo's own conventions. Keep it short — it loads every session.