@kybird/llm-wiki 0.2.2 → 0.4.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.2",
+  "version": "0.4.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-board-flags.test.js test/kanban-milestone.test.js test/kanban-monitor.test.js test/kanban-wait.test.js test/find-doc-root-worktree.test.js test/auto-update.test.js"
+  }
 }

package/skills/kanban-plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: kanban-plan
-description: Planning loop — turn a plan into board cards the work-loop can consume. Cards are written only via the CLI; decompose with divergence guards, gate what isn't ready.
-skill-version: 2
+description: Planning loop — turn a plan into board cards the work-loop can consume. Cards are written only via the CLI; decompose with divergence guards, gate what isn't ready, group multi-card plans under a milestone.
+skill-version: 4
 ---
 # When to use
 
@@ -15,7 +15,7 @@ skill-version: 2
 - 기획(this skill) = **분해**: a plan becomes cards.
 - 개발(`work-loop`) = **해소**: pick → done.
 - QA = **수렴 강제**: fake dones get reverted; `board report` shows the ratio.
-- The person watches progress through `llm-wiki board` / `board report` / `board --html`.
+- The person watches progress through `llm-wiki board` / `board report` / `llm-wiki monitor`.
   Plan so that this one screen is enough — 리뷰가 카드 수에 비례하면 무인의 의미가 없다.
 
 # Before creating cards
@@ -26,6 +26,23 @@ skill-version: 2
    it (`supersede`); never spawn a near-duplicate. Titles are identifiers (plan.md 3.5):
    no numbers, no versions in titles.
 
+# Milestones — 계획 단위 소속 (plan.md 3.8)
+
+A plan that decomposes into **2+ cards gets one milestone card** — the board's purpose
+axis. One-card work needs no milestone (과잉이다).
+
+1. `card new "<계획 제목>" --kind milestone --goal "<대의 한 문장>"` — the Goal is why
+   the plan exists; the morning human reads it above the terminal stream.
+2. Every member card carries `--milestone "<계획 제목>"` (or `card edit --milestone`
+   later — active cards only; terminal membership is history).
+3. The milestone is never picked and never closed by hand: `done`/`supersede`/`abandon`
+   of the last member auto-completes it (review-parked milestones only report).
+   Milestone progress is **derived**, never stored — don't manage its state.
+
+Rules: milestones stay **flat** (a milestone never belongs to another milestone — CLI
+rejects it). Gates don't propagate — each member carries its own `--not-before`.
+Abandoning a milestone requires its members to be terminal first (CLI enforces, lists them).
+
 # Decomposition rules (divergence guards, plan.md 2.3)
 
 - One card = one context = one commit. If you cannot say what the commit would be, it is
@@ -33,7 +50,7 @@ skill-version: 2
 - Children must be **strictly smaller** than the parent. When children replace a parent,
   `supersede` it — the parent dissolves, it is not marked done.
 - Depth ≤ 3 (plan → subtask → task). Deeper than that means you are writing the work,
-  not planning it.
+  not planning it. (The milestone sits **above** this ladder as grouping, not depth.)
 - Do not board what is not ready to start:
   - Time condition → `card new "<t>" --not-before 2026-09-05`. `pick` skips it until then.
   - Observational condition → create it, then `handoff <t> --question "조건: …"`. It waits

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: 7
 ---
 # When to use
 
@@ -18,6 +18,14 @@ skill-version: 4
 3. Never build or assume a process supervisor. The loop lives in the session; the board
    lives in files.
 
+# Loop start — bring the monitor up (사람의 실시간 관측)
+
+루프를 시작할 때 `llm-wiki monitor`를 백그라운드로 띄운다 — 밤중에 사람이 들어와도
+클레임·진행·마일스톤이 살아 있는 보드를 본다. **멱등이다**: 이미 떠 있으면 exit 0으로
+같은 URL을 되뇌므로 그대로 쓰고, 백그라운드 실행이 안 되는 환경이면 건너뛴다 —
+모니터는 관측이지 의존성이 아니다. 정지 규칙에서도 모니터는 끄지 않는다(아침의
+사람이 본다) — 읽기 전용이라 남겨두는 비용이 없다.
+
 # Loop graph
 
 ```
@@ -27,7 +35,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
@@ -61,6 +69,10 @@ pick → work → 판정 ─ done / handoff / abandon / supersede
    (보고서와 함께 세션 타임랩스 영상을 남긴다 — 아침의 사람이 40초로 밤을 본다),
    leave the questions in one place, and STOP. Do not invent new cards to look
    productive. 밤새 카드가 300장이 되는 것이 이 시스템이 죽는 방식이다 (plan.md 2.3).
+   Milestone cards are **never pickable** (they are grouping, not work — plan.md 3.8):
+   if the No-pickable detail lists them, that is normal — don't `done` or `abandon` a
+   milestone by hand; it auto-completes when its last member terminates (a `done` that
+   prints `◉ milestone 완료` closed it for you).
 
 5. **Search before work.** `llm-wiki search "<keywords>"` before starting a card. If the
    wall you are about to hit already has an abandoned card or an anti-pattern page, skip
@@ -70,6 +82,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

@@ -13,12 +13,17 @@ Files are the source of truth. Kanban card files are written ONLY via the CLI
 | 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>"` |
+| Planning work (person present) | `kanban-plan` skill → cards via `llm-wiki card new "<title>"`. A plan that splits into 2+ cards gets **one milestone card** (`--kind milestone`, members carry `--milestone`); milestones are never picked and auto-complete when all members terminate |
 | Unattended execution | `work-loop` skill → `llm-wiki pick --claim <name>`, park judgment calls with `handoff` |
+| Watching the board (human) | `llm-wiki monitor` — read-only live view (claims, elapsed, gates, terminal pile, milestones) at `http://127.0.0.1:4747` |
 
 ## 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.