@angar2/taskery 0.8.1 → 1.0.1

package/bin/update.js

@@ -1,286 +1,83 @@
 #!/usr/bin/env node
-/**
- * bin/update.js
- * `npx @angar2/taskery update` — template/ 최신 자산과 사용자 측 비교 + 머지 갱신.
- *
- * 머지 로직 (DISTRIBUTION.md §6):
- *   1. .taskery-manifest.json (cwd) 읽기 — 없으면 에러 ('init' 먼저)
- *   2. template/ 정독 → 새 해시 맵
- *   3. 각 파일 분기:
- *      a. 동일 (new == manifest) → 미터치
- *      b. 신규 (manifest에 없음) → 카피 + manifest에 추가
- *      c. 변경 (new != manifest):
- *         - 사용자 측 == manifest 해시 → 사용자 customize 없음 → 자동 갱신
- *         - 사용자 측 != manifest 해시 → 사용자 customize → *.bak 백업 + confirm
- *      d. 사라짐 (manifest에 있는데 template에 없음) → 사용자에게 경고만, 사용자 파일 보존
- *   4. *.local.md suffix → manifest에 없음 → 미터치 (방어)
- *   5. manifest 갱신 + 결과 요약
- */
-
+// update — 설치된 taskery 파일을 이 버전으로 갱신한다. 사용자가 고친 파일은 묻고, AGENTS.md는 프로젝트 절을 살려 재조립한다
 const fs = require('fs');
 const path = require('path');
-const readline = require('readline');
-
-const {
-  MANIFEST_NAME,
-  findTemplateDir,
-  walkTemplate,
-  sha256,
-  copyFile,
-  writeManifest,
-  readManifest,
-  getPackageVersion,
-  isLocalOverride,
-  generateProjectId,
-  DEFAULT_STALE_DAYS,
-  DEFAULT_LOCK_TIMEOUT_MS,
-  DEFAULT_PLATFORMS,
-  resolveInstallPlan,
-} = require('./lib');
-
-const {
-  ENTRY_DOCS_MARKER,
-  mergeGitignore,
-  ingestActivePlan,
-  retireLegacyAgentGuide,
-  recomposeEntryDocs,
-  planGitignore,
-  planTestGuide,
-} = require('./migrate');
-
-async function confirm(msg) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`${msg} (y/N) `, (ans) => {
-      rl.close();
-      resolve(ans.trim().toLowerCase() === 'y');
-    });
-  });
-}
+const L = require('./lib');
+const I = require('./install');
 
 async function main() {
   const cwd = process.cwd();
-  const templateDir = findTemplateDir();
-  const manifestPath = path.join(cwd, MANIFEST_NAME);
-
-  // 1. manifest 검사
-  const oldManifest = readManifest(manifestPath);
-  if (!oldManifest) {
-    console.error(
-      `taskery update: ${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`,
-    );
-    process.exit(1);
-  }
-
-  // 2. 설치된 플랫폼 자산만 갱신 대상 (platforms 누락 시 마이그레이션 기본값)
-  //    설치 계획(installRel 기준)으로 전개 — shared/는 플랫폼 경로로 매핑된 상태.
-  //    newTemplateFiles: installRel → { hash(소스), templateRel(복사 원본) }
-  const platforms = Array.isArray(oldManifest.platforms)
-    ? oldManifest.platforms
-    : DEFAULT_PLATFORMS;
-  const plan = resolveInstallPlan(walkTemplate(templateDir), platforms);
-  const newTemplateFiles = {};
-  for (const it of plan) {
-    newTemplateFiles[it.installRel] = { hash: it.hash, templateRel: it.templateRel };
-  }
-  const oldFiles = oldManifest.files || {};
-
-  console.log(`\ntaskery update`);
-  console.log(`  현재 manifest 버전: ${oldManifest.version}`);
-  console.log(`  새 패키지 버전: ${getPackageVersion()}\n`);
-
-  const newFiles = {};
-  const summary = { unchanged: 0, new: 0, autoUpdated: 0, customizedReplaced: 0, skipped: 0, removed: 0 };
-
-  // 2.5. 진입 문서 재조립 — **본 루프보다 먼저, 그리고 매 update 항상.**
-  //   AGENTS.md는 리포 값을 품어 템플릿과 바이트 일치가 원리적으로 불가능하다. 본 루프에 맡기면
-  //   '사용자 customize 검출'이 떠서, 덮으면 리포 값이 .bak에만 남고 거절하면 구판 문안에 고착된다.
-  //   재조립이 최종 상태까지 기록하고, 처리한 경로는 아래 루프에서 제외한다.
-  const entryMig = recomposeEntryDocs(cwd, templateDir, platforms, oldManifest);
-  const entryHandled = new Set(entryMig.handled);
-  for (const line of entryMig.notes) console.log(`  ${line}`);
-  Object.assign(newFiles, entryMig.entries);
-
-  // 3. 새 template 파일 분기 (rel = 설치 경로 installRel)
-  for (const [rel, { hash: newHash, templateRel }] of Object.entries(newTemplateFiles)) {
-    if (entryHandled.has(rel)) {
-      // 2.5에서 이행 완료(또는 보류) — 본 루프가 다시 손대면 이행 결과를 덮는다.
-      if (entryMig.held && oldFiles[rel]) newFiles[rel] = oldFiles[rel];
-      continue;
-    }
-    if (isLocalOverride(rel)) {
-      // template에 .local.md 들어가면 안 되지만 방어적 스킵
-      console.log(`  skip (.local override 영역): ${rel}`);
-      summary.skipped++;
-      continue;
-    }
-
-    const src = path.join(templateDir, templateRel);
-    const dst = path.join(cwd, rel);
-    const oldEntry = oldFiles[rel];
-
-    // .gitignore는 *절대 덮어쓰지 않는다* — 사용자 무시 규칙이 통째로 날아간다.
-    // 없으면 복사, 있으면 빠진 줄만 덧붙인다(migrate.mergeGitignore).
-    if (rel === '.gitignore') {
-      const r = mergeGitignore(src, dst);
-      newFiles[rel] = { hash: newHash, core: true, managed: true };
-      if (!r.merged) { summary.new++; console.log(`  new: ${rel}`); }
-      else if (r.added.length) { summary.autoUpdated++; console.log(`  merge: ${rel} — ${r.added.length}줄 추가 (기존 줄 보존)`); }
-      else { summary.unchanged++; }
-      continue;
-    }
-
-    // a. 신규 — manifest에 없음
-    if (!oldEntry) {
-      copyFile(src, dst);
-      newFiles[rel] = { hash: newHash, core: true, managed: true };
-      summary.new++;
-      console.log(`  new: ${rel}`);
-      continue;
-    }
-
-    const oldManifestHash = oldEntry.hash;
-
-    // b. 동일 — new == manifest → 미터치 (manifest 항목 그대로)
-    if (newHash === oldManifestHash) {
-      newFiles[rel] = oldEntry;
-      summary.unchanged++;
-      continue;
-    }
-
-    // c. 변경 — new != manifest
-    // 사용자 측 해시 비교
-    let userHash = null;
-    if (fs.existsSync(dst)) {
-      userHash = sha256(dst);
-    }
-
-    if (userHash === oldManifestHash) {
-      // 사용자 customize 없음 → 자동 갱신
-      copyFile(src, dst);
-      newFiles[rel] = { hash: newHash, core: true, managed: true };
-      summary.autoUpdated++;
-      console.log(`  auto-update: ${rel}`);
-    } else {
-      // 사용자 customize 검출 — *.bak 백업 + confirm
-      console.log(`\n  ⚠ ${rel} — 사용자 customize 검출`);
-      console.log(`    manifest 해시: ${oldManifestHash}`);
-      console.log(`    사용자 해시:   ${userHash}`);
-      console.log(`    새 코어 해시:  ${newHash}`);
-      const ok = await confirm(`    *.bak 백업 후 새 코어로 덮어쓸까?`);
-      if (ok) {
-        // .bak 백업
-        if (fs.existsSync(dst)) {
-          fs.copyFileSync(dst, dst + '.bak');
+  const main = L.findMain(cwd);
+  L.checkLegacyInstall(main, 'update');
+  const manifest = L.readManifest(main);
+  if (!manifest) L.fail("update: taskery가 설치돼 있지 않다. 'npx @angar2/taskery init'을 먼저 부른다.");
+  const platforms = Array.isArray(manifest.platforms) ? manifest.platforms : ['claude'];
+  const old = manifest.files || {};
+  const files = {};
+  const notes = [];
+  const asker = I.makeAsker();
+  try {
+    const plan = I.installPlan(platforms);
+    for (const it of plan) {
+      const dst = path.join(main, it.dst);
+      const tpl = I.readTemplate(it.src);
+      const cur = fs.existsSync(dst) ? fs.readFileSync(dst, 'utf8') : null;
+      if (it.kind === 'once') {
+        if (cur == null) {
+          I.writeFile(main, it.dst, tpl);
+          notes.push(`새로 만듦: ${it.dst}`);
+        }
+        continue;
+      }
+      if (it.kind === 'agents') {
+        const next = I.recomposeAgents(tpl, cur);
+        if (next !== cur) {
+          I.writeFile(main, it.dst, next);
+          notes.push(`재조립: ${it.dst} (프로젝트 절 유지)`);
         }
-        copyFile(src, dst);
-        newFiles[rel] = { hash: newHash, core: true, managed: true };
-        summary.customizedReplaced++;
-        console.log(`    replaced (.bak 백업): ${rel}`);
+        files[it.dst] = I.hashText(next);
+        continue;
+      }
+      const newHash = I.hashText(tpl);
+      const curHash = cur == null ? null : I.hashText(cur);
+      if (cur == null) {
+        I.writeFile(main, it.dst, tpl);
+        notes.push(`새로 만듦: ${it.dst}`);
+        files[it.dst] = newHash;
+      } else if (curHash === newHash) {
+        files[it.dst] = newHash;
+      } else if (curHash === old[it.dst]) {
+        I.writeFile(main, it.dst, tpl);
+        notes.push(`갱신: ${it.dst}`);
+        files[it.dst] = newHash;
       } else {
-        // 사용자 customize 보존 — manifest 항목은 *그대로* 유지 (다음 update가 다시 비교)
-        newFiles[rel] = oldEntry;
-        summary.skipped++;
-        console.log(`    skipped (사용자 보존): ${rel}`);
+        const ans = await asker.ask(`'${it.dst}'를 사용자가 고쳤다 — .bak으로 백업하고 새 판으로 바꿀까? (y/N) `, 'n');
+        if (ans.toLowerCase() === 'y') {
+          fs.copyFileSync(dst, `${dst}.bak`);
+          I.writeFile(main, it.dst, tpl);
+          notes.push(`바꿈(.bak 백업): ${it.dst}`);
+          files[it.dst] = newHash;
+        } else {
+          notes.push(`유지(사용자 수정): ${it.dst}`);
+          if (old[it.dst]) files[it.dst] = old[it.dst];
+        }
       }
     }
-  }
-
-  // 4. 사라짐 검사 — manifest에 있는데 새 template에 없음
-  for (const rel of Object.keys(oldFiles)) {
-    if (!(rel in newTemplateFiles)) {
-      console.log(`  ⚠ removed in new version (사용자 파일 보존): ${rel}`);
-      summary.removed++;
-      // manifest에서도 제거 (next update 시 다시 검사 X)
+    for (const rel of Object.keys(old)) {
+      if (!plan.some((it) => it.dst === rel)) notes.push(`이 버전에서 빠진 파일 — 지우지 않고 둔다: ${rel}`);
     }
+    notes.push(...I.writeConfigs(main, platforms));
+    const added = L.ensureExclude(main);
+    if (added.length) notes.push(`.git/info/exclude — ${added.join(' ')}`);
+    L.writeManifest(main, { ...manifest, version: L.getPackageVersion(), updated_at: new Date().toISOString(), platforms, files });
+    console.log(`taskery update 완료 — ${manifest.version} → ${L.getPackageVersion()}`);
+    for (const n of notes) console.log(`- ${n}`);
+  } finally {
+    asker.close();
   }
-
-  // 5. manifest 갱신 — 멀티세션(0.1.2+) / 플랫폼(0.2.0+) 필드 누락 시 자동 마이그레이션
-  const migration = { projectId: false, stale_days: false, lock_timeout_ms: false, platforms: false };
-  const projectId = oldManifest.projectId || (migration.projectId = true, generateProjectId());
-  const stale_days =
-    typeof oldManifest.stale_days === 'number'
-      ? oldManifest.stale_days
-      : (migration.stale_days = true, DEFAULT_STALE_DAYS);
-  const lock_timeout_ms =
-    typeof oldManifest.lock_timeout_ms === 'number'
-      ? oldManifest.lock_timeout_ms
-      : (migration.lock_timeout_ms = true, DEFAULT_LOCK_TIMEOUT_MS);
-  if (!Array.isArray(oldManifest.platforms)) migration.platforms = true;
-
-  // 활성 plan(0.7.0+) — 기존 값이 있으면 **반드시 그대로 보존**한다. newManifest는 아래에서
-  // 명시 필드 목록으로 새로 조립되므로, 여기서 넘기지 않으면 update 한 번에 활성 plan이
-  // 소리 없이 사라지고 구형 AGENT-GUIDE 폴백의 낡은 값으로 되돌아간다.
-  const { activePlan, ingested: activePlanIngested } = ingestActivePlan(cwd, oldManifest);
-  if (activePlanIngested) migration.activePlan = true;
-  const retiredGuide = retireLegacyAgentGuide(cwd, activePlan);
-  if (retiredGuide) console.log(`\n  ${retiredGuide}`);
-
-  const newManifest = {
-    version: getPackageVersion(),
-    installed_at: oldManifest.installed_at,
-    updated_at: new Date().toISOString(),
-    projectId,
-    platforms,
-    stale_days,
-    lock_timeout_ms,
-    activePlan: activePlan ?? null,
-    // 진입 문서 이행 완료 마커 — 있으면 다음 update가 이행을 재실행하지 않는다.
-    entryDocs: entryMig.done ? ENTRY_DOCS_MARKER : (oldManifest.entryDocs ?? null),
-    files: newFiles,
-  };
-  writeManifest(newManifest, manifestPath);
-
-  // 5.5. 부수 이행 — .gitignore 누락 패턴 / TEST-GUIDE 이관. 둘 다 사용자 승인 후에만.
-  const gi = planGitignore(cwd, platforms);
-  if (gi.missing.length > 0) {
-    console.log(`\n  taskery 자산 중 .gitignore에 없는 항목: ${gi.missing.join(', ')}`);
-    console.log(`  (등록하지 않으면 이 파일들이 커밋에 섞여 들어갑니다.)`);
-    if (await confirm(`  .gitignore에 추가할까?`)) {
-      gi.apply();
-      console.log(`    .gitignore 갱신 — ${gi.missing.length}개 패턴 추가`);
-    }
-  }
-
-  const tg = planTestGuide(cwd);
-  if (tg.conflict) {
-    // 자동 병합은 사용자 파일을 훼손할 수 있어 하지 않는다. 다만 침묵하면 TEST-GUIDE에 쌓인
-    // 내용이 아무도 안 읽는 채로 남으므로 반드시 알린다.
-    console.log(
-      `\n  ⚠ .project/TEST-GUIDE.md(폐지)와 .project/rules/TEST_RULE.local.md가 모두 있습니다.`,
-    );
-    console.log(`     TEST-GUIDE 쪽 내용은 이제 아무 스킬도 읽지 않습니다 — 필요한 항목을 직접 옮겨주세요.`);
-  }
-  if (tg.available) {
-    console.log(`\n  .project/TEST-GUIDE.md는 0.7.0에서 폐지되고 역할이 TEST_RULE.local.md로 옮겨졌습니다.`);
-    console.log(`  지금 옮기지 않으면 /task-plan·/task-dev가 기존 내용을 읽지 않습니다. (원본은 보존)`);
-    if (await confirm(`  내용을 .project/rules/TEST_RULE.local.md로 이관할까?`)) {
-      const appended = tg.apply();
-      console.log(`    이관 완료 — .project/rules/TEST_RULE.local.md (원본 TEST-GUIDE.md 보존)`);
-      if (appended.length > 0) {
-        console.log(`    누락 절 골격 ${appended.length}개 추가(${appended.join(' / ')}) — 내용은 직접 채워주세요.`);
-      }
-    }
-  }
-
-  const migratedFields = Object.entries(migration)
-    .filter(([, added]) => added)
-    .map(([k]) => k);
-  if (migratedFields.length > 0) {
-    console.log(`  manifest 마이그레이션: ${migratedFields.join(', ')} 필드 추가`);
-  }
-
-  // 결과 보고
-  console.log(`\n✅ taskery update 완료`);
-  console.log(`   동일: ${summary.unchanged}, 신규: ${summary.new}, 자동 갱신: ${summary.autoUpdated}`);
-  console.log(`   *.bak 후 갱신: ${summary.customizedReplaced}, 사용자 보존: ${summary.skipped}`);
-  if (summary.removed > 0) {
-    console.log(`   ⚠ 새 버전에서 사라진 파일: ${summary.removed} (사용자 파일 그대로 보존)`);
-  }
-  console.log();
 }
 
 main().catch((e) => {
-  console.error(`taskery update 실패: ${e.message}`);
+  console.error(e instanceof L.TaskeryError ? e.message : `taskery update 실패: ${e.stack || e.message}`);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angar2/taskery",
-  "version": "0.8.1",
-  "description": "Lightweight task system for Claude Code & Codex — 1 메인 세션(또는 멀티세션) + 스킬 9종 + catastrophic hook 안전망 2종",
+  "version": "1.0.1",
+  "description": "AI 코딩 에이전트(Claude Code·Codex)에게 일을 태스크 단위로 맡겨 기획·개발·테스트·병합까지 진행하게 하는 작업 체계",
   "bin": {
     "taskery": "bin/taskery.js",
     "create-taskery": "bin/create.js"
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "smoke:init": "node bin/init.js",
-    "smoke:update": "node bin/update.js"
+    "smoke:update": "node bin/update.js",
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "claude-code",
@@ -22,8 +23,7 @@
     "task-management",
     "ai-coding-workflow",
     "skills",
-    "slash-commands",
-    "agent-hooks"
+    "slash-commands"
   ],
   "author": "angar2 <angaridev@gmail.com>",
   "license": "MIT",

package/template/.taskery/BACKLOG.md

@@ -0,0 +1,38 @@
+# BACKLOG
+
+> 이 프로젝트에서 발견한 문제와 할 일을 모으는 곳이다. 백로그는 이 파일 하나뿐이다.
+
+## 쓰는 법
+
+1. 새 항목은 `taskery backlog-add "<제목>"`으로 만든다. 명령이 번호·등록일·상태를 채운 빈 양식을 `## 열린 항목` 맨 위에 넣는다. 번호는 직접 짓지 않는다.
+2. 필수 칸은 반드시 채우고, 모자라면 사용자에게 묻는다. 선택 칸은 대화·작업 맥락에 근거가 있으면 적거나 제안하고, 근거가 없으면 적지 않는다. 칸을 채우려고 지어내지 않는다. `<…>`를 남기지 않는다.
+3. 등록할 때는 코드를 깊게 파지 않는다. 자세한 분석은 태스크의 계획 단계에서 한다.
+4. `상태`와 `연결 태스크`는 명령이 바꾼다. `보류`·`취소`만 직접 적는다.
+5. 연결 태스크가 모두 닫히고 그중 하나 이상이 끝난(포기가 아닌) 항목은 명령이 `## 끝난 항목`으로 옮긴다. 모두 포기로 닫혔으면 `대기`로 되돌린다. 평소에는 `## 열린 항목`만 읽는다.
+
+## 항목 양식 (명령이 넣는 모양)
+
+```
+### BL-<번호> [<종류>] <제목>
+- 상태: 대기
+- 등록: <날짜>
+- 현상: <현상>
+- 연결 태스크: –
+```
+
+| 칸 | 필수 여부 | 채우는 규칙 |
+|---|---|---|
+| 번호·등록일·상태·연결 태스크 | 자동 | 명령이 채운다 |
+| 종류 | 필수 | `bug`·`improve`·`feature`·`refactor`·`docs`·`chore` 중 하나 |
+| 제목 | 필수 | 한 줄. 무엇이 문제인지, 또는 무엇을 원하는지 |
+| 현상 | 필수 | 무엇이 문제인지(기능 요청이면 왜 필요한지). 사용자 말에 근거가 있어야 한다 |
+| 플랜 | 선택 | 속할 플랜 폴더 이름, `다음 플랜 후보`, 또는 `미정` |
+| 원하는 결과 | 선택 | 끝났을 때 사용자가 보게 될 결과(화면·동작으로) |
+| 우선순위 | 선택 | `높음`·`보통`·`낮음` |
+| 발견 경위 | 선택 | 어디서 알게 됐는지 한 줄 |
+| 대상 영역 | 선택 | 관련 파일·폴더. 짐작이면 끝에 `(추정)` |
+| 세부 항목 | 선택 | 여러 개가 한 묶음이면 번호 목록 |
+
+## 열린 항목
+
+## 끝난 항목

package/template/.taskery/rules/CHANGELOG_RULE.md

@@ -0,0 +1,31 @@
+# CHANGELOG_RULE
+
+> 변경 기록의 형식이다. `close-task`가 끝난 태스크를 닫을 때 아래 "항목 틀"을 읽어 한 항목을 쓴다.
+
+## 위치
+
+- `.taskery/changelog/<YYYY-MM>.md` — 달마다 한 파일. 없으면 명령이 만든다.
+- 최신 항목이 맨 위에 온다.
+
+## 항목 틀
+
+명령은 아래 코드 블록을 읽어 `{num}`(세 자리 번호)·`{title}`(태스크 제목)·`{date}`(닫은 날)·`{type}`(유형)·`{goal}`(`## 요구사항` 첫 줄)을 채운다. 틀을 고치면 다음 항목부터 그 모양으로 적힌다.
+
+```markdown
+## [TASK-{num}] {title}
+
+- 날짜: {date}
+- 유형: {type}
+- 요약: {goal}
+```
+
+## 쓰는 때
+
+- 끝난 태스크(병합했거나, 병합이 필요 없는 태스크의 마무리를 마친 태스크)만 적는다. 포기로 닫은 태스크는 적지 않는다.
+- 적힌 항목은 사람이나 AI가 보강해도 된다.
+
+## 수정 이력
+
+| 날짜 | 변경 사항 |
+|---|---|
+| 2026-10-01 | 1.0판 — 형식만 남기고, 명령이 읽는 "항목 틀" 코드 블록을 두었다. 위치는 월별 파일 하나로 |

package/template/.taskery/rules/DEV_RULE.local.md

@@ -0,0 +1,8 @@
+# DEV_RULE.local
+
+> 이 리포의 구현 규칙이다. `task-dev`가 읽는다. 이 리포가 소유하는 파일이라 `update`가 건드리지 않는다.
+> 아는 내용만 적는다. 코드·테스트 방식에 관한 새 규칙은 AI가 문장을 제안하고 사용자가 승인한 뒤 넣는다.
+
+## 구현 규칙
+
+<!-- 코드 구조·이름 관행·금지 패턴처럼 이 프로젝트에서만 지키는 것 -->

package/template/.taskery/rules/GIT_RULE.md

@@ -0,0 +1,82 @@
+# GIT_RULE
+
+> 이 리포의 git 규칙이다. 맨 위 표는 taskery 명령이 읽어 그대로 따르고, 나머지 글은 에이전트가 읽고 따른다.
+> 이 리포만의 규칙은 표의 값을 고치거나 `GIT_RULE.local.md`에 적는다.
+
+| 항목 | 값 |
+|---|---|
+| 통합 브랜치 | `dev` |
+| 브랜치 이름 | `{type}/{dev}_TASK-{num}_{slug}` |
+| 커밋 메시지 | `{tag}: [TASK-{num}] {summary}` |
+| 병합 방식 | `no-ff` |
+
+- **통합 브랜치**: 빈 폴더에서 `init`이 만드는 부모 브랜치 이름이다. 기존 리포에서 태스크의 부모는 언제나 본진(리포 원래 폴더)이 서 있는 브랜치다.
+- **브랜치 이름**: `{type}`은 태스크 유형, `{dev}`는 작업자 식별자, `{num}`은 세 자리 태스크 번호, `{slug}`는 영문 kebab-case 이름이다. `{dev}`를 빼면 작업자 식별자를 받지 않는다.
+- **커밋 메시지**: 첫 줄 형식이다. `{tag}`는 아래 커밋 태그, `{summary}`는 medium·large면 `Phase 1 - <Phase 이름>`, small이면 태스크 제목이다. 둘째 줄부터는 명령이 파일 목록과 `- 사유: <사유>`를 붙인다.
+- **병합 방식**: `no-ff`(병합 커밋을 남긴다) 또는 `ff-only`. 명령은 로컬 병합만 한다.
+
+---
+
+## 브랜치
+
+| 브랜치 | 용도 |
+|---|---|
+| `main` | 프로덕션 |
+| `dev` | 통합 개발 — 태스크가 병합되는 기본 부모 |
+| 태스크 브랜치 | 태스크 하나만 담당한다. 부모에서 갈라져 부모로 병합된다 |
+
+### 태스크 유형
+
+| 유형 | 뜻 |
+|---|---|
+| `feature` | 새 기능 |
+| `bug` | 버그 수정 |
+| `improve` | 기존 기능 개선 |
+| `refactor` | 동작을 바꾸지 않는 구조 정리 |
+| `docs` | 문서 |
+| `chore` | 설정·의존성 등 잡일 |
+
+### 작업자 식별자
+
+실제 작업자 이름을 쓴다. 예: 사용자 `angar2`, Claude `claude`, 그 밖의 AI는 그 이름(`codex` 등).
+
+---
+
+## 커밋
+
+### 커밋 태그
+
+| 태그 | 유형 |
+|---|---|
+| `feat:` | feature |
+| `fix:` | bug |
+| `improve:` | improve |
+| `refactor:` | refactor |
+| `docs:` | docs, chore |
+
+### 예시
+
+```
+feat: [TASK-001] Phase 1 - 사용자 인증 로직
+
+- src/auth/login.ts
+- src/auth/session.ts
+- 사유: 기존 세션 방식의 한계로 토큰 인증으로 바꾼다
+```
+
+- 커밋은 `commit-task`가 한다. 커밋 대상은 코드뿐이다 — taskery 파일(`.taskery/` 등)은 git 밖이다.
+- 병합 커밋 메시지는 git 기본 메시지를 쓴다.
+
+---
+
+## 금지
+
+- 비밀값(`.env`, API 키 등)을 커밋하지 않는다.
+- 여러 태스크를 한 브랜치에서 하지 않는다.
+- 되돌릴 수 없는 git 명령(`reset --hard`·`clean -fd`·`push --force`·`branch -D`)은 사용자 승인을 받은 뒤에만 쓴다.
+
+## 수정 이력
+
+| 날짜 | 변경 사항 |
+|---|---|
+| 2026-10-01 | 1.0판 — 맨 위에 명령이 읽는 표(통합 브랜치·브랜치 이름·커밋 메시지·병합 방식)를 두고, taskery 내부 동작 설명(워크트리 위치·병합 잠금·경로 찾기·훅·검수 환경)과 태스크 문서·CHANGELOG 커밋 순서를 뺐다 |

package/template/.taskery/rules/MOCKUP_RULE.md

@@ -0,0 +1,19 @@
+# MOCKUP_RULE
+
+> 화면 목업의 위치와 형식이다. 사용자가 목업을 요청했을 때만 만들고, 그때 읽는다.
+
+## 위치
+
+- 태스크 문서 옆 `mockup/` 폴더에 `<태스크 문서 이름>-mockup.html`로 둔다. 예: `.taskery/plans/001_mvp/tasks/mockup/012_settings-save-mockup.html`. 폴더는 처음 쓸 때 만든다.
+- 태스크 하나에 목업 파일 하나다. 화면이 여럿이면 한 파일 안에서 절로 나눈다.
+
+## 형식
+
+- 정적 HTML 한 파일이다. 스타일은 파일 안 `<style>`, 움직임이 필요하면 파일 안 `<script>`로 쓰고 외부 라이브러리를 쓰지 않는다.
+- 레이아웃·색·간격·글꼴처럼 화면에서 보이는 것을 담는다. 클릭·호버는 흉내만 내도 된다.
+
+## 수정 이력
+
+| 날짜 | 변경 사항 |
+|---|---|
+| 2026-10-01 | 1.0판 — 위치·형식만 남겼다. 목업 질문 강제·생성 흐름·두 시점 활용·시각 수정 사이클 예고·정독 의무를 뺐다 |