@kybird/llm-wiki 0.2.2 → 0.4.0

package/lib/kanban-cmd.js

@@ -1,20 +1,26 @@
 // kanban 명령 계층 — 카드 쓰기는 전부 이 모듈의 CLI 경로로만 일어난다.
 // 사람은 카드를 읽기만 하고, 에이전트는 이 명령들로만 고친다 (개선계획 §3.2).
 // 서브커맨드:
-//   card new "<제목>" [--goal …] [--ac … …] [--depends a,b]
+//   card new "<제목>" [--goal …] [--ac … …] [--depends a,b] [--not-before YYYY-MM-DD]
+//                     [--kind milestone] [--milestone "<마일스톤 제목>"]
 //   card show <제목>
-//   card edit <제목> [--goal …] [--ac … …] [--add-ac …] [--check-ac 1,2] [--note …] [--plan …]
-//   pick [--claim 이름]                       원자적 집기 (락 안에서)
+//   card edit <제목> [--goal …] [--plan …] [--ac … …] [--add-ac …] [--check-ac 1,2]
+//                     [--note …] [--renew-claim] [--depends a,b] [--add-depends a,b]
+//                     [--remove-depends a,b] [--milestone "<마일스톤 제목>"]
+//   pick [--claim 이름] [--card 제목]        원자적 집기 (락 안에서)
 //   handoff <제목> --question "…"             review로 park + 클레임 반납
 //   done <제목> --result "…"                  완료 — Result 없으면 거부
 //   supersede <제목> --by a,b                 대체 — 부모는 superseded/로 소멸
 //   abandon <제목> --reason "…"               폐기 — 사유 없으면 거부
-//   board [--json]                            유도 뷰 (컬럼/WIP/대기/만료 클레임)
+//   board                                     유도 뷰 (컬럼/WIP/대기/만료 클레임) — 플래그 없음
+// card new/edit은 모르는 플래그·값 없는 플래그·바꿀 것 없는 호출을 실패로 끝낸다 —
+// no-op을 성공으로 보고하면 에이전트가 다음 단계를 거짓 전제 위에 세운다.
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { findDocRoot, loadConfig } = require('./find-doc-root');
 const kanban = require('./kanban');
+const { localToday } = require('./local-today');
 
 // ── 공용 ────────────────────────────────────────────────────────────────
 
@@ -31,10 +37,16 @@ function parseArgs(rest) {
         value = arg.slice(eq + 1);
       } else {
         key = arg.slice(2);
-        value = rest[i + 1];
-        i++;
+        // 다음 토큰이 또 플래그면 값을 삼키지 않는다 — `done --result --yes`가
+        // result='--yes'로 기록되던 결함(2026-09-09 리뷰 5-2). 값 자체가 --로
+        // 시작해야 하면 `--result=--x` 등호 형식으로 쓴다.
+        if (rest[i + 1] !== undefined && !rest[i + 1].startsWith('--')) {
+          value = rest[i + 1];
+          i++;
+        } else {
+          value = true; // 값 없는 플래그 — 필수 문자열 플래그에 이 값이 오면 거부된다.
+        }
       }
-      value = value === undefined ? true : value;
       // 같은 플래그 반복(--ac a --ac b)은 배열로 누적.
       if (flags[key] !== undefined) {
         flags[key] = [].concat(flags[key], value);
@@ -52,6 +64,40 @@ function asArray(v) {
   return v === undefined ? [] : [].concat(v);
 }
 
+// 필수 문자열 플래그 검증 — 값 없는 `--result` 등은 parseArgs가 true를 심는다.
+// 그대로 쓰면 기록에 문자열 'true'가 남는다(2026-09-09 리뷰 5-2). 문자열만 통과.
+function flagString(v) {
+  return typeof v === 'string' && v.trim() ? v : undefined;
+}
+
+// 선택 문자열 플래그 — 배열 원소 중 문자열만 (값 없는 반복 플래그의 true 제거).
+function stringArray(v) {
+  return asArray(v).filter(s => typeof s === 'string');
+}
+
+// 플래그 명세 검증 (card new/edit 공용) — 모르는 플래그와 값 없는 필수 플래그를
+// 조용히 삼키면 no-op이 성공으로 보고된다(2026-09-10 접수 결함 A). 주 사용자는
+// 종료 코드와 출력으로만 결과를 판단하는 에이전트다 — 오타 하나가 조용한 성공이
+// 되면 다음 단계가 "걸렸다"를 전제로 진행된다.
+// spec: { 이름: 'string' | 'flag' } — 'string'은 값 필수(반복 허용), 'flag'는 값 없는 스위치.
+function validateFlags(flags, spec) {
+  const unknown = Object.keys(flags).filter(k => !(k in spec));
+  if (unknown.length) {
+    fail(`모르는 플래그: ${unknown.map(k => `--${k}`).join(', ')} — 쓸 수 있는 플래그: ${Object.keys(spec).map(k => `--${k}`).join(', ')}`);
+  }
+  for (const key of Object.keys(spec)) {
+    if (spec[key] !== 'string' || flags[key] === undefined) continue;
+    if ([].concat(flags[key]).some(v => typeof v !== 'string' || !String(v).trim())) {
+      fail(`--${key} 에 값이 없다 — \`--${key} "<값>"\` 또는 \`--${key}=값\` 형태로 줘야 한다.`);
+    }
+  }
+}
+
+// 쉼표 목록 플래그("--depends a,b" → [a, b]) — validateFlags가 값 있음을 보증한다.
+function csvList(v) {
+  return stringArray(v).flatMap(s => String(s).split(',')).map(s => s.trim()).filter(Boolean);
+}
+
 // 로컬 타임존 ISO (분 단위) — 2026-08-29T23:14+09:00 형태. 클레임 만료 판정은
 // Date.parse가 오프셋을 이해하므로 이 형태로 충분하다.
 function localIso(date = new Date()) {
@@ -68,118 +114,333 @@ function fail(message) {
   process.exit(1);
 }
 
-// 보드가 스캐폴드돼 있어야 한다 — 없으면 init으로 안내.
+// 보드가 스캐폴드돼 있어야 한다 — 없으면 init으로 안내. 에러는 실제 탐색 루트와
+// LLM_WIKI_ROOT 값을 함께 보고한다 — 오버라이드가 다른 곳을 보고 있었다는 단서.
 function requireBoard() {
   const docRoot = findDocRoot();
   const paths = kanban.kanbanPaths(docRoot);
   if (!fs.existsSync(paths.kanbanDir)) {
-    fail('doc/kanban/ 이 없다. 먼저 `llm-wiki init`을 실행하라.');
+    fail(`doc/kanban/ 이 없다 (${paths.kanbanDir}${process.env.LLM_WIKI_ROOT ? ` — LLM_WIKI_ROOT=${process.env.LLM_WIKI_ROOT}` : ''}). 먼저 \`llm-wiki init\`을 실행하라.`);
   }
   return { docRoot, paths, config: kanban.loadConfig(paths) };
 }
 
 function nowIso() { return localIso(); }
 
+// ── depends_on 검증 (card new/edit 공용) ──────────────────────────────────
+// 의존성은 보통 카드를 만들 때가 아니라 계획하다가 알게 된다 — card new 때만 걸 수
+// 있으면 선행 카드가 늦게 생기는 정상 흐름을 기록할 길이 없다(2026-09-10 결함 B).
+// 여기는 쓰는 규칙만 정한다 — pick이 읽는 규칙(resolved 판정)은 바꾸지 않는다.
+
+// start에서 target까지 depends_on 간선을 따라 닿는 경로 — 순환 보고용. 없으면 null.
+function depCyclePath(graph, start, target) {
+  const seen = new Set();
+  const walk = (node, trail) => {
+    if (node === target) return trail;
+    if (seen.has(node)) return null;
+    seen.add(node);
+    for (const next of graph.get(node) || []) {
+      const found = walk(next, [...trail, next]);
+      if (found) return found;
+    }
+    return null;
+  };
+  return walk(start, [start]);
+}
+
+// 새로 거는 의존성(deps)만 검증한다 — 이미 있던 것의 제거는 레거시의 끊어진 간선을
+// 정리하는 길이어야 한다. 카드는 4폴더를 딱 한 번 로드한다(findCard 1회와 같은
+// 비용) — 락 안에서 도니 반복 로드를 피한다.
+function validateDepTargets(paths, title, deps) {
+  if (deps.includes(title)) {
+    fail(`자기 자신을 의존성으로 넣을 수 없다: ${title}`);
+  }
+  const all = kanban.listAllCards(paths);
+  const known = new Set(all.map(c => c.meta.title));
+  const missing = deps.filter(d => !known.has(d));
+  if (missing.length) {
+    fail(`의존성 카드가 없다: ${missing.join(', ')} — 끊어진 의존성은 pick을 영구히 막는다. card new로 먼저 만들어라.`);
+  }
+  // 순환은 활성(cards/) 카드의 간선으로만 판정한다 — 종결 카드를 의존성으로 넣는 것은
+  // 허용되고(pick의 resolved 판정: done/superseded는 이미 해소), 종결 카드 자신의
+  // depends_on은 아무도 기다리지 않는 죽은 이력이라 순환을 만들지 않는다.
+  const graph = new Map(
+    all
+      .filter(c => kanban.ACTIVE_STATUSES.includes(c.meta.status))
+      .map(c => [c.meta.title, Array.isArray(c.meta.depends_on) ? c.meta.depends_on : []])
+  );
+  for (const d of deps) {
+    const cyc = depCyclePath(graph, d, title);
+    if (cyc) fail(`순환 의존성이다: ${[title, ...cyc].join(' → ')} — 순환은 두 카드를 다 영구히 못 집게 만든다.`);
+  }
+}
+
 // ── card new / show / edit ──────────────────────────────────────────────
 
-function cardNew(paths, config, { positional, flags }) {
-  const title = positional[0];
-  if (!title) fail('사용법: llm-wiki card new "<제목>" [--goal …] [--ac …]');
+const CARD_NEW_FLAGS = { goal: 'string', ac: 'string', depends: 'string', 'not-before': 'string', kind: 'string', milestone: 'string' };
+const CARD_EDIT_FLAGS = {
+  goal: 'string', plan: 'string',
+  ac: 'string', 'add-ac': 'string', 'check-ac': 'string',
+  note: 'string', 'renew-claim': 'flag',
+  depends: 'string', 'add-depends': 'string', 'remove-depends': 'string',
+  milestone: 'string',
+};
 
-  const fileName = `${kanban.slugify(title)}.md`;
-  const filePath = path.join(paths.cardsDir, fileName);
-  if (fs.existsSync(filePath)) {
-    fail(`같은 제목 카드가 이미 있다: ${filePath} — 제목이 곧 식별자다(3.5). 다른 제목을 쓰거나 supersede로 대체하라.`);
+// 각 명령의 사용법 문자열 — fail(인자 오류)과 bin의 --help 가드가 같은 문자열을
+// 쓴다(2026-09-11·12 사고: `pick --help`를 확인하려다 실제로 카드를 집었다). 두
+// 군데로 갈라지면 어느 한쪽만 갱신돼 거짓 사용법을 가르치게 된다.
+const USAGE = {
+  'card new': '사용법: llm-wiki card new "<제목>" [--goal …] [--ac …] [--depends a,b] [--not-before YYYY-MM-DD] [--kind milestone] [--milestone "<마일스톤 제목>"]',
+  'card show': '사용법: llm-wiki card show <제목>',
+  'card edit': '사용법: llm-wiki card edit <제목> [--goal …] [--plan …] [--ac …] [--add-ac …] [--check-ac 1,2] [--note …] [--renew-claim] [--depends a,b] [--add-depends a,b] [--remove-depends a,b] [--milestone "<마일스톤 제목>"]',
+  card: '사용법: llm-wiki card <new|show|edit> …',
+  handoff: '사용법: llm-wiki handoff <제목> --question "…"',
+  done: '사용법: llm-wiki done <제목> --result "…" — Result 없는 완료는 거부한다.',
+  supersede: '사용법: llm-wiki supersede <제목> --by 자식1,자식2',
+  abandon: '사용법: llm-wiki abandon <제목> --reason "…" — 폐기 사유가 안티패턴의 원재료다.',
+  reopen: '사용법: llm-wiki reopen <제목> --why "…" — 되돌림 사유가 기록되지 않으면 QA가 아니다.',
+  resume: '사용법: llm-wiki resume <제목> [--note "…"]',
+  board: '사용법: llm-wiki board — 텍스트 유도 뷰(플래그 없음). 하위: board report [--json] 대시보드 · board video 타임랩스',
+  monitor: '사용법: llm-wiki monitor [--port <번호>] — 읽기 전용 실시간 보드 뷰어(127.0.0.1, 기본 4747)',
+  pick: '사용법: llm-wiki pick [--claim <이름>] [--card "<제목>"] — --card 없으면 ordinal 최저를 집는다',
+};
+
+// 카드를 집거나 끝내는 명령의 플래그 명세 — card new/edit과 같은 규칙으로
+// validateFlags를 태운다(2026-09-12 사고: 없는 pick --card 플래그가 검증 없이
+// 위임 프롬프트에 들어가 무시됐고 다른 카드가 집혔다). spec은 지금 코드가 실제로
+// 읽는 플래그만 담는다 — 임의 플래그 추가가 아니라 오타·조용한 no-op 차단이 목적.
+const PICK_FLAGS = { claim: 'string', card: 'string' };
+const HANDOFF_FLAGS = { question: 'string' };
+const DONE_FLAGS = { result: 'string' };
+const SUPERSEDE_FLAGS = { by: 'string' };
+const ABANDON_FLAGS = { reason: 'string', 'no-raw-log': 'flag' };
+const REOPEN_FLAGS = { why: 'string', reason: 'string' };
+const RESUME_FLAGS = { note: 'string' };
+
+// ── milestone 검증 (card new/edit 공용) ───────────────────────────────────
+// 소속 대상은 존재하고 kind: milestone이어야 하며, 마일스톤 카드 자신은 다른
+// 마일스톤에 속할 수 없다(평면 — plan.md 3.8). 검증은 쓰기 전에 — 의존성과 같은
+// 규칙(끊어진 소속은 회고 뷰를 영구히 비뚜러뜨린다).
+function validateMilestoneTarget(paths, milestoneTitle, selfKind) {
+  const target = kanban.findCard(paths, milestoneTitle);
+  if (!target) {
+    fail(`마일스톤 카드가 없다: ${milestoneTitle} — \`card new "${milestoneTitle}" --kind milestone\` 로 먼저 만들어라.`);
+  }
+  if (target.meta.kind !== 'milestone') {
+    fail(`마일스톤 대상이 마일스톤 카드가 아니다: ${milestoneTitle} — 일반 카드에는 소속을 걸 수 없다.`);
   }
+  if (selfKind === 'milestone') {
+    fail(`마일스톤 카드는 다른 마일스톤에 속할 수 없다(평면 — plan.md 3.8): ${milestoneTitle}`);
+  }
+}
 
-  // ordinal: float, 스텝 1000, 컬럼(todo) 내 순서 (Backlog.md 방식).
-  const ordinals = kanban.listCardsInDir(paths.cardsDir).map(c => Number(c.meta.ordinal) || 0);
-  const ordinal = ordinals.length ? Math.max(...ordinals) + 1000 : 1000;
+function cardNew(paths, config, { positional, flags }) {
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const title = positional[0];
+    if (!title) fail(USAGE['card new']);
+    validateFlags(flags, CARD_NEW_FLAGS);
+
+    const fileName = `${kanban.slugify(title)}.md`;
+    const filePath = path.join(paths.cardsDir, fileName);
+    if (fs.existsSync(filePath)) {
+      fail(`같은 제목 카드가 이미 있다: ${filePath} — 제목이 곧 식별자다(3.5). 다른 제목을 쓰거나 supersede로 대체하라.`);
+    }
+    // cards/뿐 아니라 종결 3폴더까지 검사 — 예전엔 cards/만 보아 같은 제목 재생성을
+    // 허용했고, 그 카드의 종결이 아카이브 원본을 덮어썼다(2026-09-09 리뷰 5-1-3).
+    const existingAnywhere = kanban.findCard(paths, title);
+    if (existingAnywhere) {
+      fail(`같은 제목 카드가 이미 있다: ${existingAnywhere.filePath} — 제목이 곧 식별자다(3.5). 종결 기록과 충돌하므로 다른 제목을 쓰거나 기존 카드를 reopen/resume하라.`);
+    }
+    // 슬러그 충돌도 같은 파일명이 된다 — slugify가 '/', ':' 등을 같은 '-'로 접으므로
+    // 'a/b'와 'a:b'는 같은 파일에 쓴다. 두 번째 생성이 첫 카드를 조용히 덮어쓰는
+    // 일을 만들지 않는다(2026-09-09 리뷰 5-2).
+    const slugClash = ['cardsDir', 'doneDir', 'supersededDir', 'abandonedDir']
+      .map(k => paths[k])
+      .filter(dir => fs.existsSync(dir))
+      .some(dir => fs.readdirSync(dir).includes(fileName));
+    if (slugClash) {
+      fail(`같은 파일명(${fileName})이 이미 있다 — 제목이 달라도 슬러그가 같으면 한 파일을 공유해 덮어쓴다. 제목을 달리하라.`);
+    }
 
-  const dependsOn = asArray(flags.depends).flatMap(s => String(s).split(',')).map(s => s.trim()).filter(Boolean);
-  const acTexts = asArray(flags.ac);
+    // ordinal: float, 스텝 1000, 컬럼(todo) 내 순서 (Backlog.md 방식).
+    const ordinals = kanban.listCardsInDir(paths.cardsDir).map(c => Number(c.meta.ordinal) || 0);
+    const ordinal = ordinals.length ? Math.max(...ordinals) + 1000 : 1000;
 
-  const meta = {
-    title,
-    status: 'todo',
-    ordinal,
-    created: new Date().toISOString().split('T')[0],
-  };
-  if (dependsOn.length) meta.depends_on = dependsOn;
-  // 시간 게이트 — 이 날짜 전에는 pick이 집지 않는다 (조건만족시 진행, plan.md 9번 원칙의 기계적 절반).
-  if (flags['not-before']) meta.not_before = String(flags['not-before']);
-
-  const parsed = {
-    goal: flags.goal ? String(flags.goal) : '',
-    ac: acTexts.map((text, i) => ({ checked: false, idx: i + 1, text })),
-    sections: new Map([['Plan', ''], ['Notes', ''], ['Handoff', ''], ['Result', '']]),
-  };
+    const dependsOn = csvList(flags.depends);
+    // 의존성 검증은 파일을 쓰기 전에 — 결함 B의 쓰기 규칙을 card new에도 같이
+    // 적용한다(어디는 엄격하고 어디는 관대하면 규칙을 못 배운다).
+    if (dependsOn.length) validateDepTargets(paths, title, dependsOn);
+    const acTexts = stringArray(flags.ac);
 
-  fs.writeFileSync(filePath, kanban.serializeCard(meta, parsed));
-  kanban.appendActivity(paths, { action: 'created', title });
-  console.log(`Card created: ${filePath}`);
-  console.log(`  ordinal: ${ordinal}${dependsOn.length ? `, depends_on: ${dependsOn.join(', ')}` : ''}`);
+    // kind — 현재 유일한 값은 'milestone'. 일반 카드는 kind를 아예 안 적는다:
+    // 기본값 필드는 전 카드에 누적되는 잡음이다.
+    if (flags.kind !== undefined && flags.kind !== 'milestone') {
+      fail(`--kind 값이 잘못됐다: ${flags.kind} — 쓸 수 있는 값: milestone`);
+    }
+    // 소속 검증도 쓰기 전에(같은 규칙) — 대상·평면 위반은 여기서 막힌다.
+    const milestoneTitle = flagString(flags.milestone);
+    if (milestoneTitle) validateMilestoneTarget(paths, milestoneTitle, flags.kind);
+
+    const meta = {
+      title,
+      status: 'todo',
+      ordinal,
+      created: localToday(),
+    };
+    if (flags.kind === 'milestone') meta.kind = 'milestone';
+    if (dependsOn.length) meta.depends_on = dependsOn;
+    // 시간 게이트 — 이 날짜 전에는 pick이 집지 않는다 (조건만족시 진행, plan.md 9번 원칙의 기계적 절반).
+    if (typeof flags['not-before'] === 'string') meta.not_before = flags['not-before'];
+    // 계획 단위 소속 (plan.md 3.8) — 마일스톤의 진행 상태는 전부 유도된다.
+    if (milestoneTitle) meta.milestone = milestoneTitle;
+
+    const parsed = {
+      goal: flagString(flags.goal) || '',
+      ac: acTexts.map((text, i) => ({ checked: false, idx: i + 1, text: String(text) })),
+      sections: new Map([['Plan', ''], ['Notes', ''], ['Handoff', ''], ['Result', '']]),
+    };
+
+    fs.writeFileSync(filePath, kanban.serializeCard(meta, parsed));
+    kanban.appendActivity(paths, { action: 'created', title });
+    console.log(`Card created: ${filePath}`);
+    console.log(`  ordinal: ${ordinal}${flags.kind === 'milestone' ? ', kind: milestone' : ''}${dependsOn.length ? `, depends_on: ${dependsOn.join(', ')}` : ''}${milestoneTitle ? `, milestone: ${milestoneTitle}` : ''}`);
+  });
 }
 
 function cardShow(paths, { positional }) {
   const title = positional[0];
-  if (!title) fail('사용법: llm-wiki card show <제목>');
+  if (!title) fail(USAGE['card show']);
   const cardObj = kanban.findCard(paths, title);
   if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
   console.log(fs.readFileSync(cardObj.filePath, 'utf8'));
 }
 
 function cardEdit(paths, { positional, flags }) {
-  const title = positional[0];
-  if (!title) {
-    fail('사용법: llm-wiki card edit <제목> [--goal …] [--ac …] [--add-ac …] [--check-ac 1,2] [--note …] [--plan …]');
-  }
-  const cardObj = kanban.findCard(paths, title);
-  if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const title = positional[0];
+    if (!title) {
+      fail(USAGE['card edit']);
+    }
+    // 검증은 파일을 건드리기 전에 — 모르는 플래그(오타)·값 없는 플래그·바꿀 것 없는
+    // 호출은 전부 조용한 no-op이 성공으로 보고되던 길이다(결함 A).
+    validateFlags(flags, CARD_EDIT_FLAGS);
+    if (!Object.keys(CARD_EDIT_FLAGS).some(k => flags[k] !== undefined)) {
+      fail('바꿀 것이 지정되지 않았다 — 최소한 하나의 플래그가 필요하다.');
+    }
+    const cardObj = kanban.findCard(paths, title);
+    if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
 
-  const meta = { ...cardObj.meta };
-  const parsed = { goal: cardObj.card.goal, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+    const meta = { ...cardObj.meta };
+    const parsed = { goal: cardObj.card.goal, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+    const changes = [];
 
-  if (flags.goal !== undefined) parsed.goal = String(flags.goal);
-  if (flags.plan !== undefined) parsed.sections.set('Plan', String(flags.plan));
+    if (typeof flags.goal === 'string') { parsed.goal = flags.goal; changes.push('goal'); }
+    if (typeof flags.plan === 'string') { parsed.sections.set('Plan', flags.plan); changes.push('plan'); }
 
-  // --ac는 목록 전체 교체, --add-ac는 뒤에 붙이기(번호는 최대+1 — 재정렬 후에도 #N 안정).
-  const replaceAc = asArray(flags.ac);
-  if (replaceAc.length) {
-    parsed.ac = replaceAc.map((text, i) => ({ checked: false, idx: i + 1, text: String(text) }));
-  }
-  const addAc = asArray(flags['add-ac']);
-  let nextIdx = parsed.ac.reduce((m, a) => Math.max(m, a.idx), 0) + 1;
-  for (const text of addAc) parsed.ac.push({ checked: false, idx: nextIdx++, text: String(text) });
+    // --ac는 목록 전체 교체, --add-ac는 뒤에 붙이기(번호는 최대+1 — 재정렬 후에도 #N 안정).
+    const replaceAc = stringArray(flags.ac);
+    if (replaceAc.length) {
+      parsed.ac = replaceAc.map((text, i) => ({ checked: false, idx: i + 1, text: String(text) }));
+      changes.push(`ac=${replaceAc.length}`);
+    }
+    const addAc = stringArray(flags['add-ac']);
+    if (addAc.length) {
+      let nextIdx = parsed.ac.reduce((m, a) => Math.max(m, a.idx), 0) + 1;
+      for (const text of addAc) parsed.ac.push({ checked: false, idx: nextIdx++, text: String(text) });
+      changes.push(`ac +${addAc.length}`);
+    }
 
-  // --check-ac 1,2 — AC는 객관적 증거로만 체크하라는 건 에이전트의 규율(루프 스킬)이고
-  // CLI는 번호의 안정성(#N)만 보장한다.
-  if (flags['check-ac'] !== undefined) {
-    const idxs = String(flags['check-ac']).split(',').map(s => Number(s.trim()));
-    for (const idx of idxs) {
-      const ac = parsed.ac.find(a => a.idx === idx);
-      if (!ac) fail(`AC #${idx} 가 없다 — 번호는 재정렬해도 유지된다.`);
-      ac.checked = true;
+    // --check-ac 1,2 — AC는 객관적 증거로만 체크하라는 건 에이전트의 규율(루프 스킬)이고
+    // CLI는 번호의 안전성(#N)만 보장한다.
+    if (flags['check-ac'] !== undefined) {
+      const idxs = asArray(flags['check-ac']).map(String).join(',').split(',').map(s => Number(s.trim()));
+      for (const idx of idxs) {
+        if (!Number.isInteger(idx) || idx < 1) fail(`--check-ac 는 AC 번호(쉼표 구분)를 받는다 — 받은 값: ${String(flags['check-ac'])}`);
+        const ac = parsed.ac.find(a => a.idx === idx);
+        if (!ac) fail(`AC #${idx} 가 없다 — 번호는 재정렬해도 유지된다.`);
+        ac.checked = true;
+      }
+      changes.push(`check-ac #${idxs.join(', #')}`);
     }
-  }
 
-  // Notes는 append-only 저널 — 타임스탬프와 함께 덧붙인다.
-  const notes = asArray(flags.note);
-  if (notes.length) {
-    const existing = parsed.sections.get('Notes') || '';
-    const stamped = notes.map(n => `- ${nowIso()} — ${n}`).join('\n');
-    parsed.sections.set('Notes', existing ? `${existing}\n${stamped}` : stamped);
-  }
+    // Notes는 append-only 저널 — 타임스탬프와 함께 덧붙인다.
+    const notes = stringArray(flags.note);
+    if (notes.length) {
+      const existing = parsed.sections.get('Notes') || '';
+      const stamped = notes.map(n => `- ${nowIso()} — ${n}`).join('\n');
+      parsed.sections.set('Notes', existing ? `${existing}\n${stamped}` : stamped);
+      changes.push(`note +${notes.length}`);
+    }
 
-  // --renew-claim — 긴 카드는 타임아웃 전에 클레임을 갱신한다 (루프 스킬 규칙 6).
-  // 클레임은 만료 있는 협동 락이므로, 살아있는 작업자는 주기적으로 시각을 다시 심는다.
-  if (flags['renew-claim']) {
-    if (!meta.claimed_by) fail(`클레임이 없는 카드다: ${title} — renew가 아니라 pick으로 집어라.`);
-    meta.claimed_at = nowIso();
-  }
+    // depends_on 편집 — --depends 전체 교체 → --add-depends 합집합 → --remove-depends
+    // 차집합 순서(ac 계열 어법). 종결 카드의 의존성은 pick이 읽지 않는 이력이다.
+    const replaceDeps = csvList(flags.depends);
+    const addDeps = csvList(flags['add-depends']);
+    const removeDeps = csvList(flags['remove-depends']);
+    if (replaceDeps.length || addDeps.length || removeDeps.length) {
+      if (!kanban.ACTIVE_STATUSES.includes(cardObj.meta.status)) {
+        fail(`종결 카드(${cardObj.meta.status})의 의존성은 바꾸지 않는다 — pick이 이미 기다리지 않는 이력이다: ${cardObj.filePath}`);
+      }
+      const before = Array.isArray(meta.depends_on) ? [...new Set(meta.depends_on)] : [];
+      let next = replaceDeps.length ? [...new Set(replaceDeps)] : [...before];
+      for (const d of [...new Set(addDeps)]) {
+        if (!next.includes(d)) next.push(d);
+      }
+      // 제거 대상이 목록에 없으면 오타일 확률이 높다 — 조용히 성공하면 "걸었다"고
+      // 믿은 채 진행된다(check-ac가 없는 번호를 거부하는 것과 같은 규칙).
+      const absent = removeDeps.filter(d => !next.includes(d));
+      if (absent.length) {
+        fail(`제거할 의존성이 이 카드에 없다: ${absent.join(', ')} — 현재 depends_on: [${next.join(', ') || '없음'}]`);
+      }
+      next = next.filter(d => !removeDeps.includes(d));
+      // 검증은 새로 들어온 간선에만 — 이미 있던 의존성의 제거(레거시 정리)는
+      // 대상 카드가 살아있어야 하는 게 아니다.
+      const introduced = next.filter(d => !before.includes(d));
+      validateDepTargets(paths, title, introduced);
+      const removed = before.filter(d => !next.includes(d));
+      if (introduced.length) changes.push(`depends +${introduced.join(', ')}`);
+      if (removed.length) changes.push(`depends -${removed.join(', ')}`);
+      if (next.length) meta.depends_on = next;
+      else delete meta.depends_on;
+    }
+
+    // --milestone 재지정 — 소속은 활성 카드에만 건다. 종결 카드의 소속은 회고
+    // 뷰(마일스톤 패널·완료율)가 읽는 이력이라 소급 재편하지 않는다(plan.md 3.8).
+    const milestoneTitle = flagString(flags.milestone);
+    if (milestoneTitle) {
+      if (!kanban.ACTIVE_STATUSES.includes(cardObj.meta.status)) {
+        fail(`종결 카드(${cardObj.meta.status})의 마일스톤은 바꾸지 않는다 — 회고 뷰가 읽는 이력이다: ${cardObj.filePath}`);
+      }
+      validateMilestoneTarget(paths, milestoneTitle, cardObj.meta.kind);
+      if (meta.milestone !== milestoneTitle) {
+        meta.milestone = milestoneTitle;
+        changes.push(`milestone=${milestoneTitle}`);
+      }
+    }
+
+    // --renew-claim — 긴 카드는 타임아웃 전에 클레임을 갱신한다 (루프 스킬 규칙 6).
+    // 클레임은 만료 있는 협동 락이므로, 살아있는 작업자는 주기적으로 시각을 다시 심는다.
+    // 락 안에서 만료를 재검증한다 — 만료된 클레임의 갱신은 다른 세션이 이미 재집어
+    // 작업 중인 카드의 시각을 되살려 이중 작업을 만든다. 갱신 거부 → 재집기(pick) 유도.
+    if (flags['renew-claim']) {
+      if (!meta.claimed_by) fail(`클레임이 없는 카드다: ${title} — renew가 아니라 pick으로 집어라.`);
+      const config = kanban.loadConfig(paths);
+      if (kanban.isClaimExpired({ meta }, config)) {
+        fail(`클레임이 만료됐다 (${meta.claimed_at}) — 다른 세션이 재집었을 수 있다. pick으로 다시 집어라.`);
+      }
+      meta.claimed_at = nowIso();
+      changes.push('renew-claim');
+    }
 
-  kanban.writeCard(cardObj, meta, parsed);
-  console.log(`Card edited: ${cardObj.filePath}`);
+    // 성공 문구는 실제로 무엇이 바뀌었는지 말한다. 플래그는 있었지만 결과가 동일하면
+    // (멱등 재시도) 성공을 주장하지 않고 파일도 다시 쓰지 않는다.
+    if (!changes.length) {
+      console.log(`변경 없음 — 이미 그 상태다: ${cardObj.filePath}`);
+      return;
+    }
+    kanban.writeCard(cardObj, meta, parsed);
+    console.log(`Card edited: ${cardObj.filePath} (${changes.join(', ')})`);
+  });
 }
 
 // QA 루프의 되돌림 원시형 (개선계획 4-3) — 증거 빈약한 완료를 doing으로 역류시킨다.
@@ -188,40 +449,101 @@ function reopen(options = {}) {
   const { paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  const why = flags.why || flags.reason;
-  if (!title || !why) fail('사용법: llm-wiki reopen <제목> --why "…" — 되돌림 사유가 기록되지 않으면 QA가 아니다.');
-
-  const cardObj = kanban.findCard(paths, title);
-  if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
-  if (cardObj.meta.status !== 'done') fail(`done 카드만 되돌린다 (현재: ${cardObj.meta.status}): ${cardObj.filePath}`);
-
-  const content = fs.readFileSync(cardObj.filePath, 'utf8');
-  const meta = kanban.parseFrontmatter(content);
-  const parsed = kanban.parseBody(content);
-  meta.status = 'doing';
-  delete meta.claimed_by;
-  delete meta.claimed_at;
-  const notes = parsed.sections.get('Notes') || '';
-  const line = `- ${nowIso()} — REVERTED: ${why}`;
-  parsed.sections.set('Notes', notes ? `${notes}\n${line}` : line);
-
-  fs.writeFileSync(path.join(paths.cardsDir, cardObj.fileName), kanban.serializeCard(meta, parsed));
-  fs.unlinkSync(cardObj.filePath);
-  kanban.appendActivity(paths, { action: 'reverted', title: meta.title, detail: String(why) });
-  console.log(`Reverted to doing: ${path.join(paths.cardsDir, cardObj.fileName)}`);
+  const why = flagString(flags.why) || flagString(flags.reason);
+  if (!title || !why) fail(USAGE.reopen);
+  validateFlags(flags, REOPEN_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const cardObj = kanban.findCard(paths, title);
+    if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
+    if (cardObj.meta.status !== 'done') fail(`done 카드만 되돌린다 (현재: ${cardObj.meta.status}): ${cardObj.filePath}`);
+
+    const content = fs.readFileSync(cardObj.filePath, 'utf8');
+    const meta = kanban.parseFrontmatter(content);
+    const parsed = kanban.parseBody(content);
+    meta.status = 'doing';
+    delete meta.claimed_by;
+    delete meta.claimed_at;
+    const notes = parsed.sections.get('Notes') || '';
+    const line = `- ${nowIso()} — REVERTED: ${why}`;
+    parsed.sections.set('Notes', notes ? `${notes}\n${line}` : line);
+
+    fs.writeFileSync(path.join(paths.cardsDir, cardObj.fileName), kanban.serializeCard(meta, parsed));
+    fs.unlinkSync(cardObj.filePath);
+    kanban.appendActivity(paths, { action: 'reverted', title: meta.title, detail: String(why) });
+    console.log(`Reverted to doing: ${path.join(paths.cardsDir, cardObj.fileName)}`);
+
+    // 마일스톤 역동기화 — 멤버가 되돌아왔는데 마일스톤이 이미 종결돼 있으면 같이
+    // 되돌린다. 자동 종결의 역방향: 안 하면 종결된 계획 아래 살아있는 멤버라는
+    // 썩은 상태(3.7 원칙 1)가 된다.
+    if (meta.milestone) {
+      const ms = kanban.findCard(paths, meta.milestone);
+      if (ms && ms.meta.kind === 'milestone' && kanban.TERMINAL_FOLDERS.includes(ms.meta.status)) {
+        const msMeta = kanban.parseFrontmatter(fs.readFileSync(ms.filePath, 'utf8'));
+        const msParsed = kanban.parseBody(fs.readFileSync(ms.filePath, 'utf8'));
+        msMeta.status = 'todo';
+        delete msMeta.claimed_by;
+        delete msMeta.claimed_at;
+        const msNotes = msParsed.sections.get('Notes') || '';
+        const msLine = `- ${nowIso()} — REVERTED: 멤버 '${meta.title}'의 reopen으로 마일스톤도 복귀`;
+        msParsed.sections.set('Notes', msNotes ? `${msNotes}\n${msLine}` : msLine);
+        fs.writeFileSync(path.join(paths.cardsDir, ms.fileName), kanban.serializeCard(msMeta, msParsed));
+        fs.unlinkSync(ms.filePath);
+        kanban.appendActivity(paths, { action: 'milestone-reverted', title: ms.meta.title, detail: `멤버 ${meta.title} reopen` });
+        console.log(`Milestone reverted to todo: ${path.join(paths.cardsDir, ms.fileName)}`);
+      }
+    }
+  });
 }
 
 // ── pick — 원자적 집기 ───────────────────────────────────────────────────
 
 // 준비 필터(미클레임/만료/의존 충족/WIP 여유) → ordinal 정렬 → 클레임 → doing.
 // 전 과정을 락 안에서 — 동시 pick 빈틈을 처음부터 막고 출발한다 (kanban-md 교훈).
+
+// 지정 집기(--card)의 게이트 판정 — 통상 pick의 후보 판정과 같은 규칙(review →
+// not_before → 클레임 → todo 의존)을 지정 카드 한 장에 적용한다. --card는 우선권이
+// 아니라 지정이다: 하나라도 걸리면 집지 않고 이 사유를 낸다. 통과면 null.
+function pickGateBlock(cardObj, resolvedTitles, config) {
+  const status = cardObj.meta.status;
+  if (kanban.TERMINAL_FOLDERS.includes(status)) {
+    return `이미 종결됐다 (${status}): ${cardObj.filePath}`;
+  }
+  if (!kanban.ACTIVE_STATUSES.includes(status)) {
+    return `활성 카드가 아니다 (status: ${status || '없음'}): ${cardObj.filePath}`;
+  }
+  if (status === 'review') {
+    return '사람 판정 대기(review)다 — resume으로 todo에 복귀시킨 뒤 집어라';
+  }
+  if (cardObj.meta.kind === 'milestone') {
+    return '마일스톤 카드다 — 작업 항목이 아니라 목적 축이다. 소속 카드를 집어라 (plan.md 3.8)';
+  }
+  if (cardObj.meta.not_before && String(cardObj.meta.not_before) > localToday()) {
+    return `시작 예정: ${cardObj.meta.not_before} 이후 (not_before)`;
+  }
+  if (cardObj.meta.claimed_by && !kanban.isClaimExpired(cardObj, config)) {
+    return `클레임 중: ${cardObj.meta.claimed_by}`;
+  }
+  if (status === 'todo') {
+    const deps = Array.isArray(cardObj.meta.depends_on) ? cardObj.meta.depends_on : [];
+    const unmet = deps.filter(dep => !resolvedTitles.has(dep));
+    if (unmet.length) return `의존 미충족: ${unmet.join(', ')}`;
+  }
+  return null;
+}
+
 function pick(options = {}) {
   const { paths, config } = requireBoard();
   const { flags } = parseArgs(options.rest || []);
-  const claimName = flags.claim ? String(flags.claim) : 'unnamed-agent';
-
-  const result = kanban.withLock(paths, 'pick', () => {
-    const active = kanban.listCardsInDir(paths.cardsDir);
+  validateFlags(flags, PICK_FLAGS);
+  const claimName = typeof flags.claim === 'string' && flags.claim ? flags.claim : 'unnamed-agent';
+  const wantTitle = flagString(flags.card) || null;
+
+  const result = kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    // cards/의 모든 .md가 카드는 아니다(README 등) — 활성 status가 없는 파일은
+    // 후보에서 제외한다. 예전엔 이를 집어 재직렬화하며 `## ` 앞 본문을 지웠다(5-1-4).
+    const active = kanban.listCardsInDir(paths.cardsDir)
+      .filter(c => kanban.ACTIVE_STATUSES.includes(c.meta.status));
     const doing = active.filter(c => c.meta.status === 'doing');
     const wipLimit = config.wipLimits.doing !== undefined ? config.wipLimits.doing : Infinity;
 
@@ -237,31 +559,49 @@ function pick(options = {}) {
 
     const blocked = [];
     const candidates = [];
-    const today = new Date().toISOString().split('T')[0];
-    for (const cardObj of active) {
-      const status = cardObj.meta.status;
-      // review는 사람 판정 대기 — pick이 집지 않는다.
-      if (status === 'review') continue;
-
-      // 시간 게이트 — not_before가 미래면 아직 시작하지 않는 카드다.
-      if (cardObj.meta.not_before && String(cardObj.meta.not_before) > today) {
-        blocked.push({ title: cardObj.meta.title, notBefore: cardObj.meta.not_before });
-        continue;
-      }
-
-      // 클레임이 살아있는 doing은 남의 작업. 만료됐으면 재집기 후보 — 밤에 죽은
-      // 세션의 카드를 자동 회수하는 것이 협동 락의 존재 이유다.
-      if (cardObj.meta.claimed_by && !kanban.isClaimExpired(cardObj, config)) {
-        blocked.push({ title: cardObj.meta.title, claimedBy: cardObj.meta.claimed_by });
-        continue;
+    if (wantTitle) {
+      // 지정 집기 — 매칭은 findCard 규칙 그대로(제목이 곧 식별자, 3.5). 없는 제목은
+      // 인자 오류로 실패하고, 게이트에 막히면 이유를 내고 파일을 그대로 둔다.
+      const target = kanban.findCard(paths, wantTitle);
+      if (!target) {
+        fail(`--card 대상 카드를 못 찾았다: ${wantTitle} — board로 제목을 확인하라.`);
       }
-
-      if (status === 'todo') {
-        const deps = Array.isArray(cardObj.meta.depends_on) ? cardObj.meta.depends_on : [];
-        const unmet = deps.filter(dep => !resolvedTitles.has(dep));
-        if (unmet.length) { blocked.push({ title: cardObj.meta.title, unmet }); continue; }
+      const why = pickGateBlock(target, resolvedTitles, config);
+      if (why) return { picked: null, reason: 'blocked', detail: `${target.meta.title} — ${why}` };
+      candidates.push(target);
+    } else {
+      const today = localToday(); // not_before 게이트 — 현지 날짜(5-1-5)
+      for (const cardObj of active) {
+        const status = cardObj.meta.status;
+        // 마일스톤 카드는 작업 대상이 아니다(3.8) — 집을 게 없을 때 이유로는
+        // 보고한다(사람이 보는 No pickable 상세).
+        if (cardObj.meta.kind === 'milestone') {
+          blocked.push({ title: cardObj.meta.title, isMilestone: true });
+          continue;
+        }
+        // review는 사람 판정 대기 — pick이 집지 않는다.
+        if (status === 'review') continue;
+
+        // 시간 게이트 — not_before가 미래면 아직 시작하지 않는 카드다.
+        if (cardObj.meta.not_before && String(cardObj.meta.not_before) > today) {
+          blocked.push({ title: cardObj.meta.title, notBefore: cardObj.meta.not_before });
+          continue;
+        }
+
+        // 클레임이 살아있는 doing은 남의 작업. 만료됐으면 재집기 후보 — 밤에 죽은
+        // 세션의 카드를 자동 회수하는 것이 협동 락의 존재 이유다.
+        if (cardObj.meta.claimed_by && !kanban.isClaimExpired(cardObj, config)) {
+          blocked.push({ title: cardObj.meta.title, claimedBy: cardObj.meta.claimed_by });
+          continue;
+        }
+
+        if (status === 'todo') {
+          const deps = Array.isArray(cardObj.meta.depends_on) ? cardObj.meta.depends_on : [];
+          const unmet = deps.filter(dep => !resolvedTitles.has(dep));
+          if (unmet.length) { blocked.push({ title: cardObj.meta.title, unmet }); continue; }
+        }
+        candidates.push(cardObj);
       }
-      candidates.push(cardObj);
     }
 
     candidates.sort((a, b) => (Number(a.meta.ordinal) || 0) - (Number(b.meta.ordinal) || 0));
@@ -290,6 +630,7 @@ function pick(options = {}) {
       if (b.notBefore) console.log(`  - ${b.title} — 시작 예정: ${b.notBefore} 이후 (not_before)`);
       else if (b.unmet && b.unmet.length) console.log(`  - ${b.title} — 의존 미충족: ${b.unmet.join(', ')}`);
       else if (b.claimedBy) console.log(`  - ${b.title} — 클레임 중: ${b.claimedBy}`);
+      else if (b.isMilestone) console.log(`  - ${b.title} — 마일스톤 카드(집기 대상 아님, plan.md 3.8)`);
     }
     } else if (result.detail) {
       console.log(`  ${result.detail}`);
@@ -316,52 +657,96 @@ function handoff(options = {}) {
   const { paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  const question = flags.question;
-  if (!title || !question) fail('사용법: llm-wiki handoff <제목> --question "…"');
-
-  const cardObj = requireActiveCard(paths, title);
-  const meta = { ...cardObj.meta };
-  const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+  const question = flagString(flags.question);
+  if (!title || !question) fail(USAGE.handoff);
+  validateFlags(flags, HANDOFF_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const cardObj = requireActiveCard(paths, title);
+    const meta = { ...cardObj.meta };
+    const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+
+    meta.status = 'review';
+    delete meta.claimed_by;   // 클레임 반납 — park하고 다음 카드로
+    delete meta.claimed_at;
+
+    const existing = parsed.sections.get('Handoff') || '';
+    const line = `- ${nowIso()} — QUESTION: ${question}`;
+    parsed.sections.set('Handoff', existing ? `${existing}\n${line}` : line);
+
+    kanban.writeCard(cardObj, meta, parsed);
+    kanban.appendActivity(paths, { action: 'handoff', title: meta.title, detail: String(question) });
+    console.log(`Handed off (parked for human judgment): ${cardObj.filePath}`);
+  });
+}
 
-  meta.status = 'review';
-  delete meta.claimed_by;   // 클레임 반납 — park하고 다음 카드로
+// ── 마일스톤 자동 종결 (done·supersede·abandon이 멤버 종결 뒤에 부른다) ────
+// 마지막 멤버가 종결되는 순간 마일스톤도 종결한다 — 상태를 저장하면 반드시
+// 어느 밤엔 잊히고 썩는다(3.7 원칙 1), 종결 사건이 일어나는 쓰기 안에서
+// 동기화한다. review 대기 중이면 판정을 덮지 않고 보고만. 반드시 락 안에서.
+function completeMilestoneIfAllTerminal(paths, milestoneTitle) {
+  const ms = kanban.findCard(paths, milestoneTitle);
+  if (!ms || ms.meta.kind !== 'milestone') {
+    console.log(`  ⚠ 마일스톤 카드를 못 찾았다 — 소속 참조가 끊어졌다: ${milestoneTitle}`);
+    return;
+  }
+  if (kanban.TERMINAL_FOLDERS.includes(ms.meta.status)) return; // 이미 종결된 이력
+  const members = kanban.listAllCards(paths).filter(c => c.meta.milestone === milestoneTitle);
+  if (members.some(c => kanban.ACTIVE_STATUSES.includes(c.meta.status))) return; // 진행 중 멤버 남음
+  if (ms.meta.status === 'review') {
+    console.log(`  마일스톤 전원 종결 — 다만 판정 대기(review) 중이라 자동 종결하지 않는다: ${milestoneTitle} — resume 뒤 다음 종결 사건에 종결된다`);
+    return;
+  }
+  const counts = { done: 0, superseded: 0, abandoned: 0 };
+  for (const m of members) counts[m.meta.status] += 1;
+  const meta = { ...ms.meta };
+  const parsed = { ...ms.card, ac: ms.card.ac.map(a => ({ ...a })), sections: new Map(ms.card.sections) };
+  const result = `- ${nowIso()} — 전원 종결 자동 반영: 멤버 ${members.length}장 (done ${counts.done} · superseded ${counts.superseded} · abandoned ${counts.abandoned})`;
+  const existing = parsed.sections.get('Result') || '';
+  parsed.sections.set('Result', existing ? `${existing}\n${result}` : result);
+  delete meta.claimed_by;
   delete meta.claimed_at;
-
-  const existing = parsed.sections.get('Handoff') || '';
-  const line = `- ${nowIso()} — QUESTION: ${question}`;
-  parsed.sections.set('Handoff', existing ? `${existing}\n${line}` : line);
-
-  kanban.writeCard(cardObj, meta, parsed);
-  kanban.appendActivity(paths, { action: 'handoff', title: meta.title, detail: String(question) });
-  console.log(`Handed off (parked for human judgment): ${cardObj.filePath}`);
+  kanban.writeCard(ms, meta, parsed);
+  kanban.moveCardTo(ms, paths.doneDir, 'done');
+  kanban.appendActivity(paths, { action: 'milestone-done', title: ms.meta.title, detail: `멤버 ${members.length}장 전원 종결` });
+  console.log(`  ◉ milestone 완료: '${ms.meta.title}' — 전원 종결 (${members.length}/${members.length}: done ${counts.done} · superseded ${counts.superseded} · abandoned ${counts.abandoned})`);
 }
 
 function doneCard(options = {}) {
   const { paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  const result = flags.result;
-  if (!title || !result) fail('사용법: llm-wiki done <제목> --result "…" — Result 없는 완료는 거부한다.');
-
-  const cardObj = requireActiveCard(paths, title);
-  const meta = { ...cardObj.meta };
-  const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
-
-  const unchecked = parsed.ac.filter(a => !a.checked);
-  if (unchecked.length) {
-    console.error(`⚠ AC ${unchecked.map(a => `#${a.idx}`).join(', ')} 가 체크 안 됐다 — 증거로 체크했는지 스스로 검증하라 (QA 루프가 되돌릴 수 있다).`);
-  }
+  const result = flagString(flags.result);
+  if (!title || !result) fail(USAGE.done);
+  validateFlags(flags, DONE_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const cardObj = requireActiveCard(paths, title);
+    const meta = { ...cardObj.meta };
+    const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+
+    const unchecked = parsed.ac.filter(a => !a.checked);
+    if (unchecked.length) {
+      console.error(`⚠ AC ${unchecked.map(a => `#${a.idx}`).join(', ')} 가 체크 안 됐다 — 증거로 체크했는지 스스로 검증하라 (QA 루프가 되돌릴 수 있다).`);
+    }
 
-  const existing = parsed.sections.get('Result') || '';
-  const line = `- ${nowIso()} — ${result}`;
-  parsed.sections.set('Result', existing ? `${existing}\n${line}` : line);
+    const existing = parsed.sections.get('Result') || '';
+    const line = `- ${nowIso()} — ${result}`;
+    parsed.sections.set('Result', existing ? `${existing}\n${line}` : line);
 
-  delete meta.claimed_by;
-  delete meta.claimed_at;
-  kanban.writeCard(cardObj, meta, parsed);
-  kanban.moveCardTo(cardObj, paths.doneDir, 'done');
-  kanban.appendActivity(paths, { action: 'done', title: meta.title });
-  console.log(`Done: ${path.join(paths.doneDir, cardObj.fileName)}`);
+    delete meta.claimed_by;
+    delete meta.claimed_at;
+    kanban.writeCard(cardObj, meta, parsed);
+    try {
+      kanban.moveCardTo(cardObj, paths.doneDir, 'done');
+    } catch (e) {
+      fail(e.message); // 카드는 활성으로 남는다 — Result는 이미 반영돼 있다.
+    }
+    kanban.appendActivity(paths, { action: 'done', title: meta.title });
+    console.log(`Done: ${path.join(paths.doneDir, cardObj.fileName)}`);
+    // 마일스톤 소속이 있으면 전원 종결 확인 — 자동 종결은 이 쓰기 안에서(3.8).
+    if (meta.milestone) completeMilestoneIfAllTerminal(paths, meta.milestone);
+  });
 }
 
 // 대체 — 이 카드가 저 카드들이 됨. 부모는 완료가 아니라 소멸(3.1).
@@ -369,24 +754,32 @@ function supersede(options = {}) {
   const { paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  const by = asArray(flags.by).flatMap(s => String(s).split(',')).map(s => s.trim()).filter(Boolean);
-  if (!title || !by.length) fail('사용법: llm-wiki supersede <제목> --by 자식1,자식2');
-
-  const parent = requireActiveCard(paths, title);
-  for (const child of by) {
-    const childCard = kanban.findCard(paths, child);
-    if (!childCard) fail(`자식 카드를 먼저 만들어라 (card new): ${child}`);
-    if (!kanban.ACTIVE_STATUSES.includes(childCard.meta.status)) {
-      fail(`자식 카드가 이미 종결됐다 (${childCard.meta.status}): ${child}`);
+  const by = stringArray(flags.by).flatMap(s => s.split(',')).map(s => s.trim()).filter(Boolean);
+  if (!title || !by.length) fail(USAGE.supersede);
+  validateFlags(flags, SUPERSEDE_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const parent = requireActiveCard(paths, title);
+    for (const child of by) {
+      const childCard = kanban.findCard(paths, child);
+      if (!childCard) fail(`자식 카드를 먼저 만들어라 (card new): ${child}`);
+      if (!kanban.ACTIVE_STATUSES.includes(childCard.meta.status)) {
+        fail(`자식 카드가 이미 종결됐다 (${childCard.meta.status}): ${child}`);
+      }
     }
-  }
 
-  const meta = { ...parent.meta, superseded_by: by };
-  kanban.writeCard(parent, meta);
-  kanban.moveCardTo(parent, paths.supersededDir, 'superseded');
-  kanban.appendActivity(paths, { action: 'superseded', title: parent.meta.title, detail: `by ${by.join(', ')}` });
-  console.log(`Superseded: ${parent.meta.title} → [${by.join(', ')}]`);
-  console.log(`  parent: ${path.join(paths.supersededDir, parent.fileName)}`);
+    const meta = { ...parent.meta, superseded_by: by };
+    kanban.writeCard(parent, meta);
+    try {
+      kanban.moveCardTo(parent, paths.supersededDir, 'superseded');
+    } catch (e) {
+      fail(e.message);
+    }
+    kanban.appendActivity(paths, { action: 'superseded', title: parent.meta.title, detail: `by ${by.join(', ')}` });
+    console.log(`Superseded: ${parent.meta.title} → [${by.join(', ')}]`);
+    console.log(`  parent: ${path.join(paths.supersededDir, parent.fileName)}`);
+    if (parent.meta.milestone) completeMilestoneIfAllTerminal(paths, parent.meta.milestone);
+  });
 }
 
 // 폐기 — 사유가 가장 값비싼 정보다(3.3). 없으면 거부하고, 기록은 지우지 않는다.
@@ -394,26 +787,45 @@ function abandon(options = {}) {
   const { docRoot, paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  const reason = flags.reason;
-  if (!title || !reason) fail('사용법: llm-wiki abandon <제목> --reason "…" — 폐기 사유가 안티패턴의 원재료다.');
-
-  const cardObj = requireActiveCard(paths, title);
-  const meta = { ...cardObj.meta, discard_reason: String(reason) };
-  kanban.writeCard(cardObj, meta);
-  kanban.moveCardTo(cardObj, paths.abandonedDir, 'abandoned');
-  kanban.appendActivity(paths, { action: 'abandoned', title: cardObj.meta.title, detail: String(reason) });
-
-  // 4-2: 폐기 사유를 raw에 자동 기록 (기본 on — --no-raw-log로 끈다).
-  if (!flags['no-raw-log']) {
+  const reason = flagString(flags.reason);
+  if (!title || !reason) fail(USAGE.abandon);
+  validateFlags(flags, ABANDON_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const cardObj = requireActiveCard(paths, title);
+    // 마일스톤 폐기 가드 — 살아있는 멤버가 남은 계획을 조용히 버리지 않는다.
+    // 회고 이력(3.3)을 지키려면 멤버를 먼저 종결하거나, 의도된 계획 접기면
+    // 멤버부터 폐기하라.
+    if (cardObj.meta.kind === 'milestone') {
+      const activeMembers = kanban.listAllCards(paths)
+        .filter(c => c.meta.milestone === cardObj.meta.title && kanban.ACTIVE_STATUSES.includes(c.meta.status));
+      if (activeMembers.length) {
+        fail(`마일스톤에 활성 멤버가 ${activeMembers.length}장 남아 있다: ${activeMembers.map(c => c.meta.title).join(', ')} — 멤버를 먼저 종결하거나 폐기하라.`);
+      }
+    }
+    const meta = { ...cardObj.meta, discard_reason: String(reason) };
+    kanban.writeCard(cardObj, meta);
     try {
-      const rawPath = appendAbandonRaw(docRoot, cardObj.meta.title, String(reason), path.relative(process.cwd(), path.join(paths.abandonedDir, cardObj.fileName)));
-      if (rawPath) console.log(`폐기 사유를 raw에 기록했다 (안티패턴 원재료): ${rawPath}`);
+      kanban.moveCardTo(cardObj, paths.abandonedDir, 'abandoned');
     } catch (e) {
-      console.error(`⚠ raw 기록 실패 (폐기 자체는 완료): ${e.message}`);
+      fail(e.message);
+    }
+    kanban.appendActivity(paths, { action: 'abandoned', title: cardObj.meta.title, detail: String(reason) });
+
+    // 4-2: 폐기 사유를 raw에 자동 기록 (기본 on — --no-raw-log로 끈다).
+    if (!flags['no-raw-log']) {
+      try {
+        const rawPath = appendAbandonRaw(docRoot, cardObj.meta.title, String(reason), path.relative(process.cwd(), path.join(paths.abandonedDir, cardObj.fileName)));
+        if (rawPath) console.log(`폐기 사유를 raw에 기록했다 (안티패턴 원재료): ${rawPath}`);
+      } catch (e) {
+        console.error(`⚠ raw 기록 실패 (폐기 자체는 완료): ${e.message}`);
+      }
     }
-  }
 
-  console.log(`Abandoned: ${path.join(paths.abandonedDir, cardObj.fileName)}`);
+    console.log(`Abandoned: ${path.join(paths.abandonedDir, cardObj.fileName)}`);
+    // 멤버 폐기도 종결 사건이다 — 마일스톤 전원 종결 확인(3.8).
+    if (meta.milestone) completeMilestoneIfAllTerminal(paths, meta.milestone);
+  });
 }
 
 // ── board — 유도 뷰 ──────────────────────────────────────────────────────
@@ -422,10 +834,73 @@ function abandon(options = {}) {
 function collectBoard() {
   const { paths, config } = requireBoard();
   const active = kanban.listCardsInDir(paths.cardsDir);
+  // 마일스톤 카드는 컬럼(작업 축)이 아니라 마일스톤 패널(목적 축)에만 나온다(3.8).
   const byStatus = status => active
-    .filter(c => c.meta.status === status)
+    .filter(c => c.meta.status === status && c.meta.kind !== 'milestone')
     .sort((a, b) => (Number(a.meta.ordinal) || 0) - (Number(b.meta.ordinal) || 0));
 
+  // 소속 멤버는 4폴더 전역에서 유도한다 — 종결 멤버가 회고 뷰를 채운다(3.8).
+  const membersByMilestone = new Map();
+  const addMember = c => {
+    const m = c.meta.milestone;
+    if (!m) return;
+    if (!membersByMilestone.has(m)) membersByMilestone.set(m, []);
+    membersByMilestone.get(m).push({ title: c.meta.title, status: c.meta.status, claimedBy: c.meta.claimed_by || null });
+  };
+  active.forEach(addMember);
+
+  // 종결 3폴더를 한 번만 훑는다 — 개수·최근 목록(모니터 종결 컬럼)·의존 해소
+  // 판정·마일스톤 수집을 같은 패스에서 뽑는다(모니터가 2초 폴링으로 이 뷰를
+  // 계속 요청한다). 최근 항목의 시각은 파일 mtime — 카드가 종결 폴더로 옮겨진
+  // 시각이다.
+  const terminalView = {
+    counts: { done: 0, superseded: 0, abandoned: 0 },
+    recent: [],
+    resolvedTitles: [],
+    milestones: [],
+  };
+  for (const [kind, dir] of [['done', paths.doneDir], ['superseded', paths.supersededDir], ['abandoned', paths.abandonedDir]]) {
+    for (const c of kanban.listCardsInDir(dir)) {
+      terminalView.counts[kind] += 1;
+      if (kind !== 'abandoned') terminalView.resolvedTitles.push(c.meta.title);
+      terminalView.recent.push({ title: c.meta.title, kind, at: fs.statSync(c.filePath).mtime.toISOString(), milestone: c.meta.milestone || null });
+      addMember(c);
+      if (c.meta.kind === 'milestone') terminalView.milestones.push({ card: c, at: fs.statSync(c.filePath).mtime.toISOString() });
+    }
+  }
+
+  // 마일스톤 진행 상태는 전부 유도 — 저장하지 않는다(3.7 원칙 1·2). 활성
+  // 마일스톤(ordinal순) 뒤에 종결 마일스톤(최근순).
+  const msCounts = members => {
+    const counts = { active: 0, done: 0, superseded: 0, abandoned: 0 };
+    for (const m of members) {
+      counts[kanban.ACTIVE_STATUSES.includes(m.status) ? 'active' : m.status] += 1;
+    }
+    return counts;
+  };
+  const msView = (c, completedAt) => {
+    const members = (membersByMilestone.get(c.meta.title) || []);
+    return {
+      title: c.meta.title,
+      status: c.meta.status,
+      goal: c.card.goal || '',
+      ordinal: Number(c.meta.ordinal) || 0,
+      members,
+      counts: msCounts(members),
+      total: members.length,
+      completedAt: completedAt || null,
+    };
+  };
+  const milestones = [
+    ...active
+      .filter(c => c.meta.kind === 'milestone')
+      .sort((a, b) => (Number(a.meta.ordinal) || 0) - (Number(b.meta.ordinal) || 0))
+      .map(c => msView(c, null)),
+    ...terminalView.milestones
+      .sort((a, b) => (a.at < b.at ? 1 : -1))
+      .map(({ card, at }) => msView(card, at)),
+  ];
+
   const view = {
     schemaVersion: 1,
     kind: 'kanban-board',
@@ -436,41 +911,29 @@ function collectBoard() {
       doing: byStatus('doing').map(c => viewCard(c, config)),
       review: byStatus('review').map(c => viewCard(c, config)),
     },
-    terminal: {
-      done: kanban.listCardsInDir(paths.doneDir).length,
-      superseded: kanban.listCardsInDir(paths.supersededDir).length,
-      abandoned: kanban.listCardsInDir(paths.abandonedDir).length,
-    },
-    // 종결 적체 — 완료가 쌓이는 모습이 수렴의 증거다 (HTML 보드용 최근 목록).
-    terminalRecent: [
-      ...kanban.listCardsInDir(paths.doneDir).map(c => ({ title: c.meta.title, kind: 'done', m: fs.statSync(c.filePath).mtimeMs })),
-      ...kanban.listCardsInDir(paths.supersededDir).map(c => ({ title: c.meta.title, kind: 'superseded', m: fs.statSync(c.filePath).mtimeMs })),
-      ...kanban.listCardsInDir(paths.abandonedDir).map(c => ({ title: c.meta.title, kind: 'abandoned', m: fs.statSync(c.filePath).mtimeMs })),
-    ]
-      .sort((a, b) => b.m - a.m)
-      .slice(0, 8)
-      .map(({ title, kind }) => ({ title, kind })),
-    // 의존 충족 판정용 종결 제목들 — 텍스트/HTML 렌더러가 공유한다.
-    resolved: [...kanban.listCardsInDir(paths.doneDir), ...kanban.listCardsInDir(paths.supersededDir)]
-      .map(c => c.meta.title),
+    // 목적 축 — 시간 축(terminal·terminalRecent)과 분리(3.8).
+    milestones,
+    terminal: terminalView.counts,
+    // 의존 충족 판정용 종결 제목들 — done/superseded는 이미 해소(pick 판정과 일치).
+    resolved: terminalView.resolvedTitles,
+    // 모니터 종결 컬럼 — 완료가 쌓이는 모습이 수렴의 증거다(3.2). mtime 내림차순 8건.
+    terminalRecent: terminalView.recent.sort((a, b) => (a.at < b.at ? 1 : -1)).slice(0, 8),
   };
   return { view, paths, config };
 }
 
-function boardView(options = {}) {
-  const { view, paths, config } = collectBoard();
+// board/video는 플래그를 받지 않는다 — 유도 뷰·타임랩스는 인자 없는 명령이다.
+// bin이 --json을 전역 선추출해 dispatch로 넘기므로 여기서 명시적으로 실패하지
+// 않으면 텍스트 보드를 뱉으며 exit 0 — 조용한 no-op 성공이다(2026-09-16 폐지:
+// --html/--json 유도물 경로 제거와 함께 막았다).
+const BOARD_FLAGS = {};
+const VIDEO_FLAGS = {};
 
-  if (options.json) {
-    console.log(JSON.stringify(view, null, 2));
-    return;
-  }
-  if (options.html) {
-    const htmlPath = path.join(paths.kanbanDir, 'board.html');
-    fs.writeFileSync(htmlPath, renderBoardHtml(view));
-    console.log(`Board written: ${htmlPath}`);
-    console.log('  유도물 — 서버 없이 브라우저에서 열면 된다. 갱신은 다시 `llm-wiki board --html`.');
-    return;
-  }
+function boardView(options = {}) {
+  const flags = { ...parseArgs(options.rest || []).flags };
+  if (options.json) flags.json = true;
+  validateFlags(flags, BOARD_FLAGS);
+  const { view, config } = collectBoard();
   renderBoard(view, config);
 }
 
@@ -484,18 +947,38 @@ function viewCard(cardObj, config) {
     title: cardObj.meta.title,
     ordinal: Number(cardObj.meta.ordinal) || 0,
     claimedBy: cardObj.meta.claimed_by || null,
+    // 모니터 뷰어가 경과 시간을 계산한다 — board --json 폐지(2026-09-16)로 이
+    // 스키마를 소비하는 건 모니터뿐이라 노출이 안전해졌다.
+    claimedAt: cardObj.meta.claimed_at || null,
     claimExpired: expired,
     notBefore: cardObj.meta.not_before || null,
     question: qLine ? qLine.split('QUESTION:')[1].trim() : null,
     dependsOn: cardObj.meta.depends_on || [],
+    milestone: cardObj.meta.milestone || null,
   };
 }
 
 function renderBoard(view, config) {
   const line = '────────────────────────────────────────';
-  console.log(`Kanban board (${view.generatedAt.split('T')[0]}) — 정본은 doc/kanban/ 카드 파일들`);
+  console.log(`Kanban board (${localToday()}) — 정본은 doc/kanban/ 카드 파일들`);
   console.log(line);
 
+  // 목적 축(3.8) — 활성 마일스톤은 멤버 상태 요약, 종결은 ✓ 한 줄. 컬럼에는
+  // 마일스톤 카드가 안 나온다(collectBoard에서 제외).
+  if (view.milestones.length) {
+    console.log(`마일스톤 (${view.milestones.length})`);
+    for (const m of view.milestones) {
+      if (kanban.ACTIVE_STATUSES.includes(m.status)) {
+        const finished = m.total - m.counts.active;
+        const byMs = s => m.members.filter(x => x.status === s).length;
+        console.log(`  • ${m.title} — ${finished}/${m.total} (todo ${byMs('todo')} · doing ${byMs('doing')} · review ${byMs('review')})`);
+      } else {
+        console.log(`  ✓ ${m.title} — ${m.total}/${m.total} (${m.status})`);
+      }
+    }
+    console.log(line);
+  }
+
   const wip = view.wip.doing;
   console.log(`DOING (${wip.used}/${wip.limit}${wip.used >= wip.limit ? ' — WIP 상한' : ''})`);
   if (!view.columns.doing.length) console.log('  (비어 있음)');
@@ -517,7 +1000,7 @@ function renderBoard(view, config) {
   if (!view.columns.todo.length) console.log('  (비어 있음)');
   for (const c of view.columns.todo) {
     const unmet = c.dependsOn.filter(dep => !resolved.has(dep));
-    const gate = c.notBefore && c.notBefore > new Date().toISOString().split('T')[0];
+    const gate = c.notBefore && c.notBefore > localToday();
     console.log(`  • ${c.title}${gate ? `  [시작 예정 — ${c.notBefore}]` : ''}${unmet.length ? `  [대기 — 의존: ${unmet.join(', ')}]` : ''}`);
   }
 
@@ -525,88 +1008,6 @@ function renderBoard(view, config) {
   console.log(`종결: done ${view.terminal.done} · superseded ${view.terminal.superseded} · abandoned ${view.terminal.abandoned}`);
 }
 
-// ── 정적 HTML 보드 — 사람용 시각화 (유도 뷰) ─────────────────────────────
-// 서버 없음, file://로 열린다. 드래그 이동이 있는 웹 뷰는 포맷이 굳은 뒤의
-// 확정 대상(plan.md) — 그때까지는 읽기 전용이 원칙이다.
-function escapeHtml(s) {
-  return String(s).replace(/[&<>"']/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch]));
-}
-
-function renderBoardHtml(view) {
-  const today = new Date().toISOString().split('T')[0];
-  const resolved = new Set(view.resolved);
-
-  const badges = c => {
-    const out = [];
-    if (c.claimExpired) out.push('<span class="badge warn">클레임 만료</span>');
-    else if (c.claimedBy) out.push(`<span class="badge">${escapeHtml(c.claimedBy)}</span>`);
-    if (c.notBefore && c.notBefore > today) out.push(`<span class="badge gate">시작 예정 ${escapeHtml(c.notBefore)}</span>`);
-    const unmet = c.dependsOn.filter(dep => !resolved.has(dep));
-    if (unmet.length) out.push(`<span class="badge gate">의존 대기: ${unmet.map(escapeHtml).join(', ')}</span>`);
-    return out.join(' ');
-  };
-  const cardDiv = c => `<div class="card"><div class="t">${escapeHtml(c.title)}</div>${c.question ? `<div class="q">↳ ${escapeHtml(c.question)}</div>` : ''}${badges(c)}</div>`;
-  const kindLabel = { done: '완료', superseded: '대체', abandoned: '폐기' };
-  const terminalList = view.terminalRecent.length
-    ? view.terminalRecent
-        .map(t => `<div class="card"><span class="badge t-${t.kind}">${kindLabel[t.kind]}</span><span class="tt">${escapeHtml(t.title)}</span></div>`)
-        .join('\n')
-    : '<div class="empty">비어 있음</div>';
-  const column = (label, cards) => `
-    <section>
-      <h2>${label} <span class="count">${cards.length}</span></h2>
-      ${cards.map(cardDiv).join('\n') || '<div class="empty">비어 있음</div>'}
-    </section>`;
-  const terminalSection = `
-    <section>
-      <h2>종결 적체 <span class="count">최근 ${view.terminalRecent.length}</span></h2>
-      ${terminalList}
-    </section>`;
-
-  return `<!doctype html>
-<html lang="ko">
-<head>
-<meta charset="utf-8">
-<title>llm-wiki board</title>
-<style>
-  body { font-family: -apple-system, 'Segoe UI', 'Malgun Gothic', sans-serif; margin: 24px; background: #f6f7f9; color: #1c2733; }
-  header h1 { font-size: 20px; margin: 0 0 4px; }
-  header p { margin: 0 0 20px; color: #5b6a78; font-size: 13px; }
-  main { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
-  section { background: #fff; border: 1px solid #e2e6ea; border-radius: 10px; padding: 12px; }
-  h2 { font-size: 14px; margin: 0 0 10px; text-transform: uppercase; letter-spacing: .04em; color: #40505f; }
-  .count { color: #8a97a3; font-weight: 400; }
-  .card { background: #f2f4f7; border: 1px solid #dde2e8; border-radius: 8px; padding: 8px 10px; margin-bottom: 8px; }
-  .card .t { font-size: 14px; font-weight: 600; margin-bottom: 4px; }
-  .q { font-size: 12px; color: #5b6a78; margin: 2px 0 4px; }
-  .badge { display: inline-block; font-size: 11px; background: #e3e8ee; color: #44525f; border-radius: 999px; padding: 2px 8px; margin: 2px 4px 0 0; }
-  .badge.warn { background: #fdeccf; color: #7a4d05; }
-  .badge.gate { background: #dbe7fd; color: #1c4d8f; }
-  .empty { color: #98a3ad; font-size: 13px; }
-  .tt { font-size: 13px; color: #1c2733; }
-  .t-done { background: #6ee7a0; }
-  .t-superseded { background: #c9a6ff; }
-  .t-abandoned { background: #ff8f8f; }
-  footer { margin-top: 18px; color: #5b6a78; font-size: 13px; }
-</style>
-</head>
-<body>
-<header>
-  <h1>Kanban board</h1>
-  <p>생성: ${escapeHtml(view.generatedAt)} · WIP doing ${view.wip.doing.used}/${view.wip.doing.limit} · 이 파일은 유도물 — 정본은 doc/kanban/ 카드 파일들</p>
-</header>
-<main style="grid-template-columns: repeat(4, 1fr)">
-${column('Doing', view.columns.doing)}
-${column('Review (사람 판정 대기)', view.columns.review)}
-${column('Todo', view.columns.todo)}
-${terminalSection}
-</main>
-<footer>종결: done ${view.terminal.done} · superseded ${view.terminal.superseded} · abandoned ${view.terminal.abandoned} — 갱신은 <code>llm-wiki board --html</code></footer>
-</body>
-</html>
-`;
-}
-
 // review(대기) → todo 복귀 — 조건이 충족됐거나 사람이 판정을 내렸을 때.
 // 조건부 카드(Activation/not_before)의 진행 스위치다. 대기에서 저절로 풀리는 건
 // not_before(기계 판정)뿐이고, 관측형 조건은 이 명령으로 명시적으로 푼다.
@@ -614,21 +1015,24 @@ function resume(options = {}) {
   const { paths } = requireBoard();
   const { positional, flags } = parseArgs(options.rest || []);
   const title = positional[0];
-  if (!title) fail('사용법: llm-wiki resume <제목> [--note "…"]');
-
-  const cardObj = kanban.findCard(paths, title);
-  if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
-  if (cardObj.meta.status !== 'review') fail(`review 카드만 복귀시킨다 (현재: ${cardObj.meta.status}): ${cardObj.filePath}`);
-
-  const meta = { ...cardObj.meta, status: 'todo' };
-  const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
-  const line = `- ${nowIso()} — RESUMED: ${flags.note ? String(flags.note) : '대기 조건 충족 또는 사람 판정'}`;
-  const notes = parsed.sections.get('Notes') || '';
-  parsed.sections.set('Notes', notes ? `${notes}\n${line}` : line);
-
-  kanban.writeCard(cardObj, meta, parsed);
-  kanban.appendActivity(paths, { action: 'resumed', title: meta.title, detail: flags.note ? String(flags.note) : undefined });
-  console.log(`Resumed to todo: ${cardObj.filePath}`);
+  if (!title) fail(USAGE.resume);
+  validateFlags(flags, RESUME_FLAGS);
+
+  return kanban.withLock(paths, kanban.BOARD_LOCK_NAME, () => {
+    const cardObj = kanban.findCard(paths, title);
+    if (!cardObj) fail(`카드를 못 찾았다: ${title}`);
+    if (cardObj.meta.status !== 'review') fail(`review 카드만 복귀시킨다 (현재: ${cardObj.meta.status}): ${cardObj.filePath}`);
+
+    const meta = { ...cardObj.meta, status: 'todo' };
+    const parsed = { ...cardObj.card, ac: cardObj.card.ac.map(a => ({ ...a })), sections: new Map(cardObj.card.sections) };
+    const line = `- ${nowIso()} — RESUMED: ${typeof flags.note === 'string' && flags.note ? flags.note : '대기 조건 충족 또는 사람 판정'}`;
+    const notes = parsed.sections.get('Notes') || '';
+    parsed.sections.set('Notes', notes ? `${notes}\n${line}` : line);
+
+    kanban.writeCard(cardObj, meta, parsed);
+    kanban.appendActivity(paths, { action: 'resumed', title: meta.title, detail: typeof flags.note === 'string' ? flags.note : undefined });
+    console.log(`Resumed to todo: ${cardObj.filePath}`);
+  });
 }
 
 // ── board report — 계기판 (개선계획 4-1) ─────────────────────────────────
@@ -656,7 +1060,7 @@ function boardReport(options = {}) {
   const days = [];
   for (let i = 13; i >= 0; i--) {
     const d = new Date(); d.setDate(d.getDate() - i);
-    days.push(d.toISOString().split('T')[0]);
+    days.push(localToday(d));
   }
   const trend = days.map(day => {
     const on = action => activity.filter(a => a.action === action && String(a.ts).startsWith(day)).length;
@@ -728,7 +1132,7 @@ function appendAbandonRaw(docRoot, title, reason, cardPath) {
   const rawDir = path.join(docRoot, 'raw');
   if (!fs.existsSync(rawDir)) return null;
 
-  const today = new Date().toISOString().split('T')[0];
+  const today = localToday(); // raw 로그 파일명은 현지 날짜(header-date-over-mtime)
   const rawPath = path.join(rawDir, `${today}.md`);
   let caseNum = 1;
   let header = `# ${today}\n`;
@@ -770,6 +1174,11 @@ function appendAbandonRaw(docRoot, title, reason, cardPath) {
 // 렌더는 headless Chrome 기반 CPU 작업이다 (GPU 불필요).
 function boardVideo(options = {}) {
   const { paths, config } = requireBoard();
+  // 미검증 플래그를 조용히 무시하던 결함(2026-09-16 설계 리뷰에서 접수) —
+  // video는 플래그를 받지 않는다. bin이 전역 선추출한 --json도 여기로 넘어온다.
+  const flags = { ...parseArgs(options.rest || []).flags };
+  if (options.json) flags.json = true;
+  validateFlags(flags, VIDEO_FLAGS);
   const activity = kanban.readActivity(paths);
   const cfg = loadConfig(findDocRoot());
   const repo = cfg.projectName || path.basename(process.cwd());
@@ -788,16 +1197,21 @@ function boardVideo(options = {}) {
 
   const videoProject = path.join(process.cwd(), 'video');
   if (!fs.existsSync(path.join(videoProject, 'package.json'))) {
-    console.log('video/ Remotion 프로젝트가 없다 — 타임라인만 남긴다 (렌더는 video/ 프로젝트에서).');
+    console.log('video/ Remotion 프로젝트가 없다 — 타임라인(board-timeline.json)만 남긴다.');
+    console.log('  렌더 프로젝트는 npm 패키지에 포함되지 않는다(llm-wiki 레포의 video/ 참고).');
     return;
   }
 
   console.log('Rendering board timelapse (headless Chrome — 첫 실행은 Chrome 내려받기로 몇 분 걸린다)...');
+  // kanbanDir 기준 절대경로로 렌더 — ../doc/ 하드코딩은 LLM_WIKI_ROOT 오버라이드와
+  // 다른 doc 루트에서 엉뚱한 곳을 읽게 한다(2026-09-09 리뷰 5-2). 따옴표로 감싸
+  // 경로의 공백도 안전하게.
+  const mp4Path = path.join(paths.kanbanDir, 'board-timelapse.mp4');
   execSync(
-    'npx remotion render src/index.ts BoardTimelapse ../doc/kanban/board-timelapse.mp4 --props=../doc/kanban/board-timeline.json',
+    `npx remotion render src/index.ts BoardTimelapse "${mp4Path}" --props="${timelinePath}"`,
     { cwd: videoProject, stdio: 'inherit', timeout: 570000 }
   );
-  console.log('Video written: doc/kanban/board-timelapse.mp4');
+  console.log(`Video written: ${mp4Path}`);
 }
 
 // ── 디스패치 ─────────────────────────────────────────────────────────────
@@ -809,10 +1223,16 @@ function dispatchCard(rest) {
   if (sub === 'new') cardNew(paths, kanban.loadConfig(paths), parsedArgs);
   else if (sub === 'show') cardShow(paths, parsedArgs);
   else if (sub === 'edit') cardEdit(paths, parsedArgs);
-  else fail('사용법: llm-wiki card <new|show|edit> …');
+  else fail(USAGE.card);
 }
 
 module.exports = {
+  // wait(kanban-wait)가 같은 플래그 규칙으로 재사용한다 — 계층 간 단일 파서.
+  parseArgs,
+  validateFlags,
+  fail,
+  // bin의 --help 가드가 fail()과 같은 사용법 문자열을 쓴다(한 곳 관리).
+  USAGE,
   dispatchCard,
   pick,
   handoff,
@@ -824,5 +1244,8 @@ module.exports = {
   boardView,
   boardReport,
   boardVideo,
+  // monitor(kanban-monitor)가 보드 수집·루트 검증을 재사용한다 — 유도물은 한 곳에서.
+  requireBoard,
+  collectBoard,
   scaffold: kanban.scaffold,
 };