deel-local-cli 0.8.0 → 1.0.0

package/src/agent/memory.js

@@ -0,0 +1,152 @@
+/**
+ * 기억 — 대화가 끝나도 남는 것.
+ *
+ * 왜 필요한가:
+ *   대화는 켤 때마다 처음부터다. 그래서 매번 같은 것을 설명하게 된다 —
+ *   "우리 문서는 CP949 다", "검증 포트로 7080 은 쓰지 마라", "빌드는 npm run b".
+ *   /compact 로 접히면 그마저 사라진다. 사람은 두 번째부터 짜증이 나고,
+ *   세 번째부터는 그냥 안 쓴다.
+ *
+ *   지난 대화 찾기(recall.js)와는 다른 물건이다. 그쪽은 **찾아야** 나오고,
+ *   이쪽은 **처음부터 들어가 있다.** 매번 찾으라고 할 수 없는 것 —
+ *   지켜야 하는 규칙, 되풀이하면 안 되는 실수 — 이 여기 온다.
+ *
+ * 어디에 두나:
+ *   .deel/memory.md — 사람이 열어 고칠 수 있는 글이다. 데이터베이스가 아니다.
+ *   이게 중요하다. 모델이 잘못 적은 것을 사람이 지울 수 있어야 한다.
+ *   틀린 기억은 없느니만 못하다 — 매 요청에 실려 계속 틀리게 만든다.
+ *
+ * 왜 상한을 두나:
+ *   기억은 **매 요청마다** 통째로 나간다. 백 줄이면 백 줄이 매번 나간다.
+ *   그래서 자리를 정해 두고, 넘으면 넘었다고 말한다.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// 기억 전체가 차지할 수 있는 최대 글자. 대략 2,000 토큰쯤이다.
+export const 기억최대 = 6000;
+// 한 줄이 이보다 길면 자른다. 모델이 파일을 통째로 기억에 넣으려 드는 일이 있다.
+export const 한줄최대 = 400;
+// 줄 수 상한. 자리가 남아도 이보다 많으면 사람이 못 읽는다.
+export const 줄최대 = 60;
+
+export const 자리 = (root) => join(root, '.deel', 'memory.md');
+
+const 머리말 = `# 기억
+
+이 파일은 deel 이 대화 사이에 들고 다니는 메모입니다.
+매 요청마다 모델에게 통째로 실려 나갑니다 — 그러니 짧게, 오래 갈 것만 적습니다.
+
+직접 고치셔도 됩니다. 틀린 줄은 지우세요. 지우면 그걸로 끝입니다.
+`;
+
+/** 파일에서 기억 줄을 읽어 온다. 머리말과 빈 줄은 뺀다. */
+export function 읽기(root) {
+  const p = 자리(root);
+  if (!existsSync(p)) return { 줄들: [], 자리: p, 있음: false };
+  let 글;
+  try { 글 = readFileSync(p, 'utf8'); } catch { return { 줄들: [], 자리: p, 있음: false }; }
+  const 줄들 = [];
+  for (const raw of 글.split(/\r?\n/)) {
+    const l = raw.trim();
+    if (!l) continue;
+    if (l.startsWith('#')) continue;                 // 머리말
+    if (l.startsWith('이 파일은') || l.startsWith('매 요청마다')) continue;
+    if (l.startsWith('직접 고치셔도') || l.startsWith('직접 고치')) continue;
+    줄들.push(l.replace(/^[-*]\s*/, ''));            // 목록 표시는 떼고 담는다
+  }
+  return { 줄들, 자리: p, 있음: true };
+}
+
+/** 줄들을 파일로 되돌려 쓴다. */
+export function 쓰기(root, 줄들) {
+  const p = 자리(root);
+  mkdirSync(dirname(p), { recursive: true });
+  const 몸 = 줄들.map((l) => `- ${l}`).join('\n');
+  writeFileSync(p, `${머리말}\n${몸}\n`, 'utf8');
+  return p;
+}
+
+/**
+ * 한 줄을 더한다.
+ *
+ * 이미 있는 것과 거의 같으면 안 더한다. 안 그러면 같은 말이 조금씩 다른 꼴로
+ * 스무 줄 쌓인다 — 모델은 자기가 방금 적은 것을 기억 못 하기 때문이다.
+ *
+ * @returns {{ok: boolean, why?: string, 줄: string, 줄수: number, 넘침?: boolean}}
+ */
+export function 더하기(root, 글) {
+  const 줄 = 다듬기(글);
+  if (!줄) return { ok: false, why: '적을 내용이 비었습니다', 줄: '', 줄수: 0 };
+
+  const { 줄들 } = 읽기(root);
+  if (줄들.some((x) => 같은말(x, 줄))) {
+    return { ok: false, why: '이미 기억하고 있습니다', 줄, 줄수: 줄들.length };
+  }
+
+  const 새것 = [...줄들, 줄];
+  // 자리가 넘치면 **오래된 것부터** 뺀다. 최근에 정한 것이 대개 맞다.
+  let 넘침 = false;
+  while (새것.length > 줄최대 || 새것.join('\n').length > 기억최대) {
+    if (새것.length <= 1) break;
+    새것.shift();
+    넘침 = true;
+  }
+  쓰기(root, 새것);
+  return { ok: true, 줄, 줄수: 새것.length, 넘침 };
+}
+
+/** 번호로 지운다(1부터). 사람이 /memory 화면을 보고 고르는 자리다. */
+export function 지우기(root, 번호) {
+  const { 줄들 } = 읽기(root);
+  const i = Number(번호) - 1;
+  if (!Number.isInteger(i) || i < 0 || i >= 줄들.length) return { ok: false, why: '그런 번호가 없습니다' };
+  const 뺀것 = 줄들[i];
+  const 남은것 = 줄들.filter((_, n) => n !== i);
+  쓰기(root, 남은것);
+  return { ok: true, 뺀것, 줄수: 남은것.length };
+}
+
+/** 통째로 비운다. */
+export function 비우기(root) {
+  쓰기(root, []);
+  return { ok: true };
+}
+
+/** 한 줄로 다듬는다 — 줄바꿈을 없애고 길이를 자른다. */
+function 다듬기(글) {
+  let s = String(글 ?? '').replace(/\s+/g, ' ').trim();
+  s = s.replace(/^[-*]\s*/, '');
+  if (s.length > 한줄최대) s = s.slice(0, 한줄최대) + '…';
+  return s;
+}
+
+/**
+ * 두 줄이 사실상 같은 말인가.
+ *
+ * 글자 그대로 비교하면 "CP949 를 쓴다" 와 "CP949를 쓴다" 가 다른 줄이 된다.
+ * 공백·조사·문장부호를 털고 견준다. 완벽할 필요는 없다 —
+ * 여기서 하려는 것은 '똑같은 말이 쌓이는 것' 을 막는 것뿐이다.
+ */
+function 같은말(a, b) {
+  const 털기 = (s) => String(s).toLowerCase().replace(/[\s.,!?~·'"()[\]]/g, '');
+  const x = 털기(a);
+  const y = 털기(b);
+  if (x === y) return true;
+  // 한쪽이 다른 쪽을 통째로 품고 있고 길이 차가 크지 않으면 같은 말로 본다.
+  const [짧, 긴] = x.length <= y.length ? [x, y] : [y, x];
+  return 짧.length >= 8 && 긴.includes(짧) && 긴.length - 짧.length <= 짧.length * 0.5;
+}
+
+/**
+ * 시스템 프롬프트에 넣을 토막.
+ *
+ * 없으면 빈 글을 돌려준다 — "기억: (없음)" 같은 줄을 넣으면 그 자체가
+ * 매 요청마다 나가는 쓰레기가 된다.
+ */
+export function 프롬프트토막(root) {
+  const { 줄들 } = 읽기(root);
+  if (!줄들.length) return '';
+  return '\n--- 기억 (지난 대화에서 정한 것. 사용자가 다시 말하지 않아도 지킨다) ---\n'
+    + 줄들.map((l) => `- ${l}`).join('\n');
+}

package/src/agent/mention.js

@@ -0,0 +1,164 @@
+// @파일 지목 — 말 속에 @경로 를 쓰면 그 파일을 바로 붙여 보낸다.
+//
+// 왜 필요한가:
+//   지금은 파일 하나 보여주려면 모델이 Read 도구를 스스로 불러야 한다. 왕복이
+//   한 번 더 든다. 로컬 모델은 도구 호출이 약해서 그 한 번이 자주 헛돈다 —
+//   엉뚱한 경로를 부르거나, 아예 안 부르고 지어낸다. 사람은 이미 어느 파일인지
+//   알고 있는데 모델더러 찾아보라고 시키는 셈이다.
+//
+// 여기서 어려운 것은 붙이는 일이 아니라 '아닌 것을 파일로 오해하지 않기' 다.
+// @ 로 시작하는 것은 세상에 널렸다 — 이메일 주소, CSS 의 @media, 파이썬 장식자,
+// npm 의 @scope/pkg, 사람 아이디. 잘못 붙이면 엉뚱한 글이 대화에 섞여 들어가고,
+// 사람은 자기가 안 보낸 것이 왜 거기 있는지 모른다.
+//
+// 그래서 규칙을 하나로 뒀다: **실제로 있는 경로일 때만 붙인다.**
+// 없으면 아무 말 없이 글자 그대로 둔다. 지목이 아니었을 테니 조용한 편이 맞다.
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { readTextFull } from '../tools/fsutil.js';
+import { estimateTokens } from './session.js';
+
+// 붙일 수 있는 최대 토큰. 부르는 쪽에서 컨텍스트에 맞춰 넘겨준다.
+const 기본예산 = 6000;
+const 폴더최대 = 60;      // 폴더를 지목했을 때 늘어놓을 항목 수
+const 뒤에붙는것 = /[,.?!;:)\]}"'」』]+$/;
+
+/**
+ * 글에서 @지목을 찾는다. 붙일지 말지는 여기서 안 정한다 — 자리만 찾는다.
+ *
+ * @returns {Array<{path:string, start:number, end:number, raw:string}>}
+ */
+export function findMentions(text) {
+  const s = String(text ?? '');
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] !== '@') continue;
+    // 앞이 글자면 지목이 아니다 — hong@example.com 의 @ 가 여기서 걸러진다.
+    const 앞 = i > 0 ? s[i - 1] : ' ';
+    if (!/[\s(\[{'"]/.test(앞)) continue;
+
+    // @"띄어쓰기 든 이름.txt" — 따옴표로 묶으면 통째로 하나다.
+    if (s[i + 1] === '"' || s[i + 1] === "'") {
+      const 따옴 = s[i + 1];
+      const 끝 = s.indexOf(따옴, i + 2);
+      if (끝 > i + 2) {
+        out.push({ path: s.slice(i + 2, 끝), start: i, end: 끝 + 1, raw: s.slice(i, 끝 + 1) });
+        i = 끝;
+        continue;
+      }
+    }
+
+    let j = i + 1;
+    while (j < s.length && !/[\s"'`]/.test(s[j])) j++;
+    if (j === i + 1) continue;                    // @ 뒤가 비었다
+    const raw = s.slice(i, j);
+    out.push({ path: s.slice(i + 1, j), start: i, end: j, raw });
+    i = j - 1;
+  }
+  return out;
+}
+
+/** 이 지목이 가리키는 실제 자리. 못 찾거나 범위 밖이면 왜인지 같이 준다. */
+function 찾아보기(m, scope) {
+  const 후보 = [m.path];
+  // 뒤에 붙은 문장부호를 떼고도 한 번 본다 — "@src/a.js, 이것" 처럼 쓴다.
+  const 뗀것 = m.path.replace(뒤에붙는것, '');
+  if (뗀것 && 뗀것 !== m.path) 후보.push(뗀것);
+
+  for (const p of 후보) {
+    if (!p) continue;
+    let abs;
+    try { abs = scope.resolve(p); }
+    catch (err) { return { why: 'blocked', note: err.message, path: p }; }
+    if (existsSync(abs)) return { abs, path: p };
+  }
+  return { why: 'missing', path: m.path };
+}
+
+function 폴더내용(abs, show) {
+  let 목록 = [];
+  try { 목록 = readdirSync(abs, { withFileTypes: true }); }
+  catch (err) { return `(폴더를 못 읽었습니다: ${err.message})`; }
+  const 줄들 = 목록.slice(0, 폴더최대).map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+  const 더 = 목록.length > 폴더최대 ? `\n… 전체 ${목록.length}개 중 ${폴더최대}개까지` : '';
+  return `${show} 는 폴더입니다. 안에 든 것:\n${줄들.join('\n')}${더}`;
+}
+
+/**
+ * @지목을 실제 내용으로 바꿔 붙인다.
+ *
+ * 글 자체는 안 건드린다 — 사람이 쓴 말은 그대로 두고, 뒤에 파일을 덧붙인다.
+ * 지목한 자리를 내용으로 갈아치우면 "@src/a.js 이거 왜 느려?" 가 코드 덩어리
+ * 한복판에서 끝나는 문장이 되어 버려서, 모델이 무엇을 물었는지 놓친다.
+ *
+ * @param {string} text
+ * @param {{scope?:object, budget?:number, seen?:Set<string>, onRead?:Function}} opts
+ *   seen 을 주면 통째로 붙은 파일을 '읽은 것' 으로 적어 둔다 — 그래야 Edit 이
+ *   'Read 부터 하라' 며 되돌려 보내지 않는다. 잘린 파일은 안 적는다.
+ *   안 본 데를 본 것으로 치면 그 자리를 그냥 고쳐 버린다.
+ */
+export function expand(text, { scope = null, budget = 기본예산, seen = null, onRead = null } = {}) {
+  const 원문 = String(text ?? '');
+  const 빈답 = { text: 원문, attached: [], missing: [], blocked: [] };
+  if (!원문.includes('@') || !scope?.resolve) return 빈답;
+
+  const 지목들 = findMentions(원문);
+  if (!지목들.length) return 빈답;
+
+  const attached = [];
+  const missing = [];
+  const blocked = [];
+  const 붙일것 = [];
+  const 본것 = new Set();
+  let 남은예산 = Math.max(200, Number(budget) || 기본예산);
+
+  for (const m of 지목들) {
+    const 자리 = 찾아보기(m, scope);
+    if (자리.why === 'blocked') { blocked.push({ path: 자리.path, why: 자리.note }); continue; }
+    if (자리.why === 'missing') { missing.push(자리.path); continue; }
+    if (본것.has(자리.abs)) continue;               // 같은 파일을 두 번 적지 않는다
+    본것.add(자리.abs);
+
+    const show = scope.show ? scope.show(자리.abs) : 자리.path;
+    let 몸통;
+    let 통째로 = true;
+
+    try {
+      if (statSync(자리.abs).isDirectory()) {
+        몸통 = 폴더내용(자리.abs, show);
+      } else {
+        // 사내 파일은 CP949 가 흔하다. 그냥 읽으면 통째로 깨진다.
+        const 읽음 = readTextFull(자리.abs);
+        const 줄들 = 읽음.text.split('\n');
+        const 붙은글 = 줄들.map((l, i) => `${String(i + 1).padStart(6)}\t${l}`).join('\n');
+        if (estimateTokens(붙은글) <= 남은예산) {
+          몸통 = 붙은글;
+        } else {
+          // 예산만큼만 앞에서 자른다. 글자 수로 어림잡되 남는 쪽으로 잡는다.
+          통째로 = false;
+          const 어림 = Math.max(1, Math.floor(남은예산 * 3));
+          const 자른것 = 붙은글.slice(0, 어림);
+          const 마지막줄 = 자른것.split('\n').length;
+          몸통 = `${자른것}\n… 전체 ${줄들.length}줄 중 ${마지막줄}줄까지만 붙였습니다 (나머지는 Read 로 읽으세요)`;
+        }
+        if (onRead) onRead(자리.abs, 읽음.text);
+        if (통째로 && seen) seen.add(자리.abs);
+      }
+    } catch (err) {
+      // 못 읽는 파일(바이너리 등)은 붙이지 않는다. 그렇다고 말은 해 준다.
+      몸통 = `(못 읽었습니다: ${err.message})`;
+      통째로 = false;
+    }
+
+    const 토막 = `\n\n--- ${show} ---\n${몸통}\n--- ${show} 끝 ---`;
+    남은예산 -= estimateTokens(토막);
+    붙일것.push(토막);
+    attached.push({ path: 자리.abs, show, full: 통째로 });
+    if (남은예산 <= 0) break;
+  }
+
+  if (!붙일것.length) return { text: 원문, attached, missing, blocked };
+  const 머리 = attached.length === 1
+    ? '아래는 사용자가 @ 로 지목한 파일입니다. 이미 읽은 것으로 치고 답하세요.'
+    : `아래는 사용자가 @ 로 지목한 파일 ${attached.length}개입니다. 이미 읽은 것으로 치고 답하세요.`;
+  return { text: `${원문}\n\n${머리}${붙일것.join('')}`, attached, missing, blocked };
+}

package/src/agent/modes.js

@@ -11,13 +11,51 @@
 //   오프라인일 때 웹 도구를 숨기는 것과 같은 방식이다.
 
 // 읽기만 하는 도구. 무엇을 바꾸지 않는다.
-const 읽기 = ['Read', 'Glob', 'Grep', 'WebFetch', 'Skill'];
+// Recall 은 지난 대화를 찾는다 — 파일은 안 건드리므로 읽기 쪽이다.
+// 묻기 모드에도 준다: "저번에 이거 어떻게 했더라" 가 딱 묻기 모드의 일이다.
+const 읽기 = ['Read', 'Glob', 'Grep', 'WebFetch', 'Skill', 'Recall'];
 // 계획을 적는 도구. 파일을 안 건드리므로 읽기 전용 모드에서도 준다.
-const 계획 = ['TodoWrite'];
+//
+// Remember 도 여기 있다. 기억은 사용자의 소스를 안 건드리고 .deel/memory.md
+// 한 줄을 더할 뿐이다. 오히려 계획·설계 모드에서 정한 것이야말로 다음에
+// 이어질 때 필요하다 — 거기서 못 적으면 정한 것이 그대로 날아간다.
+const 계획 = ['TodoWrite', 'Remember'];
 // 바꾸는 도구.
-const 쓰기 = ['Write', 'Edit', 'Bash'];
+// Append 는 Write 와 짝이다 — 출력 상한이 작은 모델이 큰 파일을 나눠 쓰는 길이다.
+// Write 를 주는 자리에는 반드시 같이 준다. 하나만 주면 나눠 쓸 방법이 없어진다.
+const 쓰기 = ['Write', 'Append', 'Edit', 'Bash'];
 
 export const MODES = {
+  // 처음에는 여기서 시작한다.
+  //
+  // 무슨 일을 시킬지 미리 정해 두고 켜는 사람은 드물다. 그래서 기본은 '종합' 이고,
+  // 한마디를 할 때마다 그 말이 무슨 일인지 보고 알맞은 모드로 저절로 옮겨 간다
+  // (agent/route.js). 애매하면 안 옮기고 여기 그대로 둔다.
+  //
+  // 사용자가 /plan 처럼 직접 고르면 저절로 옮기는 것은 멈춘다. 사람이 고른 것을
+  // 뒤집지 않는다. 다시 맡기려면 /work 종합 이다.
+  auto: {
+    id: 'auto',
+    name: '종합',
+    en: 'Auto',
+    glyph: '◎',
+    hint: '요청에 따라 알맞은 모드로',
+    tools: [...읽기, ...계획, ...쓰기],
+    effort: 'save',
+    think: null,
+    steps: 24,
+    say: [
+      '지금은 **종합** 모드다. 무슨 일이 올지 정해져 있지 않다.',
+      '',
+      '- 시키는 일이 무엇인지 먼저 가늠하고, 그에 맞는 방식으로 해라.',
+      '  고치는 일이면 읽고 나서 고치고, 원인을 찾는 일이면 확인부터 하고,',
+      '  설명하는 일이면 근거를 파일에서 대라.',
+      '- 큰 일이면 TodoWrite 로 쪼개 적고 하나씩 해라.',
+      '- 확인할 수 있는 것은 확인해라. 확인 못 한 것을 됐다고 하지 마라.',
+      '- 시키지 않은 일을 벌이지 마라.',
+    ].join('\n'),
+  },
+
   code: {
     id: 'code',
     name: '코드',
@@ -28,7 +66,17 @@ export const MODES = {
     effort: 'save',            // 첫 판단만 세게, 이어가기는 얕게
     think: null,               // 사용자가 정한 값을 그대로 쓴다
     steps: 24,
-    say: '코드를 읽고 고칩니다. 고치기 전에 반드시 먼저 읽으세요.',
+    say: [
+      "지금 하는 일은 **구현**이다. 아래 순서를 지켜라.",
+      "",
+      "1. 고칠 파일을 먼저 Read 로 읽는다. 안 읽고 고치려 하면 도구가 거절한다.",
+      "2. 주변 코드의 관례를 따른다 — 이름 짓는 법, 오류 다루는 법, 주석 밀도까지.",
+      "   새 관례를 들여오지 마라. 이 코드가 이미 하고 있는 대로 한다.",
+      "3. 한 번에 하나씩 고친다. 여러 파일에 흩뿌리지 마라.",
+      "4. 고친 뒤에는 확인할 방법이 있으면 실제로 돌려 본다 (검사·빌드·실행).",
+      "   확인 못 했으면 \"확인 못 했다\" 고 말한다. 됐다고 하지 마라.",
+      "5. 끝나면 무엇을 왜 바꿨는지 한두 줄로 말한다. 코드를 통째로 붙여넣지 마라.",
+    ].join('\n'),
   },
 
   architect: {
@@ -41,9 +89,23 @@ export const MODES = {
     effort: 'deep',
     think: 'high',
     steps: 20,
-    say: '구조와 설계를 다룹니다. 파일을 바꾸는 도구는 주어지지 않았습니다. '
-       + '지금 코드를 충분히 읽고, 어디를 어떻게 바꿀지 근거와 함께 제안하세요. '
-       + '고르는 이유와 버리는 이유를 같이 적으세요.',
+    say: [
+      "지금 하는 일은 **설계**다. 파일을 바꾸는 도구는 주어지지 않았다.",
+      "",
+      "먼저 읽어라. 지금 구조를 모르면 설계가 아니라 상상이다.",
+      "  - 관련된 파일을 Glob/Grep 으로 찾고 Read 로 실제로 읽는다",
+      "  - 무엇이 무엇에 기대고 있는지(의존 방향)를 파악한다",
+      "",
+      "그 다음 이 차례로 답한다.",
+      "  1. 지금 구조 — 파일과 역할, 경계가 어디인지 (경로:줄 로 짚어라)",
+      "  2. 무엇이 문제인가 — 왜 지금 모양으로는 안 되는지",
+      "  3. 선택지 2~3개 — 각각 무엇을 얻고 무엇을 잃는지, 손이 얼마나 가는지",
+      "  4. 추천 하나와 그 이유, 버린 것을 왜 버렸는지",
+      "  5. 영향받는 파일 목록",
+      "",
+      "이 코드가 이미 쓰는 관례 안에서 답을 찾아라. 새 틀을 들여오는 것은 마지막",
+      "수단이고, 그때는 왜 기존 관례로 안 되는지를 먼저 밝혀라.",
+    ].join('\n'),
   },
 
   ask: {
@@ -56,8 +118,14 @@ export const MODES = {
     effort: 'even',
     think: 'low',
     steps: 8,
-    say: '질문에 답하고 설명합니다. 시키지 않은 일을 벌이지 마세요. '
-       + '코드를 읽어 근거를 대되, 고치라는 말이 없으면 고칠 것을 제안하지 마세요.',
+    say: [
+      "지금 하는 일은 **설명**이다. 아무것도 바꾸지 않는다.",
+      "",
+      "- 근거를 파일에서 대라. 경로와 줄 번호를 같이 적어라 (src/a.js:42).",
+      "- 모르면 모른다고 하라. 그럴듯한 답을 지어내지 마라.",
+      "- 짧게, 물어본 것에만 답하라.",
+      "- 고치라는 말이 없으면 고칠 것을 제안하지 마라. 시키지 않은 일을 벌이지 마라.",
+    ].join('\n'),
   },
 
   debug: {
@@ -70,9 +138,20 @@ export const MODES = {
     effort: 'deep',
     think: 'high',
     steps: 32,               // 원인 찾기는 왔다 갔다 하므로 여유를 준다
-    say: '무엇이 잘못됐는지 찾습니다. 고치기 전에 원인을 먼저 밝히세요. '
-       + '짐작으로 고치지 말고, 확인할 수 있는 것을 확인하세요 — 로그를 보고, '
-       + '작은 것을 실제로 돌려 보고, 무엇이 사실인지 말한 다음 고치세요.',
+    say: [
+      "지금 하는 일은 **원인 찾기**다. 짐작으로 고치지 마라.",
+      "",
+      "이 순서를 지켜라.",
+      "  1. 증상을 한 문장으로 다시 적는다 — 무엇을 했을 때 무엇이 일어나는가.",
+      "  2. 재현 방법을 확보한다. 없으면 만든다. 재현 못 하면 고쳤는지도 알 수 없다.",
+      "  3. 가설을 2~3개 세운다. 각각 \"이게 맞다면 무엇이 보여야 하는가\" 를 같이 적는다.",
+      "  4. 하나씩 실제로 확인한다 — 로그를 보고, 작게 돌려 보고, 값을 찍어 본다.",
+      "     확인한 것만 사실이다. 확인 안 한 것은 아직 가설이다.",
+      "  5. 원인을 짚을 때는 증거를 같이 댄다. \"아마\" 로 시작하는 원인은 원인이 아니다.",
+      "  6. 고친 뒤 2번의 재현 절차로 다시 확인한다. 안 고쳐졌으면 3번으로 돌아간다.",
+      "",
+      "한 번에 여러 곳을 고치지 마라. 무엇이 고쳤는지 알 수 없게 된다.",
+    ].join('\n'),
   },
 
   plan: {
@@ -85,9 +164,26 @@ export const MODES = {
     effort: 'deep',
     think: 'high',
     steps: 16,
-    say: '먼저 계획만 세웁니다. 파일을 바꾸는 도구는 주어지지 않았습니다. '
-       + '무엇을 어떤 순서로 할지, 위험이 무엇인지 적고 멈추세요. '
-       + '사용자가 승인하면 그때 코드 모드로 바뀝니다.',
+    say: [
+      "지금 하는 일은 **계획 세우기**다. 파일을 바꾸는 도구는 주어지지 않았다.",
+      "코드를 고치려 들지 마라. 계획을 내고 멈춘다.",
+      "",
+      "먼저 확인하라 — 지금 무엇이 어떻게 되어 있는지 모르면 계획이 아니라 희망이다.",
+      "  Glob/Grep 으로 관련 파일을 찾고, Read 로 실제로 읽어라.",
+      "",
+      "그 다음 이 차례로 적어라.",
+      "  1. 목표 — 무엇이 끝나면 다 된 것인가 (확인할 수 있는 문장으로)",
+      "  2. 지금 상태 — 관련된 파일과 지금 동작 (경로:줄 로 짚어라)",
+      "  3. 바꿀 것 — 파일별로 무엇을 왜",
+      "  4. 순서 — 단계별로. 각 단계는 따로 확인할 수 있는 크기로 쪼개라",
+      "  5. 위험 — 무엇이 깨질 수 있고, 깨지면 어떻게 되돌리는가",
+      "  6. 확인 방법 — 무엇을 돌려 보면 됐는지 알 수 있는가",
+      "",
+      "단계는 TodoWrite 로도 적어라. 승인 뒤 그대로 이어서 하게 된다.",
+      "모르는 것이 있으면 지어내지 말고 \"이건 확인이 필요하다\" 고 적어라.",
+      "",
+      "마지막에 \"이대로 진행할까요?\" 로 끝내라. 승인을 받으면 /code 로 바꿔 실행한다.",
+    ].join('\n'),
   },
 
   orchestrator: {
@@ -100,14 +196,24 @@ export const MODES = {
     effort: 'save',
     think: null,
     steps: 40,               // 여러 갈래를 끝까지 끌고 가야 한다
-    say: '여러 단계가 걸리는 일을 끝까지 끌고 갑니다. '
-       + '먼저 TodoWrite 로 할 일을 쪼개 적고, 하나씩 끝낼 때마다 갱신하세요. '
-       + '한 번에 하나만 진행 중으로 두세요. 다 끝나면 무엇을 했는지 요약하세요.',
+    say: [
+      "지금 하는 일은 **큰 일을 끝까지 끌고 가기**다.",
+      "",
+      "  1. 시작하자마자 TodoWrite 로 전체를 단계로 쪼개 적어라. 머릿속에만 두지 마라.",
+      "     단계는 각각 따로 확인할 수 있는 크기여야 한다.",
+      "  2. 한 번에 하나만 진행 중으로 둬라. 끝나면 바로 표시하고 다음으로 넘어가라.",
+      "  3. 각 단계 끝에서 확인하라. 확인 없이 넘어가면 어디서 어긋났는지 못 찾는다.",
+      "  4. 막히면 멈추고 무엇에 막혔는지 보고하라. 우회로를 몰래 타지 마라.",
+      "  5. 계획이 틀린 것을 알게 되면 목록을 고쳐라. 틀린 계획을 끝까지 밀지 마라.",
+      "",
+      "다 끝나면 무엇을 했는지, 무엇을 못 했는지 같이 요약하라.",
+      "못 한 것을 빼고 요약하지 마라.",
+    ].join('\n'),
   },
 };
 
-export const ORDER = ['code', 'plan', 'architect', 'debug', 'ask', 'orchestrator'];
-export const DEFAULT = 'code';
+export const ORDER = ['auto', 'code', 'plan', 'architect', 'debug', 'ask', 'orchestrator'];
+export const DEFAULT = 'auto';
 
 /** 이름을 관대하게 받는다. 한글·영문·줄임말 다 통한다. */
 export function normalize(v) {
@@ -115,6 +221,7 @@ export function normalize(v) {
   if (!s) return null;
   if (MODES[s]) return s;
   const 별명 = {
+    '종합': 'auto', '자동': 'auto', '기본': 'auto', 'auto': 'auto', '맡김': 'auto',
     '코드': 'code', 'c': 'code',
     '계획': 'plan', '플랜': 'plan', 'p': 'plan',
     '설계': 'architect', '아키': 'architect', 'arch': 'architect', 'a': 'architect',