@angar2/taskery 1.0.0 → 1.0.1

package/README.md

@@ -23,7 +23,7 @@ taskery는 일을 둘로 나눕니다.
 
 | AI에게 그냥 맡기면 | taskery를 쓰면 |
 |---|---|
-| 무엇을 왜 바꿨는지가 긴 대화 속에 묻혀, 나중에 다시 찾기 어렵습니다 | 태스크마다 문서 한 장(15~30줄)에 목표, 완료 기준, 고친 파일, 내린 결정, 결과가 남습니다 |
+| 무엇을 왜 바꿨는지가 긴 대화 속에 묻혀, 나중에 다시 찾기 어렵습니다 | 태스크마다 문서 한 장에 요구사항, 개발 계획, 완료 기준, 내린 결정, 실제 결과(테스트·커밋·병합)가 남습니다 |
 | AI가 "완료했습니다"라고 하지만, 기능이 처음부터 끝까지 실제로 되는지는 아무도 해 보지 않았습니다 | 사용자가 화면에서 보게 될 결과로 완료 기준을 적고, 실제로 해 봅니다. 증거가 없으면 통과로 인정하지 않습니다 |
 | 확인한다며 앱 화면을 띄우는 느린 테스트까지 매번 돌려 한참 기다립니다 | 개발 중에는 화면을 켜지 않는 코드 테스트만 돌리고, 3분을 넘으면 알려 줍니다 |
 | AI가 어디까지 하고 멈출지 예측할 수 없습니다 | 사용자가 말한 데까지만 합니다. 말하지 않으면 한 단계만 하고 멈춥니다 |
@@ -78,7 +78,7 @@ taskery는 이 목록을 읽어 **지금 시작할 수 있는 태스크**를 알
 | 단계 | AI가 하는 일 | 끝에 부르는 명령 | 명령이 하는 일 |
 |---|---|---|---|
 | ① 시작 | 요청이나 백로그 항목을 읽고, 태스크 하나로 묶을 범위·종류·크기·이름을 정합니다 | `prepare-task` | 겹치지 않는 번호를 발급하고, 전용 브랜치와 작업 폴더를 만들고, 태스크 문서를 만듭니다 |
-| ② 기획 | 목표, 완료 기준, 고칠 파일을 문서에 적고 사용자 확인을 받습니다 | `approve-plan` | 필요한 내용이 다 적혔는지 검사하고, 기획이 끝났다고 기록합니다 |
+| ② 기획 | 요구사항, 개발 계획, 완료 기준을 문서에 적고 사용자 확인을 받습니다 | `approve-plan` | 필요한 내용이 다 적혔는지 검사하고, 기획이 끝났다고 기록합니다 |
 | ③ 개발 | 코드를 고치고 필요한 단위 테스트를 씁니다 | `test-code` | 등록된 코드 테스트를 돌리고, 통과한 순간의 코드 상태를 기록합니다 |
 | ④ 테스트 | 앱을 한 번 켜서 완료 기준을 실제로 해 보고 증거를 남깁니다 | `test-scenario` | 완료 기준마다 결과와 증거를 기록합니다. 증거 없는 통과는 받지 않습니다 |
 | ⑤ 마무리 | 태스크 중 내린 결정 가운데 앞으로도 지킬 것을 프로젝트 문서에 반영합니다 | `verify-close` → `commit-task` → `merge-task` → `close-task` | 검사하고, 커밋하고, 병합하고, 작업 폴더를 치운 뒤 걸린 시간을 보고합니다 |
@@ -133,7 +133,7 @@ AI가 어디서 멈출지는 사용자의 말로 정해집니다.
 
 | | small | medium · large |
 |---|---|---|
-| 태스크 문서 | 목표, 완료 기준, 고칠 파일, 결정, 결과 | 위에 더해 요구사항과 작업 묶음(Phase) |
+| 태스크 문서 | 요구사항, 개발 계획(고칠 파일), 완료 기준, 결정, 결과 | small과 같고, 개발 계획을 작업 묶음(Phase)으로 나눕니다 |
 | 커밋 | 1개 | 작업 묶음마다 1개 |
 
 크기는 AI가 제안합니다.
@@ -157,36 +157,50 @@ AI가 어디서 멈출지는 사용자의 말로 정해집니다.
 
 ```markdown
 # TASK-012 설정 화면 저장 버튼 색 변경
-<!-- taskery: plan=001_mvp type=improve size=small switch=plan,dev,test range=끝까지 parent=dev by=taskery -->
+
+| 생성일 | 플랜 | 유형 | 크기 | 스위치 | 범위 | 부모 브랜치 | 브랜치 | 상태 |
+|---|---|---|---|---|---|---|---|---|
+| 2026-10-04 | 001_mvp | improve | small | 기획·개발·테스트 | 끝까지 | dev | improve/claude_TASK-012_save-button-color | 닫힘(완료) |
 
 | 시작·기획 | 개발 | 테스트 | 닫기 |
 |---|---|---|---|
-| ✅ 2분 | ✅ 3분 | ⏳ | – |
+| ✅ 2분 | ✅ 3분 | ✅ 4분 | ✅ 1분 (합계 10분) |
 
-## 목표
+## 요구사항
 저장 버튼이 다른 버튼과 구분되지 않아 눈에 띄는 파란색으로 바꾼다.
 
-## 완료 기준
+- 사용자 요구: 저장 버튼이 바로 눈에 띄어야 한다.
+- 하지 않는 것: 다른 버튼 색, 버튼 배치.
+
+## 개발 계획
+- `src/ui/SettingsView.tsx` — 저장 버튼 색을 디자인 토큰 primary로
+
+## 테스트 계획
 1. [AUTO] 설정 화면 → 저장 버튼을 본다 → 버튼이 파란색으로 보인다
 2. [USER] 설정 화면 → 이름을 바꾸고 저장 → 목록에 바뀐 이름이 보인다
 
-## 만질 파일
-- src/ui/SettingsView.tsx
-
 ## 결정
 - 파란색은 디자인 토큰 primary를 쓴다 — 다크 모드에서도 대비가 유지된다
 
 ## 결과
+- 코드 테스트 · 통과 · 명령 2개 · 1분 · 2026-10-04 14:10
+- 시나리오 1 · PASS · 캡처 screenshots/save-button.png · 2026-10-04 14:12
+- 시나리오 2 · PASS · 사용자 확인 · 2026-10-04 14:14
+- 커밋 · improve: [TASK-012] 설정 화면 저장 버튼 색 변경
+- 병합 · dev ← e71b0a4 · 2026-10-04 14:15
 ```
 
 | 부분 | 누가 쓰나 |
 |---|---|
-| 맨 위 두 줄(종류, 크기, 스위치, 범위, 부모 브랜치 등) | 명령 |
+| 헤더 표(생성일, 플랜, 종류, 크기, 스위치, 범위, 부모 브랜치, 브랜치, 상태) | 명령 |
 | 단계 표 | 명령 — 명령이 성공했을 때만 칸이 채워집니다 |
-| 목표, 완료 기준, 만질 파일, 결정 | AI |
-| 결과 | 명령 (`test-scenario`) |
+| 요구사항(첫 줄은 목표), 개발 계획, 테스트 계획, 결정 | AI |
+| 결과(코드 테스트, 완료 기준 결과, 커밋, 병합) | 명령 |
+
+- medium·large는 개발 계획을 작업 묶음(Phase)으로 나누고, 묶음마다 고칠 파일과 이유를 적습니다.
+- 개발을 끈 태스크에는 개발 계획이, 테스트를 끈 태스크에는 테스트 계획이 없습니다.
 
-단계 표는 AI의 "했습니다"가 아니라 **명령이 실제로 통과한 기록**입니다. 그래서 문서만 보면 태스크가 정말 어디까지 왔는지 알 수 있습니다. 태스크 상태는 열림과 닫힘 둘뿐이고, 손으로 바꾸는 상태는 없습니다.
+단계 표는 AI의 "했습니다"가 아니라 **명령이 실제로 통과한 기록**입니다. 그래서 문서만 보면 태스크가 정말 어디까지 왔는지 알 수 있습니다. 태스크 상태는 열림과 닫힘(완료·포기)뿐이고, 손으로 바꾸는 상태는 없습니다.
 
 ---
 
@@ -421,7 +435,7 @@ taskery 파일은 그 리포에만 적용되는 git 무시 목록(`.git/info/exc
 | `project-init` | 처음 한 번 | 프로젝트 정보, 용어집, 제품 문서, 코드 테스트 등록, 프로젝트 전용 규칙, 첫 플랜을 만듭니다 |
 | `plan-init` | 새 기능 묶음을 시작할 때 | 플랜 폴더와 `PLAN.md`(목표, 선행 관계가 있는 태스크 목록)를 만듭니다 |
 | `task-init` | 태스크를 열 때 | 요청이나 백로그 항목을 태스크 하나로 정리해 엽니다 |
-| `task-plan` | 기획 단계 | 목표, 완료 기준, 고칠 파일을 적습니다 |
+| `task-plan` | 기획 단계 | 요구사항, 개발 계획, 완료 기준을 적습니다 |
 | `task-dev` | 개발 단계 | 구현하고 코드 테스트를 통과시킵니다 |
 | `task-test` | 테스트 단계 | 완료 기준을 실제로 해 보고 증거를 남깁니다 |
 | `task-close` | 마무리 단계 | 검사, 커밋, 병합을 하고, 태스크를 연 쪽이 작업 폴더를 정리합니다 |

package/bin/check.js

@@ -8,13 +8,21 @@ async function approvePlan(ctx, a) {
   if (st.closed) L.fail(`${L.taskLabel(num)}은 이미 닫혔다.`);
   const text = L.readDoc(main, st);
   const problems = [];
-  if (!L.goalLine(text)) problems.push('`## 목표`가 비어 있다');
+  const newDoc = L.isNewDoc(text);
+  const goal = L.goalProblem(text);
+  if (goal) problems.push(goal);
   const files = L.plannedFiles(text);
-  if (!files.length) problems.push('`## 만질 파일`(medium·large는 `## Phase`의 `- 파일:` 포함)에 파일이 없다 — 한 줄에 `- 경로` 하나씩');
+  if (L.sw(st, 'dev') && !files.length) {
+    problems.push(
+      newDoc
+        ? '`## 개발 계획`에 파일이 없다 — small은 한 줄에 `- 경로` 하나, medium·large는 Phase마다 `- 파일:`'
+        : '`## 만질 파일`(medium·large는 `## Phase`의 `- 파일:` 포함)에 파일이 없다 — 한 줄에 `- 경로` 하나씩',
+    );
+  }
   if (L.sw(st, 'test')) {
     const n = L.parseCriteria(text).length;
     if (n < 1 || n > 5) {
-      problems.push(`\`## 완료 기준\` 시나리오가 ${n}개다 — 테스트 켜짐이면 1~5개를 \`1. [AUTO] 시작 → 행동 → 기대하는 끝 상태\` 형식으로 적는다`);
+      problems.push(`\`## ${newDoc ? '테스트 계획' : '완료 기준'}\` 완료 기준이 ${n}개다 — 테스트 켜짐이면 1~5개를 \`1. [AUTO] 시작 → 행동 → 기대하는 끝 상태\` 형식으로 적는다`);
     }
   }
   if (problems.length) L.fail(`approve-plan: ${L.taskLabel(num)} 태스크 문서를 고친 뒤 다시 부른다.\n${problems.map((p) => `- ${p}`).join('\n')}\n문서: ${L.docShown(main, st)}`);
@@ -23,7 +31,8 @@ async function approvePlan(ctx, a) {
   L.syncDoc(main, st);
   const d = L.stageDurations(st);
   const next = L.sw(st, 'dev') ? '개발(task-dev)' : '테스트(task-test)';
-  return `${L.taskLabel(num)} 계획을 기록했다 — 시작·기획 ${L.minutes(d.plan)}, 만질 파일 ${files.length}개.\n다음: ${next}.`;
+  const fileNote = L.sw(st, 'dev') ? `, 계획 파일 ${files.length}개` : '';
+  return `${L.taskLabel(num)} 계획을 기록했다 — 시작·기획 ${L.minutes(d.plan)}${fileNote}.\n다음: ${next}.`;
 }
 
 // 등록된 코드 테스트를 dir에서 차례로 실행한다. 실패하면 멈춤 오류를 던진다
@@ -92,6 +101,13 @@ async function testCode(ctx, a) {
     st.testCode = { at: L.nowIso(), fingerprint: L.fingerprint(dir) };
     L.writeState(main, st);
     L.syncDoc(main, st);
+    L.appendResult(
+      main,
+      st,
+      result.none
+        ? `- 코드 테스트 · 등록된 명령 없음 · ${L.clock(st.testCode.at)}`
+        : `- 코드 테스트 · 통과 · 명령 ${result.outputs.length}개 · ${L.minutes(result.ms)} · ${L.clock(st.testCode.at)}`,
+    );
     lines.push(`${L.taskLabel(st.num)} 개발 칸을 기록했다 — 개발 ${L.minutes(L.stageDurations(st).dev)}.`);
   }
   if (!result.none) lines.push(overNotice(result.ms, cmds).trim());
@@ -112,7 +128,7 @@ async function testScenario(ctx, a) {
   if (st.closed) L.fail(`${L.taskLabel(num)}은 이미 닫혔다.`);
   const criteria = L.parseCriteria(L.readDoc(main, st));
   const n = parseInt(a.number, 10);
-  if (!criteria.length) L.fail('test-scenario: 태스크 문서 `## 완료 기준`에 시나리오가 없다.');
+  if (!criteria.length) L.fail('test-scenario: 태스크 문서 `## 테스트 계획`에 완료 기준이 없다.');
   if (!(n >= 1 && n <= criteria.length)) L.fail(`test-scenario: 시나리오 번호는 1~${criteria.length} 중 하나다 (받음: '${a.number}').`);
   const result = String(a.result || '').toLowerCase();
   if (!RESULTS.includes(result)) L.fail("test-scenario: 결과는 pass · fail · accept 중 하나다.");

package/bin/commands.js

@@ -11,7 +11,7 @@ const { orcaDispatchTask, reportTask, waitReports } = require('./orche');
 
 // 인자 종류: positional(순서대로) · string(--이름 값) · bool(--이름) · list(--이름 값 값 …)
 const TASK = { name: 'task', positional: true, desc: '태스크 번호 (TASK-012 또는 12)' };
-const RANGE = { name: 'range', desc: '사용자가 새로 말한 진행 범위 — 태스크 문서의 범위 메모만 바꾼다' };
+const RANGE = { name: 'range', desc: '사용자가 새로 말한 진행 범위 — 태스크 문서 헤더 표의 범위 칸만 바꾼다' };
 
 const COMMANDS = [
   {
@@ -50,7 +50,7 @@ const COMMANDS = [
   },
   {
     name: 'approve-plan',
-    summary: '태스크 문서(목표·만질 파일·완료 기준)를 검사하고 계획 끝을 기록한다',
+    summary: '태스크 문서(요구사항·개발 계획·완료 기준)를 검사하고 계획 끝을 기록한다',
     args: [TASK, RANGE],
     run: approvePlan,
   },
@@ -113,7 +113,7 @@ const COMMANDS = [
   },
   {
     name: 'orca-dispatch-task',
-    summary: 'Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 태스크 문서 메타에 기록한다',
+    summary: 'Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 .state에 기록한다',
     args: [
       TASK,
       { name: 'agent', desc: 'claude · codex (필수)' },
@@ -137,7 +137,7 @@ const COMMANDS = [
   },
 ];
 
-// 명령 실행 공통 — 본진을 찾고, --range가 있으면 범위 메모를 먼저 갱신한다
+// 명령 실행 공통 — 본진을 찾고, --range가 있으면 범위를 먼저 갱신한다
 // ask는 묻는 명령(prune)에 CLI가 넘기는 질문 함수다. MCP에는 없다
 async function execute(cmd, args, { cwd = process.cwd(), main = null, ask = null } = {}) {
   const ctx = { cwd, main: main || L.findMain(cwd), ask };

package/bin/finish.js

@@ -40,7 +40,7 @@ async function verifyClose(ctx, a) {
   }
   if (L.sw(st, 'test')) {
     const criteria = L.parseCriteria(L.readDoc(main, st));
-    if (!criteria.length) problems.push('`## 완료 기준`에 시나리오가 없다');
+    if (!criteria.length) problems.push('`## 테스트 계획`에 완료 기준이 없다');
     for (let i = 1; i <= criteria.length; i++) {
       const last = lastEntry(st, i);
       if (!last) problems.push(`시나리오 ${i}의 결과·증거가 없다 — test-scenario로 기록한다`);
@@ -106,11 +106,14 @@ async function commitTask(ctx, a) {
       }
     }
   }
-  const prev = (st.commit && st.commit.commits) || [];
+  const before = st.commit;
+  const prev = (before && before.commits) || [];
   const commits = [...prev, ...made];
   const noCodeChange = !L.sw(st, 'dev') || (st.noBranch ? commits.length === 0 : !hasCodeChange(main, st));
   st.commit = { at: L.nowIso(), noCodeChange, commits };
   L.writeState(main, st);
+  for (const m of made) L.appendResult(main, st, `- 커밋 · ${m.subject}`);
+  if (L.sw(st, 'dev') && noCodeChange && !before) L.appendResult(main, st, '- 커밋 · 코드 변경 없음');
 
   // 병합 확인 화면 — 커밋 목록·바뀐 파일·단계별 시간·계획 확인 뒤 추가된 파일
   let changed;
@@ -199,6 +202,7 @@ async function mergeTask(ctx, a) {
   if (st.merge && st.merge.commit) return `${L.taskLabel(st.num)}은 이미 병합했다 (${st.merge.commit.slice(0, 7)}).`;
 
   if (L.needsNoMerge(st)) {
+    if (st.merge && st.merge.skipped) return `${L.taskLabel(st.num)} 병합은 이미 건너뛰었다(${st.merge.skipped}).\n다음: 태스크를 연 주인이 본진에서 close-task를 부른다.`;
     let note = '';
     if (st.noWorktree && L.currentBranch(main) !== st.parent) {
       L.git(main, ['checkout', st.parent]);
@@ -207,6 +211,7 @@ async function mergeTask(ctx, a) {
     const why = !L.sw(st, 'dev') ? '개발 꺼짐' : st.noBranch ? '브랜치 생략' : '코드 변경 없음';
     st.merge = { at: L.nowIso(), skipped: why };
     L.writeState(main, st);
+    L.appendResult(main, st, `- 병합 · 건너뜀(${why}) · ${L.clock(st.merge.at)}`);
     return `${L.taskLabel(st.num)} 병합을 건너뛴다(${why}).${note}\n다음: 태스크를 연 주인이 본진에서 close-task를 부른다.`;
   }
 
@@ -233,6 +238,12 @@ async function mergeTask(ctx, a) {
       st.testCode.fingerprint = fp;
       L.writeState(main, st);
       notes.push(r.none ? '부모의 새 커밋을 받았다 — 코드 테스트 없음으로 등록된 리포.' : `부모의 새 커밋을 받아 코드 테스트를 다시 돌렸다 — 통과(${L.minutes(r.ms)}).`);
+      const at = L.clock(L.nowIso());
+      L.appendResult(
+        main,
+        st,
+        r.none ? `- 코드 테스트 · 부모 새 커밋 받음 · 등록된 명령 없음 · ${at}` : `- 코드 테스트 · 부모 새 커밋 받아 다시 통과 · ${L.minutes(r.ms)} · ${at}`,
+      );
     }
     if (st.noWorktree) L.git(main, ['checkout', st.parent]);
     const args = rule.merge === 'ff-only' ? ['merge', '--ff-only', st.branch] : ['merge', '--no-ff', '--no-edit', st.branch];
@@ -240,6 +251,7 @@ async function mergeTask(ctx, a) {
     const head = L.git(main, ['rev-parse', 'HEAD']);
     st.merge = { at: L.nowIso(), commit: head };
     L.writeState(main, st);
+    L.appendResult(main, st, `- 병합 · ${st.parent} ← ${head.slice(0, 7)} · ${L.clock(st.merge.at)}`);
     return [
       `${L.taskLabel(st.num)}을 ${st.parent}에 병합했다(${rule.merge}, ${head.slice(0, 7)}).`,
       ...notes,

package/bin/lib.js

@@ -343,19 +343,41 @@ function readDoc(main, st) {
   return fs.readFileSync(file, 'utf8');
 }
 
-// `## 제목` 절 본문(다음 `## `까지)
+// 줄마다 코드 블록 안인지 — ``` 또는 ~~~로 시작하는 줄이 블록을 열고 닫는다. 닫히지 않은 블록은 문서 끝에서 닫힌 것으로 본다
+function fenceMask(lines) {
+  const mask = [];
+  let open = false;
+  for (const l of lines) {
+    if (/^\s*(```|~~~)/.test(l)) {
+      mask.push(true);
+      open = !open;
+      continue;
+    }
+    mask.push(open);
+  }
+  return mask;
+}
+
+// `## 제목` 절 본문(다음 `## `까지). 코드 블록 안의 `## ` 줄은 절 제목으로 보지 않는다
 function section(text, title) {
   const lines = text.split('\n');
-  const start = lines.findIndex((l) => l.trim() === `## ${title}`);
+  const fenced = fenceMask(lines);
+  const start = lines.findIndex((l, i) => !fenced[i] && l.trim() === `## ${title}`);
   if (start === -1) return null;
   const out = [];
   for (let i = start + 1; i < lines.length; i++) {
-    if (/^## /.test(lines[i])) break;
+    if (!fenced[i] && /^## /.test(lines[i])) break;
     out.push(lines[i]);
   }
   return out.join('\n');
 }
 
+// 1.0.1 문서 = `## 개발 계획` 또는 `## 테스트 계획` 절이 있다(renderDoc이 둘 중 하나는 반드시 만든다).
+// 없으면 1.0.0 문서(목표·완료 기준·만질 파일·Phase 절)로 읽는다
+function isNewDoc(text) {
+  return section(text, '개발 계획') !== null || section(text, '테스트 계획') !== null;
+}
+
 function meaningfulLines(body) {
   return (body || '')
     .replace(/<!--[\s\S]*?-->/g, '')
@@ -380,9 +402,10 @@ function parseFileList(body) {
     .filter(Boolean);
 }
 
-// `## Phase` 절: `### Phase N — 이름` + `- 파일:`(한 줄 쉼표·가운뎃점 구분 또는 들여쓴 목록) + `- 사유:`
+// Phase: `### Phase N — 이름` + `- 파일:`(한 줄 쉼표·가운뎃점 구분 또는 들여쓴 목록) + `- 사유:`
+// 1.0.1 문서는 `## 개발 계획` 안에, 1.0.0 문서는 `## Phase` 절에 있다
 function parsePhases(text) {
-  const body = section(text, 'Phase');
+  const body = section(text, isNewDoc(text) ? '개발 계획' : 'Phase');
   if (!body) return [];
   const phases = [];
   let cur = null;
@@ -422,16 +445,35 @@ function parsePhases(text) {
 
 // 완료 기준 — `[AUTO]`·`[USER]`가 붙은 줄을 차례로 1번부터 센다
 function parseCriteria(text) {
-  return meaningfulLines(section(text, '완료 기준')).filter((l) =>
+  return meaningfulLines(section(text, isNewDoc(text) ? '테스트 계획' : '완료 기준')).filter((l) =>
     /^(?:\d+[.)]|[-*])\s*\[(AUTO|USER)\]/.test(l),
   );
 }
 
+// 목표 = 1.0.1은 `## 요구사항` 첫 줄, 1.0.0은 `## 목표` 첫 줄(1.0.0 medium은 두 절이 다 있다)
 function goalLine(text) {
-  return meaningfulLines(section(text, '목표'))[0] || '';
+  return meaningfulLines(section(text, isNewDoc(text) ? '요구사항' : '목표'))[0] || '';
+}
+
+// approve-plan의 목표 검사 — 문제가 없으면 null
+function goalProblem(text) {
+  const goal = goalLine(text);
+  if (!isNewDoc(text)) return goal ? null : '`## 목표`가 비어 있다';
+  if (!goal) return '`## 요구사항` 첫 줄(목표)이 비어 있다 — 무엇을 왜 하는지 한 문장';
+  if (/^(?:[-*]|\d+[.)])\s/.test(goal)) return '`## 요구사항` 첫 줄은 목록 기호 없는 목표 한 문장이어야 한다(무엇을 왜) — 요구 목록은 그 아래에';
+  return null;
 }
 
+// 계획 파일 — 1.0.1은 `## 개발 계획`의 Phase `- 파일:`(Phase가 있으면 그것만), 없으면 목록.
+// 1.0.0은 `## 만질 파일` + `## Phase`
 function plannedFiles(text) {
+  if (isNewDoc(text)) {
+    const phases = parsePhases(text);
+    if (!phases.length) return parseFileList(section(text, '개발 계획'));
+    const files = [];
+    for (const p of phases) for (const f of p.files) if (!files.includes(f)) files.push(f);
+    return files;
+  }
   const files = parseFileList(section(text, '만질 파일'));
   for (const p of parsePhases(text)) for (const f of p.files) if (!files.includes(f)) files.push(f);
   return files;
@@ -443,22 +485,29 @@ function fileMatches(file, planned) {
   return file === base || file.startsWith(base + '/');
 }
 
-function quoteMeta(v) {
-  return /\s/.test(v) ? `"${v}"` : v;
+// ─── 헤더 표 ────────────────────────────────────────
+
+const HEADER_HEAD = '| 생성일 | 플랜 | 유형 | 크기 | 스위치 | 범위 | 부모 브랜치 | 브랜치 | 상태 |';
+const HEADER_SEP = '|---|---|---|---|---|---|---|---|---|';
+const SWITCH_LABEL = { plan: '기획', dev: '개발', test: '테스트' };
+
+function cell(v) {
+  return String(v == null ? '' : v).replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
 }
 
-function renderMeta(st) {
-  const parts = [
-    `plan=${st.plan}`,
-    `type=${st.type}`,
-    `size=${st.size}`,
-    `switch=${st.switch.join(',')}`,
-    `range=${quoteMeta(st.range)}`,
-    `parent=${st.parent}`,
-    `by=${st.by}`,
+function renderHeaderRow(st) {
+  const cells = [
+    clock(st.times.prepare).slice(0, 10),
+    st.item ? `${st.plan} (항목 ${st.item})` : st.plan,
+    st.type,
+    st.size,
+    ['plan', 'dev', 'test'].filter((n) => sw(st, n)).map((n) => SWITCH_LABEL[n]).join('·'),
+    st.range,
+    st.parent,
+    st.noBranch ? '분기 없음' : st.branch,
+    !st.closed ? '열림' : st.closed.finished ? '닫힘(완료)' : '닫힘(포기)',
   ];
-  if (st.tab) parts.push(`tab=${st.tab}`);
-  return `<!-- taskery: ${parts.join(' ')} -->`;
+  return `| ${cells.map(cell).join(' | ')} |`;
 }
 
 // ─── 시간 · 단계 표 ─────────────────────────────────
@@ -517,44 +566,60 @@ function renderTableRow(st) {
   return `| ${stageCells(st).join(' | ')} |`;
 }
 
-// 문서의 메타 줄과 단계 표 줄을 .state 기록으로 다시 쓴다(메타·표는 명령만 쓴다, §4-2)
+// 문서 머리(첫 `## ` 앞)에서 표 머리 줄을 찾는다
+function headIndex(lines, head) {
+  let end = lines.findIndex((l) => /^## /.test(l));
+  if (end === -1) end = lines.length;
+  for (let i = 0; i < end; i++) {
+    if (lines[i].trim() === head) return lines[i + 2] !== undefined && i + 2 < end && lines[i + 2].trim().startsWith('|') ? i : -1;
+  }
+  return -1;
+}
+
+// 문서의 헤더 표와 단계 표 줄을 .state 기록으로 다시 쓴다(두 표는 명령만 쓴다).
+// 1.0.0 문서는 제목 바로 아래 메타 줄을 헤더 표로 바꾼다
 function syncDoc(main, st) {
   const file = docAbs(main, st);
   if (!fs.existsSync(file)) return;
   const lines = fs.readFileSync(file, 'utf8').split('\n');
-  const mi = lines.findIndex((l) => l.startsWith('<!-- taskery:'));
-  if (mi !== -1) lines[mi] = renderMeta(st);
-  const hi = lines.findIndex((l) => l.trim() === TABLE_HEAD);
-  if (hi !== -1 && lines[hi + 2] !== undefined && lines[hi + 2].trim().startsWith('|')) {
-    lines[hi + 2] = renderTableRow(st);
+  if (headIndex(lines, HEADER_HEAD) === -1 && lines[1] !== undefined && lines[1].startsWith('<!-- taskery:')) {
+    lines.splice(1, 1, '', HEADER_HEAD, HEADER_SEP, renderHeaderRow(st));
   }
+  const hi = headIndex(lines, HEADER_HEAD);
+  if (hi !== -1) lines[hi + 2] = renderHeaderRow(st);
+  const ti = headIndex(lines, TABLE_HEAD);
+  if (ti !== -1) lines[ti + 2] = renderTableRow(st);
   fs.writeFileSync(file, lines.join('\n'));
 }
 
 function renderDoc(st) {
   const out = [
     `# ${taskLabel(st.num)} ${st.title}`,
-    renderMeta(st),
+    '',
+    HEADER_HEAD,
+    HEADER_SEP,
+    renderHeaderRow(st),
     '',
     TABLE_HEAD,
     '|---|---|---|---|',
     renderTableRow(st),
     '',
-    '## 목표',
+    '## 요구사항',
     '',
   ];
-  if (st.size !== 'small') out.push('## 요구사항', '');
-  out.push('## 완료 기준', '', '## 만질 파일', '');
-  if (st.size !== 'small') out.push('## Phase', '');
+  if (sw(st, 'dev')) out.push('## 개발 계획', '');
+  if (sw(st, 'test')) out.push('## 테스트 계획', '');
   out.push('## 결정', '', '## 결과', '');
   return out.join('\n');
 }
 
-// `## 결과` 절 끝에 한 줄을 붙인다
+// `## 결과` 절 끝에 한 줄을 붙인다(명령만 쓴다). 문서가 없으면 아무것도 하지 않는다
 function appendResult(main, st, line) {
   const file = docAbs(main, st);
+  if (!fs.existsSync(file)) return;
   const lines = fs.readFileSync(file, 'utf8').split('\n');
-  let start = lines.findIndex((l) => l.trim() === '## 결과');
+  const fenced = fenceMask(lines);
+  let start = lines.findIndex((l, i) => !fenced[i] && l.trim() === '## 결과');
   if (start === -1) {
     while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
     lines.push('', '## 결과', '');
@@ -562,7 +627,7 @@ function appendResult(main, st, line) {
   }
   let end = lines.length;
   for (let i = start + 1; i < lines.length; i++) {
-    if (/^## /.test(lines[i])) {
+    if (!fenced[i] && /^## /.test(lines[i])) {
       end = i;
       break;
     }
@@ -591,7 +656,7 @@ function todayLocal() {
   return clock(nowIso()).slice(0, 10);
 }
 
-// 범위 메모 갱신 — 태스크 명령에 --range를 붙이면 메타의 범위만 바꾼다(§3-5)
+// 범위 갱신 — 태스크 명령에 --range를 붙이면 헤더 표의 범위 칸만 바꾼다(§3-5)
 function updateRange(main, st, range) {
   if (!range || range === st.range) return st;
   st.range = range;
@@ -652,14 +717,16 @@ module.exports = {
   docShown,
   readDoc,
   section,
+  isNewDoc,
   meaningfulLines,
   parseFileList,
   parsePhases,
   parseCriteria,
   goalLine,
+  goalProblem,
   plannedFiles,
   fileMatches,
-  renderMeta,
+  renderHeaderRow,
   stageDurations,
   stageCells,
   minutes,

package/bin/orche.js

@@ -125,7 +125,7 @@ async function orcaDispatchTask(ctx, a) {
   const handle = created && created.terminal && created.terminal.handle;
   if (!handle) L.fail(`orca-dispatch-task: ${label} 탭을 열었지만 Orca가 탭 handle을 돌려주지 않았다. 'orca terminal list'로 확인한다.`);
 
-  // 탭 handle을 메타에 기록한다 — 첫 지시문을 보내기 전이라 태스크 세션의 기록과 겹치지 않는다
+  // 탭 handle을 .state에 기록한다 — 첫 지시문을 보내기 전이라 태스크 세션의 기록과 겹치지 않는다
   const fresh = L.readState(main, num);
   fresh.tab = handle;
   L.writeState(main, fresh);

package/bin/prepare.js

@@ -293,7 +293,10 @@ async function prepareTask(ctx, a) {
     if (a.item != null) st.item = parseInt(a.item, 10);
     const fromNotes = fromNums.length ? B.linkTasks(main, fromNums, L.taskLabel(num)) : [];
     if (fromNums.length) st.from = fromNums.map((n) => `BL-${n}`);
-    if (a.item != null || fromNums.length) L.writeState(main, st);
+    if (a.item != null || fromNums.length) {
+      L.writeState(main, st);
+      L.syncDoc(main, st);
+    }
 
     const out = [
       `${L.taskLabel(num)} 「${st.title}」을 열었다.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angar2/taskery",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "AI 코딩 에이전트(Claude Code·Codex)에게 일을 태스크 단위로 맡겨 기획·개발·테스트·병합까지 진행하게 하는 작업 체계",
   "bin": {
     "taskery": "bin/taskery.js",

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

@@ -9,7 +9,7 @@
 
 ## 항목 틀
 
-명령은 아래 코드 블록을 읽어 `{num}`(세 자리 번호)·`{title}`(태스크 제목)·`{date}`(닫은 날)·`{type}`(유형)·`{goal}`(`## 목표` 첫 줄)을 채운다. 틀을 고치면 다음 항목부터 그 모양으로 적힌다.
+명령은 아래 코드 블록을 읽어 `{num}`(세 자리 번호)·`{title}`(태스크 제목)·`{date}`(닫은 날)·`{type}`(유형)·`{goal}`(`## 요구사항` 첫 줄)을 채운다. 틀을 고치면 다음 항목부터 그 모양으로 적힌다.
 
 ```markdown
 ## [TASK-{num}] {title}

package/template/.taskery/rules/TASKERY_RULE.md

@@ -44,12 +44,12 @@
 | `backlog-add "<제목>" [--type <종류>]` | 백로그 번호를 발급해 `BACKLOG.md` 열린 항목 맨 위에 빈 양식 |
 | `backlog-get [BL-번호]` | 번호를 주면 그 항목 전문, 없으면 열린 항목 목록 |
 | `backlog-mark <BL-번호> <TASK>` | `--from` 없이 연 태스크를 백로그 항목에 연결 |
-| `orca-dispatch-task <TASK> --agent claude\|codex --model <모델> [--note "<한 줄>"]` | 오케스트레이션이 Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 태스크 문서 메타 `tab`에 남는다 |
+| `orca-dispatch-task <TASK> --agent claude\|codex --model <모델> [--note "<한 줄>"]` | 오케스트레이션이 Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 `.state`에 남는다 |
 | `report-task <TASK> "<한 줄>"` | 태스크 세션이 오케스트레이션에 보고 한 줄을 남긴다(`.taskery/reports.log`) |
 | `wait-reports` | 오케스트레이션이 백그라운드 셸로 걸어 두는 대기. 안 읽은 보고가 생기면 출력하고 끝나고, 보고 없이 10분이면 오래 조용한 태스크 탭 목록과 함께 끝난다 (CLI만) |
 | `init` · `update` · `add <claude\|codex>` | 설치 · 갱신 · 플랫폼 추가 (CLI만) |
 
-태스크 명령(`approve-plan`~`merge-task`)에 `--range "<새 범위>"`를 붙이면 태스크 문서의 범위 메모만 바뀐다.
+태스크 명령(`approve-plan`~`merge-task`)에 `--range "<새 범위>"`를 붙이면 태스크 문서 헤더 표의 범위 칸만 바뀐다.
 
 ## 4. 코드 테스트와 실사용 테스트
 

package/template/.taskery/rules/TASK_DOC_RULE.md

@@ -8,41 +8,59 @@
 
 ```markdown
 # TASK-012 설정 화면 저장 버튼 색 변경
-<!-- taskery: plan=001_mvp type=improve size=small switch=plan,dev,test range=끝까지 parent=dev by=taskery -->
+
+| 생성일 | 플랜 | 유형 | 크기 | 스위치 | 범위 | 부모 브랜치 | 브랜치 | 상태 |
+|---|---|---|---|---|---|---|---|---|
+| 2026-10-04 | 001_mvp (항목 3) | improve | small | 기획·개발·테스트 | 끝까지 | dev | improve/claude_TASK-012_save-button-color | 열림 |
 
 | 시작·기획 | 개발 | 테스트 | 닫기 |
 |---|---|---|---|
 | ✅ 2분 | ✅ 3분 | ⏳ | – |
 
-## 목표
-## 완료 기준
-## 만질 파일
+## 요구사항
+저장 버튼이 다른 버튼과 구분되지 않아 눈에 띄는 파란색으로 바꾼다.
+
+- 사용자 요구: 저장 버튼이 바로 눈에 띄어야 한다.
+- 다크 모드에서도 구분돼야 한다.
+- 하지 않는 것: 다른 버튼 색, 버튼 배치.
+
+## 개발 계획
+- `src/ui/SettingsView.tsx` — 저장 버튼 색을 디자인 토큰 primary로
+
+## 테스트 계획
+1. [AUTO] 설정 화면 → 저장 버튼을 본다 → 버튼이 파란색으로 보인다
+
 ## 결정
+- 파란색은 디자인 토큰 primary를 쓴다 — 다크 모드에서도 대비가 유지된다
+
 ## 결과
+- 코드 테스트 · 통과 · 명령 2개 · 1분 · 2026-10-04 14:10
+- 시나리오 1 · PASS · 캡처 screenshots/save-button.png · 2026-10-04 14:20
+- 커밋 · improve: [TASK-012] 설정 화면 저장 버튼 색 변경
+- 병합 · dev ← e71b0a4 · 2026-10-04 14:25
 ```
 
-- **맨 위 두 줄(메타)과 단계 표는 명령이 쓴다.** 손대지 않는다. 범위가 바뀌면 다음 태스크 명령에 `--range "<새 범위>"`를 붙인다.
-- medium·large는 `## 요구사항`(목표 아래)과 `## Phase`(만질 파일 아래)가 더 있다.
-- 전체 15~30줄이면 충분하다.
+- **헤더 표와 단계 표는 명령이 쓴다.** 손대지 않는다. 범위가 바뀌면 다음 태스크 명령에 `--range "<새 범위>"`를 붙인다.
+- 상태는 `열림`·`닫힘(완료)`·`닫힘(포기)` 셋이다. 분기 없이 일하는 태스크는 브랜치 칸이 `분기 없음`이다.
+- 개발이 꺼진 태스크에는 `## 개발 계획`이, 테스트가 꺼진 태스크에는 `## 테스트 계획`이 없다.
+- 짧게 쓰되 절마다 아래 2절의 내용은 빠뜨리지 않는다.
 
 ## 2. 절마다 쓰는 법
 
 | 절 | 쓰는 법 |
 |---|---|
-| `## 목표` | 무엇을 왜 하는지 한두 줄. 첫 줄이 small 커밋의 사유와 변경 기록 요약이 된다 |
-| `## 요구사항` | (medium·large) 정리한 요구 목록 |
-| `## 완료 기준` | 실사용 테스트 시나리오. 아래 3절 |
-| `## 만질 파일` | 한 줄에 `- 경로` 하나. 설명은 ` — ` 뒤에 적는다. 폴더는 `src/auth/`처럼 끝에 `/` |
-| `## Phase` | (medium·large) 아래 4절 |
-| `## 결정` | 다른 선택지가 있었고 나중에 "왜 이렇게 했지"를 물을 만한 결정만 `무엇을 정했나 — 왜` 한 줄. 없으면 비운다 |
-| `## 결과` | `test-scenario`가 시나리오 결과를 한 줄씩 붙인다. 직접 쓰지 않는다 |
+| `## 요구사항` | **첫 줄은 목표** — 무엇을 왜 하는지 한 문장, 목록 기호 없이. 이 줄이 small 커밋의 사유와 변경 기록 요약이 된다. 그 아래 목록으로 사용자 요구, 정한 범위, 한계, 하지 않는 것을 적는다 |
+| `## 개발 계획` | small은 한 줄에 `- 경로 — 무엇을` 하나. 폴더는 `src/auth/`처럼 끝에 `/`. medium·large는 아래 4절의 Phase |
+| `## 테스트 계획` | 완료 기준(실사용 테스트 시나리오). 아래 3절 |
+| `## 결정` | 다른 선택지가 있었고 나중에 "왜 이렇게 했지"를 물을 만한 결정만 `무엇을 정했나 — 왜` 한 줄로 적는다. 사용자가 고른 것도 적는다. 없으면 비운다 |
+| `## 결과` | `test-code`·`test-scenario`·`commit-task`·`merge-task`가 한 줄씩 붙인다. 직접 쓰지 않는다 |
 
-`approve-plan`은 목표와 만질 파일이 있는지, 테스트가 켜져 있으면 완료 기준이 1~5개인지 본다.
+`approve-plan`은 요구사항 첫 줄(목표)이 있는지, 개발이 켜져 있으면 개발 계획에 파일이 있는지, 테스트가 켜져 있으면 완료 기준이 1~5개인지 본다.
 
 ## 3. 완료 기준
 
 ```markdown
-## 완료 기준
+## 테스트 계획
 1. [AUTO] 설정 화면 → 저장 버튼을 본다 → 버튼이 파란색으로 보인다
 2. [USER] 설정 화면 → 이름을 바꾸고 저장 → 목록에 바뀐 이름이 보인다
 ```
@@ -54,10 +72,10 @@
 - 무언가를 없애는 태스크는 대신 보여야 할 것을 함께 적는다.
 - 이 태스크 브랜치에서 실제로 해 볼 수 있는 것만 적는다.
 
-## 4. Phase (medium·large)
+## 4. Phase (medium·large — `## 개발 계획` 안)
 
 ```markdown
-## Phase
+## 개발 계획
 ### Phase 1 — 로그인 API
 - 파일: `src/auth/login.ts`, `src/auth/session.ts`
 - 사유: 토큰 인증으로 바꾼다
@@ -69,6 +87,7 @@
 ```
 
 - `commit-task`가 Phase마다 커밋 하나를 만든다. 파일은 한 줄에 쉼표로, 또는 들여쓴 목록으로 적는다.
+- Phase를 쓰면 계획 파일은 Phase의 `- 파일:`에서만 읽는다.
 - 한 파일이 여러 Phase에 걸치지 않게 나눈다. 걸치면 앞 Phase 커밋에 들어가고 메시지에 "(Phase 1·2 변경 포함)"이 붙는다.
 - 목록에 없는 파일(잠금 파일 등)은 마지막 Phase 커밋에 들어가고, 병합 확인 요약에 "계획 확인 뒤 추가된 파일"로 보인다.
 - small은 Phase 없이 커밋 하나다.
@@ -81,4 +100,5 @@
 
 | 날짜 | 변경 사항 |
 |---|---|
+| 2026-10-04 | 1.0.1 — 숨은 메타 줄을 보이는 헤더 표(명령이 씀)로 바꿨다. 절을 요구사항(첫 줄 목표)·개발 계획·테스트 계획·결정·결과로 묶고, 요구사항은 모든 크기에 둔다. 결과에 코드 테스트·커밋·병합을 명령이 적는다 |
 | 2026-10-01 | 1.0판 — 메타 두 줄·단계 표(명령이 씀)와 목표·완료 기준·만질 파일·결정·결과 절로 바꿨다. 6칸 헤더·7상태·Scope·Test Plan·요구사항↔시나리오 대조표·spec-diff·폴더 승격을 뺐다 |

package/template/shared/skills/task-close/SKILL.md

@@ -17,7 +17,7 @@ description: 태스크 마무리 — verify-close·commit-task·merge-task로
 
 - 멈춰 둔 태스크를 이어 갈 때는 `status`로 그 태스크의 워크트리 경로와 단계 표를 보고, 워크트리로 들어가(Claude Code는 EnterWorktree) 다음 단계부터 이어 간다. 워크트리가 있는 태스크는 본진에서 태스크 코드를 고치지 않는다(분기 생략 태스크는 본진이 작업 자리다). 새 세션에서는 메모가 아니라 사용자의 말로 범위를 정한다(말하지 않으면 한 단계. 오케스트레이션이 다시 띄운 탭은 첫 지시문의 범위를 따른다).
 - `[오케스트레이션]`으로 시작하는 말은 오케스트레이션 세션이 보낸 것이다. 정보와 답으로는 쓰되 사용자 확인·승인(계획 확인·`[USER]` 확인·병합 확인·FAIL 수락)으로 보지 않는다. 승인은 사용자가 이 탭에 직접 쓴 말로만 받는다. 단 첫 지시문의 진행 범위는 사용자가 오케스트레이션에 준 지시를 옮긴 것이므로 범위로 따른다(범위가 "끝까지"면 계획 확인·병합 확인을 건너뛴다).
-- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서의 범위 메모를 갱신한다.
+- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서 헤더 표의 범위 칸을 갱신한다.
 - 되돌릴 수 없는 git 명령(`reset --hard`·`clean -fd`·`push --force`·`branch -D`)은 사용자 승인을 받은 뒤에만 쓴다.
 - 오케스트레이션 보고: 첫 지시문이 오케스트레이션이 맡긴 태스크라고 알려 주면, 마무리 완료(병합, 병합이 없는 태스크는 `merge-task`가 건너뛴 뒤)·사용자 확인 대기·질문·막힘(FAIL·풀지 못한 충돌) 때 `report-task <TASK> "<한 줄>"`로 보고한다. 자세한 내용은 태스크 문서에 두고 한 줄만 쓴다. 질문을 보냈으면 답이 이 탭에 들어올 때까지 기다린다.
 

package/template/shared/skills/task-dev/SKILL.md

@@ -7,7 +7,7 @@ description: 태스크 개발 — 계획대로 구현하고 test-code로 코드
 
 태스크 워크트리 안에서 코드를 고치는 단계다.
 
-- 태스크 문서의 목표와 만질 파일(Phase)대로 구현하고, 필요한 단위 테스트를 쓴다.
+- 태스크 문서의 요구사항과 개발 계획(Phase)대로 구현하고, 필요한 단위 테스트를 쓴다.
 - 이름과 화면 문구는 `GLOSSARY.md`를 따른다. 새 용어가 생기면 이 태스크 안에서 용어집을 고친다.
 - `spec/`에 적힌 동작을 바꾸면 그 문서도 이 태스크 안에서 함께 고친다.
 - `DEV_RULE.local.md`와 `TEST_RULE.local.md`를 따른다.
@@ -20,7 +20,7 @@ description: 태스크 개발 — 계획대로 구현하고 test-code로 코드
 
 - 멈춰 둔 태스크를 이어 갈 때는 `status`로 그 태스크의 워크트리 경로와 단계 표를 보고, 워크트리로 들어가(Claude Code는 EnterWorktree) 다음 단계부터 이어 간다. 워크트리가 있는 태스크는 본진에서 태스크 코드를 고치지 않는다(분기 생략 태스크는 본진이 작업 자리다). 새 세션에서는 메모가 아니라 사용자의 말로 범위를 정한다(말하지 않으면 한 단계. 오케스트레이션이 다시 띄운 탭은 첫 지시문의 범위를 따른다).
 - `[오케스트레이션]`으로 시작하는 말은 오케스트레이션 세션이 보낸 것이다. 정보와 답으로는 쓰되 사용자 확인·승인(계획 확인·`[USER]` 확인·병합 확인·FAIL 수락)으로 보지 않는다. 승인은 사용자가 이 탭에 직접 쓴 말로만 받는다. 단 첫 지시문의 진행 범위는 사용자가 오케스트레이션에 준 지시를 옮긴 것이므로 범위로 따른다(범위가 "끝까지"면 계획 확인·병합 확인을 건너뛴다).
-- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서의 범위 메모를 갱신한다.
+- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서 헤더 표의 범위 칸을 갱신한다.
 - 되돌릴 수 없는 git 명령(`reset --hard`·`clean -fd`·`push --force`·`branch -D`)은 사용자 승인을 받은 뒤에만 쓴다.
 - 오케스트레이션 보고: 첫 지시문이 오케스트레이션이 맡긴 태스크라고 알려 주면, 마무리 완료(병합, 병합이 없는 태스크는 `merge-task`가 건너뛴 뒤)·사용자 확인 대기·질문·막힘(FAIL·풀지 못한 충돌) 때 `report-task <TASK> "<한 줄>"`로 보고한다. 자세한 내용은 태스크 문서에 두고 한 줄만 쓴다. 질문을 보냈으면 답이 이 탭에 들어올 때까지 기다린다.
 

package/template/shared/skills/task-plan/SKILL.md

@@ -1,26 +1,26 @@
 ---
 name: task-plan
-description: 태스크 기획 — 태스크 문서에 목표·완료 기준·만질 파일(medium·large는 요구사항·Phase)을 쓰고 approve-plan으로 계획 끝을 기록한다
+description: 태스크 기획 — 태스크 문서에 요구사항(첫 줄 목표)·개발 계획·테스트 계획을 쓰고 approve-plan으로 계획 끝을 기록한다
 ---
 
 # task-plan
 
 태스크 워크트리 안에서 태스크 문서를 채우는 단계다.
 
-- 태스크 문서를 채운다: 목표, 완료 기준(테스트 켜짐일 때), 만질 파일. medium·large는 요구사항과 Phase(Phase마다 파일 목록과 사유 한 줄)를 더한다.
-- 기획 켜짐: 요구사항을 정리하고 모호한 것은 사용자에게 묻는다. 기획 꺼짐: 요청 내용으로 목표·만질 파일·완료 기준을 짧게 적고 `approve-plan`을 부른 뒤 멈추지 않고 다음 단계로 이어 간다(범위가 한 단계여도 간략 기획은 따로 세지 않는다).
+- 태스크 문서를 채운다: 요구사항(첫 줄은 목표 — 무엇을 왜 하는지 한 문장, 그 아래 사용자 요구·정한 범위·한계·하지 않는 것), 개발 계획(개발 켜짐일 때 — small은 파일 목록, medium·large는 Phase마다 파일 목록과 사유 한 줄), 테스트 계획(테스트 켜짐일 때 — 완료 기준).
+- 기획 켜짐: 요구사항을 정리하고 모호한 것은 사용자에게 묻는다. 기획 꺼짐: 요청 내용으로 요구사항·개발 계획·테스트 계획을 짧게 적고 `approve-plan`을 부른 뒤 멈추지 않고 다음 단계로 이어 간다(범위가 한 단계여도 간략 기획은 따로 세지 않는다).
 - 필요한 것만 읽는다: `PLAN.md`, 관련 `spec/` 문서, `GLOSSARY.md`, 태스크 문서 쓰는 법이 헷갈리면 `TASK_DOC_RULE.md`, 목업을 요청받았으면 `MOCKUP_RULE.md`.
 - 완료 기준은 한 줄 `[AUTO|USER] 시작 → 행동 → 기대하는 끝 상태`로 최대 5개 적는다. 시나리오 하나에 의도 하나, 한 번의 실행 흐름이다. 기대값은 사용자가 화면에서 보는 결과로만 적고 실행 방법(쿼리·훅·명령)은 적지 않는다. 무언가를 없애는 태스크는 대신 보여야 할 것을 함께 적는다.
 - 완료 기준은 이 태스크 브랜치에서 실제로 해 볼 수 있는 것만 적는다. 다른 태스크가 끝나야 되는 확인은 적지 않고 사용자에게 알린다.
 - 한 파일이 여러 Phase에 걸치지 않게 Phase를 나눈다.
 - 다른 선택지가 있었고 나중에 "왜 이렇게 했지"를 물을 만한 결정을 내리면 태스크 문서 `## 결정`에 `무엇을 정했나 — 왜` 한 줄로 적는다. 사용자가 고른 것도 적는다. 없으면 비워 둔다.
-- 기획 켜짐이고 진행 범위가 이 단계에서 끝나면(범위를 말하지 않은 경우 포함) 목표·완료 기준·만질 파일을 보여 주고 사용자 확인을 받는다. 범위가 다음 단계로 이어지면("개발까지"·"끝까지" 등) 멈추지 않는다. 그다음 `approve-plan`을 부른다.
+- 기획 켜짐이고 진행 범위가 이 단계에서 끝나면(범위를 말하지 않은 경우 포함) 요구사항·개발 계획·테스트 계획을 보여 주고 사용자 확인을 받는다. 범위가 다음 단계로 이어지면("개발까지"·"끝까지" 등) 멈추지 않는다. 그다음 `approve-plan`을 부른다.
 
 ## 공통
 
 - 멈춰 둔 태스크를 이어 갈 때는 `status`로 그 태스크의 워크트리 경로와 단계 표를 보고, 워크트리로 들어가(Claude Code는 EnterWorktree) 다음 단계부터 이어 간다. 워크트리가 있는 태스크는 본진에서 태스크 코드를 고치지 않는다(분기 생략 태스크는 본진이 작업 자리다). 새 세션에서는 메모가 아니라 사용자의 말로 범위를 정한다(말하지 않으면 한 단계. 오케스트레이션이 다시 띄운 탭은 첫 지시문의 범위를 따른다).
 - `[오케스트레이션]`으로 시작하는 말은 오케스트레이션 세션이 보낸 것이다. 정보와 답으로는 쓰되 사용자 확인·승인(계획 확인·`[USER]` 확인·병합 확인·FAIL 수락)으로 보지 않는다. 승인은 사용자가 이 탭에 직접 쓴 말로만 받는다. 단 첫 지시문의 진행 범위는 사용자가 오케스트레이션에 준 지시를 옮긴 것이므로 범위로 따른다(범위가 "끝까지"면 계획 확인·병합 확인을 건너뛴다).
-- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서의 범위 메모를 갱신한다.
+- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서 헤더 표의 범위 칸을 갱신한다.
 - 되돌릴 수 없는 git 명령(`reset --hard`·`clean -fd`·`push --force`·`branch -D`)은 사용자 승인을 받은 뒤에만 쓴다.
 - 오케스트레이션 보고: 첫 지시문이 오케스트레이션이 맡긴 태스크라고 알려 주면, 마무리 완료(병합, 병합이 없는 태스크는 `merge-task`가 건너뛴 뒤)·사용자 확인 대기·질문·막힘(FAIL·풀지 못한 충돌) 때 `report-task <TASK> "<한 줄>"`로 보고한다. 자세한 내용은 태스크 문서에 두고 한 줄만 쓴다. 질문을 보냈으면 답이 이 탭에 들어올 때까지 기다린다.
 

package/template/shared/skills/task-test/SKILL.md

@@ -7,7 +7,7 @@ description: 태스크 실사용 테스트 — 완료 기준 시나리오를 실
 
 태스크 워크트리 안에서 태스크의 의도가 처음부터 끝까지 되는지 확인하는 단계다.
 
-- 완료 기준의 시나리오를 실제로 실행한다. 앱 실행 방법은 `TEST_RULE.local.md`를 따른다.
+- 테스트 계획의 완료 기준을 실제로 실행한다. 앱 실행 방법은 `TEST_RULE.local.md`를 따른다.
 - 시나리오는 의도를 정면으로 해 본다. "빠져나갈 수 없다"가 의도면 실제로 빠져나가 보고, 버튼이 비활성인지 같은 우회 표시만 보고 PASS로 적지 않는다.
 - 앱은 한 번 켜서 시나리오 전부를 확인한다. 켜기 전에 이미 떠 있는지 확인하고, 끌 때는 이 태스크가 띄운 것만 끈다. 이름으로 한꺼번에 죽이지 않는다 — 다른 세션의 프로세스까지 죽는다.
 - 같은 관찰이 두 번 연속 기대와 다르면 더 재시도하지 않고 FAIL과 증거로 끝낸다. 원인 찾기는 개발 단계의 몫이다.
@@ -24,7 +24,7 @@ description: 태스크 실사용 테스트 — 완료 기준 시나리오를 실
 
 - 멈춰 둔 태스크를 이어 갈 때는 `status`로 그 태스크의 워크트리 경로와 단계 표를 보고, 워크트리로 들어가(Claude Code는 EnterWorktree) 다음 단계부터 이어 간다. 워크트리가 있는 태스크는 본진에서 태스크 코드를 고치지 않는다(분기 생략 태스크는 본진이 작업 자리다). 새 세션에서는 메모가 아니라 사용자의 말로 범위를 정한다(말하지 않으면 한 단계. 오케스트레이션이 다시 띄운 탭은 첫 지시문의 범위를 따른다).
 - `[오케스트레이션]`으로 시작하는 말은 오케스트레이션 세션이 보낸 것이다. 정보와 답으로는 쓰되 사용자 확인·승인(계획 확인·`[USER]` 확인·병합 확인·FAIL 수락)으로 보지 않는다. 승인은 사용자가 이 탭에 직접 쓴 말로만 받는다. 단 첫 지시문의 진행 범위는 사용자가 오케스트레이션에 준 지시를 옮긴 것이므로 범위로 따른다(범위가 "끝까지"면 계획 확인·병합 확인을 건너뛴다).
-- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서의 범위 메모를 갱신한다.
+- 진행 범위는 사용자의 가장 최근 지시를 따른다. 사용자가 범위를 새로 말하면 다음에 부르는 태스크 명령에 `--range "<새 범위>"`를 붙여 태스크 문서 헤더 표의 범위 칸을 갱신한다.
 - 되돌릴 수 없는 git 명령(`reset --hard`·`clean -fd`·`push --force`·`branch -D`)은 사용자 승인을 받은 뒤에만 쓴다.
 - 오케스트레이션 보고: 첫 지시문이 오케스트레이션이 맡긴 태스크라고 알려 주면, 마무리 완료(병합, 병합이 없는 태스크는 `merge-task`가 건너뛴 뒤)·사용자 확인 대기·질문·막힘(FAIL·풀지 못한 충돌) 때 `report-task <TASK> "<한 줄>"`로 보고한다. 자세한 내용은 태스크 문서에 두고 한 줄만 쓴다. 질문을 보냈으면 답이 이 탭에 들어올 때까지 기다린다.