@kybird/llm-wiki 0.3.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybird/llm-wiki",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "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",
@@ -38,6 +38,6 @@
     "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"
+    "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: 5
+skill-version: 8
 ---
 # When to use
 
@@ -18,6 +18,16 @@ skill-version: 5
 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을 되뇐다. 다른 프로젝트의
+모니터가 기본 포트를 쓰고 있으면 **다음 포트에 자기 보드를 띄운다** — 멀티
+프로젝트 밤에도 각자의 보드가 각자의 URL에 뜬다. 백그라운드 실행이 안 되는
+환경이면 건너뛴다 — 모니터는 관측이지 의존성이 아니다. 정지 규칙에서도 모니터는
+끄지 않는다(아침의 사람이 본다) — 읽기 전용이라 남겨두는 비용이 없다.
+
 # Loop graph
 
 ```
@@ -61,6 +71,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

package/templates/AGENTS.md

@@ -13,8 +13,9 @@ 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