@kybird/llm-wiki 0.2.2 → 0.4.0

package/README.md

@@ -47,17 +47,26 @@ That's it. The agent does the rest.
 | `llm-wiki compile list` | Show raw logs not yet compiled — header date **or** content hash (`compile-state.json`), so same-day appends are caught too |
 | `llm-wiki compile index` | Rebuild `doc/wiki/index.md` (with aliases and answers), regenerate `compile-state.json`, and sync the QMD index. **This is a "compile complete" declaration** — run it after the wiki-compile skill's phases, not instead of them |
 | `llm-wiki lint` | Broken links, **evidence back-matching** (hash refs & `### Error` quotes must exist verbatim in `doc/raw/`), uncompiled concepts, metadata, staleness |
-| `llm-wiki board` / `board report` | Derived kanban view / dashboard (done:abandoned ratio, trend, QA reverts, waiting queue) |
+| `llm-wiki board` / `board report` | Derived kanban view (text only, no flags) / dashboard (done:abandoned ratio, trend, QA reverts, waiting queue) |
 | `llm-wiki board video` | Replay `activity.jsonl` into a board timelapse MP4 (requires the `video/` Remotion project; CPU render, no GPU) |
-| `llm-wiki card new/show/edit` | Create and edit cards — the CLI is the only writer (sentinel-safe sections) |
-| `llm-wiki pick --claim <name>` | Atomically claim the next eligible card (lock, WIP limit, dependencies, claim expiry) |
+| `llm-wiki monitor [--port <n>]` | Live read-only board view at `http://127.0.0.1:<n>` (default 4747) — who claimed what and for how long (`zcode · 14분`), claim expiry, REVIEW questions, gates/dependency waits, the terminal pile (종결 적체 — newest done/superseded/abandoned with timestamps), and an activity stream. A **milestone panel** (purpose axis, plan.md 3.8) shows in-progress milestones expanded with their member cards and completed ones collapsed with progress — click a milestone to read its Goal (the plan's 대의) and full member list. Click any card (columns, terminal pile, activity rows) to read the full card file. Polls every 2s (re-renders only on change); the page renders agent-authored text via `textContent` only. Starting one while another monitor already listens is **idempotent** — exit 0, same URL (a port held by anything else fails with guidance). **The CLI stays the only writer** — every non-GET method gets a 405; the server keeps no state |
+| `llm-wiki card new/show/edit` | Create and edit cards — the CLI is the only writer (sentinel-safe sections). `--kind milestone` creates a milestone card (the plan's 대의 lives in its Goal; not pickable, auto-completes when all members terminate); `--milestone "<title>"` attaches a card to one — membership is frontmatter, milestone progress is derived, never stored (plan.md 3.8) |
+| `llm-wiki pick --claim <name> [--card <title>]` | Atomically claim the next eligible card (lock, WIP limit, dependencies, claim expiry). `--card` claims a specific card by title — every gate still applies: a blocked pick prints why and leaves all files untouched, an unknown title fails (exit 1) |
 | `llm-wiki handoff <title> --question "…"` | Park a card for human judgment and release the claim |
-| `llm-wiki done <title> --result "…"` | Complete a card — Result is required |
+| `llm-wiki done <title> --result "…"` | Complete a card — Result is required. Completing the last member auto-completes its milestone |
 | `llm-wiki supersede <title> --by a,b` | Replace a card by children; the parent dissolves into `superseded/` |
 | `llm-wiki abandon <title> --reason "…"` | Discard — reason required, and auto-logged to `doc/raw/` as anti-pattern material |
 | `llm-wiki reopen <title> --why "…"` | QA: revert a fake-done card back to doing |
+| `llm-wiki wait [--for handoff\|done\|any\|stall] [--since <ISO>] [--timeout <s>] [--stall-min <m>] [--json]` | Block until a board event, then exit — **exit codes are the contract: 0 = event (one line to stdout), 2 = timeout (nothing printed), 1 = error**; callers re-arm on 2 and act on 0. `--for` picks the event (`handoff` default; `stall` fires after `--stall-min` minutes of silence, default 20). `--since` (default: now) is checked *before* waiting starts, so events that piled up while the caller was busy are returned immediately. Read-only; timestamp-based (survives wholesale `activity.jsonl` rewrites), skips broken lines, waits for the file to exist, `fs.watch` + 5s poll fallback (junction-safe) |
 
-`search`, `lint`, `compile list|index`, `board`, `pick` accept `--json` (a `{schemaVersion: 1, kind: …}` envelope for scripts and skills).
+`search`, `lint`, `compile list|index`, `board report`, `pick` accept `--json` (a `{schemaVersion: 1, kind: …}` envelope for scripts and skills). `wait --json` is different by design: it prints the matched event itself as one JSON line (or a `{action: "stall", …}` line), because callers parse that line directly.
+
+Any subcommand accepts `--help`/`-h` anywhere in its args: it prints that command's usage and exits 0 without touching the board — exploring a command must never mutate cards. Every board and card command also rejects unknown flags (`모르는 플래그`), so a typo'd flag fails loudly instead of silently no-oping.
+
+```bash
+# overnight re-arm loop: wake on the next handoff parked after midnight; silent exit 2 after an hour
+llm-wiki wait --for handoff --since 2026-09-12T00:00:00Z --timeout 3600 --json
+```
 
 ## What `init` creates
 
@@ -82,15 +91,15 @@ your-repo/
 
 ## Updating
 
-The skills, hooks, and scripts copied into your repo are **marker-protected copies**. Updating is two commands:
+`npm update` is the only step. The skills, hooks, and scripts copied into your repo are **marker-protected copies**, and the first `llm-wiki` command you run after a version change re-syncs them automatically (it prints one summary line; `llm-wiki init --check` shows the full report, `llm-wiki init` applies manually as before):
 
 ```bash
-npm update -g llm-wiki    # refresh the global CLI
-llm-wiki init --check     # what would change? (ok / stale / user-modified / missing)
-llm-wiki init             # apply — stale copies update, your edits survive
+npm update -g @kybird/llm-wiki    # then run any llm-wiki command — copies auto-update
 ```
 
-The contract: a copy keeps its version marker (`skill-version:` in skills, `llm-wiki-template-version:` in hooks and scripts) only while it is unmodified. **To customize a copy, delete its marker line** — `init` then treats it as yours and never overwrites it. Repos that keep their own canonical hook can skip the copy entirely: set `"hooksPath": "templates/githooks"` in `llm-wiki.config.json`.
+The version stamp lives per-repo in `~/.llm-wiki/auto-update/` (override with `LLM_WIKI_STATE_DIR`), never inside your repo. Opt out with `"autoUpdate": false` in `llm-wiki.config.json`, or `LLM_WIKI_NO_AUTO_UPDATE=1` for a single run.
+
+The contract: a copy keeps its version marker (`skill-version:` in skills, `llm-wiki-template-version:` in hooks and scripts) only while it is unmodified. **To customize a copy, delete its marker line** — updates then treat it as yours and never overwrite it. Repos that keep their own canonical hook can skip the copy entirely: set `"hooksPath": "templates/githooks"` in `llm-wiki.config.json`. The seeded `AGENTS.md` is yours forever — written once at `init`, never updated.
 
 ## Configuration (optional)
 
@@ -113,6 +122,8 @@ Create `llm-wiki.config.json` in your repo root:
 
 You can also set `LLM_WIKI_ROOT=/path/to/doc-parent` to point at a `doc/` outside the repo.
 
+**Git worktrees:** the board is a project resource, not a branch resource — no matter how many linked worktrees you have, cards, claims and the activity log (`doc/kanban/`) live in one place, the primary worktree's `doc/`. `findDocRoot` resolves a linked worktree to the primary worktree's `doc/` (via `git rev-parse --git-common-dir`). Intended side effect: `pick`/`done` run from a secondary worktree modify files in the primary worktree — those changes stay uncommitted there and are committed there. Set `LLM_WIKI_WORKTREE_LOCAL=1` to restore the old cwd-based (per-worktree) behavior.
+
 ## How the knowledge flows
 
 ```
@@ -164,6 +175,8 @@ git config core.hooksPath templates/githooks
 
 `llm-wiki.config.json` here declares `"hooksPath": "templates/githooks"`, so `init` never creates a `githooks/` copy — the active hook *is* the canonical template. See [doc/improvement-plan.md](doc/improvement-plan.md) for the roadmap state and [doc/plan.md](doc/plan.md) for the design record.
 
+Regression tests (round-trip serialization, duplicate titles, non-card pick, concurrent writes) run on throwaway boards — never touch this repo's `doc/`: `npm test`.
+
 ## License
 
 MIT

package/TROUBLESHOOTING.md

@@ -4,6 +4,15 @@
 >
 > QMD is **optional**. Without it, `llm-wiki search` falls back to grep and the wiki index still rebuilds correctly.
 
+## 워크트리마다 보드가 다르게 보인다 (kanban, not QMD)
+
+Symptom: two `git worktree`s of the same repo show different boards — a card abandoned in the primary worktree is still live in a linked one, cards created in the primary are invisible in the link, and `doc/kanban/activity.jsonl` conflicts on every merge.
+
+That was a defect, fixed in the doc-root resolution: the board is a project resource, not a branch resource. `findDocRoot` (`lib/find-doc-root.js`) now resolves to the **primary worktree's** `doc/` when run inside a linked worktree, so every worktree sees (and writes) the same cards, claims and activity log. Search order: `LLM_WIKI_ROOT` → primary worktree `doc/` (if a git repo and `doc/wiki` exists there) → walk up from cwd → `cwd/doc`.
+
+- Intended side effect: `pick`/`done` run from a secondary worktree modify the primary worktree's files. Those changes stay uncommitted in the primary worktree and get committed there. This is by design, not a bug.
+- Opt-out — restore the old per-worktree (cwd-based) behavior: set `LLM_WIKI_WORKTREE_LOCAL=1`.
+
 ## Runtime CUDA OOM vs build-time compile failure
 
 These are two different failure modes:

package/bin/llm-wiki.js

@@ -7,6 +7,12 @@ const { compile } = require('../lib/wiki-compile');
 const { lint } = require('../lib/wiki-lint');
 const { init } = require('../lib/init');
 const kanbanCmd = require('../lib/kanban-cmd');
+const kanbanMonitor = require('../lib/kanban-monitor');
+const kanbanWait = require('../lib/kanban-wait');
+const skills = require('../lib/skills');
+const { findDocRoot } = require('../lib/find-doc-root');
+const { maybeAutoUpdate } = require('../lib/auto-update');
+const { version } = require('../package.json');
 
 function printUsage() {
   console.log(`llm-wiki — LLM-friendly knowledge graph + kanban for AI coding agents
@@ -18,35 +24,95 @@ Usage:
   llm-wiki lint                      Validate wiki integrity (links, metadata, evidence)
   llm-wiki init [--check]            Scaffold doc/ + skills/ + hooks (--check: report only)
 
+Skills (git channel — prompt edits without npm publish, plan.md 6.2):
+  llm-wiki skills add <url>          Register a skill repo (owner/repo → GitHub)
+  llm-wiki skills remove <url>       Unregister
+  llm-wiki skills list               Show registered sources
+  llm-wiki skills sync [--yes]       Clone, show diff, install after approval (6.5)
+                                     [--skill <name>]   sync one skill only
+
 Kanban (cards are files; CLI is the only writer):
-  llm-wiki board [--html] [--json]   Derived board view (columns, WIP, queue) / static HTML
+  llm-wiki board                     Derived board view (columns, WIP, queue) — text only, no flags
   llm-wiki board report              Dashboard (done:abandoned ratio, trend, reverts)
   llm-wiki board video               Timelapse of board activity → MP4 (needs video/ project)
-  llm-wiki card new "<title>"        Create card (--goal, --ac, --depends)
+  llm-wiki monitor [--port <n>]      Live read-only board view at http://127.0.0.1:<n>
+                                     (default 4747) — claims, elapsed, gates, activity;
+                                     the CLI stays the only writer (405 on writes)
+  llm-wiki card new "<title>"        Create card (--goal, --ac, --depends, --not-before;
+                                     --kind milestone = milestone card, --milestone "<t>"
+                                     attaches to one — plan-level grouping, plan.md 3.8)
   llm-wiki card show <title>         Print card file
-  llm-wiki card edit <title>         Sentinel-safe edits (--goal/--ac/--add-ac/--check-ac/--note/--plan)
-  llm-wiki pick --claim <name>       Atomically claim the next eligible card (locks, WIP, deps)
+  llm-wiki card edit <title>         Sentinel-safe edits; unknown/blank flags fail, output
+                                     says what changed (--goal/--plan/--ac/--add-ac/
+                                     --check-ac/--note/--renew-claim/--depends/
+                                     --add-depends/--remove-depends/--milestone)
+                                     --milestone (re)groups an active card under a
+                                     milestone card
+  llm-wiki pick --claim <name> [--card <title>]
+                                     Atomically claim the next eligible card (locks, WIP, deps);
+                                     --card names a specific card — gates are never bypassed;
+                                     milestone cards are never picked (plan.md 3.8)
   llm-wiki handoff <title> --question "…"   Park for human judgment, release claim
-  llm-wiki done <title> --result "…"        Complete (Result required)
+  llm-wiki done <title> --result "…"        Complete (Result required). Completing the
+                                     last member auto-completes its milestone (3.8)
   llm-wiki supersede <title> --by a,b       Replace by children (parent dissolves)
   llm-wiki abandon <title> --reason "…"     Discard (reason required, never deleted)
   llm-wiki reopen <title> --why "…"         QA: revert a fake-done card to doing
   llm-wiki resume <title> [--note "…"]      Return a review (parked) card to todo
+  llm-wiki wait [--for <필터>] [--since <ISO ts>] [--timeout <초>] [--stall-min <분>] [--json]
+                                     Block until a board event, then exit. 종료 코드가 계약:
+                                     0 = 이벤트(stdout 한 줄), 2 = 타임아웃(출력 없음 — 조용히
+                                     재무장), 1 = 오류. 필터: handoff(기본) | done | any |
+                                     stall(--stall-min 분 무활동 후 0, 기본 20). --since 생략
+                                     시 지금 — 이후의 기존 이벤트는 대기 전에 먼저 검사한다
 
 Optional:
   npm i @tobilu/qmd                  Enable semantic search (falls back to grep if absent)
+  npm update -g @kybird/llm-wiki     Copied skills/hooks/scripts auto-update on the next
+                                     command ("autoUpdate": false in llm-wiki.config.json,
+                                     or LLM_WIKI_NO_AUTO_UPDATE=1, to opt out)
   --json                             Machine-readable output: {schemaVersion: 1, kind: ...}
-                                     (search, lint, compile list|index)
+                                     (search, lint, compile list|index, board report, pick)
   LLM_WIKI_ROOT=/path                Override doc/ root location
   llm-wiki.config.json               { "projectName": "...", "collections": {...},
-                                       "hooksPath": "templates/githooks" }`);
+                                       "hooksPath": "templates/githooks",
+                                       "skills": { "sources": ["<git-url>"], "enabled": ["<name>"] } }`);
 }
 
 const [, , subcommand, ...rest] = process.argv;
-// --json/--html은 어느 위치에 와도 플래그로 뽑아낸다 (검색어 문자열에서 제외).
+// --json은 어느 위치에 와도 플래그로 뽑아낸다 (검색어 문자열에서 제외). board는
+// --json/--html을 받지 않는다 — 추출된 사실을 dispatch 너머 명령에 넘겨 명시적으로
+// 실패시킨다(전역 선추출이 validateFlags를 우회하게 두면 조용한 no-op 성공이 된다).
 const jsonRequested = rest.includes('--json');
-const htmlRequested = rest.includes('--html');
-const args = rest.filter(a => a !== '--json' && a !== '--html');
+const args = rest.filter(a => a !== '--json');
+
+// 가드 — 탐색용 호출이 보드를 건드리지 못하게(2026-09-11·12 사고). 부작용 있는
+// 서브커맨드를 확인하려고 `pick --help`를 쳤다가 실제로 카드를 집는 일을 원천
+// 차단한다: 알려진 서브커맨드의 args 어디에 --help/-h가 있어도 그 명령의 사용법만
+// 찍고 나간다. 종료 코드 0 — --help는 오류가 아니고, 카드 파일과 activity 로그는
+// 한 글자도 바뀌지 않는다. 사용법 문자열은 각 명령의 fail()이 쓰는 것과 같은 곳
+// (kanban-cmd의 USAGE)에서 온다. 전용 문자열이 없는 읽기 전용 명령(search 등)은
+// 전체 사용법으로 대신한다. return으로 자연 종료한다 — Windows 파이프 stdout은
+// 비동기라 process.exit은 마지막 줄을 지울 수 있다(kanban-wait 교훈).
+const KNOWN_SUBCOMMANDS = ['search', 'compile', 'lint', 'init', 'skills', 'board', 'monitor', 'card',
+  'pick', 'handoff', 'done', 'supersede', 'abandon', 'reopen', 'resume', 'wait'];
+if (KNOWN_SUBCOMMANDS.includes(subcommand) && (args.includes('--help') || args.includes('-h'))) {
+  const usageKey = subcommand === 'card' && ['new', 'show', 'edit'].includes(args[0]) ? `card ${args[0]}` : subcommand;
+  const usage = kanbanCmd.USAGE[usageKey];
+  if (usage) console.log(usage);
+  else printUsage();
+  return;
+}
+
+// npm 업데이트 자동 반영(README "Updating") — 리포를 실제로 쓰는 명령 앞에서만.
+// init은 자체 동기화 흐름이 있고, 도움말·버전·오타 명령은 리포를 건드릴 이유가 없다.
+// wait도 빠진다 — 백그라운드 관측 명령이라 동기화를 몰고 올 이유가 없고, 무엇보다
+// stdout이 "이벤트 한 줄 or 침묵" 계약이라 auto-update 배너가 그 계약을 깬다.
+// 실패는 maybeAutoUpdate 안에서 삼켜진다 — 갱신 실패가 명령을 막지 않는다.
+if (['search', 'compile', 'lint', 'skills', 'board', 'card', 'pick', 'handoff',
+  'done', 'supersede', 'abandon', 'reopen', 'resume'].includes(subcommand)) {
+  maybeAutoUpdate();
+}
 
 switch (subcommand) {
   case 'search':
@@ -61,10 +127,25 @@ switch (subcommand) {
   case 'init':
     init({ check: args.includes('--check') });
     break;
+  case 'skills':
+    // sync는 diff 제시 후 승인 프롬프트를 위해 async다.
+    skills.dispatch(args, findDocRoot()).catch(e => {
+      console.error(e.message);
+      process.exitCode = 1;
+    });
+    break;
   case 'board':
     if (args[0] === 'report') kanbanCmd.boardReport({ json: jsonRequested });
-    else if (args[0] === 'video') kanbanCmd.boardVideo({ rest: args });
-    else kanbanCmd.boardView({ rest: args, json: jsonRequested, html: htmlRequested });
+    else if (args[0] === 'video') kanbanCmd.boardVideo({ rest: args, json: jsonRequested });
+    else kanbanCmd.boardView({ rest: args, json: jsonRequested });
+    break;
+  case 'monitor':
+    // auto-update 트리거 목록에 없다 — stdout 첫 줄이 URL 계약이라 배너가 깨면
+    // 안 된다(wait 제외와 같은 이유). monitor는 async(멱등 재사용 검사)다.
+    kanbanMonitor.monitor({ rest: args, json: jsonRequested }).catch(e => {
+      console.error(`✗ ${e.message}`);
+      process.exit(1);
+    });
     break;
   case 'card':
     kanbanCmd.dispatchCard(args);
@@ -90,11 +171,18 @@ switch (subcommand) {
   case 'resume':
     kanbanCmd.resume({ rest: args });
     break;
+  case 'wait':
+    kanbanWait.wait({ rest: args, json: jsonRequested });
+    break;
   case '--help':
   case '-h':
   case undefined:
     printUsage();
     break;
+  case '--version':
+  case '-v':
+    console.log(version);
+    break;
   default:
     console.error(`Unknown command: ${subcommand}`);
     printUsage();

package/lib/auto-update.js

@@ -0,0 +1,79 @@
+// npm 업데이트 자동 반영 (README "Updating").
+// 설치된 패키지 버전과 이 레포가 마지막으로 동기화한 버전이 다르면, init과 같은
+// 마커 인식 동기화(syncCopies)를 자동으로 돈다 — 사용자는 npm update 만 하면 되고
+// 사본(skills/·scripts/·githooks)은 다음 어떤 명령에서든 따라온다.
+//
+// 버전 스탬프는 사용자 홈(~/.llm-wiki/auto-update/<레포경로해시>.version)에 둔다 —
+// 소비 리포의 커밋 트리를 오염시키지 않고, git 없는 디렉터리에서도 동작한다.
+// LLM_WIKI_STATE_DIR로 위치를 바꿀 수 있다(테스트 밀폐용).
+// 어떤 실패든 조용히 넘어간다 — 갱신 실패가 명령 자체를 막으면 안 된다.
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { findDocRoot, loadConfig } = require('./find-doc-root');
+const { syncCopies } = require('./init');
+const { version: PKG_VERSION } = require('../package.json');
+
+function stateDir() {
+  return process.env.LLM_WIKI_STATE_DIR || path.join(os.homedir(), '.llm-wiki');
+}
+
+function stampPath(repoRoot) {
+  // resolve로 정규화해 해시 — 슬래시/백슬래시 모양 차이가 키를 갈라놓지 않게.
+  const key = crypto.createHash('md5').update(path.resolve(repoRoot)).digest('hex').slice(0, 16);
+  return path.join(stateDir(), 'auto-update', `${key}.version`);
+}
+
+function readStamp(p) {
+  try {
+    return fs.readFileSync(p, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+// 명령 디스패치 직전에 부른다. docRoot를 (있다면) findDocRoot로 스스로 정한다.
+function maybeAutoUpdate() {
+  try {
+    const docRoot = findDocRoot();
+    const root = path.dirname(path.resolve(docRoot));
+
+    // init된 흔적이 없는 디렉터리에서는 아무것도 쓰지 않는다 — 모르는 리포 오염 금지.
+    // (findDocRoot의 cwd/doc 폴백이 낯선 디렉터리를 돌려줄 수 있다.)
+    const initMark =
+      fs.existsSync(path.join(root, 'doc', 'kanban')) ||
+      fs.existsSync(path.join(root, 'doc', 'wiki'));
+    if (!initMark) return;
+
+    const cfg = loadConfig(path.join(root, 'doc'));
+    if (cfg.autoUpdate === false) return; // 옵트아웃 — init 재실행으로만 갱신
+    if (process.env.LLM_WIKI_NO_AUTO_UPDATE === '1') return; // 일회성 끄기
+
+    const sp = stampPath(root);
+    if (readStamp(sp) === PKG_VERSION) return; // 이 버전으로 이미 동기화됨
+
+    const copies = syncCopies(root, { apply: true, config: cfg });
+    const actions = [...copies.skills, ...copies.scripts, ...copies.hooks];
+    const changed = actions.filter(a => a.status === 'updated' || a.status === 'copied');
+    const userModified = actions.filter(a => a.status === 'user-modified').length;
+
+    fs.mkdirSync(path.dirname(sp), { recursive: true });
+    fs.writeFileSync(sp, PKG_VERSION);
+
+    // 조용한 no-op 금지(계약): 뭘 바꿨는지 한 줄로 말한다. 바뀐 게 없으면 침묵.
+    if (changed.length > 0) {
+      const updated = changed.filter(a => a.status === 'updated').length;
+      const copied = changed.length - updated;
+      const skipped = userModified > 0 ? ` · 사용자 수정본 건너뜀 ${userModified}` : '';
+      console.log(
+        `llm-wiki v${PKG_VERSION}: npm 업데이트 자동 반영 — 사본 갱신 updated ${updated} · copied ${copied}${skipped}` +
+        ` (상세: llm-wiki init --check)`
+      );
+    }
+  } catch {
+    // 자동 갱신은 부가 기능이다 — 어떤 실패든 명령을 막지 않는다.
+  }
+}
+
+module.exports = { maybeAutoUpdate, stampPath };

package/lib/find-doc-root.js

@@ -1,13 +1,55 @@
-// cwd 기반 doc/ 루트 자동 탐색.
+// doc/ 루트 자동 탐색.
 // llm-wiki는 어느 리포에서 실행되든 동작해야 하므로, 스크립트 자신의 위치(__dirname)
-// 에 의존하지 않고 cwd에서 위로 올라가며 `doc/wiki`를 찾는다.
+// 에 의존하지 않는다. 보드(카드·클레임·활동 로그)는 프로젝트 자원이지 브랜치 자원이
+// 아니므로 git 링크 워크트리에서 실행돼도 주 워크트리의 doc/을 향한다(2026-09-12
+// sugarScan 실측 — 워크트리마다 보드가 갈라져 폐기 카드가 부 워크트리에서 되살아났다).
 //
 // 탐색 우선순위:
-//   1. LLM_WIKI_ROOT 환경변수 (명시적 오버라이드)
-//   2. cwd에서 위로 올라가며 doc/wiki 디렉토리가 있는 첫 조상
-//   3. cwd/doc (init 전이라 없어도 호출 가능하도록 폴백)
+//   1. LLM_WIKI_ROOT 환경변수 (명시적 오버라이드 — git을 부르지 않는다)
+//   2. git 저장소면 주 워크트리의 doc/ (doc/wiki가 있을 때; LLM_WIKI_WORKTREE_LOCAL=1로 끈다)
+//   3. cwd에서 위로 올라가며 doc/wiki 디렉토리가 있는 첫 조상 (git 아닌 곳 폴백)
+//   4. cwd/doc (init 전이라 없어도 호출 가능하도록 폴백)
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
+
+// 2단계 탐색 결과 캐시 — findDocRoot는 명령마다 여러 번 불리므로 git 자식 프로세스는
+// 시작 디렉터리당 프로세스에서 한 번만 돌린다 (value가 null이어도 캐시한다).
+let primaryWorktreeDocCache = { startDir: null, doc: null };
+
+function gitOutput(args, cwd) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 5000 });
+    if (r.error || r.status !== 0) return null; // git 없음·저장소 아님·타임아웃
+    return (r.stdout || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// 주 워크트리의 doc/ 경로. 못 찾으면(비저장소, init 전, git 실패) null → 상위 탐색으로.
+function primaryWorktreeDoc(startDir) {
+  const key = path.resolve(startDir);
+  if (primaryWorktreeDocCache.startDir === key) return primaryWorktreeDocCache.doc;
+  let doc = null;
+  // --path-format=absolute는 git 2.31+ 옵션이다 — 실패하면 옛 git으로 한 번 더.
+  let commonDir = gitOutput(['rev-parse', '--path-format=absolute', '--git-common-dir'], key);
+  if (!commonDir) {
+    commonDir = gitOutput(['rev-parse', '--git-common-dir'], key);
+  }
+  if (commonDir) {
+    // 상대 경로로 나오면 cwd 기준으로 절대화. dirname(<주 워크트리>/.git) = 저장소 루트.
+    const primaryRoot = path.dirname(path.resolve(key, commonDir));
+    const wiki = path.join(primaryRoot, 'doc', 'wiki');
+    try {
+      if (fs.statSync(wiki).isDirectory()) doc = path.join(primaryRoot, 'doc');
+    } catch {
+      // 주 워크트리에 doc/wiki 없음 = init 전 — 조용히 상위 탐색으로
+    }
+  }
+  primaryWorktreeDocCache = { startDir: key, doc };
+  return doc;
+}
 
 function findDocRoot(startDir) {
   // 1) 환경변수 오버라이드
@@ -15,8 +57,17 @@ function findDocRoot(startDir) {
     return path.resolve(process.env.LLM_WIKI_ROOT);
   }
 
-  // 2) cwd에서 위로 올라가며 doc/wiki 탐색
-  let dir = path.resolve(startDir || process.cwd());
+  const start = startDir || process.cwd();
+
+  // 2) 주 워크트리의 doc/ — 링크 워크트리의 브랜치 사본이 아니라 프로젝트 정본.
+  //    LLM_WIKI_WORKTREE_LOCAL=1이면 종전 동작(cwd 기준)으로 되돌린다.
+  if (process.env.LLM_WIKI_WORKTREE_LOCAL !== '1') {
+    const primaryDoc = primaryWorktreeDoc(start);
+    if (primaryDoc) return primaryDoc;
+  }
+
+  // 3) cwd에서 위로 올라가며 doc/wiki 탐색
+  let dir = path.resolve(start);
   for (let i = 0; i < 20; i++) {
     const candidate = path.join(dir, 'doc', 'wiki');
     if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
@@ -27,7 +78,7 @@ function findDocRoot(startDir) {
     dir = parent;
   }
 
-  // 3) 폴백: cwd/doc (init 전 상태에서도 호출 허용)
+  // 4) 폴백: cwd/doc (init 전 상태에서도 호출 허용)
   return path.join(process.cwd(), 'doc');
 }
 
@@ -63,6 +114,8 @@ function loadConfig(docRoot) {
     projectName: null, // null이면 index.md 헤더에 프로젝트명 생략
     collections: defaultCollectionNames(docRoot),
     hooksPath: null,
+    // npm 업데이트 자동 반영(README "Updating") — false면 init 재실행으로만 갱신.
+    autoUpdate: true,
   };
 
   const candidates = [
@@ -81,6 +134,7 @@ function loadConfig(docRoot) {
             raw: (user.collections && user.collections.raw) || defaults.collections.raw,
           },
           hooksPath: user.hooksPath !== undefined ? user.hooksPath : defaults.hooksPath,
+          autoUpdate: user.autoUpdate !== undefined ? user.autoUpdate : defaults.autoUpdate,
         };
       } catch (e) {
         // 깨진 config는 무시하고 기본값 사용 (사용자에게 에러 띄우지 않음)

package/lib/init.js

@@ -137,8 +137,39 @@ function exists(p) {
   }
 }
 
+// skills/·scripts/·githooks 사본을 마커 규칙대로 동기화한다 — init 본체와 자동 갱신
+// (lib/auto-update.js)이 같은 쓰기를 공유한다. 따로 두면 어느 한쪽만 새로워진다.
+// config는 hooksPath 판정에 필요 — 없으면 여기서 읽는다.
+function syncCopies(cwd, { apply = false, config } = {}) {
+  const cfg = config || loadConfig(path.join(cwd, 'doc'));
+  const out = { skills: [], scripts: [], hooks: [], hooksSkipped: null };
+
+  out.skills = syncSkills(
+    path.join(PKG_ROOT, 'skills'),
+    SKILL_TARGETS.map(t => path.join(cwd, t)),
+    { apply }
+  );
+
+  const scriptsDest = path.join(cwd, 'scripts');
+  if (apply) fs.mkdirSync(scriptsDest, { recursive: true });
+  out.scripts = syncMarkedFiles(path.join(PKG_ROOT, 'templates', 'scripts'), [scriptsDest], TEMPLATE_VERSION_RE, { apply });
+
+  if (cfg.hooksPath) {
+    out.hooksSkipped = cfg.hooksPath;
+  } else {
+    const hooksDest = path.join(cwd, 'githooks');
+    if (apply) fs.mkdirSync(hooksDest, { recursive: true });
+    out.hooks = syncMarkedFiles(path.join(PKG_ROOT, 'templates', 'githooks'), [hooksDest], TEMPLATE_VERSION_RE, { apply });
+  }
+  return out;
+}
+
 function init(options = {}) {
-  const cwd = process.cwd();
+  // LLM_WIKI_ROOT는 doc/ 루트 자체를 가리킨다 — 오버라이드가 있으면 그 부모를
+  // 레포 루트로 삼아 거기에 스캐폴드한다. 무시하면 init은 cwd/doc에 골격을 놓고
+  // 다른 명령은 오버라이드 루트를 읽어 "doc/kanban이 없다 → init을 실행하라"의
+  // 안내 무한루프가 된다(2026-09-09 리뷰 5-2).
+  const cwd = process.env.LLM_WIKI_ROOT ? path.dirname(path.resolve(process.env.LLM_WIKI_ROOT)) : process.cwd();
 
   // --check: 아무것도 쓰지 않고 레포 복사본 vs 패키지 정본의 신선함만 보고 (개선계획 1-7).
   if (options.check) {
@@ -189,36 +220,21 @@ function init(options = {}) {
     console.log('✓ AGENTS.md already exists, untouched.');
   }
 
-  // 2. skills/ (정본 → 복사본). 마커 규칙: skill-version이 살아있는 복사본만 갱신하고,
-  //    마커를 지운 파일(사용자 수정)은 건너뛴다 — syncSkills 주석 참고.
-  const skillsSrc = path.join(PKG_ROOT, 'skills');
-  const actions = syncSkills(skillsSrc, SKILL_TARGETS.map(t => path.join(cwd, t)), { apply: true });
+  // 2~4. skills/·scripts/·githooks 사본 동기화 — 마커 규칙(살아있으면 갱신, 지웠으면
+  //     사용자 수정본으로 건너뜀)은 syncCopies가 지킨다. init과 자동 갱신이 공유.
+  const cfg = loadConfig(docDir);
+  const copies = syncCopies(cwd, { apply: true, config: cfg });
   for (const target of SKILL_TARGETS) {
     console.log(`✓ Synced skills/ → ${target}/`);
   }
-  printSkillSyncReport(actions, cwd);
-
-  // 3. scripts/ 동기화 스크립트 — 스킬과 같은 마커 규칙으로 동기화(2026-08-29 확장).
-  //    마커를 지운 파일(사용자 수정)은 건너뛴다 — init이 훅 보조 스크립트를 덮어쓰지 않는다.
-  const scriptsSrc = path.join(PKG_ROOT, 'templates', 'scripts');
-  const scriptsDest = path.join(cwd, 'scripts');
-  fs.mkdirSync(scriptsDest, { recursive: true });
-  const scriptsActions = syncMarkedFiles(scriptsSrc, [scriptsDest], TEMPLATE_VERSION_RE, { apply: true });
+  printSkillSyncReport(copies.skills, cwd);
   console.log('✓ Synced templates/scripts → scripts/');
-  printSkillSyncReport(scriptsActions, cwd);
-
-  // 4. githooks — 기본은 마커 규칙 사본 동기화. 레포가 config로 hooksPath를 선언했으면
-  //    (이 레포처럼 templates/를 정본으로 직접 쓰는 경우) 사본을 만들지 않는다.
-  const cfg = loadConfig(docDir);
-  if (cfg.hooksPath) {
-    console.log(`✓ hooks: 레포 선언 경로 ${cfg.hooksPath} 를 그대로 쓴다 (githooks/ 사본 없음).`);
+  printSkillSyncReport(copies.scripts, cwd);
+  if (copies.hooksSkipped) {
+    console.log(`✓ hooks: 레포 선언 경로 ${copies.hooksSkipped} 를 그대로 쓴다 (githooks/ 사본 없음).`);
   } else {
-    const hooksSrc = path.join(PKG_ROOT, 'templates', 'githooks');
-    const hooksDest = path.join(cwd, 'githooks');
-    fs.mkdirSync(hooksDest, { recursive: true });
-    const hooksActions = syncMarkedFiles(hooksSrc, [hooksDest], TEMPLATE_VERSION_RE, { apply: true });
     console.log('✓ Synced templates/githooks → githooks/');
-    printSkillSyncReport(hooksActions, cwd);
+    printSkillSyncReport(copies.hooks, cwd);
   }
 
   // 5. QMD 컬렉션 이름 충돌 검사 (리포 폴더명 기반 기본값이라도, 여러 리포명이 sanitize 후
@@ -243,4 +259,4 @@ function init(options = {}) {
   console.log('Done. AI agents will now use wiki-search/log/compile/lint + work-loop/board.');
 }
 
-module.exports = { init };
+module.exports = { init, syncCopies };