leerness 1.9.1 → 1.9.3

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.9.3 — 2026-05-08
+
+이번 릴리스는 "이전 작업과 새 작업의 인과관계·재귀 안내·디자인 일관성"을 자동화합니다.
+
+### Added — 인과관계·재사용·일관성
+
+- `leerness impact <target>` — 변경 전 영향 분석. `<target>`을 `import/require/href/src/@import/url()`로 참조하는 모든 파일을 단일 패스로 식별.
+- `leerness reuse find <query>` — `reuse-map.md`, `design-system.md`, `feature-contracts.md`, `plan/progress`, 그리고 코드의 export/식별자에서 기존 자원을 통합 검색.
+- `leerness reuse register <name> --where <path> --kind component|hook|util|api [--note ...]` — `reuse-map.md`에 자동 row 추가.
+- `leerness ui consistency [path] [--strict] [--fail-on-violation]` — `design-system.md`의 토큰 표를 파싱해 코드의 hex 색상이 토큰에 등록되어 있는지 검사. `--strict`는 px/rem 사이즈도, `--fail-on-violation`은 비-제로 종료.
+- `leerness graph [path] [--out <file>]` — 의존성 그래프를 mermaid 형식으로 출력하거나 파일로 저장.
+- `leerness guide [target]` — 위 4개를 한 번에 실행하는 변경 전 통합 가이드.
+
+### Migration
+
+기존 1.9.x 사용자는 `npx leerness@latest update . --yes`로 즉시 자동 마이그레이션됩니다.
+
+## 1.9.2 — 2026-05-08
+
+스킬을 살아 있는 학습 사이클로 끌어올린 릴리스. 동일 API 작업이 반복될 때 기존 패턴을 발견·재사용하고, 더 나은 방법이 생기면 최적화 이력으로 누적합니다.
+
+### Added — 스킬 학습 사이클
+
+- `leerness skill learn <id> --doc <url> --command "..." --capability "..." [--note ...]`
+  - 새 스킬을 `.harness/skills/<id>/skill.json`에 생성하거나, 카탈로그 스킬을 로컬에 materialize.
+  - `--doc` / `--capability`는 반복 가능 (n번 적으면 모두 누적).
+  - `skill.json` 스키마 확장: `sources[]`, `patterns[]`, `optimizations[]`, `usage{count,lastUsed,lastNote}`.
+- `leerness skill use <id> [--note ...]`: 사용 횟수+1, lastUsed 갱신.
+- `leerness skill optimize <id> --before "..." --after "..." [--note ...]`: 최적화 이력 누적.
+- `leerness skill remove <id>`: 사용자 정의 스킬 삭제 (카탈로그 스킬은 로컬 메타만 정리).
+- `leerness skill consolidate [--threshold 0.3]`: 모든 스킬의 capability 토큰 jaccard 비교로 통합 후보 자동 발견.
+- `leerness skill list`가 카탈로그 + 사용자 스킬을 합쳐 출력 (출처/사용횟수/최종 컬럼 추가).
+- `leerness skill info <id>`가 sources/patterns/optimizations까지 모두 표시.
+
+### Added — 게이트 통합
+
+- `leerness gate [path]` — `verify + audit + scan secrets + encoding check + lazy detect`을 한번에 실행해 단일 요약을 출력. 한 단계라도 실패하면 비-제로 종료.
+- `leerness self check`을 `leerness update --check`의 thin wrapper로 통합. 단일 출처(npm view + 캐시)로 일원화하면서 1.8.0과의 호환을 위해 명령 자체는 유지.
+
+### Migration
+
+기존 1.9.x 사용자는 `npx leerness@latest update . --yes`로 즉시 자동 마이그레이션됩니다. 카탈로그 스킬에 대한 사용 기록은 처음 `skill use`/`skill optimize` 시점부터 누적되기 시작합니다.
+
 ## 1.9.1 — 2026-05-08
 
 1.9.0을 실 프로젝트(memo-cli)에서 운영하며 발견한 **5개 메타 감사 사항**을 패치합니다.

package/bin/harness.js

@@ -6,7 +6,7 @@ const path = require('path');
 const cp = require('child_process');
 const readline = require('readline');
 
-const VERSION = '1.9.1';
+const VERSION = '1.9.3';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -56,7 +56,7 @@ function arg(name, def = null) { const i = process.argv.indexOf(name); return i
 function has(name) { return process.argv.includes(name); }
 function nonFlagArgs() {
   const out = [];
-  const withValue = new Set(['--language','--skills','--path','--status','--progress','--goal','--reason','--next','--target','--token-env','--package','--out','--from','--repo','--id','--note','--evidence','--query','--limit','--action','--agent','--tool']);
+  const withValue = new Set(['--language','--skills','--path','--status','--progress','--goal','--reason','--next','--target','--token-env','--package','--out','--from','--repo','--id','--note','--evidence','--query','--limit','--action','--agent','--tool','--doc','--command','--capability','--before','--after','--display','--threshold']);
   const a = process.argv.slice(2);
   for (let i = 0; i < a.length; i++) {
     const x = a[i];
@@ -65,6 +65,11 @@ function nonFlagArgs() {
   }
   return out;
 }
+function argAll(name) {
+  const out = []; const a = process.argv;
+  for (let i = 0; i < a.length; i++) if (a[i] === name && a[i+1] && !a[i+1].startsWith('-')) out.push(a[++i]);
+  return out;
+}
 function detectProjectName(root) { try { const pkg = JSON.parse(read(path.join(root, 'package.json'))); if (pkg.name) return pkg.name; } catch {} return path.basename(root); }
 function detectLanguageValue(root, value = 'auto') {
   const v = String(value || 'auto').toLowerCase();
@@ -404,32 +409,162 @@ function addSkill(root, name, silent = false) {
   if (!silent) ok(`skill installed: ${name}`);
 }
 
-function skillList(root) {
-  // 1.9.1: 설치 여부 컬럼 추가 (root가 없으면 생략)
-  let installed = new Set();
+// ===== Skill registry (catalog + user-defined merged) =====
+function userSkillsDir(root) { return path.join(absRoot(root), '.harness/skills'); }
+function userSkillFile(root, id) { return path.join(userSkillsDir(root), id, 'skill.json'); }
+
+function loadUserSkill(root, id) {
+  const f = userSkillFile(root, id);
+  if (!exists(f)) return null;
+  try { return JSON.parse(read(f)); } catch { return null; }
+}
+function saveUserSkill(root, id, data) {
+  const dir = path.join(userSkillsDir(root), id); mkdirp(dir);
+  writeUtf8(path.join(dir, 'skill.json'), JSON.stringify(data, null, 2) + '\n');
+  // README mirror
+  const usage = data.usage || { count: 0 };
+  const readme = `# ${data.displayNameKo || id}\n\n## Capabilities\n${(data.capabilities || []).map(c => '- ' + c).join('\n') || '-'}\n\n## Sources\n${(data.sources || []).map(s => `- ${s.url || s}`).join('\n') || '-'}\n\n## Patterns (성공 명령/접근)\n${(data.patterns || []).map(p => `- \`${p.command}\` — ${p.note || ''}`).join('\n') || '-'}\n\n## Optimization history\n${(data.optimizations || []).map(o => `- ${o.at}: ${o.note || ''}${o.before||o.after?` (${o.before||'?'} → ${o.after||'?'})`:''}`).join('\n') || '-'}\n\n## Usage\n${usage.count || 0}회 사용 / 마지막: ${usage.lastUsed || '-'}\n${usage.lastNote ? '\n마지막 노트: ' + usage.lastNote : ''}\n`;
+  writeUtf8(path.join(dir, 'README.md'), readme);
+}
+
+function listAllSkills(root) {
+  const out = {};
+  for (const [k, v] of Object.entries(skillCatalog)) out[k] = { ...v, _source: 'catalog' };
   if (root) {
-    const skillsDir = path.join(absRoot(root), '.harness/skills');
-    if (exists(skillsDir)) {
-      try { for (const e of fs.readdirSync(skillsDir)) installed.add(e); } catch {}
+    const dir = userSkillsDir(root);
+    if (exists(dir)) {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        const data = loadUserSkill(root, e.name);
+        if (!data) continue;
+        if (out[e.name]) out[e.name] = { ...out[e.name], ...data, _source: 'catalog+local' };
+        else out[e.name] = { ...data, _source: 'user' };
+      }
     }
   }
-  const showInstalled = root && installed.size >= 0;
-  if (showInstalled) {
-    log('| ID | 한글명 | 가능한 작업 | 최종 업데이트 | 검증 | 설치됨 |');
-    log('|---|---|---|---|---|---|');
-    for (const [k, v] of Object.entries(skillCatalog)) log(`| ${k} | ${v.displayNameKo} | ${v.capabilities.join('<br>')} | ${v.lastUpdated} | ${v.verification} | ${installed.has(k) ? '✓' : '·'} |`);
-  } else {
-    log('| ID | 한글명 | 가능한 작업 | 최종 업데이트 | 검증 |');
-    log('|---|---|---|---|---|');
-    for (const [k, v] of Object.entries(skillCatalog)) log(`| ${k} | ${v.displayNameKo} | ${v.capabilities.join('<br>')} | ${v.lastUpdated} | ${v.verification} |`);
+  return out;
+}
+
+function skillList(root) {
+  const all = listAllSkills(root);
+  log('| ID | 한글명 | 출처 | 능력(요약) | 사용횟수 | 최종 |');
+  log('|---|---|---|---|---|---|');
+  for (const [id, v] of Object.entries(all)) {
+    const cap = (v.capabilities || []).slice(0, 3).join(' / ') + ((v.capabilities || []).length > 3 ? ' …' : '');
+    const usage = v.usage?.count || 0;
+    const last = v.usage?.lastUsed?.slice(0, 10) || v.lastUpdated || '-';
+    log(`| ${id} | ${v.displayNameKo || id} | ${v._source} | ${cap} | ${usage} | ${last} |`);
   }
 }
-function skillInfo(name) {
-  const v = skillCatalog[name];
+
+function skillInfo(name, root) {
+  const all = listAllSkills(root);
+  const v = all[name];
   if (!v) return fail(`Unknown skill: ${name}`);
-  log(`${name}`); log(`한글명: ${v.displayNameKo}`); log(`버전: ${v.version}`);
-  log(`최종 업데이트: ${v.lastUpdated}`); log(`검증: ${v.verification}`);
-  log('가능한 작업:'); v.capabilities.forEach(x => log('- ' + x));
+  log(`# ${name} (${v._source})`);
+  log(`한글명: ${v.displayNameKo || name}`);
+  log(`버전: ${v.version || '-'} / 최종: ${v.lastUpdated || '-'} / 검증: ${typeof v.verification === 'object' ? v.verification.status : v.verification || '-'}`);
+  log(`사용: ${v.usage?.count || 0}회 / 마지막: ${v.usage?.lastUsed || '-'}`);
+  log('Capabilities:'); (v.capabilities || []).forEach(x => log('- ' + x));
+  if ((v.sources || []).length) { log('Sources:'); v.sources.forEach(s => log('- ' + (s.url || s))); }
+  if ((v.patterns || []).length) { log('Patterns:'); v.patterns.forEach(p => log(`- \`${p.command}\` — ${p.note || ''}`)); }
+  if ((v.optimizations || []).length) { log('Optimizations:'); v.optimizations.forEach(o => log(`- ${o.at}: ${o.note || ''}`)); }
+}
+
+function skillLearn(root, id) {
+  if (!id) return fail('id required (e.g., skill learn open-meteo --command "..." --doc URL)');
+  const docs = argAll('--doc');
+  const command = arg('--command', null);
+  const note = arg('--note', null);
+  const caps = argAll('--capability');
+  const display = arg('--display', null);
+  let data = loadUserSkill(root, id);
+  if (!data) {
+    // start from catalog if exists
+    const base = skillCatalog[id];
+    data = base ? { name: id, ...base, sources: [], patterns: [], optimizations: [], usage: { count: 0, lastUsed: null } }
+                : { name: id, displayNameKo: display || id, version: '1.0.0', lastUpdated: today(), verification: 'unverified', capabilities: [], sources: [], patterns: [], optimizations: [], usage: { count: 0, lastUsed: null } };
+  }
+  if (display) data.displayNameKo = display;
+  for (const d of docs) if (!data.sources.some(s => (s.url || s) === d)) data.sources.push({ at: now(), url: d });
+  for (const c of caps) if (!data.capabilities.includes(c)) data.capabilities.push(c);
+  if (command) data.patterns.push({ at: now(), command, note: note || '' });
+  data.lastUpdated = today();
+  saveUserSkill(root, id, data);
+  ok(`skill learned: ${id} (sources=${data.sources.length}, patterns=${data.patterns.length}, capabilities=${data.capabilities.length})`);
+}
+
+function skillUse(root, id) {
+  if (!id) return fail('id required');
+  let data = loadUserSkill(root, id);
+  if (!data) {
+    const base = skillCatalog[id];
+    if (!base) return fail(`skill not found: ${id}`);
+    data = { name: id, ...base, sources: [], patterns: [], optimizations: [], usage: { count: 0, lastUsed: null } };
+  }
+  data.usage = data.usage || { count: 0, lastUsed: null };
+  data.usage.count++;
+  data.usage.lastUsed = now();
+  if (arg('--note', null)) data.usage.lastNote = arg('--note', null);
+  saveUserSkill(root, id, data);
+  ok(`skill used: ${id} (count=${data.usage.count})`);
+}
+
+function skillOptimize(root, id) {
+  if (!id) return fail('id required');
+  let data = loadUserSkill(root, id);
+  if (!data) {
+    const base = skillCatalog[id];
+    if (!base) return fail(`skill not found: ${id}`);
+    data = { name: id, ...base, sources: [], patterns: [], optimizations: [], usage: { count: 0, lastUsed: null } };
+  }
+  data.optimizations = data.optimizations || [];
+  data.optimizations.push({ at: now(), before: arg('--before', '') || '', after: arg('--after', '') || '', note: arg('--note', '') || '' });
+  data.lastUpdated = today();
+  saveUserSkill(root, id, data);
+  ok(`skill optimized: ${id} (total=${data.optimizations.length})`);
+}
+
+function skillRemove(root, id) {
+  if (!id) return fail('id required');
+  const dir = path.join(userSkillsDir(root), id);
+  if (!exists(dir)) return fail(`skill folder not found: ${id}`);
+  if (skillCatalog[id]) {
+    // catalog 스킬은 로컬 메타만 제거 (카탈로그는 패키지 내장이라 영구 제거 불가)
+    fs.rmSync(dir, { recursive: true, force: true });
+    ok(`local meta removed for catalog skill: ${id} (catalog 자체는 패키지에 내장)`);
+  } else {
+    fs.rmSync(dir, { recursive: true, force: true });
+    ok(`user skill removed: ${id}`);
+  }
+}
+
+function skillConsolidate(root) {
+  const all = listAllSkills(root);
+  const ids = Object.keys(all);
+  function tokens(v) {
+    return new Set((v.capabilities || []).join(' ').toLowerCase().split(/[\s,/·.()[\]]+/).filter(t => t.length >= 2));
+  }
+  function jaccard(a, b) {
+    const inter = new Set([...a].filter(x => b.has(x))).size;
+    const uni = new Set([...a, ...b]).size;
+    return uni ? inter / uni : 0;
+  }
+  const tokenized = {};
+  for (const id of ids) tokenized[id] = tokens(all[id]);
+  const threshold = parseFloat(arg('--threshold', '0.3'));
+  const candidates = [];
+  for (let i = 0; i < ids.length; i++) for (let j = i + 1; j < ids.length; j++) {
+    const a = ids[i], b = ids[j];
+    const s = jaccard(tokenized[a], tokenized[b]);
+    if (s >= threshold) candidates.push({ a, b, score: s });
+  }
+  if (!candidates.length) return ok(`no consolidation candidates (jaccard < ${threshold})`);
+  candidates.sort((x, y) => y.score - x.score);
+  log(`# Consolidation candidates (jaccard >= ${threshold})`);
+  log('| A | B | score | 권장 |');
+  log('|---|---|---|---|');
+  for (const c of candidates) log(`| ${c.a} | ${c.b} | ${c.score.toFixed(2)} | \`leerness skill learn <new> --capability ...\` 후 \`leerness skill remove <old>\` |`);
 }
 
 const planPath = root => path.join(root, '.harness/plan.md');
@@ -900,13 +1035,224 @@ function mergeDesign(root) {
   ok(merged ? 'design guides merged into .harness/design-system.md' : 'nothing to merge');
 }
 
-function selfCheck(root) {
-  let latest = 'unknown';
-  try { latest = cp.execSync('npm view leerness version', { encoding:'utf8', stdio:['ignore','pipe','ignore'], timeout:10000 }).trim(); }
-  catch { latest = 'npm registry unavailable'; }
-  const verF = path.join(root,'.harness/HARNESS_VERSION');
-  const local = exists(verF) ? read(verF).trim() : 'not installed';
-  log(`Leerness CLI: ${VERSION}`); log(`Project: ${local}`); log(`NPM latest: ${latest}`);
+// 1.9.2: self check를 update --check의 thin wrapper로 통합 (단일 출처).
+async function selfCheck(root) {
+  return await updateCmd(root, { checkOnly: true });
+}
+
+// 1.9.2: 게이트 5종 한번에 실행 (verify + audit + scan secrets + encoding check + lazy detect).
+function gate(root) {
+  root = absRoot(root);
+  log('# leerness gate (5 checks)');
+  let bad = 0;
+  function step(label, fn) {
+    log(`\n## ${label}`);
+    const code0 = process.exitCode || 0;
+    try { fn(); } catch (e) { fail(`${label} threw: ${e.message}`); bad++; }
+    if (process.exitCode && process.exitCode !== code0) bad++;
+    process.exitCode = 0;
+  }
+  step('verify', () => verify(root));
+  step('audit', () => audit(root));
+  step('scan secrets', () => scanSecrets(root));
+  step('encoding check', () => encodingCheck(root));
+  step('lazy detect', () => lazyDetect(root));
+  log(`\n# gate summary: ${bad} 단계 실패`);
+  if (bad) process.exitCode = 1;
+  else ok('all gates passed');
+}
+
+// ===== 1.9.3: Causal / reuse / consistency =====
+const CODE_EXT = new Set(['.js','.ts','.jsx','.tsx','.mjs','.cjs','.css','.scss','.sass','.less','.html','.htm','.vue','.svelte','.md','.json','.py','.rb','.go','.rs','.java','.kt','.swift','.cs','.php']);
+function* walkCode(root, base = root, depth = 0) {
+  if (depth > 12) return;
+  for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+    const p = path.join(base, e.name);
+    const r = path.relative(root, p).replace(/\\/g, '/');
+    if (Array.from(SCAN_SKIP_DIRS).some(d => r === d || r.startsWith(d + '/'))) continue;
+    if (e.isDirectory()) yield* walkCode(root, p, depth + 1);
+    else if (CODE_EXT.has(path.extname(p).toLowerCase())) yield p;
+  }
+}
+function escapeRegex(s) { return String(s).replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&'); }
+
+function impactCmd(root, target) {
+  if (!target) return fail('target required (e.g., impact src/components/card.html)');
+  root = absRoot(root);
+  const abs = path.isAbsolute(target) ? target : path.resolve(root, target);
+  const base = path.basename(target);
+  const noext = path.basename(target, path.extname(target));
+  const direct = [];
+  const targetRel = rel(root, abs);
+  for (const f of walkCode(root)) {
+    if (path.resolve(f) === path.resolve(abs)) continue;
+    let text; try { text = read(f); } catch { continue; }
+    const patterns = [
+      new RegExp(`(?:import\\s+[^;\\n]*?from\\s+['"]|require\\(['"]|@import\\s+['"]|href=["']|src=["']|url\\(\\s*['"]?|include\\(['"]?)[^'")\\s]*${escapeRegex(base)}`),
+      // bare reference to filename without extension (e.g., 'card' alias)
+      new RegExp(`['"][^'"\\n]*${escapeRegex(noext)}\\b[^'"\\n]*['"]`)
+    ];
+    if (patterns.some(re => re.test(text))) direct.push(rel(root, f));
+  }
+  log(`# impact: ${targetRel}`);
+  if (direct.length === 0) ok('영향 범위 없음 (참조하는 파일 없음)');
+  else {
+    log(`참조하는 파일 ${direct.length}개:`);
+    direct.forEach(d => log('- ' + d));
+  }
+  return { target: targetRel, direct };
+}
+
+function reuseMapPath(root) { return path.join(root, '.harness/reuse-map.md'); }
+function designSystemPath(root) { return path.join(root, '.harness/design-system.md'); }
+function featureContractsPath(root) { return path.join(root, '.harness/feature-contracts.md'); }
+
+function reuseFind(root, query) {
+  if (!query) return fail('query required');
+  root = absRoot(root);
+  const re = new RegExp(escapeRegex(query), 'i');
+  const matches = [];
+  for (const src of [reuseMapPath(root), designSystemPath(root), featureContractsPath(root), planPath(root), progressPath(root)]) {
+    if (!exists(src)) continue;
+    const text = read(src);
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i])) matches.push({ source: rel(root, src), line: i + 1, text: lines[i].trim() });
+    }
+  }
+  // 코드 export/식별자 검색
+  for (const f of walkCode(root)) {
+    if (rel(root, f).startsWith('.harness/')) continue;
+    let text; try { text = read(f); } catch { continue; }
+    const lines = text.split('\n');
+    const exportRe = new RegExp(`(?:export\\s+(?:default\\s+)?(?:async\\s+)?(?:function|const|class|let|var)\\s+(\\w*${escapeRegex(query)}\\w*)|class\\s+(\\w*${escapeRegex(query)}\\w*)|<(\\w*${escapeRegex(query)}\\w*)\\b)`, 'i');
+    for (let i = 0; i < lines.length; i++) {
+      if (exportRe.test(lines[i])) matches.push({ source: rel(root, f), line: i + 1, text: lines[i].trim().slice(0, 120) });
+    }
+  }
+  log(`# reuse find: "${query}"`);
+  if (!matches.length) return ok('기존 자원 없음 — 새로 만드는 것이 최선의 선택일 수 있음');
+  log(`${matches.length}개 후보:`);
+  for (const m of matches.slice(0, parseInt(arg('--limit', '20'), 10))) log(`- ${m.source}:${m.line}  ${m.text}`);
+  log(`\n💡 새로 만들기 전에 위 자원을 재사용/확장 가능한지 확인하세요.`);
+}
+
+function reuseRegister(root, name) {
+  if (!name) return fail('name required (e.g., reuse register Card --where components/card.html --kind component --note "기본 카드")');
+  root = absRoot(root);
+  const where = arg('--where', '?');
+  const kind = arg('--kind', 'component');
+  const note = arg('--note', '-');
+  const file = reuseMapPath(root);
+  const text = exists(file) ? read(file) : '';
+  if (text.includes(`| ${name} |`)) return warn(`already registered: ${name}`);
+  const newRow = `| ${name} | ${where} | ${kind} | ${note} |`;
+  const lines = text.split('\n');
+  const headerIdx = lines.findIndex(l => /^\|\s*-+\s*\|/.test(l));
+  if (headerIdx >= 0) {
+    lines.splice(headerIdx + 1, 0, newRow);
+    writeUtf8(file, lines.join('\n'));
+  } else {
+    append(file, '\n' + newRow + '\n');
+  }
+  ok(`reuse registered: ${name} (${kind}) → ${where}`);
+}
+
+function uiConsistency(root) {
+  root = absRoot(root);
+  // 1) design-system.md에서 토큰 값 추출
+  const ds = exists(designSystemPath(root)) ? read(designSystemPath(root)) : '';
+  const tokens = {};
+  for (const line of ds.split('\n')) {
+    const m = line.match(/^\|\s*([\w.\-]+)\s*\|\s*([^|]+?)\s*\|/);
+    if (!m) continue;
+    const key = m[1].trim();
+    const val = m[2].trim();
+    if (key === 'Token' || /^-+$/.test(key) || val === 'Value' || /실제 값으로 업데이트/.test(val) || !val) continue;
+    tokens[key] = val;
+  }
+  const tokenSet = new Set(Object.values(tokens).map(v => v.toLowerCase()));
+  if (Object.keys(tokens).length === 0) {
+    warn('design-system.md에 토큰이 등록되지 않음 (Tokens 표를 채우면 일관성 검사 가능)');
+    return;
+  }
+  ok(`등록된 디자인 토큰: ${Object.keys(tokens).length}개`);
+  const findings = [];
+  for (const f of walkCode(root)) {
+    if (rel(root, f).startsWith('.harness/')) continue;
+    if (!/\.(css|scss|sass|less|html|jsx|tsx|vue|svelte|js|ts)$/i.test(f)) continue;
+    let text; try { text = read(f); } catch { continue; }
+    const hexes = [...text.matchAll(/#[0-9a-fA-F]{3,8}\b/g)];
+    for (const h of hexes) {
+      const v = h[0].toLowerCase();
+      if (!tokenSet.has(v)) {
+        const line = text.slice(0, h.index).split('\n').length;
+        findings.push({ file: rel(root, f), line, value: h[0], type: 'hex' });
+      }
+    }
+    // px/rem 휴리스틱은 false positive가 많아 옵션
+    if (has('--strict')) {
+      const sizes = [...text.matchAll(/\b(\d+)(px|rem)\b/g)];
+      for (const s of sizes) {
+        const v = `${s[1]}${s[2]}`;
+        if (!tokenSet.has(v)) {
+          const line = text.slice(0, s.index).split('\n').length;
+          findings.push({ file: rel(root, f), line, value: v, type: 'size' });
+        }
+      }
+    }
+  }
+  if (!findings.length) return ok('UI consistency 통과 (모든 색상이 토큰)');
+  warn(`토큰 외 값 ${findings.length}개:`);
+  for (const f of findings.slice(0, 30)) log(`  ${f.file}:${f.line}  ${f.value}  (${f.type})`);
+  if (findings.length > 30) log(`  ... +${findings.length - 30}개`);
+  if (has('--fail-on-violation')) process.exitCode = 1;
+}
+
+function graphCmd(root) {
+  root = absRoot(root);
+  const edges = [];
+  for (const f of walkCode(root)) {
+    if (rel(root, f).startsWith('.harness/')) continue;
+    let text; try { text = read(f); } catch { continue; }
+    const re = /(?:import\s+[^;\n]*?from\s+['"]|require\(['"]|@import\s+['"]|href=["']|src=["'])([^'")\s]+)/g;
+    let m;
+    while ((m = re.exec(text))) {
+      edges.push({ src: rel(root, f), dst: m[1] });
+    }
+  }
+  const out = arg('--out', null);
+  const lines = ['```mermaid', 'graph TD'];
+  const nodeSet = new Set();
+  for (const e of edges) { nodeSet.add(e.src); nodeSet.add(e.dst); }
+  for (const e of edges) lines.push(`  "${e.src}" --> "${e.dst}"`);
+  lines.push('```');
+  const md = `# Code dependency graph\n\n생성: ${now()}\n노드: ${nodeSet.size}, 엣지: ${edges.length}\n\n` + lines.join('\n') + '\n';
+  if (out) {
+    writeUtf8(path.resolve(root, out), md);
+    ok(`graph 저장: ${out}`);
+  } else {
+    log(md);
+  }
+}
+
+function guideCmd(root, target) {
+  root = absRoot(root);
+  log(`# 변경 전 가이드 ${target ? `(target: ${target})` : ''}`);
+  log(`Date: ${today()}\n`);
+  if (target) {
+    log('## 1. Impact — 변경하면 영향받는 파일');
+    impactCmd(root, target);
+    log('');
+  }
+  log('## 2. Reuse — 기존 자원 검색');
+  const q = target ? path.basename(target, path.extname(target)) : arg('--query', '');
+  if (q) reuseFind(root, q);
+  else log('(target 또는 --query 없음 — reuse 검색 스킵)');
+  log('');
+  log('## 3. UI consistency — 디자인 토큰 일치');
+  uiConsistency(root);
+  log('\n💡 다음 단계: 위 결과를 바탕으로 작업 계획을 plan/progress에 기록 후 진행하세요.');
 }
 
 // ===== Auto update =====
@@ -1082,7 +1428,7 @@ function viewworkInstall(root) {
 }
 
 function help() {
-  log(`Leerness v${VERSION}\n\nUsage:\n  leerness init [path] [--language auto|ko|en] [--skills recommended|all|a,b]\n  leerness migrate [path] [--dry-run] [--force]\n  leerness update [path] [--check|--yes|--force|--from <tarball>]\n  leerness auto-update install [path]\n  leerness status [path]\n  leerness verify [path]\n  leerness debug [path]\n  leerness audit [path]\n  leerness check [path]\n  leerness scan secrets [path]\n  leerness encoding check [path]\n  leerness lazy detect [path]\n  leerness memory search "query" [--limit 5]\n  leerness handoff [path]\n  leerness session close [path]\n  leerness viewwork install [path]\n  leerness viewwork emit [path] [--action a] [--note n] [--agent x] [--tool t]\n  leerness route <task-type>\n  leerness self check [path]\n  leerness readme sync [path]\n  leerness consistency check [path]\n  leerness consistency merge-design-guide [path]\n  leerness plan show|init|add|drop|progress|sync [args]\n  leerness task list|add|update|drop [args]\n  leerness skill list|info|add <name>\n`);
+  log(`Leerness v${VERSION}\n\nUsage:\n  leerness init [path] [--language auto|ko|en] [--skills recommended|all|a,b]\n  leerness migrate [path] [--dry-run] [--force]\n  leerness update [path] [--check|--yes|--force|--from <tarball>]\n  leerness auto-update install [path]\n  leerness status [path]\n  leerness verify [path]\n  leerness debug [path]\n  leerness audit [path]\n  leerness check [path]\n  leerness scan secrets [path]\n  leerness encoding check [path]\n  leerness lazy detect [path]\n  leerness memory search "query" [--limit 5]\n  leerness handoff [path]\n  leerness session close [path]\n  leerness viewwork install [path]\n  leerness viewwork emit [path] [--action a] [--note n] [--agent x] [--tool t]\n  leerness route <task-type>\n  leerness self check [path]\n  leerness readme sync [path]\n  leerness consistency check [path]\n  leerness consistency merge-design-guide [path]\n  leerness plan show|init|add|drop|progress|sync [args]\n  leerness task list|add|update|drop [args]\n  leerness skill list|info <name>\n  leerness skill learn <id> --doc <url> --command "..." --capability "..." [--note ...]\n  leerness skill use <id> [--note ...]\n  leerness skill optimize <id> --before "..." --after "..." [--note ...]\n  leerness skill remove <id>\n  leerness skill consolidate [--threshold 0.3]\n  leerness gate [path]                       # verify+audit+scan+encoding+lazy\n  leerness impact <target>                   # 변경 전 영향 분석\n  leerness reuse find <query>                # 기존 자원 검색 (재귀 안내)\n  leerness reuse register <name> --where <p> --kind component|hook|util|api [--note ...]\n  leerness ui consistency [path] [--strict] [--fail-on-violation]\n  leerness graph [path] [--out <file>]       # mermaid 의존성 그래프\n  leerness guide [target]                    # impact + reuse + ui consistency 통합 가이드\n`);
 }
 
 async function main() {
@@ -1107,12 +1453,27 @@ async function main() {
   if (cmd === 'viewwork' && args[1] === 'install') return viewworkInstall(args[2] || process.cwd());
   if (cmd === 'viewwork' && args[1] === 'emit')    return viewworkEmit(args[2] || process.cwd(), { action: arg('--action','task'), note: arg('--note',''), agent: arg('--agent','leerness'), tool: arg('--tool','leerness-cli') });
   if (cmd === 'route')     return route(args[1] || 'planning');
-  if (cmd === 'self' && args[1] === 'check')   return selfCheck(absRoot(args[2] || process.cwd()));
+  if (cmd === 'self' && args[1] === 'check')   return await selfCheck(absRoot(args[2] || process.cwd()));
   if (cmd === 'self' && args[1] === 'migrate') return log('Run: npx --yes leerness@latest migrate . --dry-run, then migrate without --dry-run after review.');
   if (cmd === 'readme' && args[1] === 'sync')  return readmeCmd(args[2] || process.cwd());
   if (cmd === 'consistency' && args[1] === 'check')              return consistencyCheck(args[2] || process.cwd());
   if (cmd === 'consistency' && args[1] === 'merge-design-guide') return mergeDesign(args[2] || process.cwd());
-  if (cmd === 'skill' && args[1] === 'list') return skillList(args[2] || arg('--path', null));
+  if (cmd === 'skill' && args[1] === 'list')        return skillList(args[2] || arg('--path', process.cwd()));
+  if (cmd === 'skill' && args[1] === 'info')        return skillInfo(args[2], absRoot(arg('--path', process.cwd())));
+  if (cmd === 'skill' && args[1] === 'add')         return addSkill(absRoot(arg('--path', process.cwd())), args[2]);
+  if (cmd === 'skill' && args[1] === 'learn')       return skillLearn(absRoot(arg('--path', process.cwd())), args[2]);
+  if (cmd === 'skill' && args[1] === 'use')         return skillUse(absRoot(arg('--path', process.cwd())), args[2]);
+  if (cmd === 'skill' && args[1] === 'optimize')    return skillOptimize(absRoot(arg('--path', process.cwd())), args[2]);
+  if (cmd === 'skill' && args[1] === 'remove')      return skillRemove(absRoot(arg('--path', process.cwd())), args[2]);
+  if (cmd === 'skill' && args[1] === 'consolidate') return skillConsolidate(absRoot(arg('--path', process.cwd())));
+  if (cmd === 'gate')                               return gate(args[1] || process.cwd());
+  if (cmd === 'impact')                             return impactCmd(arg('--path', process.cwd()), args[1]);
+  if (cmd === 'reuse' && args[1] === 'find')        return reuseFind(arg('--path', process.cwd()), args.slice(2).filter(x => !x.startsWith('-')).join(' '));
+  if (cmd === 'reuse' && args[1] === 'register')    return reuseRegister(arg('--path', process.cwd()), args[2]);
+  if (cmd === 'ui' && args[1] === 'consistency')    return uiConsistency(args[2] || process.cwd());
+  if (cmd === 'graph')                              return graphCmd(args[1] || process.cwd());
+  if (cmd === 'guide')                              return guideCmd(arg('--path', process.cwd()), args[1]);
+  // legacy duplicate routing removed below (was: skill list/info/add)
   if (cmd === 'skill' && args[1] === 'info') return skillInfo(args[2]);
   if (cmd === 'skill' && args[1] === 'add')  return addSkill(absRoot(arg('--path', process.cwd())), args[2]);
   if (cmd === 'plan') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -149,6 +149,83 @@ run('route planning',      ['route', 'planning']);
 run('route bugfix',        ['route', 'bugfix']);
 run('skill list',          ['skill', 'list']);
 run('skill info',          ['skill', 'info', 'office']);
+
+// 1.9.2: 스킬 학습 사이클 회귀
+run('skill learn (new)',   ['skill', 'learn', 'open-meteo', '--doc', 'https://open-meteo.com/en/docs', '--command', 'fetch hourly+daily JSON', '--capability', 'http fetch', '--capability', 'cache', '--note', 'e2e learn', '--display', 'Open-Meteo 날씨 스킬', '--path', tmp]);
+run('skill use (new)',     ['skill', 'use', 'open-meteo', '--note', 'first call', '--path', tmp]);
+run('skill use (catalog)', ['skill', 'use', 'office', '--note', 'catalog skill materialize', '--path', tmp]);
+run('skill optimize',      ['skill', 'optimize', 'open-meteo', '--before', 'no cache', '--after', 'If-Modified-Since', '--note', 'e2e opt', '--path', tmp]);
+
+total++;
+{
+  const f = path.join(tmp, '.harness/skills/open-meteo/skill.json');
+  const ok = fs.existsSync(f) && JSON.parse(fs.readFileSync(f, 'utf8')).optimizations.length === 1;
+  console.log(ok ? '✓ skill.json optimizations 누적' : '✗ skill.json optimizations 누적 실패');
+  if (!ok) failed++;
+}
+total++;
+{
+  const data = JSON.parse(fs.readFileSync(path.join(tmp, '.harness/skills/open-meteo/skill.json'), 'utf8'));
+  const ok = data.usage.count === 1 && data.sources.length >= 1 && data.patterns.length >= 1;
+  console.log(ok ? '✓ skill usage/sources/patterns 누적' : '✗ skill usage/sources/patterns 누적 실패');
+  if (!ok) failed++;
+}
+
+run('skill consolidate',   ['skill', 'consolidate', '--threshold', '0.1', '--path', tmp]);
+run('skill remove (user)', ['skill', 'remove', 'open-meteo', '--path', tmp]);
+total++;
+{
+  const ok = !fs.existsSync(path.join(tmp, '.harness/skills/open-meteo'));
+  console.log(ok ? '✓ skill remove: 디렉토리 삭제' : '✗ skill remove: 디렉토리 잔존');
+  if (!ok) failed++;
+}
+
+// 1.9.3 회귀: impact / reuse / ui consistency / graph / guide
+// 가짜 페이지/컴포넌트/스타일 작성
+fs.mkdirSync(path.join(tmp, 'src/components'), { recursive: true });
+fs.mkdirSync(path.join(tmp, 'src/pages'), { recursive: true });
+fs.mkdirSync(path.join(tmp, 'src/styles'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'src/styles/tokens.css'), `:root { --color-primary: #ff5722; --color-text: #222222; }\n`);
+fs.writeFileSync(path.join(tmp, 'src/components/Card.html'), `<div class="card"><slot/></div>\n`);
+fs.writeFileSync(path.join(tmp, 'src/pages/home.html'), `<link href="../styles/tokens.css"><include src="../components/Card.html"/>\n`);
+fs.writeFileSync(path.join(tmp, 'src/pages/about.html'), `<link href="../styles/tokens.css"><include src="../components/Card.html"/>\n`);
+// design-system 토큰 채우기 (#ff5722 / #222222 등록)
+const dsPath = path.join(tmp, '.harness/design-system.md');
+let dsText = fs.readFileSync(dsPath, 'utf8');
+dsText = dsText.replace('| color.primary | (실제 값으로 업데이트) | |', '| color.primary | #ff5722 | 메인 컬러 |');
+dsText = dsText.replace('| color.surface | | |', '| color.surface | #222222 | 본문 텍스트 |');
+fs.writeFileSync(dsPath, dsText);
+
+run('impact: Card.html → home/about',  ['impact', 'src/components/Card.html', '--path', tmp]);
+run('reuse find: Card 후보',           ['reuse', 'find', 'Card', '--path', tmp]);
+run('reuse register: Card',            ['reuse', 'register', 'Card', '--where', 'src/components/Card.html', '--kind', 'component', '--note', 'e2e card', '--path', tmp]);
+
+total++;
+{
+  const reuse = fs.readFileSync(path.join(tmp, '.harness/reuse-map.md'), 'utf8');
+  const ok = /\| Card \| src\/components\/Card\.html \| component \|/.test(reuse);
+  console.log(ok ? '✓ reuse-map.md에 Card row 자동 추가' : '✗ Card row 미등록');
+  if (!ok) failed++;
+}
+
+run('ui consistency: pass (토큰 외 색상 없음)', ['ui', 'consistency', tmp]);
+
+// 의도적 일탈: 토큰 외 색상 추가 → ui consistency 경고
+fs.writeFileSync(path.join(tmp, 'src/pages/contact.html'), `<style>.box { color: #abcdef; background: #123456; }</style>\n`);
+total++;
+{
+  const r = cp.spawnSync(process.execPath, [CLI, 'ui', 'consistency', tmp, '--fail-on-violation'], { encoding: 'utf8' });
+  const ok = r.status === 1 && /토큰 외 값/.test(r.stdout) && /#abcdef/i.test(r.stdout);
+  console.log(ok ? '✓ ui consistency: 일탈 색상 #abcdef 검출 + 비0 종료' : '✗ ui consistency 일탈 미검출');
+  if (!ok) { failed++; console.log(r.stdout); }
+}
+
+run('graph: mermaid 출력',             ['graph', tmp]);
+run('guide: 통합 가이드',               ['guide', 'src/components/Card.html', '--path', tmp]);
+
+run('gate (all checks)',   ['gate', tmp]);
+
+run('self check (= update --check)', ['self', 'check', tmp], { });
 run('readme sync',         ['readme', 'sync', tmp]);
 run('consistency check',   ['consistency', 'check', tmp]);
 run('--version',           ['--version']);