@angar2/taskery 1.0.1 → 1.0.3

package/README.md

@@ -275,7 +275,7 @@ Node 프로젝트는 `package-lock.json`이 있으면 `npm ci`로 설치합니
 
 ## 오케스트레이션 — 한 줄 지시로 여러 태스크를 나눠 맡기기
 
-**오케스트레이션** = 한 세션(관리 세션)이 백로그를 태스크로 나누고, 태스크마다 새 AI 탭을 띄워 맡기고, 보고를 받아 정리하는 방식입니다. Orca 안에서 씁니다.
+**오케스트레이션** = 한 세션(관리 세션)이 백로그를 태스크로 나누고, 태스크마다 새 AI 탭을 띄워 맡기고, 보고를 받아 정리하는 방식입니다. Orca 안에서 씁니다. Orca를 쓸 수 없을 때는 사용자가 직접 세션을 열어 첫 지시를 붙여 넣는 방식으로도 진행할 수 있습니다.
 
 ```
                           👤 사용자
@@ -294,9 +294,9 @@ Node 프로젝트는 `package-lock.json`이 있으면 `npm ci`로 설치합니
 |---|---|
 | ① | 사용자가 관리 세션에 한 줄로 지시합니다. 예: "백로그 BL-1~3을 끝까지 진행해" |
 | ② | 관리 세션이 백로그와 `PLAN.md`를 읽고 태스크로 나눕니다. 어떤 태스크를 어떤 순서와 AI로 진행할지 표로 보여 주고 확인받습니다. 지시에 이미 정해져 있으면 다시 묻지 않습니다 |
-| ③ | 태스크마다 작업 폴더를 만들고(`prepare-task`), Orca 새 탭에 Claude나 Codex를 띄워 첫 지시를 보냅니다(`orca-dispatch-task`) |
+| ③ | 태스크마다 작업 폴더를 만들고(`prepare-task`), Orca 새 탭에 Claude나 Codex를 띄워 첫 지시를 보냅니다(`orca-dispatch-task`). 첫 지시는 늘 같은 틀(기본 정보·작업 방식·이번 태스크 지시)로 나갑니다. Orca를 쓸 수 없거나 사용자가 원하면, 관리 세션이 첫 지시를 보여 주고 사용자가 직접 연 세션에 붙여 넣습니다 |
 | ④ | 각 탭이 자기 작업 폴더에서 기획부터 마무리까지 진행합니다. 끝났을 때, 확인을 기다릴 때, 질문이 있을 때, 막혔을 때 보고함에 한 줄 남깁니다(`report-task`) |
-| ⑤ | 관리 세션은 기다리는 동안 잠들어 있어 토큰을 쓰지 않습니다(`wait-reports`). 보고가 오거나 10분이 지나면 깨어나 처리합니다 |
+| ⑤ | 관리 세션은 기다리는 동안 잠들어 있어 토큰을 쓰지 않습니다(`wait-reports`). 보고가 오거나 60분이 지나면 깨어나 처리합니다 |
 | ⑥ | 사용자 확인이 필요하면 관리 세션이 "TASK-108 탭에서 화면 확인해 주세요"라고 알립니다. 사용자는 그 탭에서 직접 답합니다 |
 | ⑦ | 끝난 태스크는 병합 잠금 안에서 하나씩 dev에 병합됩니다(`merge-task`) |
 | ⑧ | 관리 세션이 끝난 태스크의 작업 폴더와 탭을 치우고(`close-task`), 시작할 수 있는 다음 태스크로 빈자리를 채웁니다. 그리고 ③으로 돌아갑니다 |
@@ -345,7 +345,7 @@ Node 프로젝트는 `package-lock.json`이 있으면 `npm ci`로 설치합니
 
 ## 빠른 시작
 
-> **준비물**: Node.js 18 이상, git 2.31 이상, 위 두 에이전트 중 하나 이상. 오케스트레이션을 쓰려면 Orca가 필요합니다.
+> **준비물**: Node.js 18 이상, git 2.31 이상, 위 두 에이전트 중 하나 이상. 오케스트레이션은 Orca를 기본으로 씁니다(Orca가 없으면 태스크 세션을 직접 엽니다).
 
 ### 1. 설치
 
@@ -490,7 +490,7 @@ taskery 파일은 그 리포에만 적용되는 git 무시 목록(`.git/info/exc
 - PR로 병합하는 방식은 다루지 않습니다. 병합은 로컬에서만 합니다.
 - 태스크 문서와 백로그는 git 이력에 남지 않습니다.
 - 빌드 결과 복제는 macOS에서만 됩니다. 다른 환경에서는 평소처럼 빌드합니다.
-- 오케스트레이션은 Orca 안에서만 됩니다.
+- 오케스트레이션의 탭 자동 띄우기는 Orca 안에서만 됩니다. 그 밖에서는 사용자가 태스크 세션을 직접 열고 첫 지시를 붙여 넣습니다.
 - Codex는 작업 폴더로 옮겨 갈 수 없습니다. Codex로 태스크를 하려면 오케스트레이션이 Codex 탭을 띄우거나, 사용자가 그 작업 폴더에서 Codex를 엽니다.
 
 ---

package/bin/commands.js

@@ -113,12 +113,16 @@ const COMMANDS = [
   },
   {
     name: 'orca-dispatch-task',
-    summary: 'Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 .state에 기록한다',
+    summary: 'Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(탭 handle은 .state에 기록). --manual이면 띄우지 않고 사용자가 붙여 넣을 첫 지시문을 출력한다',
     args: [
       TASK,
-      { name: 'agent', desc: 'claude · codex (필수)' },
-      { name: 'model', desc: '에이전트 모델 — 사용자가 정한 것 (필수)' },
-      { name: 'note', desc: '첫 지시문 끝에 붙일 오케스트레이션의 말 한 줄' },
+      { name: 'agent', desc: 'claude · codex (--manual이 아니면 필수)' },
+      { name: 'model', desc: '에이전트 모델 — 사용자가 정한 것 (--manual이 아니면 필수)' },
+      { name: 'manual', type: 'bool', desc: '손 전달 — 탭을 띄우지 않고 작업 폴더·실행 안내·첫 지시문을 출력한다. Orca를 쓸 수 없거나 사용자가 태스크 세션을 직접 열겠다고 했을 때' },
+      { name: 'scope', desc: "첫 지시문 '맡는 일' 칸 — 이번 태스크가 맡는 일" },
+      { name: 'avoid', desc: "첫 지시문 '손대지 않는 것' 칸" },
+      { name: 'read', desc: "첫 지시문 '먼저 읽을 것' 칸 — 태스크 문서·플랜 문서 말고 더 읽을 문서" },
+      { name: 'extra', desc: "첫 지시문 '그 밖' 칸 — 위 칸에 들지 않는 이번 태스크만의 지시" },
     ],
     run: orcaDispatchTask,
   },
@@ -130,7 +134,7 @@ const COMMANDS = [
   },
   {
     name: 'wait-reports',
-    summary: '안 읽은 보고가 생기면 그 줄들을 출력하고 끝난다. 보고 없이 10분이면 오래 조용한 태스크 탭 목록과 함께 끝난다(백그라운드 셸로 건다)',
+    summary: '안 읽은 보고가 생기면 출력하고 끝난다. 보고 없이 60분이면 오래 조용한 태스크 탭 목록과 함께 끝난다(백그라운드 셸로 건다)',
     args: [],
     cliOnly: true,
     run: waitReports,

package/bin/finish.js

@@ -286,6 +286,15 @@ function writeChangelog(main, st, goal) {
   return file;
 }
 
+// orca worktree rm 뒤 폴더가 사라지기를 기다리는 최대 시간
+const ORCA_RM_WAIT_MS = 30 * 1000;
+
+// 경로가 사라질 때까지 기다린다(최대 ms)
+function waitGone(p, ms) {
+  const until = Date.now() + ms;
+  while (fs.existsSync(p) && Date.now() < until) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+}
+
 // 워크트리·브랜치 정리 — 커밋 안 된 변경이 있으면 남기고, 브랜치는 병합된 것만 지운다.
 // force는 prune에서 사용자가 확인했을 때만 — 병합 안 된 브랜치도 지운다(복구 명령 출력)
 function cleanup(main, st, { force = false } = {}) {
@@ -307,6 +316,8 @@ function cleanup(main, st, { force = false } = {}) {
       try {
         execFileSync('orca', ['worktree', 'rm', '--worktree', `path:${st.worktree}`, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
         notes.push(`Orca 워크트리를 지웠다: ${st.worktree}`);
+        // Orca는 답한 뒤에도 뒤에서 폴더를 지우고 병합된 브랜치도 함께 지운다 — 폴더가 사라질 때까지 기다린 뒤 브랜치를 본다
+        waitGone(st.worktree, ORCA_RM_WAIT_MS);
       } catch (e) {
         notes.push(`Orca 워크트리를 지우지 못해 남겼다: ${((e.stderr || '') + '').trim() || e.message}`);
         branchFree = false;
@@ -325,7 +336,10 @@ function cleanup(main, st, { force = false } = {}) {
   }
   if (!merged && !force) notes.push(`브랜치 ${st.branch}는 부모에 병합되지 않아 남겼다.`);
   else if (!branchFree || L.currentBranch(main) === st.branch) notes.push(`브랜치 ${st.branch}를 지우지 못해 남겼다(사용 중).`);
-  else if (L.git(main, ['branch', merged ? '-d' : '-D', st.branch], { allowFail: true }) === null) notes.push(`브랜치 ${st.branch}를 지우지 못해 남겼다.`);
+  else if (L.git(main, ['branch', merged ? '-d' : '-D', st.branch], { allowFail: true }) === null) {
+    // 그 사이 Orca가 지웠으면 실패가 아니다
+    notes.push(L.branchExists(main, st.branch) ? `브랜치 ${st.branch}를 지우지 못해 남겼다.` : `브랜치 ${st.branch}가 지워졌다. 복구: git branch ${st.branch} ${tip}`);
+  }
   else notes.push(`브랜치 ${st.branch}를 지웠다. 복구: git branch ${st.branch} ${tip}`);
   return notes;
 }

package/bin/lib.js

@@ -716,6 +716,7 @@ module.exports = {
   docAbs,
   docShown,
   readDoc,
+  fenceMask,
   section,
   isNewDoc,
   meaningfulLines,

package/bin/orche.js

@@ -6,10 +6,12 @@ const L = require('./lib');
 
 const AGENTS = ['claude', 'codex'];
 // 보고 없이 기다리는 시간이자 '오래 조용한 탭'의 기준. 환경 변수는 시험 전용 통로다
-const WAIT_MS = Number(process.env.TASKERY_WAIT_REPORTS_MS) || 10 * 60 * 1000;
+const WAIT_MS = Number(process.env.TASKERY_WAIT_REPORTS_MS) || 60 * 60 * 1000;
 const POLL_MS = Math.min(1000, WAIT_MS);
 // 첫 지시문을 보낸 뒤 턴 시작을 지켜보는 시간(orca terminal send --wait-submit)
 const SUBMIT_WAIT_SEC = 30;
+// 턴 시작 미관측 뒤 Enter를 보내고 화면을 읽기 전 기다리는 시간
+const SCREEN_SETTLE_MS = 2000;
 
 function reportsFile(main) {
   return path.join(main, '.taskery', 'reports.log');
@@ -45,10 +47,10 @@ function shq(v) {
   return /^[A-Za-z0-9_.\/:=@%+-]+$/.test(v) ? v : `'${String(v).replace(/'/g, `'\\''`)}'`;
 }
 
-// 에이전트 실행 명령 — 권한·승인 옵션은 붙이지 않는다(사용자 설정 그대로, I5)
+// 에이전트 실행 명령 — 권한·승인 옵션은 붙이지 않는다(사용자 설정 그대로, I5). 모델이 없으면 모델 옵션을 뺀다
 function agentCommand(main, agent, model) {
-  if (agent === 'claude') return `claude --model ${shq(model)}`;
-  return `codex -m ${shq(model)} --add-dir ${shq(path.join(main, '.taskery'))}`;
+  if (agent === 'claude') return model ? `claude --model ${shq(model)}` : 'claude';
+  return `codex ${model ? `-m ${shq(model)} ` : ''}--add-dir ${shq(path.join(main, '.taskery'))}`;
 }
 
 // 단계 표에서 비어 있는 첫 단계의 스킬 — 새 태스크면 task-plan
@@ -63,19 +65,40 @@ function oneLine(text) {
   return String(text).replace(/\s*\n\s*/g, ' ').trim();
 }
 
-// 첫 지시문 틀(§5-4) — 마지막 줄은 --note를 줬을 때만
-function firstInstruction(st, note) {
+// 첫 지시문 '■ 이번 태스크 지시' 칸 — 인자 이름과 칸 이름, 나오는 순서
+const BRIEF = [
+  ['scope', '맡는 일'],
+  ['avoid', '손대지 않는 것'],
+  ['read', '먼저 읽을 것'],
+  ['extra', '그 밖'],
+];
+
+// 첫 지시문 틀(§5-4) — '■ 이번 태스크 지시' 칸은 넘긴 칸이 있을 때만
+function firstInstruction(st, brief = {}) {
   const label = L.taskLabel(st.num);
-  const lines = [
+  const blocks = [
     `[오케스트레이션] taskery 태스크 ${label} 「${st.title}」를 맡는다. 이 세션은 태스크 세션이다.`,
-    `- 태스크 문서: ${st.doc} — 먼저 읽는다.`,
-    `- 시작: ${startSkill(st)}부터 한다. 태스크 만들기(task-init)와 워크트리 준비는 끝났다.`,
-    `- 진행 범위: ${st.range}. 범위와 무관하게 사용자 확인·FAIL·풀지 못한 충돌에서는 멈춘다.`,
-    `- 보고: 마무리 완료(병합, 병합이 없는 태스크는 merge-task가 건너뛴 뒤)·사용자 확인 대기·질문·막힘 때 report-task ${label} "<한 줄>"을 부른다.`,
-    '- 마무리(merge-task)까지 끝나면 보고하고 멈춘다. 워크트리 정리와 태스크 닫기는 오케스트레이션이 한다.',
+    [
+      '■ 기본 정보',
+      `- 태스크 문서: ${st.doc}`,
+      `- 플랜 문서: .taskery/plans/${st.plan}/PLAN.md`,
+      `- 시작 단계: ${startSkill(st)} (태스크 만들기(task-init)와 워크트리 준비는 끝났다)`,
+      `- 진행 범위: ${st.range}`,
+    ],
+    [
+      '■ 작업 방식',
+      '- 태스크 문서와 플랜 문서를 먼저 읽는다.',
+      '- 맡은 일 밖은 손대지 않는다. 필요해 보이면 report-task로 묻는다.',
+      '- 진행 범위와 무관하게 사용자 확인·FAIL·풀지 못한 충돌에서는 멈춘다.',
+      '- 사용자 확인은 그대로 따라 할 수 있는 실행 절차(명령·누를 곳·기대 결과)와 함께 요청한다.',
+      '- 규칙 파일(.taskery/rules/·AGENTS.md)은 사용자 승인 없이 고치지 않는다.',
+      `- 보고: 마무리 완료(병합, 병합이 없는 태스크는 merge-task가 건너뛴 뒤)·사용자 확인 대기·질문·막힘 때 report-task ${label} "<한 줄>"을 부른다.`,
+      '- 멈춤: 마무리(merge-task)까지 끝나면 보고하고 멈춘다. 워크트리 정리와 태스크 닫기는 오케스트레이션이 한다.',
+    ],
   ];
-  if (note && oneLine(note)) lines.push(`- 오케스트레이션이 전하는 말: ${oneLine(note)}`);
-  return lines.join('\n');
+  const given = BRIEF.map(([key, name]) => [name, brief[key] == null ? '' : oneLine(brief[key])]).filter(([, v]) => v);
+  if (given.length) blocks.push(['■ 이번 태스크 지시', ...given.map(([name, v]) => `- ${name}: ${v}`)]);
+  return blocks.map((b) => (Array.isArray(b) ? b.join('\n') : b)).join('\n\n');
 }
 
 // 지시문을 보내고 턴 시작이 관측됐는지 돌려준다. 받지 않았으면 refused. 관측할 수 없는 곳(영수증 없음·provider가 보고 못 함)은 보낸 것으로 본다
@@ -98,27 +121,50 @@ function onScreen(handle, marker) {
   }
 }
 
+// 손 전달(--manual) — 탭을 띄우지 않고 사용자에게 전할 작업 폴더·실행 안내·첫 지시문을 돌려준다
+function manualDispatch(main, st, a, brief) {
+  const prevTab = st.tab;
+  // 남은 탭 기록을 지운다 — 남겨 두면 wait-reports가 그 handle을 계속 확인한다
+  if (prevTab) {
+    delete st.tab;
+    L.writeState(main, st);
+    L.syncDoc(main, st);
+  }
+  const run = a.agent ? agentCommand(main, a.agent, a.model && String(a.model)) : `Claude Code는 claude, Codex는 ${agentCommand(main, 'codex')}`;
+  return [
+    '손 전달 — 탭을 띄우지 않았다. 사용자에게 아래를 전하고, 사용자가 작업 폴더에서 에이전트 세션을 열어 첫 지시문을 그대로 붙여 넣게 한다.',
+    `- 작업 폴더: ${L.workDir(main, st)}`,
+    `- 실행: ${run}`,
+    ...(prevTab ? [`- 앞서 연 탭 ${prevTab}은 기록에서 지웠다. 그 탭에서 세션이 이미 일을 시작하지 않았는지 확인하고 닫는다.`] : []),
+    '--- 첫 지시문 ---',
+    firstInstruction(st, brief),
+  ].join('\n');
+}
+
 async function orcaDispatchTask(ctx, a) {
   const main = ctx.main;
+  L.requireInstalled(main);
+  if (!a.task) L.fail('orca-dispatch-task: 빠진 입력이 있다.\n- <task> — 태스크 번호 (첫 번째 인자)');
+  const num = L.parseTaskNum(a.task);
+  const st = L.readState(main, num);
+  const label = L.taskLabel(num);
+  if (st.closed) L.fail(`${label}은 이미 닫혔다.`);
+  const dir = L.workDir(main, st);
+  if (!fs.existsSync(dir)) L.fail(`orca-dispatch-task: ${label}의 워크트리가 없다(${dir}). 'status'로 확인한다.`);
+  if (a.agent && !AGENTS.includes(a.agent)) L.fail(`orca-dispatch-task: --agent '${a.agent}'을 모른다. ${AGENTS.join(' · ')} 중 하나를 넣는다.`);
+  const brief = { scope: a.scope, avoid: a.avoid, read: a.read, extra: a.extra };
+  if (a.manual) return manualDispatch(main, st, a, brief);
   if (!L.inOrca()) {
     L.fail(
-      'orca-dispatch-task: Orca 탭 안이 아니라 태스크 세션을 띄울 수 없다(Orca 전용 — Orca 환경 변수 ORCA_TERMINAL_HANDLE이 없다). ' +
-        'Orca 탭에서 연 오케스트레이션 세션에서 부르거나, 사용자가 그 태스크의 워크트리에서 직접 세션을 연다.',
+      'orca-dispatch-task: Orca 탭 안이 아니라 태스크 세션을 띄울 수 없다(Orca 환경 변수 ORCA_TERMINAL_HANDLE이 없다). ' +
+        'Orca 탭 안에서 불렀다면 MCP 도구가 아니라 CLI(npx @angar2/taskery orca-dispatch-task …)로 다시 부른다. ' +
+        'Orca를 쓸 수 없으면 --manual로 다시 불러 사용자에게 손 전달한다.',
     );
   }
-  L.requireInstalled(main);
   const missing = [];
-  if (!a.task) missing.push('<task> — 태스크 번호 (첫 번째 인자)');
   if (!a.agent) missing.push(`--agent — ${AGENTS.join(' · ')}`);
   if (!a.model) missing.push('--model — 에이전트 모델 (사용자가 정한 것)');
   if (missing.length) L.fail(`orca-dispatch-task: 빠진 입력이 있다.\n${missing.map((m) => `- ${m}`).join('\n')}`);
-  if (!AGENTS.includes(a.agent)) L.fail(`orca-dispatch-task: --agent '${a.agent}'을 모른다. ${AGENTS.join(' · ')} 중 하나를 넣는다.`);
-  const num = L.parseTaskNum(a.task);
-  const st = L.readState(main, num);
-  const label = L.taskLabel(num);
-  if (st.closed) L.fail(`${label}은 이미 닫혔다.`);
-  const dir = L.workDir(main, st);
-  if (!fs.existsSync(dir)) L.fail(`orca-dispatch-task: ${label}의 워크트리가 없다(${dir}). 'status'로 확인한다.`);
 
   const command = agentCommand(main, a.agent, String(a.model));
   const created = orca(['terminal', 'create', '--worktree', `path:${dir}`, '--title', label, '--command', command]);
@@ -131,7 +177,7 @@ async function orcaDispatchTask(ctx, a) {
   L.writeState(main, fresh);
   L.syncDoc(main, fresh);
 
-  const text = firstInstruction(fresh, a.note);
+  const text = firstInstruction(fresh, brief);
   const manual = `탭 화면을 'orca terminal read --terminal ${handle}'로 확인하고, 준비되면 아래 첫 지시문을 'orca terminal send --terminal ${handle} --text "<첫 지시문>" --enter'로 보낸다.\n--- 첫 지시문 ---\n${text}`;
   let waited;
   try {
@@ -153,13 +199,23 @@ async function orcaDispatchTask(ctx, a) {
     if (r.refused) L.fail(`orca-dispatch-task: ${label} 탭(${handle})이 첫 지시문을 받지 않았다 — ${r.refused}\n${manual}`);
     return r.observed;
   };
-  // 턴 시작이 관측되지 않으면 화면을 보고, 지시문이 보이지 않을 때만 한 번 더 보낸다(준비 전 입력이 사라진 경우)
+  // Orca가 턴 시작을 관측했다고 답해도 지시문이 입력창에 제출되지 않은 채 남은 적이 있다(stash TASK-105).
+  // 그래서 관측 여부와 무관하게 Enter만 한 번 더 보낸다 — 입력창이 비었거나 이미 진행 중이면 영향이 없다
+  const observed = send();
   let sendNote = null;
-  if (!send()) {
+  try {
+    orca(['terminal', 'send', '--terminal', handle, '--enter']);
+  } catch (e) {
+    if (observed) sendNote = `확인용 Enter를 보내지 못했다(${e.message}) — 탭에서 진행을 확인한다.`;
+    else L.fail(`orca-dispatch-task: ${label} 탭(${handle})에서 첫 지시문의 턴 시작이 관측되지 않았고, Enter도 보내지 못했다 — ${e.message}\n'orca terminal read --terminal ${handle}'로 화면을 읽어, 지시문이 입력창에 남아 있으면 Enter를, 없으면 아래 첫 지시문을 보낸다.\n--- 첫 지시문 ---\n${text}`);
+  }
+  // 관측되지 않았으면 화면을 본다 — 지시문이 보이면 Enter로 들어간 것이고, 없으면 준비 전에 사라진 것이라 한 번 더 보낸다
+  if (!observed) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, SCREEN_SETTLE_MS);
     if (onScreen(handle, text.split('\n')[0].split(' ').slice(0, 4).join(' '))) {
-      sendNote = '턴 시작은 관측되지 않았지만 탭 화면에 첫 지시문이 보인다 — 탭에서 진행을 확인한다.';
+      sendNote = '턴 시작이 관측되지 않아 Enter를 한 번 더 보냈고, 탭 화면에 첫 지시문이 보인다 — 탭에서 진행을 확인한다.';
     } else if (send()) {
-      sendNote = '첫 전송은 턴 시작이 관측되지 않고 화면에도 없어 한 번 더 보냈다.';
+      sendNote = '첫 전송은 턴 시작이 관측되지 않고 Enter 뒤 화면에도 없어 한 번 더 보냈다.';
     } else {
       L.fail(`orca-dispatch-task: ${label} 탭(${handle})에 첫 지시문을 두 번 보냈지만 턴 시작이 관측되지 않았다.\n${manual}`);
     }
@@ -170,7 +226,7 @@ async function orcaDispatchTask(ctx, a) {
     `- 폴더: ${dir}`,
     `- 첫 지시문을 보냈다(시작: ${startSkill(fresh)}, 범위: ${fresh.range}).`,
     ...(sendNote ? [`- 알림: ${sendNote}`] : []),
-    '다음: wait-reports를 백그라운드 셸로 걸어 둔다.',
+    '다음: wait-reports가 걸려 있지 않으면 백그라운드 셸로 걸어 둔다.',
   ].join('\n');
 }
 
@@ -223,18 +279,24 @@ function quietTabs(main) {
   return out;
 }
 
+// 끝날 때 열린 태스크가 있으면 다시 걸라는 줄을 붙인다 — 다시 걸지 않으면 그 뒤의 보고를 놓친다
+function withRearm(main, lines) {
+  if (L.listStates(main).some((st) => !st.closed)) lines.push('맡긴 태스크가 남아 있으면 곧바로 wait-reports를 다시 걸어 둔다(사용자 답을 기다리는 중이어도).');
+  return lines.join('\n');
+}
+
 async function waitReports(ctx) {
   const main = ctx.main;
   L.requireInstalled(main);
   const until = Date.now() + WAIT_MS;
   for (;;) {
     const lines = takeUnread(main);
-    if (lines.length) return lines.join('\n');
+    if (lines.length) return withRearm(main, lines);
     if (Date.now() >= until) break;
     await new Promise((r) => setTimeout(r, Math.min(POLL_MS, Math.max(0, until - Date.now()))));
   }
   const quiet = quietTabs(main);
-  return [`보고 없이 ${L.minutes(WAIT_MS)}이 지났다.`, `오래 조용한 탭: ${quiet.length ? '' : '없음'}`.trimEnd(), ...quiet].join('\n');
+  return withRearm(main, [`보고 없이 ${L.minutes(WAIT_MS)}이 지났다.`, `오래 조용한 탭: ${quiet.length ? '' : '없음'}`.trimEnd(), ...quiet]);
 }
 
 module.exports = { orcaDispatchTask, reportTask, waitReports, firstInstruction };

package/bin/prepare.js

@@ -218,12 +218,26 @@ async function installPackages(dir) {
   return [`npm ci 실패(${took}) — 워크트리에서 직접 설치한다(${dir}):\n${L.tail(r.out, 15)}`];
 }
 
-// PLAN.md 목록 항목 줄 끝에 태스크 번호를 붙인다(`--item`)
-function linkItem(main, plan, item, label) {
+// PLAN.md `## 태스크 목록` 절에서 항목 줄을 찾는다. 다른 절의 번호 목록(목표 등)은 보지 않는다. 없으면 멈춘다
+function itemLine(main, plan, item) {
   const file = path.join(main, '.taskery', 'plans', plan, 'PLAN.md');
   const lines = fs.readFileSync(file, 'utf8').split('\n');
-  const idx = lines.findIndex((l) => new RegExp(`^\\s*${item}\\.\\s`).test(l));
-  if (idx === -1) L.fail(`prepare-task: ${plan}/PLAN.md에 항목 ${item}이 없다. 목록 형식은 '${item}. <한 줄 설명> — 선행: <항목 번호들 또는 없음>'이다.`);
+  const fenced = L.fenceMask(lines);
+  const start = lines.findIndex((l, i) => !fenced[i] && l.trim() === '## 태스크 목록');
+  let idx = -1;
+  for (let i = start + 1; start !== -1 && i < lines.length && !(!fenced[i] && /^## /.test(lines[i])); i++) {
+    if (!fenced[i] && new RegExp(`^\\s*${item}\\.\\s`).test(lines[i])) {
+      idx = i;
+      break;
+    }
+  }
+  if (idx === -1) L.fail(`prepare-task: ${plan}/PLAN.md \`## 태스크 목록\`에 항목 ${item}이 없다. 목록 형식은 '${item}. <한 줄 설명> — 선행: <항목 번호들 또는 없음>'이다.`);
+  return { file, lines, idx };
+}
+
+// 항목 줄 끝에 태스크 번호를 붙인다(`--item`)
+function linkItem(main, plan, item, label) {
+  const { file, lines, idx } = itemLine(main, plan, item);
   const linked = lines[idx].match(/TASK-\d+/g) || [];
   lines[idx] = `${lines[idx].replace(/\s+$/, '')} (${label})`;
   fs.writeFileSync(file, lines.join('\n'));
@@ -236,6 +250,7 @@ async function prepareTask(ctx, a) {
   const rule = L.readGitRule(main);
   const switches = validate(a, rule);
   const plan = resolvePlan(main, a.plan);
+  if (a.item != null) itemLine(main, plan, a.item); // 브랜치·워크트리를 만들기 전에 확인한다
   const noBranch = !!a['no-branch'];
   const noWorktree = noBranch || !!a['no-worktree'];
   const parent = checkMain(main);

package/package.json

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

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

@@ -44,9 +44,9 @@
 | `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은 `.state`에 남는다 |
+| `orca-dispatch-task <TASK> [--agent claude\|codex --model <모델>] [--manual] [--scope "<맡는 일>"] [--avoid "<손대지 않는 것>"] [--read "<먼저 읽을 것>"] [--extra "<그 밖>"]` | Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(`--manual`이 아니면 `--agent`·`--model` 필수, 탭 handle은 `.state`에 남는다). `--manual`이면 띄우지 않고 작업 폴더·실행 안내와 함께 사용자가 붙여 넣을 첫 지시문을 출력한다(손 전달) |
 | `report-task <TASK> "<한 줄>"` | 태스크 세션이 오케스트레이션에 보고 한 줄을 남긴다(`.taskery/reports.log`) |
-| `wait-reports` | 오케스트레이션이 백그라운드 셸로 걸어 두는 대기. 안 읽은 보고가 생기면 출력하고 끝나고, 보고 없이 10분이면 오래 조용한 태스크 탭 목록과 함께 끝난다 (CLI만) |
+| `wait-reports` | 오케스트레이션이 백그라운드 셸로 걸어 두는 대기. 안 읽은 보고가 생기면 출력하고 끝나고, 보고 없이 60분이면 오래 조용한 태스크 탭 목록과 함께 끝난다 (CLI만) |
 | `init` · `update` · `add <claude\|codex>` | 설치 · 갱신 · 플랫폼 추가 (CLI만) |
 
 태스크 명령(`approve-plan`~`merge-task`)에 `--range "<새 범위>"`를 붙이면 태스크 문서 헤더 표의 범위 칸만 바뀐다.
@@ -110,3 +110,4 @@
 | 2026-10-01 | S4 — 로컬 규칙 틀(`TEST_RULE.local.md`·`DEV_RULE.local.md`)을 `init`이 만든다는 줄을 더했다 |
 | 2026-10-01 | S3 — 오케스트레이션 명령 `orca-dispatch-task`·`report-task`·`wait-reports`와 `reports.log`를 더했다 |
 | 2026-10-01 | S2 — `prune`·`backlog-*`·`prepare-task --from`·`status`의 시작할 수 있는 태스크, 새 워크트리 준비(빌드 결과 폴더 APFS 복제·exclude 등록·닫을 때 본진 씨앗 갱신·`npm ci`)를 더했다 |
+| 2026-10-09 | 첫 지시문 정형화 — orca-dispatch-task의 --note를 칸별 인자로 바꾸고 손 전달(--manual)을 더했다. wait-reports 기다리는 시간을 60분으로 늘렸다 |

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

@@ -9,6 +9,9 @@ description: 오케스트레이션 — 백로그를 태스크로 기획하고,
 
 - 태스크는 서브에이전트에 맡기지 않는다. 태스크 세션은 Orca 새 탭의 독립 세션이며, 사용자가 그 탭에서 확인하고 개입할 수 있어야 한다.
 - 태스크마다 `task-init`(여는 일)을 이 세션이 하고, `orca-dispatch-task`로 태스크 세션을 띄운다. 에이전트와 모델은 사용자가 정하고, 정하지 않았으면 태스크 구성 확인 때 묻는다.
+- 첫 지시문의 역할·작업 방식은 명령이 같은 문장으로 채운다. 이 세션은 이번 태스크만의 지시를 칸별로 넘긴다 — `--scope`(맡는 일)·`--avoid`(손대지 않는 것)·`--read`(태스크 문서·플랜 문서 말고 먼저 읽을 것)·`--extra`(그 밖). 리포 규칙(`*.local.md`)에 이미 있는 것과 첫 지시문에 이미 있는 것(보고·멈춤 등)은 다시 쓰지 않는다. 필요 없는 칸은 비운다.
+- **손 전달**: Orca를 쓸 수 없거나(Orca 밖·탭 띄우기 실패) 사용자가 태스크 세션을 직접 열겠다고 하면 `orca-dispatch-task --manual`로 부른다. 명령이 내는 작업 폴더·실행 안내·첫 지시문을 사용자에게 전해 붙여 넣어 달라고 하고, `wait-reports`가 걸려 있지 않으면 곧바로 건다(사용자가 언제 붙여 넣든 보고는 `reports.log`에 남는다).
+- 손으로 연 세션에 보낼 말도 `[오케스트레이션]`을 붙여 사용자에게 전달을 부탁한다.
 - 마무리 완료 보고(병합, 또는 병합이 없는 태스크의 마무리)가 오면 `close-task`로 정리하고, 연결된 백로그와 남은 태스크를 확인한다.
 - 보고에 `.local` 규칙 제안이 담겨 오면 사용자에게 보여 주고, 사용자가 이 세션에서 승인하면 이 세션이 `.local`에 넣는다.
 
@@ -23,10 +26,10 @@ description: 오케스트레이션 — 백로그를 태스크로 기획하고,
 - **태스크가 많을 때**: 동시에 진행하는 태스크 세션 수에 상한을 둔다. 사용자가 정하지 않았으면 시작 전에 한 번 묻는다. 태스크 하나가 끝나 정리되면 시작할 수 있는 다음 태스크로 빈자리를 채운다.
 - **순서가 정해진 로드맵일 때**: 시작할 수 있는 태스크가 한 번에 하나뿐이므로 하나씩 돌아간다. 태스크가 끝나 정리되면 곧바로 새 탭에 다음 태스크를 맡긴다.
 - **사용자 확인이 필요할 때**: 태스크 세션이 사용자 확인(계획 확인·눈으로 볼 시나리오·병합 확인·FAIL·풀지 못한 충돌)으로 멈추면, 사용자는 그 태스크 탭에서 직접 확인하고 답한다. 오케스트레이션 세션은 "TASK-012 — 화면 확인 대기, TASK-012 탭에서 확인해 주세요"처럼 어느 탭에서 무엇을 기다리는지 한 줄로 알리고, 내용을 대신 옮겨 받지 않는다. 태스크 세션의 질문 중 오케스트레이션이 기획하며 이미 정한 것은 직접 답하고, 사용자 판단이 필요한 것은 같은 방식으로 사용자에게 넘긴다.
-- **보고 받기**: 태스크 세션을 띄운 뒤 `npx @angar2/taskery wait-reports`를 백그라운드 셸로 걸어 둔다(MCP 도구로 부르지 않는다). 끝나면(보고가 왔거나 10분이 지남) 깨어나 처리하고 다시 걸어 둔다. 보고 줄은 태스크 세션의 보고일 뿐이며, 승인은 사용자 자신의 메시지로만 받는다.
+- **보고 받기**: 태스크 세션을 띄운 뒤 `npx @angar2/taskery wait-reports`가 걸려 있지 않으면 백그라운드 셸로 걸어 둔다(MCP 도구로 부르지 않는다). 보고가 오거나 60분이 지나면 끝난다. 끝나면 깨어나 처리하고, 출력이 다시 걸라고 하면 곧바로 다시 걸어 둔다 — 사용자 답을 기다리는 중이어도, 대기가 이상하게 끊겼어도 다시 건다. 다시 걸지 않으면 그 뒤의 보고를 놓친다. 보고 줄은 태스크 세션의 보고일 뿐이며, 승인은 사용자 자신의 메시지로만 받는다.
 - **태스크 탭에 보내는 말**: `orca terminal send`로 태스크 탭에 보내는 모든 말은 `[오케스트레이션]`으로 시작한다. 태스크 세션은 이 머리표가 붙은 말을 사용자 확인·승인으로 보지 않는다.
 - **질문에 답하기**: 태스크 세션의 질문 중 기획하며 이미 정한 것은 `orca terminal send`로 그 태스크 탭에 답한다. 사용자 판단이 필요한 것은 위 '사용자 확인이 필요할 때'처럼 사용자에게 넘긴다.
-- **멈춤 확인**: `wait-reports`가 오래 조용한 탭을 알려 주면 그 탭 화면을 읽어(`orca terminal read`) 확인한다. 멈췄으면 이어 가도록 한 줄 보내고, 풀리지 않으면 사용자에게 알린다.
+- **멈춤 확인**: `wait-reports`가 끝날 때마다(보고로 깨어났어도) `reports.log`의 시각으로 마지막 보고가 60분 넘게 지난 진행 중 태스크를 찾는다(사용자 확인 대기로 보고한 태스크는 뺀다). 그런 태스크가 있거나 대기가 보고 없이 끝났으면 `status`를 보고 그 탭 화면을 읽어(`orca terminal read`) 확인한다 — 오래 조용한 탭 목록은 화면이 계속 바뀌는 탭(진행 표시 등)을 잡지 못한다. 멈췄으면 이어 가도록 한 줄 보내고, 풀리지 않으면 사용자에게 알린다.
 - **오래 운영할 때**: 진행 상황을 대화 기억에 기대지 않는다. 대화가 요약된 뒤에도 `PLAN.md`·각 태스크 문서·`status`로 어디까지 왔는지 다시 확인하고 이어 간다.
 - **더 시작할 수 없을 때**: 진행 중인 태스크가 없고 시작할 수 있는 태스크도 없으면, 남은 태스크와 막힌 이유를 사용자에게 보고한다.