@angar2/taskery 0.4.0 → 0.6.0

package/README.md

@@ -39,7 +39,7 @@ draft → planned → developing → developed → testing → tested → closed
 | `developed` | 구현 완료 (자가 검증 통과) |
 | `testing` | 독립 검증 진행 중 |
 | `tested` | 독립 검증 완료 |
-| `closed` | git 커밋 + dev 병합 완료 |
+| `closed` | git 커밋 + 부모 브랜치 병합 완료 |
 
 > 상태별 전이 조건과 task 문서 양식은 [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md)에서 확인 가능
 
@@ -153,8 +153,8 @@ my-app/
 같은 프로젝트에서 여러 메인 세션을 동시에 운영해 독립 task를 병렬로 진행한다.
 
 - 새 task를 시작하면(`/task-init`) 작업 폴더(`~/.taskery/worktrees/<projectId>/TASK-NNN_<출처>_<슬러그>/`)와 작업 브랜치를 함께 분기한다.
-- 작업 폴더에서 새 메인 세션을 열어 진행하거나, 메인 세션 1개로 모든 작업을 지휘하거나, 메인이 서브 세션을 호출해 병렬로 진행한다 — 운영 방식은 자유. 메인 워크트리(원본 폴더)는 `dev` 전용 상태로 유지된다.
-- task 완료(`/task-close`) 시 머지 락으로 직렬화한 후 dev에 `--no-ff` 병합한다. 다른 세션이 먼저 머지해 충돌이 발생하면 본 세션이 단순/의미적/판단 불가 3단계로 해결을 시도한다.
+- 작업 폴더에서 새 메인 세션을 열어 진행하거나, 메인 세션 1개로 모든 작업을 지휘하거나, 메인이 서브 세션을 호출해 병렬로 진행한다 — 운영 방식은 자유. 메인 워크트리(원본 폴더)는 task를 시작한 브랜치(*부모 브랜치*, 기본은 `dev`)를 그대로 유지한다.
+- task 완료(`/task-close`) 시 머지 락으로 직렬화한 후 **그 부모 브랜치**에 `--no-ff` 병합한다(개인은 `dev`, 회사/로드맵은 서 있던 브랜치). 다른 세션이 먼저 머지해 충돌이 발생하면 본 세션이 단순/의미적/판단 불가 3단계로 해결을 시도한다.
 - 머지 직후 작업 폴더와 작업 브랜치는 자동 정리된다(보존 키워드 사용 시 양쪽 유지). 안전망으로 복구 명령이 함께 출력된다.
 
 요건: git ≥ 2.31. 보조 명령 `npx @angar2/taskery status` / `prune`로 진행 현황과 stale 정리를 확인한다.
@@ -189,7 +189,7 @@ my-app/
 | `/task-plan` | task | task의 요구사항·범위·개발 계획·테스트 계획 작성 |
 | `/task-dev` | task | 계획에 따른 단계별 구현 + 자가 검증 |
 | `/task-test` | task | 별도 격리 세션에서 독립 검증 (메인 가정 차단) |
-| `/task-close` | task | 최종 검증 후 git 커밋 + dev 브랜치 `--no-ff` 병합 |
+| `/task-close` | task | 최종 검증 후 git 커밋 + 부모 브랜치 `--no-ff` 병합 |
 | `/add-backlog` | meta | 사용자 발화로 plan(기능 그룹)별 `tasks/<NNN_slug>/BACKLOG.md`에 task 후보 1건씩 추가 (0.1.2+) |
 | `/log-friction` | meta | 사용자 불편을 `.project/FRICTION_LOG.md`에 한 행 기록 |
 | `/run-team` | meta | 여러 작업을 묶을 수 있는 단위로 task로 나눠 자동 병렬 처리 — 리더 세션이 팀원(독립 세션)에게 task를 1건씩 분배하고 흐름을 관리 (Claude 전용 · 실험 기능 전제 · 0.3.x+) |
@@ -240,7 +240,7 @@ npx @angar2/taskery init
 /task-plan TASK-001            # draft → planned : 요구사항·범위·개발 계획·테스트 계획 작성
 /task-dev TASK-001             # planned → developed : 단계별 구현과 자체 검증
 /task-test TASK-001            # developed → tested : 별도 격리 세션으로 독립 검증
-/task-close TASK-001           # tested → closed : 최종 검증 후 git 커밋과 dev 병합
+/task-close TASK-001           # tested → closed : 최종 검증 후 git 커밋과 부모 브랜치 병합
 
 # 불편 발생 시 등록
 /log-friction                  # 사용자 불편 한 행 기록

package/bin/backlog.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// 활성 plan별 BACKLOG.md 조작 CLI — add(추가) / get(조회) / mark(확인 마킹) 묶음
+/**
+ * bin/backlog.js
+ * `npx @angar2/taskery backlog-add|backlog-get|backlog-mark ...` — 백로그 조작.
+ *
+ * dispatcher(taskery.js)가 서브op(add|get|mark)를 첫 인자로 주입한다.
+ *   add  --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>
+ *        → withMetaLock + BL-NNN 채번 + append. stdout: { blNum, blId }
+ *   get  <BL-NNN>          → 항목 메타 JSON ({ blId, status, type, title, slug, summary, target, taskNums }). 없으면 exit 1
+ *   mark <BL-NNN> <TASK-NNN> → withMetaLock + [ ]→[x] + TASK 마크. stdout: { blId, taskNum }
+ *
+ * 채번·서식·락은 전부 코드(lib.js)가 보장 — LLM 손 파싱/Edit 제거.
+ * 실패(인자 미달 / 활성 plan 부재 / 항목 없음 등) 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  appendBacklogItem,
+  parseBacklogItem,
+  markBacklogChecked,
+} = require('./lib');
+
+function parseFlags(argv) {
+  // --key value | --key=value 둘 다 지원. 정의된 키만 수집.
+  const KEYS = ['type', 'title', 'slug', 'summary', 'target'];
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const eq = a.indexOf('=');
+    let key;
+    let val;
+    if (eq !== -1) {
+      key = a.slice(2, eq);
+      val = a.slice(eq + 1);
+    } else {
+      key = a.slice(2);
+      val = argv[++i];
+    }
+    if (KEYS.includes(key)) out[key] = val;
+  }
+  return out;
+}
+
+function parseTaskNum(token) {
+  // 'TASK-007' | 'TASK-7' | '7' → 7
+  const m = String(token).match(/(\d+)/);
+  return m ? parseInt(m[1], 10) : NaN;
+}
+
+function resolveMainWt() {
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery backlog 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+  return mainWt;
+}
+
+async function doAdd(rest) {
+  const meta = parseFlags(rest);
+  const missing = ['type', 'title', 'slug', 'summary', 'target'].filter((k) => !meta[k]);
+  if (missing.length) {
+    console.error(
+      `사용법: npx @angar2/taskery backlog-add --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>`,
+    );
+    console.error(`누락: ${missing.map((k) => '--' + k).join(', ')}`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  const blNum = await appendBacklogItem(mainWt, meta);
+  const blId = `BL-${String(blNum).padStart(3, '0')}`;
+  process.stdout.write(JSON.stringify({ blNum, blId }) + '\n');
+}
+
+function doGet(rest) {
+  const blId = rest[0];
+  if (!blId || !/^BL-\d+$/.test(blId)) {
+    console.error(`사용법: npx @angar2/taskery backlog-get <BL-NNN>`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  const item = parseBacklogItem(mainWt, blId);
+  if (!item) {
+    console.error(`${blId} 항목 없음.`);
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify(item) + '\n');
+}
+
+async function doMark(rest) {
+  const blId = rest[0];
+  const taskNum = parseTaskNum(rest[1]);
+  if (!blId || !/^BL-\d+$/.test(blId) || !Number.isInteger(taskNum)) {
+    console.error(`사용법: npx @angar2/taskery backlog-mark <BL-NNN> <TASK-NNN>`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  await markBacklogChecked(mainWt, blId, taskNum);
+  process.stdout.write(JSON.stringify({ blId, taskNum }) + '\n');
+}
+
+async function main() {
+  const op = process.argv[2];
+  const rest = process.argv.slice(3);
+  try {
+    if (op === 'add') await doAdd(rest);
+    else if (op === 'get') doGet(rest);
+    else if (op === 'mark') await doMark(rest);
+    else {
+      console.error(`backlog: 알 수 없는 op '${op}' (add | get | mark)`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`taskery backlog-${op} 실패: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/close.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// task close 결정적 준비 CLI — Phase 커밋·status=closed·flows/문서 커밋·추적마커 (비가역 머지/정리는 스킬)
+/**
+ * bin/close.js
+ * `npx @angar2/taskery close <TASK-NNN>` — close 결정적 준비.
+ *
+ * 게이트(status=tested) → Phase 커밋(D2 자동 매핑) → status=closed → flows/문서 커밋 → 추적마커까지
+ * 코드가 수행하고 멈춘다. 이후 비가역(사전 rebase+충돌해결 / 머지 락 / 부모 --no-ff 머지 /
+ * worktree remove / branch -d)은 스킬(task-close)이 git-guard hook + 복구출력 보호 하에 수행.
+ *
+ * stdout: { prepped, branch, parent, wtPath, registered, commits, aheadOfParent }. parent = 머지 대상. exit 0.
+ * 콜백(스킬이 LLM 판단 후 처리):
+ *   - exit 3 + { blocked:'status', current }  — status가 tested 아님 (게이트 차단)
+ *   - exit 2 + { blocked:'mapping', files, phases, reason } — Phase↔파일 매핑 모호 (수동 커밋 필요)
+ * 그 외 실패 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  closeTask,
+} = require('./lib');
+
+async function main() {
+  const arg = process.argv[2];
+  const m = String(arg || '').match(/(\d+)/);
+  if (!m) {
+    console.error('사용법: npx @angar2/taskery close <TASK-NNN>');
+    process.exit(1);
+  }
+  const taskNum = parseInt(m[1], 10);
+
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery close 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = await closeTask(mainWt, { taskNum });
+  } catch (e) {
+    console.error(`taskery close 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (result.blocked === 'status') {
+    console.error(
+      `close 게이트 차단 — status=${result.current} (tested 아님). /task-test 통과 후 재호출.`,
+    );
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(3);
+  }
+  if (result.blocked === 'mapping') {
+    console.error(
+      `Phase↔파일 매핑 모호 (${result.reason}) — Dev Plan '파일' 필드 확인 후 수동 Phase 커밋 필요.`,
+    );
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(2);
+  }
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+
+main();

package/bin/fork.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 /**
  * bin/fork.js
- * `npx @angar2/taskery fork <type> <dev> <src> <slug>` — task 분기.
+ * `npx @angar2/taskery fork <type> <dev> <src> <slug> [--size <s> --title "<t>" --promote]` — task 분기.
  *
  * [채번 → 워크트리·브랜치 생성]을 init 락으로 원자 실행 (병렬 task-init 번호 충돌 차단).
- * 성공 시 결과 JSON 한 줄을 stdout으로 출력 ({ taskNum, nnn, branch, wtPath, projectId }).
+ * --size·--title 주면 fork 직후 §1.3 빈 골격 task.md도 코드가 자동 생성(C1, 생성일·status=draft 자동).
+ * 성공 시 결과 JSON 한 줄을 stdout으로 출력 ({ taskNum, nnn, branch, wtPath, projectId, [docPath, registered, promoted | scaffoldError] }).
  * 실패(정책 위배 / 동일 항목 진행중 / 동일 브랜치명 등) 시 stderr + exit 1.
+ * 골격 생성 실패는 워크트리 생성을 무효화하지 않음 — exit 0 + scaffoldError로 보고(스킬이 폴백 Write).
  *
  * 호출 주체: `/task-init` Step 6 (사용자 직접 호출도 가능하나 통상 스킬 경유).
  */
@@ -17,16 +19,38 @@ const {
   readManifest,
   getMainWorktreePath,
   forkTask,
+  scaffoldTaskDoc,
 } = require('./lib');
 
 const VALID_TYPES = ['feature', 'bug', 'improve', 'refactor', 'docs', 'chore'];
+const VALID_SIZES = ['micro', 'small', 'medium', 'large'];
 
 async function main() {
-  const [type, dev, src, slug] = process.argv.slice(2);
+  // 위치 인자 4개 + 플래그(--size <s> / --title "<t>" / --promote).
+  const argv = process.argv.slice(2);
+  const positional = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--promote') {
+      opts.promote = true;
+    } else if (a.startsWith('--')) {
+      opts[a.slice(2)] = argv[++i];
+    } else {
+      positional.push(a);
+    }
+  }
+  const [type, dev, src, slug] = positional;
 
   if (!type || !dev || !src || !slug) {
-    console.error('사용법: npx @angar2/taskery fork <type> <dev> <src> <slug>');
-    console.error('예: npx @angar2/taskery fork feature claude BL-003 login-feature');
+    console.error(
+      '사용법: npx @angar2/taskery fork <type> <dev> <src> <slug> [--size <s> --title "<제목>" --promote]',
+    );
+    console.error('예: npx @angar2/taskery fork feature claude BL-003 login --size medium --title "로그인 기능"');
+    process.exit(1);
+  }
+  if (opts.size && !VALID_SIZES.includes(opts.size)) {
+    console.error(`--size는 ${VALID_SIZES.join(' | ')} 중 하나 (받음: ${opts.size})`);
     process.exit(1);
   }
   if (!VALID_TYPES.includes(type)) {
@@ -54,13 +78,33 @@ async function main() {
     process.exit(1);
   }
 
+  let result;
   try {
-    const result = await forkTask(mainWt, { type, dev, src, slug });
-    process.stdout.write(JSON.stringify(result) + '\n');
+    result = await forkTask(mainWt, { type, dev, src, slug });
   } catch (e) {
     console.error(`taskery fork 실패: ${e.message}`);
     process.exit(1);
   }
+
+  // 골격 자동 생성 (--size·--title 제공 시). 워크트리는 이미 생성됐으므로 실패해도 exit 1 X.
+  let out = result;
+  if (opts.size && opts.title) {
+    try {
+      const doc = scaffoldTaskDoc(mainWt, result.wtPath, {
+        taskNum: result.taskNum,
+        slug,
+        title: opts.title,
+        type,
+        size: opts.size,
+        parent: result.parent,
+        promoted: !!opts.promote,
+      });
+      out = { ...result, docPath: doc.file, registered: doc.registered, promoted: doc.promoted };
+    } catch (e) {
+      out = { ...result, scaffoldError: e.message };
+    }
+  }
+  process.stdout.write(JSON.stringify(out) + '\n');
 }
 
 main();

package/bin/init.js

@@ -161,6 +161,29 @@ async function main() {
     console.log(`  .gitignore — 사용자 선택으로 패스`);
   }
 
+  // 4.7. MCP 서버 등록 — Claude는 .mcp.json 생성(첫 세션 승인 게이트), Codex는 명령 안내.
+  //   MCP 도구 8종 = lib core의 구조화 입구(CLI와 동일 함수). 미등록 환경은 npx CLI가 폴백.
+  if (platforms.includes('claude')) {
+    const mcpJsonPath = path.join(cwd, '.mcp.json');
+    let mcpConfig = { mcpServers: {} };
+    if (fs.existsSync(mcpJsonPath)) {
+      // 기존 .mcp.json의 다른 서버 보존 — taskery 항목만 머지.
+      try {
+        mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
+      } catch (e) {
+        mcpConfig = { mcpServers: {} };
+      }
+      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    }
+    if (!mcpConfig.mcpServers.taskery) {
+      mcpConfig.mcpServers.taskery = { command: 'npx', args: ['-y', '@angar2/taskery', 'mcp'] };
+      fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+      console.log(`  .mcp.json — taskery MCP 서버 등록 (첫 세션에서 승인 필요)`);
+    } else {
+      console.log(`  .mcp.json — taskery 서버 이미 등록됨, 스킵`);
+    }
+  }
+
   // 5. 결과 보고
   console.log(`\n✅ taskery init 완료`);
   console.log(`   카피: ${copied}개 / 스킵: ${skipped}개`);
@@ -168,11 +191,16 @@ async function main() {
   console.log(`   manifest: ${MANIFEST_NAME}\n`);
   const entryFile = platforms.includes('claude') ? 'CLAUDE.md' : 'AGENTS.md';
   console.log(`다음 단계:`);
-  console.log(`  1. ${entryFile} 정독 + 프로젝트 메타 + 검증 명령 채우기`);
+  let step = 1;
+  console.log(`  ${step++}. ${entryFile} 정독 + 프로젝트 메타 + 검증 명령 채우기`);
+  if (platforms.includes('claude')) {
+    console.log(`  ${step++}. Claude 첫 세션에서 taskery MCP 서버 승인 (.mcp.json — 구조화 도구 8종; 미승인 시 npx CLI 폴백)`);
+  }
   if (platforms.includes('codex')) {
-    console.log(`  2. Codex 최초 1회 '/hooks'로 hook trust 승인 (.codex/config.toml — git-guard / closed-immutable)`);
+    console.log(`  ${step++}. Codex 최초 1회 '/hooks'로 hook trust 승인 (.codex/config.toml — git-guard / closed-immutable)`);
+    console.log(`     + MCP 등록: codex mcp add taskery -- npx -y @angar2/taskery mcp`);
   }
-  console.log(`  3. 에이전트 진입 → '/project-init' → '/plan-init <기능그룹>' → '/task-init'\n`);
+  console.log(`  ${step++}. 에이전트 진입 → '/project-init' → '/plan-init <기능그룹>' → '/task-init'\n`);
 }
 
 main().catch((e) => {