deel-local-cli 1.1.0 → 1.2.0

package/src/skills/builtin//353/201/235/352/271/214/354/247/200-/355/225/230/352/270/260/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: 끝까지-하기
+description: 시킨 것이 여러 조각일 때 쉬운 것만 하고 멈추지 않기. 빼먹은 것은 말한다
+---
+
+# 끝까지 하기
+
+## 왜 있나
+
+한 번에 여러 가지를 시키면 앞의 한둘만 하고 "다 했습니다" 로 끝나는 일이
+잦다. 나머지는 조용히 사라진다. 사람은 다 된 줄 알고 넘어갔다가 나중에
+발견한다 — 그때는 이미 그걸 믿고 다음 일을 시작한 뒤다.
+
+**빼먹는 것 자체보다, 빼먹은 줄 모르게 하는 것이 나쁘다.**
+
+## 어떻게
+
+### 1. 조각부터 다 센다
+
+시작하기 전에 요청을 조각으로 끊는다. '그리고', '또', '~도', 쉼표,
+줄바꿈이 경계다. 중간에 끼워 넣은 말도 조각이다.
+
+셋을 넘으면 **TodoWrite 로 적는다.** 머리로 들고 있으면 반드시 샌다.
+
+### 2. 순서를 정한다
+
+- 남의 답을 기다려야 하는 것부터 던져 놓는다
+- 서로 안 엮인 것은 한 번에 처리한다
+- 막힐 것 같은 것을 **뒤로 미루지 않는다.** 미루면 시간이 없어 못 하게 되고,
+  그게 정확히 조용히 빠지는 자리다
+
+### 3. 하나씩 끝내고 표시한다
+
+- 끝난 것은 바로 done 으로 바꾼다
+- 다음으로 넘어가기 전에 **그 조각이 정말 끝났는지** 본다. 절반쯤 해 놓고
+  넘어간 것이 나중에 다 됐다고 세어진다
+
+### 4. 막히면 나머지를 먼저 끝낸다
+
+한 조각이 막혔다고 전부 멈추지 않는다.
+
+- 그것에 안 엮인 나머지를 **전부** 끝낸다
+- 막힌 것은 무엇이 왜 막혔는지 적는다
+- 범위를 줄이는 것은 사람이 정할 일이다. 혼자 줄이고 다 했다고 하지 않는다
+
+### 5. 끝에 반드시 셈을 맞춘다
+
+원래 요청을 다시 읽고 조각과 하나씩 맞춰 본다.
+
+  시킨 것 5개 · 끝낸 것 4개 · 못 한 것 1개 (왜: …)
+
+숫자가 안 맞으면 아직 안 끝난 것이다.
+
+## 말할 때
+
+- 다 했으면 짧게 "다 했다" 고 한다
+- 못 한 것이 있으면 **먼저** 말한다. 잘된 것 뒤에 붙이면 안 읽힌다
+- 나중에 하겠다는 것도 안 한 것이다. 그렇게 적는다
+
+## 하지 말 것
+
+- 쉬운 것만 하고 "다 했습니다"
+- 조각을 세지 않고 시작하기
+- 막혔다고 통째로 멈추기
+- 조용히 범위 줄이기 — 줄였으면 줄였다고 말한다

package/src/skills/builtin//354/212/244/354/212/244/353/241/234-/352/262/200/355/206/240/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: 스스로-검토
+description: 다 됐다고 말하기 전에 스스로 훑고 못 잰 것까지 말하기. 끝냈을 때·커밋 전에 쓴다
+---
+
+# 스스로 검토
+
+## 왜 있나
+
+"다 됐습니다" 는 제일 하기 쉬운 말이고, 제일 자주 틀리는 말이다.
+사람이 그 말을 믿고 넘어간 뒤에 깨진 것을 발견하면, 그 다음부터는
+아무 말도 못 믿게 된다.
+
+**검토는 잘한 것을 확인하는 자리가 아니라 안 한 것을 찾는 자리다.**
+
+## 훑는 차례
+
+### 1. 시킨 것을 다 했나
+
+- 요청을 다시 읽는다. 조각이 여럿이면 하나씩 짚는다
+- 조용히 줄인 것은 없나. 줄였으면 **줄였다고 말한다** — 그건 사람이 정할 일이다
+- 못 한 것이 있으면 무엇을 왜 못 했는지 적는다
+
+### 2. 돌려 봤나
+
+- 화면·숫자로 확인했나, 아니면 될 것 같아서 말하는 건가
+- 검사가 있으면 돌렸나. **전체**를 돌렸나
+- 고친 자리를 실제로 밟는 검사인가
+
+### 3. 안 되어야 하는 것도 봤나
+
+되는 길만 보면 절반이다.
+
+- 빈 값·없는 파일·권한 없음·끊긴 연결
+- 한글·공백 든 경로·CRLF
+- 다른 셸(PowerShell·cmd)·다른 OS 에서도 같은가
+
+### 4. 조용히 실패하는 자리는 없나
+
+- 삼킨 오류(`catch {}`)
+- 못 찾으면 기본값으로 넘어가는 자리 — 그게 맞는 기본값인가
+- 조건 때문에 통째로 건너뛰어지는 검사
+
+### 5. 남은 것을 치웠나
+
+- 임시 파일·디버그 출력·주석 처리한 코드
+- 띄운 프로세스·열린 포트·안 지운 임시 폴더
+
+### 6. 왜 그랬는지 적었나
+
+겪어서 알게 된 것은 코드에 안 남는다. 다음 사람(과 다음의 나)이 그걸
+모르면 같은 데서 또 넘어진다. 주석이나 커밋 본문에 남긴다.
+
+## 무엇을 못 쟀는지 말한다
+
+이게 제일 중요하다. **못 잰 것을 안 말하면 사람은 다 쟀다고 읽는다.**
+
+- "로컬 모델로는 못 재 봤습니다. 가짜 게이트웨이로만 확인했습니다"
+- "unzip 이 없는 자리에서는 11건을 못 쟀습니다"
+- "인식률은 잴 방법이 없어 그 이유로 결정하지 않았습니다"
+
+## 어떻게 말하나
+
+- 됐으면 됐다고 짧게. 에두르지 않는다
+- 안 됐으면 **출력을 붙여** 말한다. "검사가 실패합니다" 만으로는 부족하다
+- 지어낸 숫자를 쓰지 않는다. 안 잰 것은 "안 쟀다" 고 한다
+- 잘못을 길게 뉘우치지 않는다. 무엇이 틀렸고 어떻게 했는지만 적는다
+
+## 하지 말 것
+
+- 안 돌려 보고 "될 겁니다"
+- 요청의 일부를 조용히 빼고 "다 했습니다"
+- 실패한 검사를 안 보이는 곳에 두기
+- 못 잰 것을 잰 것처럼 말하기

package/src/skills/builtin//354/260/224/353/237/254/353/263/264/352/270/260/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: 찔러보기
+description: 되는지 모를 때 시간 정해 작게 찔러 답만 얻고 버리기. 헤매지 않으려고 쓴다
+---
+
+# 찔러보기 (spike)
+
+## 언제 쓰나
+
+- 이 방법이 되는지 안 되는지를 모른다
+- 남의 규격·API 가 실제로 무엇을 돌려주는지 모른다
+- 둘 중 어느 쪽이 나은지 재 보지 않고는 못 정하겠다
+
+**모르는 채로 본 코드를 짜기 시작하면 안 된다.** 절반쯤 짓고 나서 안 된다는
+것을 알게 되고, 그때는 되돌리기도 아깝다.
+
+## 어떻게
+
+### 1. 물음을 하나로 좁힌다
+
+답이 **예/아니오** 나 **숫자 하나**로 나와야 한다.
+
+- ✗ "이 방식이 괜찮을까"
+- ✓ "이 프록시가 401 을 줄 때 본문에 사람이 읽을 문장이 들어 있나"
+- ✓ "파일 600개짜리 폴더를 훑는 데 몇 ms 걸리나"
+
+### 2. 시간을 먼저 정한다
+
+15분, 30분, 한 시간. 정하고 시작한다. 넘기면 **멈추고 무엇까지 알아냈는지
+말한다.** 끝이 없는 찌르기는 찌르기가 아니라 헤매는 것이다.
+
+### 3. 제일 더러운 방법으로 짠다
+
+- 임시 폴더에 짠다. 본 코드에 안 섞는다
+- 오류 처리·이름·구조 다 신경 안 쓴다
+- 화면에 답만 찍히면 된다
+
+### 4. 답을 적고 **버린다**
+
+찔러 본 코드는 지운다. 남기는 것은 **알아낸 사실 한 줄**이다.
+
+  "unzip 은 Git Bash PATH 에만 있다. cmd 에는 없고, npm 은 cmd 로 돈다."
+  "폴더 600개 훑기 7ms — 켤 때마다 해도 된다."
+  "이 모델은 content 가 비고 전부 thinking 으로 간다. 상한이 낮으면 본문이 안 나온다."
+
+그 한 줄이 본 코드의 주석이 되고 결정의 근거가 된다.
+
+## 왜 버리나
+
+찔러 본 코드는 **답을 얻으려고** 짠 것이지 오래 쓰려고 짠 게 아니다.
+그대로 두면 오류 처리도 없고 이름도 엉망인 것이 본 코드가 된다.
+"어차피 도니까" 로 남긴 것이 나중에 제일 오래 남는다.
+
+## 하지 말 것
+
+- 시간을 안 정하고 시작하기
+- 찌르다가 슬그머니 본 구현으로 넘어가기
+- 답을 안 적고 코드만 남기기 — 코드는 무엇을 알아냈는지 말해 주지 않는다
+- 사내망·운영 서버에 대고 찌르기. 가짜를 세워서 찌른다

package/src/skills/builtin//354/260/250/352/267/274/354/260/250/352/267/274-/353/224/224/353/262/204/352/271/205/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: 차근차근-디버깅
+description: 재현→좁히기→원인→고치기→증명. 짐작으로 손대지 않기. 고장·재발에 쓴다
+---
+
+# 차근차근 디버깅
+
+## 왜 있나
+
+안 되는 것을 보면 바로 고치고 싶어진다. 그래서 짐작으로 한 줄 바꾸고
+"이제 될 겁니다" 라고 말하게 된다. 그게 맞을 때도 있는데, **틀렸을 때
+그걸 알 방법이 없다.** 그리고 틀린 채로 넘어간 것은 반드시 다시 돌아온다.
+
+## 순서
+
+### 1. 재현한다 — 이걸 건너뛰지 않는다
+
+고칠 수 있는 것은 **볼 수 있는 것**뿐이다.
+
+- 무엇을 하면 터지는가를 명령 한 줄로 만든다
+- 매번 터지는가, 가끔인가. 가끔이면 몇 번에 한 번인가
+- 못 재현하면 거기서 멈추고 **무엇이 더 필요한지 말한다.** 재현 못 한 채
+  고치는 것은 고치는 게 아니라 바꾸는 것이다
+
+### 2. 좁힌다 — 반씩 자른다
+
+원인을 짐작하지 말고 **범위를 자른다.**
+
+- 언제부터 됐나 / 안 됐나 (되던 시점이 있으면 그 사이가 범위다)
+- 되는 입력과 안 되는 입력의 차이는 정확히 무엇인가
+- 절반을 빼면 여전히 터지나
+- 다른 자리(다른 셸·다른 PC·다른 폴더)에서도 터지나
+
+세 번 좁혔는데 범위가 안 줄면 좁히는 방향이 틀린 것이다. 처음으로 돌아간다.
+
+### 3. 원인을 말로 만든다
+
+**"A 일 때 B 가 C 를 하므로 D 가 된다"** 꼴로 한 문장이 나와야 한다.
+안 나오면 아직 원인을 모르는 것이다. 이때 고치면 증상만 덮게 된다.
+
+"아마 인코딩 문제일 것" 은 원인이 아니다.
+"파일이 CP949 로 저장돼 있는데 utf8 로 읽어서 앞 두 글자가 깨진다" 가 원인이다.
+
+### 4. 고치기 전에 실패를 못 박는다
+
+**터지는 것을 먼저 검사로 만든다.** 지금 실패해야 맞다.
+
+- 실패하는 것을 확인한 뒤에 고친다
+- 안 만들면 "고쳤다" 를 증명할 방법이 없고, 다음에 같은 게 돌아와도 모른다
+- 검사를 만들기 어려운 자리면, 최소한 재현 명령과 그 출력을 남긴다
+
+### 5. 고치고 증명한다
+
+- 아까 실패하던 것이 통과하는가
+- **다른 것이 안 깨졌는가** — 전체 검사를 돌린다
+- 원인을 지웠는가, 증상을 덮었는가. 덮었으면 그렇다고 말한다
+
+## 겪은 것에서 나온 규칙
+
+- **문법이 맞는다고 맞는 게 아니다.** 셸이 `${...}` 를 먹어서 만들어진
+  `error: + '…'` 는 `node --check` 를 통과한다. 검사가 잡았다.
+- **같은 코드가 셸에 따라 다르게 돈다.** Git Bash 의 PATH 에만 있는 도구에
+  기댄 검사가 npm(cmd) 에서만 실패했다. "간헐적" 으로 보이면 **무엇이
+  다른지**부터 본다 — 대개 간헐적이 아니다.
+- **조용히 건너뛴 것이 실패보다 나쁘다.** 실패는 눈에 띄지만 건너뛴 것은
+  통과처럼 보인다.
+
+## 하지 말 것
+
+- 재현 없이 고치기
+- 한 번에 여러 군데 고치기 — 뭐가 들었는지 알 수 없게 된다
+- 원인을 모른 채 `try/catch` 로 덮기
+- "이제 될 겁니다" — 돌려 보고 말한다

package/src/skills/builtin//354/275/224/353/223/234-/354/244/204/354/235/264/352/270/260/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: 코드-줄이기
+description: 동작은 그대로 두고 읽기 쉽게 줄이기. 정리해달라는 말에 쓴다
+---
+
+# 코드 줄이기
+
+## 규칙 하나
+
+**동작을 바꾸지 않는다.** 줄이기와 고치기를 같이 하면, 뭔가 깨졌을 때
+줄여서 깨진 건지 고치다 깨진 건지 알 수 없다. 둘을 섞지 않는다.
+
+시작하기 전에 검사가 초록인지 본다. 빨강에서 시작하면 줄이는 게 아니라
+그냥 헤매는 것이다.
+
+## 무엇을 줄이나 — 값이 큰 순서
+
+### 1. 같은 것이 세 군데 이상
+
+두 군데는 놔둔다. 세 번째가 나타나면 묶는다. **두 번에 묶으면** 나중에
+셋이 서로 다른 방향으로 갈라질 때 억지로 한 틀에 우겨넣게 된다.
+
+### 2. 이름이 하는 일과 다른 것
+
+`process()`, `data`, `handle2()`. 이름만 바꿔도 읽는 속도가 달라진다.
+이름을 못 짓겠으면 그 함수가 두 가지 일을 하고 있는 것이다.
+
+### 3. 세 겹 넘는 중첩
+
+- 일찍 돌려보낸다 (`if (없으면) return`)
+- 안쪽 덩어리를 이름 있는 함수로 뺀다
+
+### 4. 죽은 것
+
+안 쓰는 함수·변수·주석 처리된 코드. **지운다.** "나중에 쓸까 봐" 는 이유가
+못 된다 — 되돌리기가 있다.
+
+### 5. 주석이 코드를 되풀이하는 것
+
+```js
+// i 를 1 늘린다
+i += 1;
+```
+지운다. **왜 그렇게 했는지**만 남긴다. 무엇을 하는지는 코드가 말한다.
+
+## 무엇을 안 줄이나
+
+- **왜 그런지 적어 둔 주석.** 이건 코드에 안 남는 정보다. 제일 먼저 지워지고
+  제일 아깝다
+- 겪어서 붙은 예외 처리. `// 윈도우 GNU tar 는 'C:\' 를 원격 호스트로 오해한다`
+  같은 것. 이유가 안 적혀 있으면 지우기 전에 왜 있는지부터 찾는다
+- 검사 코드 — 조금 지저분해도 괜찮다. 검사는 읽히는 것보다 **잡는 것**이 일이다
+- 이미 잘 도는 남의 코드
+
+## 끝내기 전에
+
+- 검사가 여전히 전부 초록인가
+- 지운 것 중에 **왜 있었는지 모르는 채로** 지운 게 있나. 있으면 되돌린다
+- 줄인 만큼 읽기 쉬워졌나. 짧아지기만 하고 더 어려워졌으면 되돌린다
+
+## 하지 말 것
+
+- 줄이면서 기능 고치기
+- 검사가 빨강인 채로 시작하기
+- 한 번에 여러 파일 갈아엎기 — 무엇이 깨졌는지 못 찾는다
+- 짧게 만들려고 한 줄에 우겨넣기. 짧은 것과 읽기 쉬운 것은 다르다

package/src/skills/discover.js

@@ -1,10 +1,20 @@
 // 스킬·슬래시명령 찾기.
-// deel 는 스킬을 품고 다니지 않는다 — 켜질 때 그 PC 를 훑어 있는 것을 쓴다.
-// Claude Code 와 같은 형식을 읽으므로, 그쪽으로 쓰인 것이 그대로 먹는다.
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+// deel 는 그 PC 를 훑어 있는 것을 쓴다. Claude Code 와 같은 형식을 읽으므로,
+// 그쪽으로 쓰인 것이 그대로 먹는다.
+//
+// **다만 일하는 방법 몇 가지는 품고 다닌다(builtin/).**
+// 전에는 하나도 안 품었다. 그런데 사내에서 새로 받은 PC 에는 ~/.claude/skills 도
+// 플러그인도 없다 — 거기서는 방법론이 0개였고, 모델은 매번 제 나름대로 했다.
+// 시킨 것만 겨우 하고 끝나는 얄팍한 결과가 거기서 나온다.
+// 품고 다니는 것은 **가장 낮은 자리**에 둔다. 같은 이름을 사용자가 만들면 그쪽이 이긴다.
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
+// 이 파일 옆의 builtin/ — 패키지에 같이 실려 나간다(package.json files: src).
+export const 내장자리 = join(dirname(fileURLToPath(import.meta.url)), 'builtin');
+
 // --- YAML 앞머리 읽기 (name, description 만 쓰므로 최소만 구현) -------------
 export function frontmatter(text) {
   if (!text.startsWith('---')) return { data: {}, body: text };
@@ -156,6 +166,11 @@ export function discover(root, opts = {}) {
   const commands = [];
   const plugins = [];
 
+  // 0) 품고 다니는 것 — 제일 먼저 넣어 제일 낮은 자리를 준다.
+  // dedupe 는 나중에 온 것이 이기므로, 사용자·프로젝트가 같은 이름을 만들면 그쪽이 이긴다.
+  // 끄고 싶으면 opts.내장 = false (검사에서 이 여섯을 세지 않으려고 쓴다).
+  if (opts.내장 !== false) skillsIn(내장자리, 'builtin', null, skills, caps.skills);
+
   // 1) 플러그인
   // 같은 플러그인이 cache/ 와 marketplaces/ 양쪽에 있을 수 있다.
   // 이름이 같으면 알맹이가 더 많은 쪽 하나만 쓴다.

package/src/tools/edit-match.js

@@ -46,11 +46,22 @@ function findAll(text, needle, tier) {
   let re;
   try { re = new RegExp(p, 'g'); } catch { return []; }
   const out = [];
-  for (const m of text.matchAll(re)) {
-    if (m[0].length === 0) continue;
-    out.push({ start: m.index, end: m.index + m[0].length });
-    if (out.length > 50) break;   // 너무 많으면 어차피 모호하다
-  }
+  // 만들 때 말고 **돌릴 때** 터지는 것이 있다.
+  //
+  // 모델은 큰 파일을 고칠 때 덩이를 통째로 old_string 에 담아 보낸다. 4만 자쯤
+  // 넘어가면 new RegExp 는 멀쩡히 만들어지는데(패턴만 훑는다) 실제로 돌릴 때
+  // 프로그램 크기 한도에 걸려 SyntaxError 가 난다. 위의 try 는 만들 때만 감싸므로
+  // 그 오류가 그대로 튀어나가서 "찾지 못했습니다" 대신 도구가 죽었다.
+  //
+  // 여기서는 못 찾은 것으로 친다. 정확히 일치하는 경우는 위에서 indexOf 로 이미
+  // 처리했으니, 느슨하게 맞춰 보는 이 길만 포기하는 것이다.
+  try {
+    for (const m of text.matchAll(re)) {
+      if (m[0].length === 0) continue;
+      out.push({ start: m.index, end: m.index + m[0].length });
+      if (out.length > 50) break;   // 너무 많으면 어차피 모호하다
+    }
+  } catch { return []; }
   return out;
 }
 

package/src/tools/excel-com.js

@@ -17,7 +17,7 @@
 //   2) 엑셀은 바쁘면 호출을 거절한다(0x80010001, 0x800AC472). 잘못된 호출이
 //      아니라 '지금은 말고' 라는 뜻이라, 쉬었다 다시 부르면 된다.
 import { spawn } from 'node:child_process';
-import { mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { decode } from './encoding.js';

package/src/tools/excel.js

@@ -5,7 +5,7 @@
 //
 // 부르는 쪽은 어느 갈래인지 몰라도 된다. 다만 암호가 필요할 때는 물어볼 수
 // 있어야 하므로, 물어보는 방법을 받아 온다(askPassword).
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 import { readXlsx, toCsv, looksXlsx, looksOle } from './xlsx.js';
 import { excelToTables, canUseExcel } from './excel-com.js';

package/src/tools/fsutil.js

@@ -171,14 +171,6 @@ export function walk(root, { limit = 20000, skipDirs = SKIP_DIRS } = {}) {
   return out;
 }
 
-// 텍스트 파일인지 — 앞부분에 NUL 이 있으면 바이너리로 본다.
-export function isText(path) {
-  try {
-    const fd = readFileSync(path);
-    return !fd.subarray(0, 8000).includes(0);
-  } catch { return false; }
-}
-
 /**
  * 글 파일을 읽는다. 무엇으로 쓰여 있든 알아보고 읽는다.
  *

package/src/tools/index.js

@@ -3,7 +3,7 @@
 import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { execFile } from 'node:child_process';
-import { globToRegex, walk, readText, readTextFull, SKIP_DIRS, 내부살림 } from './fsutil.js';
+import { globToRegex, walk, readText, readTextFull, 내부살림 } from './fsutil.js';
 import { encode, label as encLabel, decode as decodeBytes, consoleCodepage, looksBinary } from './encoding.js';
 import { checkCommand, checkPaths, isMutating } from '../safety/guard.js';
 import { 띄우기, JOBS_TOOL } from './jobs.js';

package/src/tools/todo.js

@@ -39,16 +39,32 @@ export function render(items) {
 export const TODO_TOOL = {
   schema: {
     name: 'TodoWrite',
+    /*
+     * 문장 차례가 곧 중요도다.
+     *
+     * 창이 좁으면 tools/index.js 가 **뒤에서부터 문장째로 잘라 낸다**(설명길이).
+     * 그러니 규격(state·doing)이 뒤에 있으면 작은 모델에서 조용히 사라진다.
+     * 규격 → 규칙 → 조언 차례로 둔다.
+     *
+     * '세 단계 이상 걸리는 일이면' 이라고 적었더니 모델이 그걸 **세 개를 적으라는
+     * 말**로 읽었다. 열 단계짜리 일도 세 줄로 뭉쳐 나왔다. 그래서 개수 이야기를
+     * 따로 못 박는다 — 개수는 일의 크기가 정하는 것이고 상한이 없다.
+     */
     description:
-      '할 일 목록을 만들고 갱신한다. 세 단계 이상 걸리는 일이면 먼저 목록을 만들고, '
+      '할 일 목록을 만들고 갱신한다. 여러 단계가 걸리는 일이면 먼저 목록을 만들고, '
       + '하나를 끝낼 때마다 바로 갱신한다. 목록 전체를 매번 통째로 보낸다. '
-      + 'state 는 todo(아직) / doing(하는 중) / done(끝) 셋 중 하나이고, doing 은 한 번에 하나만 둔다.',
+      + 'state 는 todo(아직) / doing(하는 중) / done(끝) 셋 중 하나이고, doing 은 한 번에 하나만 둔다. '
+      + '단계 수는 일의 크기가 정한다 — 정해진 개수도 상한도 없다. '
+      + '개수를 맞추려고 다른 일을 한 줄에 뭉치지 마라. '
+      + '각 단계는 끝났는지 따로 확인할 수 있는 크기로 적어라.',
     parameters: {
       type: 'object',
       properties: {
         todos: {
           type: 'array',
-          description: '할 일 전체 목록',
+          // 인자 설명은 따로 잘리므로, 개수 이야기를 여기에도 한 번 둔다.
+          // 창이 좁아 바깥 설명이 잘려 나가도 이건 남는다.
+          description: '할 일 전체 목록. 개수 제한 없음 — 일의 크기만큼 적는다',
           items: {
             type: 'object',
             properties: {

package/src/ui/ansi.js

@@ -54,6 +54,12 @@ export const cursor = {
   show: () => ON && process.stdout.write('\x1b[?25h'),
   up: (n = 1) => ON && process.stdout.write(`\x1b[${n}A`),
   clearLine: () => ON && process.stdout.write('\x1b[2K\r'),
+  // 여러 조각을 한 덩이로 묶어 한 번에 내보낼 때 쓰는 글자값.
+  //
+  // 나눠 쓰면 그 사이가 화면에 그대로 보인다. 커서를 숨기기 전에 지우는 글이
+  // 먼저 나가면, 커서가 상자 안을 훑고 지나가는 것이 눈에 띈다.
+  숨김: ON ? '\x1b[?25l' : '',
+  보임: ON ? '\x1b[?25h' : '',
 };
 
 // 한글·한자·가나는 터미널에서 두 칸을 차지한다. 표 정렬이 이걸 모르면 어긋난다.
@@ -175,5 +181,3 @@ export const mark = {
   tree: c.gray('└'),
   branch: c.gray('├'),
 };
-
-export const COLOR_ON = ON;

package/src/ui/inputbox.js

@@ -36,7 +36,8 @@
 import { c, width, cursor, clip } from './ansi.js';
 import { statusLine, contextWarning } from './status.js';
 import { 접어쓰기 } from './wrap.js';
-import { 문구고르기, 돌림틀, 걸린시간, 느긋해질때, 문구주기 } from './working.js';
+import { 문구고르기, 걸린시간, 느긋해질때, 문구주기 } from './working.js';
+import { 그림고르기 } from './motion.js';
 import { 최대추천 } from './complete.js';
 
 const 줄끝지움 = '\x1b[K';
@@ -317,7 +318,9 @@ export class InputBox {
     const 갈래 = 지난 >= 느긋해질때 ? '느긋' : this.일감.갈래;
     const 회차 = Math.floor((this.틱 * 돌림주기) / 문구주기);
     this.그리기(this.session, '', 0, {
-      돌림: 돌림틀[this.틱 % 돌림틀.length],
+      // 갈래에 맞는 작은 그림. 무엇을 하는 중인지 글자와 그림이 같이 말한다.
+      // DEEL_NO_MOTION=1 이면 예전처럼 한 칸짜리 돌림표가 온다.
+      돌림: 그림고르기(갈래, this.틱),
       말: 문구고르기(갈래, 회차),
       곁: [
         걸린시간(지난),
@@ -369,7 +372,6 @@ export class InputBox {
       process.stdout.write('\n');
       this.줄중간 = false;
     }
-    this.지우기();
 
     const { 줄들, 커서: 자리 } = 프레임({
       글,
@@ -382,10 +384,35 @@ export class InputBox {
       추천,
     });
 
-    cursor.hide();
-    process.stdout.write(줄들.map((l) => l + 줄끝지움).join('\n') + '\n');
     /*
-     * 방금 찍은 마지막 줄 **다음** 줄에 커서가 있다. 거기서 되짚어 올라간다.
+     * ── 지우지 않고 덮어쓴다. 그리고 한 번에 내보낸다 ────────────────────
+     *
+     * 예전에는 이랬다: 지우기() 로 상자를 싹 지우고 → 새로 그리고 → 커서를
+     * 되돌린다. 세 번을 따로 내보냈다. 터미널은 받는 대로 그리므로 **그 사이가
+     * 사람 눈에 보인다** — 상자가 한 번 비었다가 다시 차는 것이 백스페이스를
+     * 누를 때마다 반복되어, 화면이 깜빡 꺼지는 것처럼 느껴졌다. 글자를 지울
+     * 때는 한 번에 한 글자씩 여러 번 누르므로 특히 심했다.
+     *
+     * 그래서 두 가지를 바꿨다.
+     *   1) 지우고 다시 그리지 않는다. 상자 맨 윗줄로 올라가 **덮어쓴다.**
+     *      줄 끝마다 줄끝지움이 붙으므로 전에 있던 글자가 남을 자리가 없다.
+     *      빈 화면이 스쳐 가는 순간 자체가 사라진다.
+     *   2) 지우기·그리기·커서 되돌리기를 한 덩이로 묶어 **한 번만** 쓴다.
+     *      중간 상태가 화면에 못 나간다.
+     *
+     * 상자가 전보다 짧아졌을 때만 남는 줄이 생긴다. 그때만 그 줄을 지운다.
+     */
+    const 이전줄 = this.그린줄;
+    // 커서는 상자 아래에서 커서위 번째 줄에 있다. 맨 윗줄까지 남은 거리.
+    const 윗줄까지 = 이전줄 ? Math.max(0, 이전줄 - 1 - this.커서위) : 0;
+    const 남은줄 = Math.max(0, 이전줄 - 줄들.length);
+
+    let 나갈것 = cursor.숨김 + '\r' + 위로(윗줄까지);
+    나갈것 += 줄들.map((l) => l + 줄끝지움).join('\n') + '\n';
+    for (let i = 0; i < 남은줄; i++) 나갈것 += 줄끝지움 + '\n';
+    /*
+     * 방금 찍은 마지막 줄 **다음** 줄에 커서가 있다(남은 줄을 지웠으면 그만큼
+     * 더 아래). 거기서 되짚어 올라간다.
      *
      * 오른쪽으로 옮길 때 한 칸이 어긋나기 쉽다. \r 은 커서를 1칸째에 놓고,
      * \x1b[nC 는 거기서 n칸 **더** 간다 — 그래서 1부터 세는 목표 칸으로
@@ -393,8 +420,10 @@ export class InputBox {
      * 백스페이스가 엉뚱한 자리를 지우는 것처럼 보인다.
      */
     const 오른쪽 = Math.max(0, 자리.열 - 1);
-    process.stdout.write(위로(자리.위 + 1) + '\r' + (오른쪽 ? `\x1b[${오른쪽}C` : ''));
-    cursor.show();
+    나갈것 += 위로(남은줄 + 자리.위 + 1) + '\r' + (오른쪽 ? `\x1b[${오른쪽}C` : '');
+    나갈것 += cursor.보임;
+    process.stdout.write(나갈것);
+
     this.그린줄 = 줄들.length;
     this.커서위 = 자리.위;
   }