@kybird/llm-wiki 0.2.0

package/skills/work-loop/SKILL.md

@@ -0,0 +1,88 @@
+---
+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
+---
+# When to use
+
+- A **dedicated unattended session** — user said "루프 돌려" (run the loop) before sleep,
+  or a host scheduler started this session at off-peak. The board is the task list; there
+  is no competing native todo here.
+- Not for ordinary interactive sessions — those should just use `llm-wiki search` and the
+  wiki skills.
+
+# Trigger (no daemon — plan.md 4.4)
+
+1. Primary: a human asks, the session runs this skill until the stop rule fires.
+2. Secondary: a host-level scheduler (e.g. ZCode 예약) starts the session at midnight.
+3. Never build or assume a process supervisor. The loop lives in the session; the board
+   lives in files.
+
+# Loop graph
+
+```
+pick → work → 판정 ─ done / handoff / abandon / supersede
+  ↑                     │
+  └────── next card ←───┘
+집을 카드 없음 → review(대기) 큐 점검 → 전부 대기면 질문을 모아 정지 (반스래시)
+```
+
+# Rules (all six 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
+     automatically; you never see them. Don't try to work around the gate.
+   - A card parked in `review` whose Handoff states an **activation condition**
+     (e.g. "수렴 데이터 7일 축적 후") — while walking the review queue, you may
+     evaluate the condition yourself, but only with objective evidence (`board report`
+     numbers, activity.jsonl, repo state). If it holds, `llm-wiki resume <제목>
+     --note "조건 충족: <근거>"` sends it back to todo. If not, leave it parked.
+   Never resume on vibes. The gate exists so divergence waits its turn.
+
+1. **Judgment = closed list.** Only these four go to `handoff`: ① spec decisions
+   ② credentials or outward-facing actions ③ judgment-call merge conflicts
+   ④ repeatedly failing tests you cannot diagnose. Everything else — naming, structure,
+   implementation details, test approach — you decide yourself. Opening the list wider
+   produces chronic park-avoidance in the other direction: an empty done/ pile.
+
+2. **Blocked ≠ stopped.** When a card hits the judgment list, `llm-wiki handoff <제목>
+   --question "…"` and immediately pick the next card. Never wait for session approval —
+   this session runs unattended (plan.md 2.1: 승인 대기 = 오프피크 낭비). The question is
+   a record made at the wall, not a pre-work approval request — 무인 세션에는 시작 전에
+   물어볼 상대가 없고, 질문은 밤새 대기 큐에 모여 아침에 일괄 답한다.
+
+3. **AC by objective evidence only.** Check an AC (`card edit --check-ac N`) because you
+   ran something that proves it — command output, passing test, diff — never because the
+   code "looks right". `done --result` answers exactly two things: 무엇을 바꿨고, 무엇으로
+   검증했는가. The QA pass (below) reverts fake dones.
+
+4. **Stop rule.** `pick` returns "No pickable card": check the board's review queue.
+   If everything is parked, run `llm-wiki board report` **and** `llm-wiki board video`
+   (보고서와 함께 세션 타임랩스 영상을 남긴다 — 아침의 사람이 40초로 밤을 본다),
+   leave the questions in one place, and STOP. Do not invent new cards to look
+   productive. 밤새 카드가 300장이 되는 것이 이 시스템이 죽는 방식이다 (plan.md 2.3).
+
+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
+   or supersede — same wall twice in one night is the failure the wiki exists to prevent.
+
+6. **Renew the claim.** A claim expires (board.yml `claim_timeout_minutes`, default 1h).
+   On a long card, `llm-wiki card edit <제목> --renew-claim` before the timeout, or
+   another loop instance will reclaim the card under you.
+
+# Splitting (supersede) — divergence guard
+
+Supersede only when each child is **strictly smaller** than the parent in context needed.
+Guideline while the convergence data is still being collected: card depth ≤ 3, one card =
+one context = one commit. `llm-wiki supersede <부모> --by 자식1,자식2` — the parent
+dissolves; its history stays in `superseded/`.
+
+# QA pass (개선계획 4.3)
+
+Run at the end of the night, or in a separate morning session:
+
+- Walk recent `doc/kanban/done/` cards newest-first. For each: does `Result` state a real
+  verification, and are checked ACs backed by evidence in Notes or the diff?
+- Evidence-thin → `llm-wiki reopen <제목> --why "…"` (reverts to doing). A temporary
+  increase in card count is the price of a real convergence curve (plan.md 2.4).
+- `llm-wiki board report` shows the revert count — reverts are signal, not shame.

package/templates/doc/raw/.gitkeep

@@ -0,0 +1,2 @@
+# wiki-log 스킬이 이 디렉토리에 YYYY-MM-DD.md 형식의 일일 로그를 기록합니다.
+# 이 파일 자체는 빈 디렉토리를 git에 유지하기 위한 플레이스홀더입니다.

package/templates/doc/wiki/index.md

@@ -0,0 +1,36 @@
+---
+tags: [index]
+
+# Wiki Index
+
+이 프로젝트의 구조화된 지식 베이스입니다. `doc/raw/` 로그에서 추출한 핵심 개념과 패턴을 정리했습니다.
+
+---
+
+## Concepts
+
+| 개념 | 설명 |
+|------|------|
+
+---
+
+## Patterns
+
+| 패턴 | 설명 |
+|------|------|
+
+---
+
+## Anti-Patterns
+
+| 안티패턴 | 설명 |
+|------|------|
+
+---
+
+## Statistics
+
+- Total concepts: 0
+- Total patterns: 0
+- Total anti-patterns: 0
+- Last updated: never

package/templates/githooks/pre-commit

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# llm-wiki-template-version: 1 — 이 줄이 살아있으면 `llm-wiki init`이 정본(templates/)으로 갱신하고,
+# 지워져 있으면 사용자 수정본으로 보고 건너뛴다 (plan.md 6.1).
+# Drift 가드: CLAUDE.md(정본)와 복사본(agents.md, GEMINI.md ...)이 항상 같은지 확인.
+#  - CLAUDE.md가 스테이징된 채 바뀌었다면 → 모든 복사본으로 자동 동기화 + 재스테이징.
+#  - 복사본만 직접 편집했다면 → 커밋 거부 (정본 CLAUDE.md를 고치고 동기화할 것).
+set -uo pipefail
+
+canon="CLAUDE.md"
+mirrors=("agents.md" "GEMINI.md")
+
+staged_canon=$(git diff --cached --name-only -- "$canon" | wc -l)
+
+# 정본 또는 어떤 복사본이라도 스테이징됐는지 조사.
+any_staged=0
+for m in "${mirrors[@]}"; do
+  c=$(git diff --cached --name-only -- "$m" | wc -l)
+  [ "$c" -gt 0 ] && any_staged=1
+done
+
+# 각 복사본에 대해 drift 검사 (정본/복사본 둘 다 미스테이징이면 건너뜀).
+if [ "$staged_canon" -gt 0 ] || [ "$any_staged" -gt 0 ]; then
+  for m in "${mirrors[@]}"; do
+    if ! cmp -s "$canon" "$m"; then
+      if [ "$staged_canon" -gt 0 ]; then
+        # 정본이 바뀜 → 이 복사본으로 동기화.
+        cp -f "$canon" "$m"
+        git add "$m"
+        echo "[pre-commit] $canon(정본) 변경 감지 → $m 동기화 및 재스테이징." >&2
+      else
+        # 복사본만 직접 편집됨 → 거부.
+        echo "[pre-commit] $m 를 직접 편집함. 정본은 $canon 입니다." >&2
+        echo "[pre-commit] 변경사항을 $canon 에 적용 후 'scripts/sync_agent_docs.sh' 를 실행하거나," >&2
+        echo "[pre-commit] 이 커밋에서 $m 변경분을 빼세요 (git restore --staged $m)." >&2
+        exit 1
+      fi
+    fi
+  done
+fi
+
+# ── 미컴파일 raw 로그 넛지 ────────────────────────────────────
+# doc/raw/*.md가 커밋에 포함되면 compile list로 미컴파일 로그를 보여준다.
+# 경고만 하고 커밋은 막지 않는다. 무거운 QMD embed은 훅에서 돌리지 않는다 —
+# index 갱신(compile index)은 사람/세션이 직접 호출하는 것을 남긴다.
+if git diff --cached --name-only -- 'doc/raw/*.md' | grep -q .; then
+  if command -v llm-wiki >/dev/null 2>&1; then
+    echo "[pre-commit] doc/raw/ 로그가 커밋에 포함됨 — 미컴파일 항목 점검:" >&2
+    llm-wiki compile list >&2 || echo "[pre-commit] llm-wiki compile list 실행 실패 (무시하고 계속)." >&2
+  fi
+fi
+
+# ── 스킬 동기화 가드 ──────────────────────────────────────────
+# .agents/skills/(정본) ↔ .claude/skills/(복사본) 디렉토리 미러.
+skill_canon=".agents/skills"
+skill_mirror=".claude/skills"
+
+staged_skill_canon=$(git diff --cached --name-only -- "$skill_canon/" | wc -l)
+staged_skill_mirror=$(git diff --cached --name-only -- "$skill_mirror/" | wc -l)
+
+if [ "$staged_skill_canon" -gt 0 ] || [ "$staged_skill_mirror" -gt 0 ]; then
+  if ! diff -rq "$skill_canon" "$skill_mirror" >/dev/null 2>&1; then
+    if [ "$staged_skill_canon" -gt 0 ]; then
+      # 정본이 바뀜 → 복사본으로 미러 동기화.
+      bash "$(git rev-parse --show-toplevel)/scripts/sync_skills.sh" >&2
+      git add "$skill_mirror/"
+      echo "[pre-commit] $skill_canon/(정본) 변경 감지 → $skill_mirror/ 동기화 및 재스테이징." >&2
+    else
+      # 복사본만 직접 편집됨 → 거부.
+      echo "[pre-commit] $skill_mirror/ 를 직접 편집함. 정본은 $skill_canon/ 입니다." >&2
+      echo "[pre-commit] 변경사항을 $skill_canon/ 에 적용 후 'scripts/sync_skills.sh' 를 실행하거나," >&2
+      echo "[pre-commit] 이 커밋에서 $skill_mirror/ 변경분을 빼세요 (git restore --staged $skill_mirror/)." >&2
+      exit 1
+    fi
+  fi
+fi
+
+exit 0

package/templates/scripts/sync_agent_docs.bat

@@ -0,0 +1,33 @@
+@echo off
+REM llm-wiki-template-version: 1 — 이 줄이 살아있으면 llm-wiki init이 갱신하고, 지워져 있으면 사용자 수정본으로 건너뛴다 (plan.md 6.1).
+REM CLAUDE.md(정본) -> 복사본 동기화.
+REM 복사본 목록에 새 에이전트 파일을 추가하면 자동으로 동기화된다.
+REM 항상 CLAUDE.md만 편집하고 이 스크립트를 실행할 것.
+setlocal
+cd /d "%~dp0.."
+
+set "CANON=CLAUDE.md"
+REM 복사본 목록 — 새 에이전트 파일은 여기에 추가.
+call :sync_one agents.md
+if errorlevel 1 exit /b 1
+call :sync_one GEMINI.md
+if errorlevel 1 exit /b 1
+
+echo [sync] 모든 복사본 동기화 OK.
+endlocal
+exit /b 0
+
+REM --- 서브루틴: sync_one <mirror> ---
+:sync_one
+copy /y "%CANON%" "%~1" >nul
+if errorlevel 1 (
+    echo [sync] ERROR: %~1 복사 실패
+    exit /b 1
+)
+fc "%CANON%" "%~1" >nul
+if errorlevel 1 (
+    echo [sync] ERROR: %~1 동기화 후에도 불일치
+    exit /b 1
+)
+echo [sync] %CANON% -^> %~1 OK
+exit /b 0

package/templates/scripts/sync_agent_docs.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# llm-wiki-template-version: 1 — 이 줄이 살아있으면 llm-wiki init이 갱신하고, 지워져 있으면 사용자 수정본으로 건너뛴다 (plan.md 6.1).
+# CLAUDE.md(정본) → 복사본 동기화.
+# 복사본 목록(mirrors)에 새 에이전트 파일을 추가하면 자동으로 동기화된다.
+# 항상 CLAUDE.md만 편집하고 이 스크립트를 실행할 것.
+# (pre-commit 가드가 커밋 시 자동으로 같은 일을 하므로, 보통은 수동 실행 불필요.)
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+canon="CLAUDE.md"
+mirrors=("agents.md" "GEMINI.md")
+
+for m in "${mirrors[@]}"; do
+  cp -f "$canon" "$m"
+  echo "[sync] $canon -> $m"
+
+  if cmp -s "$canon" "$m"; then
+    : # OK
+  else
+    echo "[sync] ERROR: $m 와 $canon 이(가) 불일치. 확인 필요." >&2
+    exit 1
+  fi
+done
+
+echo "[sync] OK: 모든 복사본이 $canon 과(과) 동일합니다."

package/templates/scripts/sync_skills.bat

@@ -0,0 +1,26 @@
+@echo off
+REM llm-wiki-template-version: 1 — 이 줄이 살아있으면 llm-wiki init이 갱신하고, 지워져 있으면 사용자 수정본으로 건너뛴다 (plan.md 6.1).
+REM .agents/skills/ (canon) -> .claude/skills/ (mirror) directory mirror.
+REM robocopy /MIR = full mirror based on canon (removes items absent from canon).
+REM Always edit .agents/skills/ only, then run this script.
+setlocal
+cd /d "%~dp0.."
+
+set "CANON=.agents\skills"
+set "MIRROR=.claude\skills"
+
+if not exist "%CANON%\" (
+    echo [sync-skills] ERROR: canon %CANON% not found
+    exit /b 1
+)
+
+REM robocopy exit codes: 0-7 = OK (copied/identical), 8+ = error.
+robocopy "%CANON%" "%MIRROR%" /MIR /NFL /NDL /NJH /NJS /NC /NS >nul
+if errorlevel 8 (
+    echo [sync-skills] ERROR: robocopy failed ^(exit %errorlevel%^)
+    exit /b 1
+)
+
+echo [sync-skills] %CANON% -^> %MIRROR% mirror OK.
+endlocal
+exit /b 0

package/templates/scripts/sync_skills.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# llm-wiki-template-version: 1 — 이 줄이 살아있으면 llm-wiki init이 갱신하고, 지워져 있으면 사용자 수정본으로 건너뛴다 (plan.md 6.1).
+# .agents/skills/(정본) → .claude/skills/(복사본) 디렉토리 미러링.
+# 정본에 없는 스킬/파일은 복사본에서 제거(완전 미러).
+# 항상 .agents/skills/만 편집하고 이 스크립트를 실행할 것.
+# (pre-commit 가드가 커밋 시 자동으로 같은 일을 하므로, 보통은 수동 실행 불필요.)
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+canon=".agents/skills"
+mirror=".claude/skills"
+
+if [ ! -d "$canon" ]; then
+  echo "[sync-skills] ERROR: 정본 $canon 이(가) 없습니다." >&2
+  exit 1
+fi
+
+# 1) 정본 → 복사본 전체 복사 (cp -rf, 기존 파일 덮어쓰기).
+mkdir -p "$mirror"
+cp -rf "$canon"/. "$mirror"/
+
+# 2) 미러링: 복사본에만 있는 항목(정본에 없는 스킬) 제거.
+if [ -d "$mirror" ]; then
+  while IFS= read -r item; do
+    name=$(basename "$item")
+    if [ ! -e "$canon/$name" ]; then
+      rm -rf "$mirror/$name"
+      echo "[sync-skills] 정본에 없음 → 제거: $mirror/$name"
+    fi
+  done < <(find "$mirror" -mindepth 1 -maxdepth 1)
+fi
+
+# 3) 검증: diff -rq 가 빈 출력이면 완전 미러.
+if diff -rq "$canon" "$mirror" >/dev/null 2>&1; then
+  echo "[sync-skills] OK: $canon → $mirror 완전 미러."
+else
+  echo "[sync-skills] ERROR: 동기화 후에도 불일치. diff 확인 필요." >&2
+  diff -rq "$canon" "$mirror" >&2 || true
+  exit 1
+fi