leerness 1.9.30 → 1.9.31

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.9.31 — 2026-05-15
+
+**`leerness agents quota` — 외부 AI CLI 사용량/한도 추정 + provider 대시보드 안내**.
+
+### Added
+
+- **`leerness agents quota`** (1.9.31): 활성 CLI별 quota/rate-limit 정보 표시.
+  - **claude**: 비대화형 quota API 없음 → `/status` 슬래시 또는 https://console.anthropic.com/settings/usage 안내.
+  - **codex**: `codex --help`에서 `usage`/`quota` 키워드 감지 시 시도 가능 표시, 미감지 시 https://platform.openai.com/account/usage 안내.
+  - **gemini**: 무료 티어 `60 req/min, 1000 req/day` 명시.
+  - **copilot (gh)**: `gh auth status`로 인증 확인 → 구독자 무제한 또는 `gh auth login` 필요 안내.
+  - `--json` 출력 지원 (`{ quota: [{id, bin, status, quota, hint, raw}, ...] }`).
+- **`agents` 사용법 메시지에 `quota` 추가**: `list|check|quota|dispatch`.
+- **`agents dispatch` 안내문에 quota 명령 cross-link** (1.9.31+).
+
+### Policy
+- ❌ leerness는 사용량을 직접 추적하지 않음 (provider 대시보드 참조)
+- ✅ sub-agent 분배 시 quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
+- ✅ rate-limit/plan 차이는 provider별 다름 — leerness는 hint만 제공
+
+### 실측 (이번 라운드 사용 사례)
+- agents quota 신규 명령 검증 후 sub-agent ×3 동시 분배
+- e2e: 146/146 통과 (1.9.30 144 + quota 2)
+
 ## 1.9.30 — 2026-05-15
 
 **외부 AI CLI 오케스트레이션 — 환경변수 활성화 정책 + `leerness agents list/check/dispatch`**.

package/README.md

@@ -2,7 +2,7 @@
 
 > 한국어 우선 AI 개발 하네스. 멀티 에이전트 오케스트레이션 · 자동 검수 · 워크스페이스 가시성 · Ollama opt-in 통합.
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.29-green)]() [![tests](https://img.shields.io/badge/e2e-139%2F139-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
+[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.31-green)]() [![tests](https://img.shields.io/badge/e2e-146%2F146-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ## ⚙️ 설치 (Install)
 
@@ -31,6 +31,8 @@ npm i --save-dev leerness && npx leerness handoff .
 - LLM 컨텍스트 비용 → `--compact` 모드로 4KB → 500자
 - AI가 "API 호출 완료"라 보고했지만 코드에 호출 흔적이 없는 낙관적 표시 → `optimism-check`로 자동 감지 (1.9.26/27)
 - 코드 리뷰가 표면적이라 도메인 깊이 부족 → `leerness review <file> --persona security,performance,ux`로 도메인 페르소나 자동 부여 (1.9.29)
+- 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하고 싶지만 자동 호출은 위험 → 환경변수 활성화 + `leerness agents list/dispatch`로 명시적 분배 (1.9.30)
+- 어떤 CLI에 quota 여유가 남았는지 한눈에 보고 싶을 때 → `leerness agents quota`로 provider별 사용량/한도 추정 (1.9.31)
 
 ---
 
@@ -97,6 +99,9 @@ leerness review <file> --persona security,performance,ux   # 1.9.29 도메인
 leerness persona list                                       # 5종 내장 + 사용자 정의
 leerness persona show security                              # 페르소나 본문
 leerness persona add my-domain                              # 사용자 정의 페르소나
+leerness agents list                                        # 1.9.30 외부 AI CLI 상태표
+leerness agents quota                                       # 1.9.31 CLI별 사용량/한도 추정
+leerness agents dispatch "<task>" --to gemini               # 1.9.30 sub-agent 명령 생성
 ```
 
 ### 워크스페이스 (멀티 프로젝트)
@@ -213,6 +218,9 @@ leerness orchestrate "복잡한 기능" --agents 20
 | `handoff --compact` | LLM 시스템 프롬프트용 압축 출력 | 1.9.22 |
 | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 (security/performance/ux/testing/docs) | 1.9.29 |
 | `persona list/show/add` | 페르소나 카탈로그 관리 (.harness/personas/) | 1.9.29 |
+| `agents list/check` | 4 CLI(claude/codex/gemini/copilot) 활성/설치 상태표 (env + PATH 검증) | 1.9.30 |
+| `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 (자동 호출 금지) | 1.9.30 |
+| `agents quota` | provider별 사용량/한도 추정 + 대시보드 안내 | 1.9.31 |
 
 ---
 
@@ -293,6 +301,47 @@ leerness persona add my-domain   # .harness/personas/my-domain.md 템플릿 생
 
 ---
 
+## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31)
+
+claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용. **자동 호출 절대 금지** — 환경변수 활성화 + PATH 존재 둘 다 충족 시에만 ready.
+
+### 활성화 (`.env`)
+```bash
+LEERNESS_ENABLE_CLAUDE=1     # Anthropic Claude Code CLI
+LEERNESS_ENABLE_CODEX=1      # OpenAI Codex CLI (격리 sandbox)
+LEERNESS_ENABLE_GEMINI=1     # Google Gemini CLI (--yolo 모드는 워크스페이스 직접 수정 가능)
+LEERNESS_ENABLE_COPILOT=1    # GitHub Copilot CLI (gh copilot)
+```
+
+### 사용
+```bash
+leerness agents list                              # 4 CLI 상태표 (env + PATH + 버전)
+leerness agents quota                             # provider별 사용량/한도 추정 (1.9.31)
+leerness agents dispatch "<task>" --to gemini     # ready CLI에 명령 자동 생성
+```
+
+### quota 안내 (1.9.31)
+| CLI | 추정 | 안내 |
+|---|---|---|
+| claude | `unknown` | 대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage |
+| codex | `cli-supported` 또는 `unknown` | `codex usage`/`codex quota` 시도 또는 https://platform.openai.com/account/usage |
+| gemini | `rate-limited` | 무료 60 req/min, 1000 req/day · https://ai.google.dev/gemini-api/docs/rate-limits |
+| copilot | `subscription` 또는 `not-authed` | 월 구독자 무제한 · `gh auth login` 필요 시 안내 |
+
+### 실측 (이번 라운드)
+- Sub B (rpg-craft, Claude 페르소나) → 20/20 pass, 1,567 라인
+- Sub C (rpg-achievements, Claude 페르소나) → 22/22 pass, 1,375 라인
+- Sub D (rpg-instance, Claude 페르소나, cross-project require 시연) → 20/20 pass, 1,016 라인
+- → **3 도메인 동시 진행**, 메인 에이전트가 sub-agent들에 페르소나 + 영역 분배 + 충돌 방지 컨벤션 명시.
+
+### 정책
+- ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인 에이전트가 명시적 실행)
+- ✅ `agents dispatch`는 명령 텍스트만 출력 — 복사해서 실행
+- ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
+- ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 — 격리 sandbox 아님 (codex와 차이)
+
+---
+
 ## 🤝 Claude Code 통합
 
 설치 시 자동 등록: `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md` · `.claude/skills/leerness.md` (스킬 정의) · `.claude/settings.local.json` (SessionStart hook `update --check`) · `.cursor/rules/leerness.mdc` (Cursor) · `.github/copilot-instructions.md` (Copilot)
@@ -323,6 +372,10 @@ leerness skill consolidate
 | `LEERNESS_GITHUB_TOKEN` | gh release용 (있을 때) |
 | **`LEERNESS_OLLAMA_BASE_URL`** | **1.9.22 — orchestrate opt-in 활성화** |
 | `LEERNESS_OLLAMA_MODEL` | 기본 모델 (orchestrate `--model`로 override) |
+| **`LEERNESS_ENABLE_CLAUDE`** | **1.9.30 — `agents list/dispatch` Claude Code CLI 활성** (=1) |
+| **`LEERNESS_ENABLE_CODEX`** | **1.9.30 — Codex CLI 활성** (=1) |
+| **`LEERNESS_ENABLE_GEMINI`** | **1.9.30 — Gemini CLI 활성** (=1) |
+| **`LEERNESS_ENABLE_COPILOT`** | **1.9.30 — gh copilot 활성** (=1) |
 
 ---
 
@@ -362,12 +415,14 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
 npm test     # = node ./scripts/e2e.js
 ```
 
-**139/139 시나리오** 통과 (1.9.7~1.9.29 회귀 + 신규 검증).
+**146/146 시나리오** 통과 (1.9.7~1.9.31 회귀 + 신규 검증).
 
 ---
 
 ## 📜 변경 이력 (최근)
 
+- **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정 + 대시보드 안내). 멀티 에이전트 분배 신호.
+- **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책 + `leerness agents list/check/dispatch`
 - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배)
 - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15
 - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수

package/bin/harness.js

@@ -6,7 +6,7 @@ const path = require('path');
 const cp = require('child_process');
 const readline = require('readline');
 
-const VERSION = '1.9.30';
+const VERSION = '1.9.31';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -2373,11 +2373,73 @@ function agentsCmd(root, sub, ...args) {
     log(`## 정책 (1.9.30)`);
     log(`  - leerness는 외부 CLI를 자동 호출하지 않음 (사용자 명시적 실행)`);
     log(`  - 메인 에이전트(Claude)가 위 명령을 보고 sub-agent로 spawn 가능`);
-    log(`  - quota 체크: 각 CLI마다 다름 — claude는 /status, codex는 별도 대시보드 등`);
+    log(`  - quota 체크: \`leerness agents quota\` (1.9.31+)`);
     return;
   }
 
-  fail('사용법: leerness agents list|check|dispatch "<task>" --to <id>');
+  if (sub === 'quota') {
+    // 1.9.31: 각 CLI 사용량/쿼터 추정 + provider 대시보드 링크
+    const results = [];
+    for (const agent of EXTERNAL_AGENTS) {
+      const base = _checkAgent(agent);
+      const out = { id: agent.id, bin: agent.bin, status: base.status, quota: null, hint: null, raw: null };
+      if (base.status !== 'ready') {
+        out.hint = base.status === 'not-installed' ? `${agent.bin} CLI 미설치` : base.status === 'disabled' ? `${agent.envFlag}=1 필요` : '알 수 없음';
+        results.push(out); continue;
+      }
+      // CLI별 quota 탐지 시도
+      try {
+        if (agent.id === 'claude') {
+          // claude는 /status 슬래시 (대화형)만 지원. 비대화형 추정 불가.
+          out.quota = 'unknown';
+          out.hint = '대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage 확인';
+        } else if (agent.id === 'codex') {
+          // codex CLI: codex --help에 usage 명령 있는지 확인
+          const r = cp.spawnSync(agent.bin, ['--help'], { encoding: 'utf8', timeout: 4000, shell: true });
+          const help = (r.stdout || r.stderr || '').toLowerCase();
+          if (help.includes('usage') || help.includes('quota')) {
+            out.quota = 'cli-supported';
+            out.hint = '`codex usage` 또는 `codex quota` 시도 가능';
+          } else {
+            out.quota = 'unknown';
+            out.hint = 'https://platform.openai.com/account/usage 확인';
+          }
+          out.raw = help.slice(0, 200);
+        } else if (agent.id === 'gemini') {
+          // gemini CLI: 무료 티어는 분당 60req 제한, CLI 자체에선 노출 안 됨
+          out.quota = 'rate-limited';
+          out.hint = '무료 티어: 60 req/min, 1000 req/day · 유료는 https://ai.google.dev/gemini-api/docs/rate-limits';
+        } else if (agent.id === 'copilot') {
+          // gh copilot은 GitHub Copilot 구독 (월 단위 quota 없음, individual/business 플랜)
+          const r = cp.spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 4000, shell: true });
+          const authed = r.status === 0;
+          out.quota = authed ? 'subscription' : 'not-authed';
+          out.hint = authed ? 'Copilot 구독자 무제한 (월 플랜) · https://github.com/settings/copilot' : '`gh auth login` 필요';
+        }
+      } catch (e) {
+        out.quota = 'error';
+        out.hint = e.message;
+      }
+      results.push(out);
+    }
+    if (has('--json')) { log(JSON.stringify({ quota: results }, null, 2)); return; }
+    log(`# 외부 AI CLI quota 추정 (1.9.31)`);
+    log('');
+    log(`| Agent | 상태 | quota | 안내 |`);
+    log(`|---|---|---|---|`);
+    for (const q of results) {
+      const statusEmoji = q.status === 'ready' ? '🟢' : q.status === 'not-installed' ? '⚪' : q.status === 'disabled' ? '🟡' : '❓';
+      log(`| ${q.id} | ${statusEmoji} ${q.status} | ${q.quota || '-'} | ${q.hint || '-'} |`);
+    }
+    log('');
+    log(`## 주의`);
+    log(`  - leerness는 CLI 사용량을 직접 추적하지 않음 (provider 대시보드 참조)`);
+    log(`  - rate-limit/quota는 plan/티어에 따라 달라짐`);
+    log(`  - sub-agent 분배 시 quota 여유 큰 CLI 우선 활용 권장`);
+    return;
+  }
+
+  fail('사용법: leerness agents list|check|quota|dispatch "<task>" --to <id>');
   return process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.9.30",
+  "version": "1.9.31",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -834,6 +834,39 @@ total++;
   if (!ok) { failed++; console.log(r.stdout.slice(0, 400)); }
 }
 
+// 1.9.31 회귀: agents quota (각 CLI 사용량/quota 조회)
+total++;
+{
+  // agents quota — env=0 시 모두 disabled/not-installed, 안내 메시지 포함
+  const env = { ...process.env, LEERNESS_ENABLE_CLAUDE: '0', LEERNESS_ENABLE_CODEX: '0', LEERNESS_ENABLE_GEMINI: '0', LEERNESS_ENABLE_COPILOT: '0' };
+  const r = cp.spawnSync(process.execPath, [CLI, 'agents', 'quota'], { encoding: 'utf8', timeout: 15000, env });
+  const okText = r.status === 0
+    && /외부 AI CLI quota 추정 \(1\.9\.31\)/.test(r.stdout)
+    && /\| claude \|/.test(r.stdout)
+    && /\| codex \|/.test(r.stdout)
+    && /\| gemini \|/.test(r.stdout)
+    && /\| copilot \|/.test(r.stdout)
+    && /provider 대시보드 참조/.test(r.stdout);
+  // JSON 출력
+  const r2 = cp.spawnSync(process.execPath, [CLI, 'agents', 'quota', '--json'], { encoding: 'utf8', timeout: 15000, env });
+  let parsed = null;
+  try { parsed = JSON.parse(r2.stdout); } catch {}
+  const okJson = parsed && Array.isArray(parsed.quota) && parsed.quota.length === 4
+    && parsed.quota.every(q => typeof q.id === 'string' && typeof q.status === 'string' && (q.hint === null || typeof q.hint === 'string'));
+  const ok = okText && okJson;
+  console.log(ok ? '✓ B(1.9.31) agents quota: 4 CLI 사용량/안내 + JSON 출력' : `✗ quota 실패 (text=${okText} json=${okJson})`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 500)); }
+}
+
+total++;
+{
+  // 사용법 메시지에 quota 포함
+  const r = cp.spawnSync(process.execPath, [CLI, 'agents', 'foo'], { encoding: 'utf8', timeout: 10000 });
+  const ok = r.status !== 0 && /list\|check\|quota\|dispatch/.test(r.stdout + r.stderr);
+  console.log(ok ? '✓ B(1.9.31) agents 사용법에 quota 명시' : `✗ usage 메시지 실패`);
+  if (!ok) { failed++; console.log((r.stdout + r.stderr).slice(0, 300)); }
+}
+
 // 1.9.22 회귀: handoff --compact + orchestrate opt-in 정책 + llm-bench record
 total++;
 {