@kybird/llm-wiki 0.3.0 → 0.4.2

package/README.md

@@ -47,20 +47,21 @@ 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 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 **the same board's** monitor already listens is **idempotent** — exit 0, same URL. A port held by **another project's** monitor: default execution walks to the next free port (4747→4748→…, each board gets its own URL; the header shows the project name); an explicit `--port` fails with the owner's name. **`--all`** starts a **fleet view** — every llm-wiki project on this machine as tiles (WIP, review queue, milestone progress, last activity) with each project's full board one click away; projects register themselves in a machine-local registry (`~/.llm-wiki/projects.json`) as they run commands. **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). `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.
+`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 card command also rejects unknown flags (`모르는 플래그`), so a typo'd flag fails loudly instead of silently no-oping.
+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

package/bin/llm-wiki.js

@@ -7,6 +7,7 @@ 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');
@@ -31,20 +32,32 @@ Skills (git channel — prompt edits without npm publish, plan.md 6.2):
                                      [--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, --not-before)
+  llm-wiki monitor [--port <n>] [--all]  Live read-only board view at http://127.0.0.1:<n>
+                                     (default 4747, walks to the next free port past other
+                                     projects' monitors) — claims, elapsed, gates, activity;
+                                     --all = fleet view of EVERY llm-wiki project on this
+                                     machine (tiles + per-project boards); the CLI stays the
+                                     only writer (405 on any write method)
+  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; unknown/blank flags fail, output
                                      says what changed (--goal/--plan/--ac/--add-ac/
                                      --check-ac/--note/--renew-claim/--depends/
-                                     --add-depends/--remove-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
+                                     --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
@@ -62,7 +75,7 @@ Optional:
                                      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",
@@ -70,10 +83,11 @@ Optional:
 }
 
 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`를 쳤다가 실제로 카드를 집는 일을 원천
@@ -83,7 +97,7 @@ const args = rest.filter(a => a !== '--json' && a !== '--html');
 // (kanban-cmd의 USAGE)에서 온다. 전용 문자열이 없는 읽기 전용 명령(search 등)은
 // 전체 사용법으로 대신한다. return으로 자연 종료한다 — Windows 파이프 stdout은
 // 비동기라 process.exit은 마지막 줄을 지울 수 있다(kanban-wait 교훈).
-const KNOWN_SUBCOMMANDS = ['search', 'compile', 'lint', 'init', 'skills', 'board', 'card',
+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;
@@ -125,8 +139,16 @@ switch (subcommand) {
     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);

package/lib/auto-update.js

@@ -50,6 +50,10 @@ function maybeAutoUpdate() {
     if (cfg.autoUpdate === false) return; // 옵트아웃 — init 재실행으로만 갱신
     if (process.env.LLM_WIKI_NO_AUTO_UPDATE === '1') return; // 일회성 끄기
 
+    // 기계의 프로젝트 등록부 — monitor --all(플릿)이 이 머신의 보드들을 아는
+    // 길이다. 버전 동기화와 무관하게 매번 갱신한다(마지막 본 시각 포함).
+    recordProject(docRoot, cfg);
+
     const sp = stampPath(root);
     if (readStamp(sp) === PKG_VERSION) return; // 이 버전으로 이미 동기화됨
 
@@ -76,4 +80,38 @@ function maybeAutoUpdate() {
   }
 }
 
-module.exports = { maybeAutoUpdate, stampPath };
+// ── 기계의 프로젝트 등록부 (monitor --all 플릿의 발견 소스) ─────────────────
+// <stateDir>/projects.json — { "<리포 절대경로>": { name, docRoot, lastSeen } }.
+// 능동 명령(maybeAutoUpdate)과 monitor 시작이 매번 갱신한다. 플릿은 파일이
+// 정본인 보드들을 직접 읽으므로, 이 등록부는 "어떤 프로젝트가 이 머신에 사나"의
+// 유일한 목록이다 — 스탬프 해시는 경로를 못 되돌려서 이 용도로 못 쓴다.
+function registryPath() {
+  return path.join(stateDir(), 'projects.json');
+}
+
+function recordProject(docRoot, cfg) {
+  try {
+    const root = path.dirname(path.resolve(docRoot));
+    const name = (cfg && cfg.projectName) || path.basename(root);
+    let data = {};
+    try { data = JSON.parse(fs.readFileSync(registryPath(), 'utf8')); } catch { /* 없음 — 첫 등록 */ }
+    data[root] = { name, docRoot: path.resolve(docRoot), lastSeen: new Date().toISOString() };
+    fs.mkdirSync(stateDir(), { recursive: true });
+    fs.writeFileSync(registryPath(), JSON.stringify(data, null, 2) + '\n');
+  } catch {
+    // 등록부는 부가 기능이다 — 실패가 명령을 막지 않는다(maybeAutoUpdate와 같은 규칙).
+  }
+}
+
+function readProjects() {
+  try {
+    const data = JSON.parse(fs.readFileSync(registryPath(), 'utf8'));
+    return Object.values(data)
+      .filter(p => p && p.docRoot && fs.existsSync(path.join(p.docRoot, 'kanban')))
+      .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { maybeAutoUpdate, stampPath, recordProject, readProjects };