leerness 1.7.0 → 1.8.0

package/README.md

@@ -1,19 +1,18 @@
 # Leerness
 
-Leerness는 AI 에이전트가 프로젝트의 목표, 계획, 작업 상태, 기술 결정, 디자인/기능 일관성, 검증된 스킬을 유지하며 개발하도록 돕는 AX 최적화 개발 하네스입니다.
+Leerness는 AI 에이전트가 프로젝트의 목적, 계획, 진행 상태, 설계 결정, 디자인/기능 일관성, 검증된 스킬을 지속적으로 참조하며 개발하도록 돕는 AX 최적화 개발 하네스입니다.
 
 ## 주요 기능
 
-- `plan.md` 기반 전체 계획과 범위 관리
-- `progress-tracker.md` 기반 사용자 요청 단위 상태 추적
-- `context-routing.md` 기반 작업 유형별 참조 파일 안내
-- `writeback-policy.md` 기반 작업 후 문서 갱신 규칙
-- `session close` 기반 세션 종료 인수인계와 미완료 작업 노출
-- `protected-files.md` 기반 `.harness/` 및 핵심 문서 삭제 방지
-- `design-system.md`, `consistency-policy.md`, `reuse-map.md` 기반 디자인/기능 일관성 유지
-- `readme sync` 기반 루트 `README.md` Leerness 관리 섹션 최신화
-- 한글명과 가능한 작업이 표시되는 스킬 라이브러리
-- AI 검증 스킬 업로드를 위한 토큰 게이트와 dry-run 우선 정책
+- `.harness/` 기반 장기 맥락 유지
+- `plan.md`와 `progress-tracker.md` 기반 계획/작업 추적
+- 언어 자동 감지 또는 선택 설치
+- 스킬 라이브러리 선택 설치와 한글 스킬 정보 표시
+- AI 검증 스킬의 라이브러리화, 병합, 마이그레이션, 배포 흐름 지원
+- 기존 하네스/스킬/지침 파일 비파괴 마이그레이션
+- `.env.example`, `.gitignore`, README managed section 병합 업데이트
+- 디자인 가이드 병합, 재사용 맵, 일관성 정책 제공
+- 세션 종료 인수인계와 미완료 작업 추적
 
 ## 설치
 
@@ -21,112 +20,66 @@ Leerness는 AI 에이전트가 프로젝트의 목표, 계획, 작업 상태,
 npx leerness init
 ```
 
-언어 지정:
+언어와 스킬을 명시하려면:
 
 ```bash
-npx leerness init --language ko
-npx leerness init --language en
-npx leerness init --language auto
+npx leerness init --language ko --skills recommended
+npx leerness init --language en --skills office,commerce-api
 ```
 
-추천 스킬 포함:
+기존 프로젝트 마이그레이션:
 
 ```bash
-npx leerness init --skills recommended
+npx leerness migrate --dry-run
+npx leerness migrate
 ```
 
-## 핵심 명령어
+## 설치 시 선택 흐름
 
-```bash
-leerness status .
-leerness verify .
-leerness debug .
-leerness route planning
-leerness route consistency
-leerness session close .
-```
+대화형 터미널에서 `--yes`, `--language`, `--skills`를 생략하면 Leerness가 설치 언어와 스킬 라이브러리 설치 여부를 묻습니다.
+
+- 언어: 자동 감지, 한국어, English
+- 스킬: 기본 하네스만, 추천 스킬, 전체 스킬, 직접 입력
 
-계획 관리:
+CI 또는 자동화 환경에서는 프롬프트 없이 명시 옵션을 사용하세요.
 
 ```bash
-leerness plan show
-leerness plan init --goal "프로젝트 목적"
-leerness plan add "결제 기능 구현" --status planned
-leerness plan drop "관리자 대시보드" --reason "이번 버전 범위 제외"
-leerness plan progress
-leerness plan sync
+npx leerness init --yes --language ko --skills recommended
 ```
 
-작업 추적:
+## 비파괴 마이그레이션 정책
 
-```bash
-leerness task list
-leerness task add "사용자 요청" --status requested
-leerness task update T-0001 --status in-progress
-leerness task drop T-0001 --reason "사용자가 제외"
-```
+Leerness는 마이그레이션 전에 기존 하네스, 스킬, 지침, README, 환경 예시 파일을 `.harness/archive/`에 백업합니다.
 
-README 동기화:
+덮어쓰기 위험이 있는 파일은 다음 정책을 따릅니다.
 
-```bash
-leerness readme sync .
-```
+- 프로젝트 메모리 파일은 기본 보존
+- `AGENTS.md`, `CLAUDE.md`, Copilot/Cursor 지침은 새 템플릿과 기존 내용을 병합
+- `.env.example`, `.gitignore`는 기존 내용을 유지하고 필요한 줄만 추가
+- README는 Leerness managed marker 구간만 갱신
+- 작업 결과는 `.harness/migration-report.md`에 기록
 
-디자인/기능 일관성:
+## 주요 명령어
 
 ```bash
-leerness consistency check .
-leerness consistency merge-design-guide .
-```
+leerness status .
+leerness verify .
+leerness debug .
+leerness route <task-type>
+leerness session close .
 
-스킬:
+leerness plan show
+leerness plan add "작업명" --status planned
+leerness task list
+leerness task drop T-0001 --reason "사용자 요청으로 제외"
 
-```bash
 leerness skill list
 leerness skill info commerce-api
-leerness skill add ai-verified-skill-publisher --path .
-```
 
-최신 버전 확인:
-
-```bash
-leerness self check .
-```
-
-## 생성 구조
-
-```text
-.harness/
-  plan.md
-  progress-tracker.md
-  guideline.md
-  plan-progress-boundary.md
-  project-brief.md
-  current-state.md
-  context-routing.md
-  writeback-policy.md
-  protected-files.md
-  consistency-policy.md
-  design-system.md
-  reuse-map.md
-  session-close-policy.md
-  anti-lazy-work-policy.md
-  leerness-maintenance.md
-  skills/
-  library/
-  archive/
+leerness consistency check .
+leerness readme sync .
 ```
 
-## 계획과 진행률의 역할 분리
-
-- `plan.md`: 프로젝트 목표, 범위, milestone, 제외/드랍 항목, 계획 변경 이력
-- `progress-tracker.md`: 사용자 요청 단위 상태, 증거, 다음 액션
-- `guideline.md`: 계획과 진행률을 어떻게 따라야 하는지에 대한 실행 기준
-
-## 보호 정책
-
-AI 에이전트는 `.harness/`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/leerness.mdc`, `.github/copilot-instructions.md`, 루트 `README.md`의 Leerness 관리 섹션을 임의 삭제하거나 초기화하지 않아야 합니다. 정리가 필요하면 삭제보다 병합, 아카이브, deprecated 표시를 우선합니다.
-
 ## 라이선스
 
 MIT

package/bin/harness.js

@@ -6,7 +6,7 @@ const path = require('path');
 const cp = require('child_process');
 const readline = require('readline');
 
-const VERSION = '1.7.0';
+const VERSION = '1.8.0';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -221,17 +221,116 @@ function coreFiles(root, lang = 'ko', selectedSkills = []) {
     '.harness/templates/decision.md': '# Decision\n\n## Decision\n\n## Reason\n\n## Alternatives\n\n## Impact\n'
   };
 }
-function parseSkills() {
-  const v = arg('--skills', '');
+function parseSkillsValue(v) {
   if (!v || v === true) return [];
   if (v === 'all') return Object.keys(skillCatalog);
   if (v === 'recommended') return ['office', 'commerce-api', 'ai-verified-skill-publisher'];
-  return String(v).split(',').map(s => s.trim()).filter(Boolean);
+  return String(v).split(',').map(s => s.trim()).filter(Boolean).filter(s => skillCatalog[s]);
+}
+function parseSkills() { return parseSkillsValue(arg('--skills', '')); }
+function detectLanguageValue(root, value = 'auto') {
+  const v = String(value || 'auto').toLowerCase();
+  if (v === 'ko' || v === 'en') return v;
+  const candidates = ['README.md', 'docs/guideline.md', '.harness/project-brief.md', '.harness/plan.md'];
+  let text = '';
+  for (const c of candidates) { const p = path.join(root, c); if (exists(p)) text += read(p).slice(0, 3000); }
+  return /[가-힣]/.test(text) ? 'ko' : 'en';
+}
+function ask(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, answer => { rl.close(); resolve(String(answer || '').trim()); });
+  });
+}
+async function resolveInstallOptions(root, opts = {}) {
+  const explicitLang = arg('--language', null);
+  const explicitSkills = arg('--skills', null);
+  let lang = explicitLang ? detectLanguageValue(root, explicitLang) : detectLanguageValue(root, 'auto');
+  let skills = explicitSkills ? parseSkillsValue(explicitSkills) : [];
+  const shouldAsk = !has('--yes') && !opts.nonInteractive && process.stdin.isTTY && process.stdout.isTTY && !opts.migration;
+  if (shouldAsk && !explicitLang) {
+    log('\n설치 언어를 선택하세요.');
+    log('1) 자동 감지');
+    log('2) 한국어');
+    log('3) English');
+    const a = await ask('선택 [1]: ');
+    lang = a === '2' ? 'ko' : a === '3' ? 'en' : detectLanguageValue(root, 'auto');
+  }
+  if (shouldAsk && !explicitSkills) {
+    log('\n설치할 스킬 라이브러리를 선택하세요.');
+    log('0) 기본 하네스만 설치');
+    log('1) 추천 스킬 설치: office, commerce-api, ai-verified-skill-publisher');
+    log('2) 전체 스킬 설치');
+    log('3) 직접 입력');
+    skillList();
+    const a = await ask('선택 [1]: ');
+    if (!a || a === '1') skills = parseSkillsValue('recommended');
+    else if (a === '2') skills = parseSkillsValue('all');
+    else if (a === '3') skills = parseSkillsValue(await ask('스킬 ID를 쉼표로 입력: '));
+    else if (a === '0') skills = [];
+  }
+  return { lang, skills };
+}
+function copyRecursiveSafe(src, dst) {
+  if (!exists(src)) return;
+  if (src.includes(path.sep + '.harness' + path.sep + 'archive')) return;
+  const st = fs.statSync(src);
+  if (st.isDirectory()) {
+    mkdirp(dst);
+    for (const e of fs.readdirSync(src)) {
+      if (e === 'node_modules' || e === '.git') continue;
+      copyRecursiveSafe(path.join(src, e), path.join(dst, e));
+    }
+  } else {
+    mkdirp(path.dirname(dst));
+    fs.copyFileSync(src, dst);
+  }
+}
+function migrationCandidates(root, files) {
+  const fixed = [
+    'AGENTS.md','CLAUDE.md','.cursor/rules/leerness.mdc','.cursor/rules/project-rules.mdc',
+    '.github/copilot-instructions.md','README.md','.env.example','.gitignore',
+    'docs/guideline.md','docs/history.md','guideline.md','history.md',
+    'AI_HARNESS.md','HARNESS.md','PROJECT_CONTEXT.md','CONTEXT.md','ARCHITECTURE.md','DECISIONS.md','CURRENT_STATE.md','TASK_LOG.md',
+    '.harness','.ai','harness'
+  ];
+  const all = Array.from(new Set([...fixed, ...Object.keys(files)]));
+  return all.filter(f => exists(path.join(root, f)));
+}
+function createBackup(root, reason, files, dry = false) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const ar = path.join(root, '.harness/archive', `leerness-${VERSION}-${stamp}`);
+  const candidates = migrationCandidates(root, files);
+  if (dry) return { archiveDir: ar, candidates };
+  mkdirp(ar);
+  const fileRoot = path.join(ar, 'files');
+  for (const f of candidates) copyRecursiveSafe(path.join(root, f), path.join(fileRoot, f === '.harness' ? '.harness-before-migration' : f));
+  write(path.join(ar, 'migration-manifest.json'), JSON.stringify({
+    version: VERSION,
+    reason,
+    createdAt: now(),
+    policy: 'backup-before-write; preserve-by-default; merge-managed-files; merge-env-and-gitignore',
+    candidates
+  }, null, 2) + '\n');
+  return { archiveDir: ar, candidates };
+}
+function managedMerge(file, next, previous, archiveDir) {
+  if (!previous || previous.trim() === next.trim()) return next;
+  const tag = '<!-- leerness:migration-preserved -->';
+  if (previous.includes(tag)) return next;
+  return next.trimEnd() + `\n\n---\n${tag}\n## Preserved previous content\n\nPrevious content was backed up before migration. Archive reference:\n\n\`${archiveDir ? path.relative(process.cwd(), archiveDir).replace(/\\/g, '/') : '.harness/archive'}\`\n\nThe content below is retained so AI agents can migrate useful custom instructions instead of losing them.\n\n<details>\n<summary>Previous ${file}</summary>\n\n\`\`\`md\n${previous.replace(/```/g, '\\`\\`\\`')}\n\`\`\`\n\n</details>\n`;
 }
 function writeIfSafe(root, file, content, opts = {}) {
   const p = path.join(root, file);
-  if (exists(p) && !opts.force) return { action: 'preserved', file };
-  write(p, content); return { action: exists(p) ? 'updated' : 'created', file };
+  const already = exists(p);
+  if (already && !opts.force && !opts.mergeManaged) return { action: 'preserved', file };
+  if (already && opts.mergeManaged && !opts.force) {
+    const prev = read(p);
+    write(p, managedMerge(file, content, prev, opts.archiveDir));
+    return { action: 'merged', file };
+  }
+  write(p, content);
+  return { action: already ? 'updated' : 'created', file };
 }
 function mergeLinesFile(p, lines) {
   const current = exists(p) ? read(p) : '';
@@ -239,22 +338,54 @@ function mergeLinesFile(p, lines) {
   for (const line of lines) if (!next.includes(line)) next += (next.endsWith('\n') || !next ? '' : '\n') + line + '\n';
   write(p, next);
 }
+function writeMigrationReport(root, backup, actions) {
+  const p = path.join(root, '.harness/migration-report.md');
+  const rows = actions.map(a => `| ${a.file} | ${a.action} |`).join('\n');
+  write(p, `# Leerness Migration Report\n\nVersion: ${VERSION}\nDate: ${now()}\nBackup: ${rel(root, backup.archiveDir)}\n\n## Policy\n\n- Existing harness, skill, and instruction files are backed up before migration.\n- Project memory files are preserved by default.\n- Managed instruction files are merged with previous content instead of being blindly overwritten.\n- .env.example and .gitignore are line-merged only.\n\n## Backed Up Candidates\n\n${backup.candidates.map(x => '- ' + x).join('\n')}\n\n## File Actions\n\n| File | Action |\n|---|---|\n${rows}\n`);
+}
 function syncReadme(root) {
   const p = path.join(root, 'README.md');
   const existing = exists(p) ? read(p) : '';
   write(p, mergeSection(existing, managedReadmeBlock(detectProjectName(root))));
   ok('README.md Leerness section synced');
 }
-function install(root, opts = {}) {
+async function install(root, opts = {}) {
   root = absRoot(root); mkdirp(root);
-  const lang = detectLanguage(root); const skills = parseSkills();
-  log(`\nLeerness v${VERSION}`); log(`Target: ${root}`); log(`Language: ${lang}`);
-  if (!opts.dry) archive(root, opts.force ? 'force' : 'safe');
+  const resolved = await resolveInstallOptions(root, opts);
+  const lang = resolved.lang;
+  const skills = resolved.skills;
+  log(`\nLeerness v${VERSION}`);
+  log(`Target: ${root}`);
+  log(`Language: ${lang}`);
+  log(`Skills: ${skills.length ? skills.join(', ') : 'none'}`);
   const files = coreFiles(root, lang, skills);
+  const backup = createBackup(root, opts.force ? 'force' : (opts.migration ? 'migration' : 'init'), files, opts.dry);
+  if (opts.dry) {
+    log(`Backup target: ${backup.archiveDir}`);
+    log('Files that would be backed up:');
+    backup.candidates.forEach(f => log('- ' + f));
+  } else {
+    ok(`backup created: ${rel(root, backup.archiveDir)}`);
+  }
+  const managedOverwrite = new Set([
+    'AGENTS.md','CLAUDE.md','.cursor/rules/leerness.mdc','.github/copilot-instructions.md',
+    '.harness/HARNESS_VERSION','.harness/manifest.json','.harness/LANGUAGE','.harness/skills-lock.json',
+    '.harness/context-routing.md','.harness/writeback-policy.md','.harness/task-type-map.md',
+    '.harness/leerness-maintenance.md','.harness/protected-files.md','.harness/AX_MIGRATION_GUIDE.md',
+    '.harness/AX_NEW_PROJECT_GUIDE.md','.harness/AX_SKILL_LIBRARY_GUIDE.md'
+  ]);
+  const actions = [];
   for (const [f, c] of Object.entries(files)) {
-    if (opts.dry) { log(`[dry-run] ${exists(path.join(root, f)) ? 'preserve/update' : 'create'} ${f}`); continue; }
-    const allowOverwrite = ['AGENTS.md','CLAUDE.md','.cursor/rules/leerness.mdc','.github/copilot-instructions.md','.harness/HARNESS_VERSION','.harness/manifest.json','.harness/LANGUAGE','.harness/skills-lock.json','.harness/context-routing.md','.harness/writeback-policy.md','.harness/task-type-map.md','.harness/leerness-maintenance.md'].includes(f) || opts.force;
-    const r = writeIfSafe(root, f, c, { force: allowOverwrite });
+    const existsNow = exists(path.join(root, f));
+    const mergeManaged = managedOverwrite.has(f);
+    if (opts.dry) {
+      const action = existsNow ? (mergeManaged || opts.force ? 'merge/update from backup-aware template' : 'preserve') : 'create';
+      log(`[dry-run] ${action}: ${f}`);
+      actions.push({ file:f, action });
+      continue;
+    }
+    const r = writeIfSafe(root, f, c, { force: opts.force, mergeManaged, archiveDir: backup.archiveDir });
+    actions.push(r);
     ok(`${r.action}: ${r.file}`);
   }
   if (!opts.dry) {
@@ -262,12 +393,9 @@ function install(root, opts = {}) {
     mergeLinesFile(path.join(root, '.env.example'), ['# Leerness uses environment variable names only. Do not store real secrets here.', 'LEERNESS_NPM_TOKEN=', 'LEERNESS_GITHUB_TOKEN=']);
     syncReadme(root);
     installSkills(root, skills);
+    writeMigrationReport(root, backup, actions);
   }
 }
-function archive(root, reason) {
-  const ar = path.join(root, '.harness/archive', `leerness-${VERSION}-${new Date().toISOString().replace(/[:.]/g,'-')}`);
-  mkdirp(ar); write(path.join(ar, 'migration-manifest.json'), JSON.stringify({ version: VERSION, reason, createdAt: now() }, null, 2) + '\n');
-}
 function installSkills(root, skills) {
   for (const name of skills) addSkill(root, name, true);
 }
@@ -317,12 +445,12 @@ function mergeDesign(root) { root = absRoot(root); const canonical = path.join(r
 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 local = exists(path.join(root,'.harness/HARNESS_VERSION')) ? read(path.join(root,'.harness/HARNESS_VERSION')).trim() : 'not installed'; log(`CLI: ${VERSION}`); log(`Project: ${local}`); log(`NPM latest: ${latest}`); }
 function publishLibrary(targetPath, target) { const execute = has('--execute'); if (!execute) { log('dry-run only. Add --execute to publish.'); return; } const envs = target === 'npm' ? ['LEERNESS_NPM_TOKEN','NPM_TOKEN','NODE_AUTH_TOKEN'] : ['LEERNESS_GIT_TOKEN','LEERNESS_GITHUB_TOKEN','GITHUB_TOKEN','GH_TOKEN']; const found = envs.find(e => process.env[e]); if (!found && has('--no-prompt')) { fail('publish token not found'); process.exitCode = 1; return; } if (!found) { fail(`publish token required. Set one of: ${envs.join(', ')}`); process.exitCode = 1; return; } ok(`token provided by ${found}; publish command would execute for ${targetPath}`); }
 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 status [path]\n  leerness verify [path]\n  leerness debug [path]\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  leerness session close [path]\n`); }
-function main() {
+async function main() {
   const args = nonFlagArgs(); const cmd = args[0] || 'init';
   if (has('--version') || has('-v')) return log(VERSION);
   if (has('--help') || has('-h')) return help();
-  if (cmd === 'init') return install(args[1] || process.cwd(), { force:false, dry:false });
-  if (cmd === 'migrate') return install(args[1] || process.cwd(), { force:has('--force'), dry:has('--dry-run') });
+  if (cmd === 'init') return await install(args[1] || process.cwd(), { force:false, dry:false, migration:false });
+  if (cmd === 'migrate') return await install(args[1] || process.cwd(), { force:has('--force'), dry:has('--dry-run'), migration:true });
   if (cmd === 'status') return status(args[1] || process.cwd());
   if (cmd === 'verify') return verify(args[1] || process.cwd());
   if (cmd === 'debug') return debug(args[1] || process.cwd());
@@ -341,4 +469,4 @@ function main() {
   if (cmd === 'library' && args[1] === 'publish') return publishLibrary(args[2] || '.', arg('--target','npm'));
   return help();
 }
-main();
+main().catch(err => { fail(err && err.message ? err.message : String(err)); process.exitCode = 1; });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "leerness",
-  "version": "1.7.0",
-  "description": "Leerness: AI 에이전트의 장기 맥락, 계획, 작업 추적, 스킬 라이브러리, 디자인/기능 일관성, 세션 인수인계를 관리하는 AX 최적화 개발 하네스.",
+  "version": "1.8.0",
+  "description": "Leerness: 비파괴 마이그레이션, 언어/스킬 선택 설치, 계획/작업 추적, 스킬 라이브러리, 디자인/기능 일관성을 관리하는 AX 최적화 AI 개발 하네스.",
   "keywords": [
     "leerness",
     "ai",