triflux 7.2.2 → 7.3.1

package/hub/intent.mjs

@@ -1,7 +1,7 @@
 // hub/intent.mjs — Intent Classification Engine
 // 사용자 요청의 "진짜 의도"를 분석 → 카테고리 분류 → 최적 에이전트/모델 자동 선택
 
-import { execFileSync, execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 
 /** 캐시 엔트리: { category, confidence, ts } */
@@ -39,8 +39,9 @@ function _getCached(hash) {
 
 function _tryCodexClassify(prompt) {
   try {
-    const raw = execSync(
-      `codex exec "Classify intent: ${prompt.replace(/"/g, '\\"')}. Reply JSON: {intent, confidence}"`,
+    const raw = execFileSync(
+      'codex',
+      ['exec', `Classify intent: ${prompt}. Reply JSON: {intent, confidence}`],
       { timeout: 8000, encoding: 'utf8' }
     );
     // JSON 블록 추출 (응답에 다른 텍스트가 섞일 수 있음)

package/hub/pipeline/gates/consensus.mjs

@@ -0,0 +1,94 @@
+// hub/pipeline/gates/consensus.mjs — Consensus Quality Gate
+//
+// N개 결과의 합의도를 평가하여 5단계 분기 결정
+// proceed(>=90%) / proceed_warn(>=75%) / retry(<75%+재시도) / escalate(<75%+감독) / abort
+
+/** 단계별 합의 임계값 (%) */
+export const STAGE_THRESHOLDS = {
+  plan: 50,
+  define: 75,
+  execute: 75,
+  verify: 80,
+  security: 100,
+};
+
+/** 환경변수 기반 기본 임계값 (기본 75) */
+function getDefaultThreshold() {
+  const env = typeof process !== 'undefined' && process.env?.TRIFLUX_CONSENSUS_THRESHOLD;
+  if (env != null && env !== '') {
+    const parsed = Number(env);
+    if (!Number.isNaN(parsed) && parsed >= 0 && parsed <= 100) return parsed;
+  }
+  return 75;
+}
+
+/**
+ * 성공률 기반 5단계 분기 결정
+ * @param {number} successRate - 합의 성공률 (0-100)
+ * @param {number} retryCount - 현재 재시도 횟수
+ * @param {number} maxRetries - 최대 재시도 횟수
+ * @param {string} [mode] - 실행 모드 ('supervised' | 기타)
+ * @returns {'proceed' | 'proceed_warn' | 'retry' | 'escalate' | 'abort'}
+ */
+export function evaluateQualityBranch(successRate, retryCount, maxRetries, mode) {
+  if (successRate >= 90) return 'proceed';
+  if (successRate >= 75) return 'proceed_warn';
+
+  // <75%: 재시도 가능 여부에 따라 분기
+  if (retryCount < maxRetries) return 'retry';
+  if (mode === 'supervised') return 'escalate';
+  return 'abort';
+}
+
+/**
+ * N개 결과의 합의도 평가
+ * @param {Array<{ success: boolean }>} results - 평가 대상 결과 배열
+ * @param {object} [options]
+ * @param {string} [options.stage] - 파이프라인 단계 (STAGE_THRESHOLDS 키)
+ * @param {number} [options.threshold] - 합의 임계값 직접 지정 (stage보다 우선)
+ * @param {number} [options.retryCount=0] - 현재 재시도 횟수
+ * @param {number} [options.maxRetries=2] - 최대 재시도 횟수
+ * @param {string} [options.mode] - 실행 모드 ('supervised' 등)
+ * @returns {{ successRate: number, threshold: number, decision: string, reasoning: string, results: Array }}
+ */
+export function evaluateConsensus(results, options = {}) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return {
+      successRate: 0,
+      threshold: options.threshold ?? getDefaultThreshold(),
+      decision: 'abort',
+      reasoning: '평가 대상 결과가 없습니다.',
+      results: [],
+    };
+  }
+
+  const retryCount = options.retryCount ?? 0;
+  const maxRetries = options.maxRetries ?? 2;
+  const mode = options.mode;
+
+  // 임계값 결정: 직접 지정 > stage별 > 환경변수 > 기본 75
+  const threshold = options.threshold
+    ?? (options.stage && STAGE_THRESHOLDS[options.stage])
+    ?? getDefaultThreshold();
+
+  const successCount = results.filter(r => r.success).length;
+  const successRate = Math.round((successCount / results.length) * 100);
+
+  const decision = evaluateQualityBranch(successRate, retryCount, maxRetries, mode);
+
+  const reasoningMap = {
+    proceed: `합의율 ${successRate}% (>= 90%): 전원 합의. 진행.`,
+    proceed_warn: `합의율 ${successRate}% (>= 75%): 부분 합의. 경고와 함께 진행.`,
+    retry: `합의율 ${successRate}% (< 75%): 재시도 ${retryCount + 1}/${maxRetries} 가능.`,
+    escalate: `합의율 ${successRate}% (< 75%): 감독 모드 에스컬레이션.`,
+    abort: `합의율 ${successRate}% (< 75%): 합의 실패. 중단.`,
+  };
+
+  return {
+    successRate,
+    threshold,
+    decision,
+    reasoning: reasoningMap[decision],
+    results,
+  };
+}

package/hub/pipeline/gates/index.mjs

@@ -2,3 +2,4 @@
 
 export { CRITERIA, runConfidenceCheck } from './confidence.mjs';
 export { RED_FLAGS, QUESTIONS, runSelfCheck } from './selfcheck.mjs';
+export { STAGE_THRESHOLDS, evaluateQualityBranch, evaluateConsensus } from './consensus.mjs';

package/hub/routing/complexity.mjs

@@ -0,0 +1,166 @@
+// hub/routing/complexity.mjs — 작업 복잡도 스코어링
+// 작업 설명 텍스트에서 복잡도를 0-1 범위로 계산한다.
+// 외부 의존성 없음 (순수 텍스트 분석)
+
+/**
+ * 복잡도 지표 키워드 사전
+ * 카테고리별 키워드와 가중치 (0-1)
+ */
+const COMPLEXITY_INDICATORS = {
+  // 높은 복잡도 (0.7-1.0)
+  high: {
+    keywords: [
+      'refactor', 'architecture', 'security', 'migration', 'distributed',
+      'concurrent', 'parallel', 'optimization', 'performance', 'scalability',
+      'cryptograph', 'encryption', 'authentication', 'authorization',
+      'database schema', 'data model', 'state machine', 'event-driven',
+      'microservice', 'orchestrat', 'pipeline', 'workflow',
+      // 한국어
+      '리팩터링', '리팩토링', '아키텍처', '보안', '마이그레이션', '분산',
+      '동시성', '병렬', '최적화', '성능', '확장성',
+      '암호화', '인증', '인가', '데이터베이스 스키마', '데이터 모델',
+      '상태 머신', '이벤트 드리븐', '마이크로서비스', '오케스트레이션',
+    ],
+    weight: 0.85,
+  },
+  // 중간 복잡도 (0.4-0.7)
+  medium: {
+    keywords: [
+      'implement', 'integrate', 'api', 'endpoint', 'middleware',
+      'validation', 'error handling', 'testing', 'debug', 'fix bug',
+      'configuration', 'deploy', 'ci/cd', 'docker', 'container',
+      'cache', 'queue', 'webhook', 'notification', 'logging',
+      // 한국어
+      '구현', '통합', '엔드포인트', '미들웨어', '유효성 검사',
+      '에러 처리', '오류 처리', '테스트', '디버깅', '버그 수정',
+      '설정', '배포', '컨테이너', '캐시', '알림', '로깅',
+    ],
+    weight: 0.55,
+  },
+  // 낮은 복잡도 (0.1-0.4)
+  low: {
+    keywords: [
+      'readme', 'comment', 'typo', 'rename', 'format', 'lint',
+      'update version', 'bump', 'add dependency', 'install',
+      'simple', 'trivial', 'minor', 'small change', 'one-liner',
+      // 한국어
+      '문서화', '주석', '오타', '이름 변경', '포맷', '버전 업데이트',
+      '의존성 추가', '설치', '간단', '사소한', '소규모', '한 줄',
+    ],
+    weight: 0.2,
+  },
+};
+
+/**
+ * 어휘 복잡도 계산 (20%)
+ * 고유 단어 비율 + 평균 단어 길이 기반
+ * @param {string[]} words
+ * @returns {number} 0-1
+ */
+function lexicalComplexity(words) {
+  if (words.length === 0) return 0;
+  const unique = new Set(words);
+  const typeTokenRatio = unique.size / words.length;
+  const avgWordLen = words.reduce((sum, w) => sum + w.length, 0) / words.length;
+  // 긴 단어(기술 용어)가 많을수록 복잡
+  const lenScore = Math.min(avgWordLen / 10, 1);
+  return typeTokenRatio * 0.5 + lenScore * 0.5;
+}
+
+/**
+ * 시맨틱 깊이 계산 (35%)
+ * 키워드 사전 매칭 기반
+ * @param {string} text
+ * @returns {number} 0-1
+ */
+function semanticDepth(text) {
+  const lower = text.toLowerCase();
+  let maxWeight = 0;
+  let matchCount = 0;
+
+  for (const [, category] of Object.entries(COMPLEXITY_INDICATORS)) {
+    for (const kw of category.keywords) {
+      if (lower.includes(kw)) {
+        matchCount++;
+        if (category.weight > maxWeight) maxWeight = category.weight;
+      }
+    }
+  }
+  // 매칭 키워드 수와 최고 가중치 조합
+  const countScore = Math.min(matchCount / 5, 1);
+  return maxWeight * 0.6 + countScore * 0.4;
+}
+
+/**
+ * 작업 범위 계산 (25%)
+ * 문장 수, 줄 수, 파일/경로 참조 기반
+ * @param {string} text
+ * @returns {number} 0-1
+ */
+function taskScope(text) {
+  const lines = text.split('\n').filter((l) => l.trim().length > 0);
+  const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 0);
+  const fileRefs = (text.match(/[\w\-/]+\.\w{1,5}/g) || []).length;
+
+  const lineScore = Math.min(lines.length / 20, 1);
+  const sentenceScore = Math.min(sentences.length / 10, 1);
+  const fileScore = Math.min(fileRefs / 5, 1);
+
+  return lineScore * 0.3 + sentenceScore * 0.3 + fileScore * 0.4;
+}
+
+/**
+ * 불확실성 계산 (20%)
+ * 모호한 표현, 질문, 조건문 기반
+ * @param {string} text
+ * @returns {number} 0-1
+ */
+function uncertainty(text) {
+  const lower = text.toLowerCase();
+  const uncertainWords = [
+    'maybe', 'perhaps', 'might', 'could', 'possibly', 'unclear',
+    'not sure', 'investigate', 'explore', 'research', 'try',
+    'consider', 'evaluate', 'assess', 'determine', 'figure out',
+  ];
+  let count = 0;
+  for (const w of uncertainWords) {
+    if (lower.includes(w)) count++;
+  }
+  const questions = (text.match(/\?/g) || []).length;
+  const wordScore = Math.min(count / 4, 1);
+  const questionScore = Math.min(questions / 3, 1);
+  return wordScore * 0.6 + questionScore * 0.4;
+}
+
+/**
+ * 작업 복잡도 스코어링
+ * @param {string} taskDescription — 작업 설명 텍스트
+ * @returns {{ score: number, breakdown: { lexical: number, semantic: number, scope: number, uncertainty: number } }}
+ */
+export function scoreComplexity(taskDescription) {
+  if (!taskDescription || typeof taskDescription !== 'string') {
+    return { score: 0, breakdown: { lexical: 0, semantic: 0, scope: 0, uncertainty: 0 } };
+  }
+
+  const words = taskDescription.toLowerCase().split(/\s+/).filter((w) => w.length > 0);
+  const lexical = lexicalComplexity(words);
+  const semantic = semanticDepth(taskDescription);
+  const scope = taskScope(taskDescription);
+  const uncertain = uncertainty(taskDescription);
+
+  // 가중 합산: 어휘(20%) + 시맨틱(35%) + 범위(25%) + 불확실성(20%)
+  const score = Math.min(
+    lexical * 0.20 + semantic * 0.35 + scope * 0.25 + uncertain * 0.20,
+    1,
+  );
+
+  return {
+    score: Math.round(score * 1000) / 1000,
+    breakdown: {
+      lexical: Math.round(lexical * 1000) / 1000,
+      semantic: Math.round(semantic * 1000) / 1000,
+      scope: Math.round(scope * 1000) / 1000,
+      uncertainty: Math.round(uncertain * 1000) / 1000,
+    },
+  };
+}

package/hub/routing/index.mjs

@@ -0,0 +1,117 @@
+// hub/routing/index.mjs — 통합 라우팅 진입점
+// Q-Learning 동적 라우팅 + agent-map.json 정적 폴백
+// 환경변수 TRIFLUX_DYNAMIC_ROUTING=true 로 옵트인 (기본 false)
+
+import { createRequire } from 'node:module';
+import { QLearningRouter } from './q-learning.mjs';
+import { scoreComplexity } from './complexity.mjs';
+
+const _require = createRequire(import.meta.url);
+
+/** agent-map.json 정적 매핑 */
+let AGENT_MAP;
+try {
+  AGENT_MAP = _require('../team/agent-map.json');
+} catch {
+  AGENT_MAP = {};
+}
+
+/** 싱글턴 라우터 인스턴스 (lazy init) */
+let _router = null;
+
+/**
+ * 라우터 인스턴스 획득 (lazy singleton)
+ * @returns {QLearningRouter}
+ */
+function getRouter() {
+  if (!_router) {
+    _router = new QLearningRouter();
+    _router.load();
+  }
+  return _router;
+}
+
+/**
+ * 동적 라우팅 활성화 여부
+ * @returns {boolean}
+ */
+function isDynamicRoutingEnabled() {
+  const env = process.env.TRIFLUX_DYNAMIC_ROUTING;
+  return env === 'true' || env === '1';
+}
+
+/**
+ * 통합 라우팅 결정
+ * 우선순위: Q-Learning 예측 (신뢰도 >= 0.6) -> agent-map.json 기본값
+ *
+ * @param {string} agentType — 에이전트 역할명 ("executor", "designer" 등)
+ * @param {string} [taskDescription=''] — 작업 설명 (동적 라우팅용)
+ * @returns {{ cliType: string, source: 'dynamic' | 'static', confidence: number, complexity: number }}
+ */
+export function resolveRoute(agentType, taskDescription = '') {
+  // 정적 기본값
+  const staticCli = AGENT_MAP[agentType] || agentType;
+  const { score: complexity } = scoreComplexity(taskDescription);
+
+  // 동적 라우팅 비활성화 시 정적 매핑 반환
+  if (!isDynamicRoutingEnabled()) {
+    return { cliType: staticCli, source: 'static', confidence: 1, complexity };
+  }
+
+  // 작업 설명 없으면 정적 폴백
+  if (!taskDescription || taskDescription.trim().length === 0) {
+    return { cliType: staticCli, source: 'static', confidence: 1, complexity };
+  }
+
+  const router = getRouter();
+  const prediction = router.predict(taskDescription);
+
+  // 신뢰도 기준 미달 시 정적 폴백
+  if (prediction.confidence < 0.6) {
+    return { cliType: staticCli, source: 'static', confidence: prediction.confidence, complexity };
+  }
+
+  return {
+    cliType: prediction.action,
+    source: 'dynamic',
+    confidence: prediction.confidence,
+    complexity,
+  };
+}
+
+/**
+ * 라우팅 피드백 업데이트
+ * @param {string} taskDescription — 작업 설명
+ * @param {string} action — 수행한 CLI 타입
+ * @param {number} reward — 보상 (-1 ~ 1)
+ * @param {boolean} [persist=true] — 영속화 여부
+ */
+export function updateRoute(taskDescription, action, reward, persist = true) {
+  if (!isDynamicRoutingEnabled()) return;
+
+  const router = getRouter();
+  router.update(taskDescription, action, reward);
+  if (persist) router.save();
+}
+
+/**
+ * 라우터 상태 조회 (진단용)
+ * @returns {{ enabled: boolean, epsilon: number, totalUpdates: number, stateCount: number }}
+ */
+export function routerStatus() {
+  const enabled = isDynamicRoutingEnabled();
+  if (!enabled) {
+    return { enabled, epsilon: 0, totalUpdates: 0, stateCount: 0 };
+  }
+  const router = getRouter();
+  return {
+    enabled,
+    epsilon: router.epsilon,
+    totalUpdates: router.totalUpdates,
+    stateCount: router.stateCount,
+  };
+}
+
+// re-export for convenience
+export { scoreComplexity } from './complexity.mjs';
+export { QLearningRouter, ACTIONS } from './q-learning.mjs';

package/hub/routing/q-learning.mjs

@@ -0,0 +1,335 @@
+// hub/routing/q-learning.mjs — 테이블 기반 Q-Learning 동적 라우팅
+// agent-map.json 폴백을 유지하면서, 작업 결과 피드백으로 가중치를 학습한다.
+// 외부 의존성 없음 (fs, path, crypto만 사용)
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { scoreComplexity } from './complexity.mjs';
+
+const _require = createRequire(import.meta.url);
+
+/** agent-map.json 정적 매핑 (폴백용) */
+let AGENT_MAP;
+try {
+  AGENT_MAP = _require('../team/agent-map.json');
+} catch {
+  AGENT_MAP = {};
+}
+
+/** 사용 가능한 CLI 액션 */
+const ACTIONS = ['codex', 'gemini', 'claude', 'haiku', 'sonnet'];
+
+/** 특성 벡터 키워드 (48차원, 에이전트 타입 기반) */
+const FEATURE_KEYWORDS = [
+  // 실행/구현 (codex 친화)
+  'implement', 'execute', 'build', 'fix', 'debug', 'code', 'refactor', 'test',
+  // 분석/설계 (claude/sonnet 친화)
+  'analyze', 'architect', 'plan', 'review', 'security', 'optimize', 'research', 'evaluate',
+  // 디자인/문서 (gemini 친화)
+  'design', 'ui', 'ux', 'frontend', 'visual', 'document', 'write', 'explain',
+  // 간단/빠른 (haiku 친화)
+  'simple', 'quick', 'trivial', 'rename', 'format', 'lint', 'typo', 'minor',
+  // 한국어 — 실행/구현 (codex 친화)
+  '구현', '빌드', '수정', '디버깅', '리팩터링', '테스트',
+  // 한국어 — 분석/설계 (claude/sonnet 친화)
+  '분석', '아키텍처', '설계', '검토', '보안', '최적화',
+  // 한국어 — 디자인/문서 (gemini 친화)
+  '디자인', '문서화',
+  // 한국어 — 간단/빠른 (haiku 친화)
+  '간단', '사소한',
+];
+
+/**
+ * 텍스트에서 48차원 특성 벡터 추출
+ * 단어 경계를 기준으로 매칭하여 부분 문자열 오탐을 방지한다.
+ * @param {string} text
+ * @returns {number[]} 48-dim binary feature vector
+ */
+function extractFeatures(text) {
+  const lower = text.toLowerCase();
+  return FEATURE_KEYWORDS.map((kw) => {
+    // 영문 단일 단어: 단어 경계(\b) 적용
+    // 한국어 또는 다중 단어 구문: 공백/문장 경계 기반 포함 여부 확인
+    if (/^[a-z]+$/.test(kw)) {
+      return new RegExp(`\\b${kw}\\b`).test(lower) ? 1 : 0;
+    }
+    return lower.includes(kw) ? 1 : 0;
+  });
+}
+
+/**
+ * 특성 벡터를 상태 키로 변환 (해시 기반)
+ * @param {number[]} features
+ * @returns {string}
+ */
+function stateKey(features) {
+  const hash = createHash('sha256').update(features.join(',')).digest('hex');
+  return hash.slice(0, 16);
+}
+
+/**
+ * LRU 캐시 (예측 결과 캐싱)
+ */
+class LRUCache {
+  /** @param {number} maxSize @param {number} ttlMs */
+  constructor(maxSize = 256, ttlMs = 5 * 60 * 1000) {
+    this._maxSize = maxSize;
+    this._ttlMs = ttlMs;
+    /** @type {Map<string, { value: *, ts: number }>} */
+    this._cache = new Map();
+  }
+
+  get(key) {
+    const entry = this._cache.get(key);
+    if (!entry) return undefined;
+    if (Date.now() - entry.ts > this._ttlMs) {
+      this._cache.delete(key);
+      return undefined;
+    }
+    // LRU: 다시 삽입하여 순서 갱신
+    this._cache.delete(key);
+    this._cache.set(key, entry);
+    return entry.value;
+  }
+
+  set(key, value) {
+    if (this._cache.has(key)) this._cache.delete(key);
+    this._cache.set(key, { value, ts: Date.now() });
+    // 초과 시 가장 오래된 항목 제거
+    if (this._cache.size > this._maxSize) {
+      const oldest = this._cache.keys().next().value;
+      this._cache.delete(oldest);
+    }
+  }
+
+  clear() {
+    this._cache.clear();
+  }
+}
+
+/**
+ * Q-Learning 라우터
+ * 테이블 기반 Q-Learning으로 작업→CLI 매핑을 학습한다.
+ */
+export class QLearningRouter {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.learningRate=0.1] — 학습률 (alpha)
+   * @param {number} [opts.discountFactor=0.9] — 할인율 (gamma)
+   * @param {number} [opts.epsilon=0.3] — 탐색 확률 (epsilon-greedy)
+   * @param {number} [opts.epsilonDecay=0.995] — 엡실론 감쇠율
+   * @param {number} [opts.epsilonMin=0.05] — 최소 엡실론
+   * @param {number} [opts.minConfidence=0.6] — 최소 신뢰도 (이하면 폴백)
+   * @param {string} [opts.modelPath] — Q-table 영속화 경로
+   */
+  constructor(opts = {}) {
+    this._lr = opts.learningRate ?? 0.1;
+    this._gamma = opts.discountFactor ?? 0.9;
+    this._epsilon = opts.epsilon ?? 0.3;
+    this._epsilonDecay = opts.epsilonDecay ?? 0.995;
+    this._epsilonMin = opts.epsilonMin ?? 0.05;
+    this._minConfidence = opts.minConfidence ?? 0.6;
+    this._modelPath = opts.modelPath ?? join(homedir(), '.omc', 'routing-model.json');
+
+    /** @type {Map<string, Map<string, number>>} state -> (action -> Q-value) */
+    this._qTable = new Map();
+
+    /** @type {Map<string, number>} state -> visit count */
+    this._visitCounts = new Map();
+
+    /** 총 업데이트 횟수 */
+    this._totalUpdates = 0;
+
+    /** 예측 캐시 */
+    this._cache = new LRUCache(256, 5 * 60 * 1000);
+  }
+
+  /**
+   * 상태에 대한 Q-values 조회 (없으면 초기화)
+   * @param {string} state
+   * @returns {Map<string, number>}
+   */
+  _getQValues(state) {
+    if (!this._qTable.has(state)) {
+      const qValues = new Map();
+      for (const action of ACTIONS) {
+        qValues.set(action, 0);
+      }
+      this._qTable.set(state, qValues);
+    }
+    return this._qTable.get(state);
+  }
+
+  /**
+   * 작업 설명으로부터 최적 CLI 타입 예측
+   * @param {string} taskDescription
+   * @returns {{ action: string, confidence: number, exploration: boolean, complexity: number }}
+   */
+  predict(taskDescription) {
+    const features = extractFeatures(taskDescription);
+    const state = stateKey(features);
+
+    // 캐시 확인
+    const cached = this._cache.get(state);
+    if (cached) return cached;
+
+    const qValues = this._getQValues(state);
+    const visits = this._visitCounts.get(state) || 0;
+
+    // 엡실론-그리디: 탐색 vs 활용
+    const isExploration = Math.random() < this._epsilon;
+
+    let action;
+    if (isExploration) {
+      // 무작위 탐색
+      action = ACTIONS[Math.floor(Math.random() * ACTIONS.length)];
+    } else {
+      // 최적 액션 선택 (최대 Q-value)
+      let maxQ = -Infinity;
+      action = ACTIONS[0];
+      for (const [a, q] of qValues) {
+        if (q > maxQ) {
+          maxQ = q;
+          action = a;
+        }
+      }
+    }
+
+    // 신뢰도 계산: 방문 횟수 기반 (최소 10회 이상이면 안정)
+    const confidence = visits >= 10
+      ? Math.min(visits / 50, 1)
+      : visits / 10;
+
+    const { score: complexity } = scoreComplexity(taskDescription);
+
+    const result = { action, confidence, exploration: isExploration, complexity };
+    // 탐색(랜덤) 결과는 캐싱하지 않음 — 매번 새로운 랜덤 액션 생성
+    if (!isExploration) this._cache.set(state, result);
+    return result;
+  }
+
+  /**
+   * Q-table 업데이트 (보상 피드백)
+   * @param {string} taskDescription — 작업 설명
+   * @param {string} action — 수행한 액션 (CLI 타입)
+   * @param {number} reward — 보상 (-1 ~ 1)
+   */
+  update(taskDescription, action, reward) {
+    if (!ACTIONS.includes(action)) return;
+
+    const features = extractFeatures(taskDescription);
+    const state = stateKey(features);
+    const qValues = this._getQValues(state);
+    const oldQ = qValues.get(action) || 0;
+
+    // 최대 미래 Q-value (단일 상태이므로 현재 상태의 max)
+    let maxFutureQ = -Infinity;
+    for (const [, q] of qValues) {
+      if (q > maxFutureQ) maxFutureQ = q;
+    }
+
+    // Q-Learning 업데이트: Q(s,a) = Q(s,a) + lr * (reward + gamma * max_Q(s') - Q(s,a))
+    const newQ = oldQ + this._lr * (reward + this._gamma * maxFutureQ - oldQ);
+    qValues.set(action, newQ);
+
+    // 방문 횟수 증가
+    this._visitCounts.set(state, (this._visitCounts.get(state) || 0) + 1);
+    this._totalUpdates++;
+
+    // 엡실론 감쇠
+    this._epsilon = Math.max(this._epsilonMin, this._epsilon * this._epsilonDecay);
+
+    // 캐시 무효화 (해당 상태)
+    this._cache.clear();
+  }
+
+  /**
+   * Q-table을 JSON 파일로 영속화
+   */
+  save() {
+    const dir = join(this._modelPath, '..');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    const data = {
+      version: 1,
+      epsilon: this._epsilon,
+      totalUpdates: this._totalUpdates,
+      qTable: {},
+      visitCounts: {},
+    };
+
+    for (const [state, qValues] of this._qTable) {
+      data.qTable[state] = Object.fromEntries(qValues);
+    }
+    for (const [state, count] of this._visitCounts) {
+      data.visitCounts[state] = count;
+    }
+
+    writeFileSync(this._modelPath, JSON.stringify(data, null, 2), 'utf8');
+  }
+
+  /**
+   * 영속화된 Q-table 로드
+   * @returns {boolean} 로드 성공 여부
+   */
+  load() {
+    if (!existsSync(this._modelPath)) return false;
+
+    try {
+      const raw = readFileSync(this._modelPath, 'utf8');
+      const data = JSON.parse(raw);
+      if (data.version !== 1) return false;
+
+      this._epsilon = data.epsilon ?? this._epsilon;
+      this._totalUpdates = data.totalUpdates ?? 0;
+      this._qTable = new Map();
+      this._visitCounts = new Map();
+
+      for (const [state, qObj] of Object.entries(data.qTable || {})) {
+        const qValues = new Map();
+        for (const [action, q] of Object.entries(qObj)) {
+          if (ACTIONS.includes(action)) qValues.set(action, q);
+        }
+        this._qTable.set(state, qValues);
+      }
+      for (const [state, count] of Object.entries(data.visitCounts || {})) {
+        this._visitCounts.set(state, count);
+      }
+
+      this._cache.clear();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * agent-map.json 폴백 조회
+   * @param {string} agentType — 에이전트 역할명
+   * @returns {string} CLI 타입
+   */
+  static fallback(agentType) {
+    return AGENT_MAP[agentType] || agentType;
+  }
+
+  /** 현재 엡실론 값 */
+  get epsilon() {
+    return this._epsilon;
+  }
+
+  /** 총 업데이트 횟수 */
+  get totalUpdates() {
+    return this._totalUpdates;
+  }
+
+  /** Q-table 상태 수 */
+  get stateCount() {
+    return this._qTable.size;
+  }
+}
+
+// 모듈 레벨 export
+export { ACTIONS, FEATURE_KEYWORDS, extractFeatures, stateKey, LRUCache };

package/hub/team/backend.mjs

@@ -0,0 +1,88 @@
+// hub/team/backend.mjs — CLI 백엔드 추상화 레이어
+// 각 CLI(codex/gemini/claude)의 명령 빌드 로직을 클래스로 캡슐화한다.
+// v7.2.2
+import { createRequire } from "node:module";
+
+const _require = createRequire(import.meta.url);
+
+// ── 백엔드 클래스 ──────────────────────────────────────────────────────────
+
+export class CodexBackend {
+  name() { return "codex"; }
+  command() { return "codex"; }
+
+  /**
+   * @param {string} prompt — 프롬프트 (프롬프트 파일 경로가 아닌 PowerShell 표현식)
+   * @param {string} resultFile — 결과 저장 경로
+   * @param {object} [opts]
+   * @returns {string} PowerShell 명령 (cls 제외)
+   */
+  buildArgs(prompt, resultFile, opts = {}) {
+    return `codex exec ${prompt} -o '${resultFile}' --color never`;
+  }
+
+  env() { return {}; }
+}
+
+export class GeminiBackend {
+  name() { return "gemini"; }
+  command() { return "gemini"; }
+
+  buildArgs(prompt, resultFile, opts = {}) {
+    return `gemini -p ${prompt} -o text > '${resultFile}' 2>'${resultFile}.err'`;
+  }
+
+  env() { return {}; }
+}
+
+export class ClaudeBackend {
+  name() { return "claude"; }
+  command() { return "claude"; }
+
+  buildArgs(prompt, resultFile, opts = {}) {
+    return `claude -p ${prompt} --output-format text > '${resultFile}' 2>&1`;
+  }
+
+  env() { return {}; }
+}
+
+// ── 레지스트리 ─────────────────────────────────────────────────────────────
+
+/** @type {Map<string, CodexBackend|GeminiBackend|ClaudeBackend>} */
+const backends = new Map([
+  ["codex",  new CodexBackend()],
+  ["gemini", new GeminiBackend()],
+  ["claude", new ClaudeBackend()],
+]);
+
+/**
+ * 백엔드 이름으로 조회한다.
+ * @param {string} name — "codex" | "gemini" | "claude"
+ * @returns {CodexBackend|GeminiBackend|ClaudeBackend}
+ * @throws {Error} 등록되지 않은 이름
+ */
+export function getBackend(name) {
+  const b = backends.get(name);
+  if (!b) throw new Error(`지원하지 않는 CLI: ${name}`);
+  return b;
+}
+
+/**
+ * 에이전트명 또는 CLI명을 Backend로 해석한다.
+ * agent-map.json을 통해 에이전트명 → CLI명으로 변환 후 레지스트리에서 조회한다.
+ * @param {string} agentOrCli — "executor", "codex", "designer" 등
+ * @returns {CodexBackend|GeminiBackend|ClaudeBackend}
+ */
+export function getBackendForAgent(agentOrCli) {
+  const agentMap = _require("./agent-map.json");
+  const cliName = agentMap[agentOrCli] || agentOrCli;
+  return getBackend(cliName);
+}
+
+/**
+ * 등록된 모든 백엔드를 반환한다.
+ * @returns {Array<CodexBackend|GeminiBackend|ClaudeBackend>}
+ */
+export function listBackends() {
+  return Array.from(backends.values());
+}

package/hub/team/cli/commands/start/index.mjs

@@ -1,102 +1,103 @@
-import { decomposeTask } from "../../../orchestrator.mjs";
-import { hasWindowsTerminal, hasWindowsTerminalSession } from "../../../session.mjs";
-import { AMBER, BOLD, DIM, GREEN, RED, RESET, WHITE } from "../../../shared.mjs";
-import { getDefaultHubUrl, getHubInfo, startHubDaemon } from "../../services/hub-client.mjs";
-import { ensureTmuxOrExit } from "../../services/runtime-mode.mjs";
-import { saveTeamState } from "../../services/state-store.mjs";
-import { fail, ok, warn } from "../../render.mjs";
-import { parseTeamArgs } from "./parse-args.mjs";
-import { startInProcessTeam } from "./start-in-process.mjs";
-import { startMuxTeam } from "./start-mux.mjs";
-import { startHeadlessTeam } from "./start-headless.mjs";
-import { startWtTeam } from "./start-wt.mjs";
-
-function printStartUsage() {
-  console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET}\n`);
-  console.log(`  사용법: ${WHITE}tfx multi "작업 설명"${RESET}`);
-  console.log(`          ${WHITE}tfx multi --agents codex,gemini --lead claude "작업"${RESET}`);
-  console.log(`          ${WHITE}tfx multi --teammate-mode headless "작업"${RESET} ${DIM}(psmux 헤드리스, 기본)${RESET}`);
-  console.log(`          ${WHITE}tfx multi --teammate-mode wt "작업"${RESET} ${DIM}(Windows Terminal split-pane)${RESET}`);
-  console.log(`          ${WHITE}tfx multi --teammate-mode in-process "작업"${RESET} ${DIM}(mux 불필요)${RESET}\n`);
-}
-
-function printWorkerPreview(agents, subtasks) {
-  for (let index = 0; index < subtasks.length; index += 1) {
-    const preview = subtasks[index].length > 44 ? `${subtasks[index].slice(0, 44)}…` : subtasks[index];
-    console.log(`    ${DIM}[${agents[index]}-${index + 1}] ${preview}${RESET}`);
-  }
-  console.log("");
-}
-
-function renderTmuxInstallHelp() {
-  console.log(`\n  ${RED}${BOLD}tmux 미발견${RESET}\n`);
-  console.log("  현재 선택한 모드는 tmux 기반 팀세션이 필요합니다.\n");
-  console.log(`  설치:\n    WSL2:   ${WHITE}wsl sudo apt install tmux${RESET}\n    macOS:  ${WHITE}brew install tmux${RESET}\n    Linux:  ${WHITE}apt install tmux${RESET}\n`);
-  console.log(`  Windows에서는 WSL2를 권장합니다:\n    1. ${WHITE}wsl --install${RESET}\n    2. ${WHITE}wsl sudo apt install tmux${RESET}\n    3. ${WHITE}tfx multi "작업"${RESET}\n`);
-}
-
-export { parseTeamArgs };
-
-export async function teamStart(args = []) {
-  const { agents, lead, layout, teammateMode, task: rawTask, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile } = parseTeamArgs(args);
-  // --assign 사용 시 task를 자동 생성
-  const task = rawTask || (assigns.length > 0 ? assigns.map(a => a.prompt).join(" + ") : "");
-  if (!task) return printStartUsage();
-
-  console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET}\n`);
-
-  // P1b: 워커 수 계산 — 단일 워커 headless에는 Hub 불필요
-  const workerCount = assigns.length > 0 ? assigns.length : agents.length;
-  const needsHub = workerCount >= 2 || teammateMode !== "headless";
-
-  let hub = null;
-  if (needsHub) {
-    hub = await getHubInfo();
-    if (!hub) {
-      process.stdout.write("  Hub 시작 중...");
-      try { hub = await startHubDaemon(); } catch (error) { if (error?.code === "HUB_SERVER_MISSING") fail("hub/server.mjs 없음 — hub 모듈이 설치되지 않음"); }
-      console.log(` ${hub ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`}`);
-      if (!hub) warn("Hub 시작 실패 — 수동으로 실행: tfx hub start");
-    } else ok(`Hub: ${DIM}${hub.url}${RESET}`);
-  } else {
-    ok(`Hub: ${DIM}건너뜀 (단일 워커 headless)${RESET}`);
-  }
-
-  const sessionId = `tfx-multi-${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`;
-  const subtasks = decomposeTask(task, agents.length);
-  const hubUrl = hub?.url || getDefaultHubUrl();
-  let effectiveMode = teammateMode;
-  if (effectiveMode === "wt" && !hasWindowsTerminal()) { warn("wt.exe 미발견 — in-process 모드로 자동 fallback"); effectiveMode = "in-process"; }
-  if (effectiveMode === "wt" && !hasWindowsTerminalSession()) { warn("WT_SESSION 미감지(Windows Terminal 외부) — in-process 모드로 자동 fallback"); effectiveMode = "in-process"; }
-
-  console.log(`  세션:  ${WHITE}${sessionId}${RESET}`);
-  console.log(`  모드:  ${effectiveMode}`);
-  console.log(`  리드:  ${AMBER}${lead}${RESET}`);
-  console.log(`  워커:  ${agents.map((agent) => `${AMBER}${agent}${RESET}`).join(", ")}`);
-  printWorkerPreview(agents, subtasks);
-
-  if (effectiveMode === "tmux") {
-    try { ensureTmuxOrExit(); } catch { return renderTmuxInstallHelp(); }
-  }
-
-  const state = effectiveMode === "in-process"
-    ? await startInProcessTeam({ sessionId, task, lead, agents, subtasks, hubUrl })
-    : effectiveMode === "headless"
-      ? await startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile })
-      : effectiveMode === "wt"
-        ? await startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl })
-        : await startMuxTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl, teammateMode: effectiveMode });
-
-  if (!state) return fail("in-process supervisor 시작 실패");
-  saveTeamState(state, sessionId);
-  if (typeof state.postSave === "function") state.postSave();
-  if (effectiveMode === "in-process") {
-    ok("네이티브 in-process 팀 시작 완료");
-    console.log(`  ${DIM}tmux 없이 실행됨 (직접 CLI 프로세스)${RESET}`);
-    console.log(`  ${DIM}제어: tfx multi send/control/tasks/status${RESET}\n`);
-  } else if (effectiveMode === "wt") {
-    ok("Windows Terminal wt 팀 시작 완료");
-    console.log(`  ${DIM}현재 pane 기준으로 ${state.layout} 분할 생성됨${RESET}`);
-    console.log(`  ${DIM}wt 모드는 자동 프롬프트 주입/Hub direct 제어(send/control)가 제한됩니다.${RESET}\n`);
-  }
-}
+import { decomposeTask } from "../../../orchestrator.mjs";
+import { hasWindowsTerminal, hasWindowsTerminalSession } from "../../../session.mjs";
+import { AMBER, BOLD, DIM, GREEN, RED, RESET, WHITE } from "../../../shared.mjs";
+import { getDefaultHubUrl, getHubInfo, startHubDaemon } from "../../services/hub-client.mjs";
+import { ensureTmuxOrExit } from "../../services/runtime-mode.mjs";
+import { saveTeamState } from "../../services/state-store.mjs";
+import { fail, ok, warn } from "../../render.mjs";
+import { parseTeamArgs } from "./parse-args.mjs";
+import { startInProcessTeam } from "./start-in-process.mjs";
+import { startMuxTeam } from "./start-mux.mjs";
+import { startHeadlessTeam } from "./start-headless.mjs";
+import { startWtTeam } from "./start-wt.mjs";
+
+function printStartUsage() {
+  console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET}\n`);
+  console.log(`  사용법: ${WHITE}tfx multi "작업 설명"${RESET}`);
+  console.log(`          ${WHITE}tfx multi --agents codex,gemini --lead claude "작업"${RESET}`);
+  console.log(`          ${WHITE}tfx multi --teammate-mode headless "작업"${RESET} ${DIM}(psmux 헤드리스, 기본)${RESET}`);
+  console.log(`          ${WHITE}tfx multi --teammate-mode wt "작업"${RESET} ${DIM}(Windows Terminal split-pane)${RESET}`);
+  console.log(`          ${WHITE}tfx multi --teammate-mode in-process "작업"${RESET} ${DIM}(mux 불필요)${RESET}\n`);
+}
+
+function printWorkerPreview(agents, subtasks) {
+  for (let index = 0; index < subtasks.length; index += 1) {
+    const preview = subtasks[index].length > 44 ? `${subtasks[index].slice(0, 44)}…` : subtasks[index];
+    console.log(`    ${DIM}[${agents[index]}-${index + 1}] ${preview}${RESET}`);
+  }
+  console.log("");
+}
+
+function renderTmuxInstallHelp() {
+  console.log(`\n  ${RED}${BOLD}tmux 미발견${RESET}\n`);
+  console.log("  현재 선택한 모드는 tmux 기반 팀세션이 필요합니다.\n");
+  console.log(`  설치:\n    WSL2:   ${WHITE}wsl sudo apt install tmux${RESET}\n    macOS:  ${WHITE}brew install tmux${RESET}\n    Linux:  ${WHITE}apt install tmux${RESET}\n`);
+  console.log(`  Windows에서는 WSL2를 권장합니다:\n    1. ${WHITE}wsl --install${RESET}\n    2. ${WHITE}wsl sudo apt install tmux${RESET}\n    3. ${WHITE}tfx multi "작업"${RESET}\n`);
+}
+
+export { parseTeamArgs };
+
+export async function teamStart(args = []) {
+  const { agents, lead, layout, teammateMode, task: rawTask, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile } = parseTeamArgs(args);
+  // --assign 사용 시 task를 자동 생성
+  const task = rawTask || (assigns.length > 0 ? assigns.map(a => a.prompt).join(" + ") : "");
+  if (!task) return printStartUsage();
+
+  console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET}\n`);
+
+  // P1b: 워커 수 계산 — 단일 워커 headless에는 Hub 불필요
+  const workerCount = assigns.length > 0 ? assigns.length : agents.length;
+  const needsHub = workerCount >= 2 || teammateMode !== "headless";
+
+  let hub = null;
+  if (needsHub) {
+    hub = await getHubInfo();
+    if (!hub) {
+      process.stdout.write("  Hub 시작 중...");
+      try { hub = await startHubDaemon(); } catch (error) { if (error?.code === "HUB_SERVER_MISSING") fail("hub/server.mjs 없음 — hub 모듈이 설치되지 않음"); }
+      console.log(` ${hub ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`}`);
+      if (!hub) warn("Hub 시작 실패 — 수동으로 실행: tfx hub start");
+    } else ok(`Hub: ${DIM}${hub.url}${RESET}`);
+  } else {
+    ok(`Hub: ${DIM}건너뜀 (단일 워커 headless)${RESET}`);
+  }
+
+  const sessionId = `tfx-multi-${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`;
+  const subtasks = decomposeTask(task, agents.length);
+  const hubUrl = hub?.url || getDefaultHubUrl();
+  let effectiveMode = teammateMode;
+  if (effectiveMode === "wt" && !hasWindowsTerminal()) { warn("wt.exe 미발견 — in-process 모드로 자동 fallback"); effectiveMode = "in-process"; }
+  if (effectiveMode === "wt" && !hasWindowsTerminalSession()) { warn("WT_SESSION 미감지(Windows Terminal 외부) — in-process 모드로 자동 fallback"); effectiveMode = "in-process"; }
+
+  console.log(`  세션:  ${WHITE}${sessionId}${RESET}`);
+  console.log(`  모드:  ${effectiveMode}`);
+  console.log(`  리드:  ${AMBER}${lead}${RESET}`);
+  console.log(`  워커:  ${agents.map((agent) => `${AMBER}${agent}${RESET}`).join(", ")}`);
+  printWorkerPreview(agents, subtasks);
+
+  if (effectiveMode === "tmux") {
+    try { ensureTmuxOrExit(); } catch { return renderTmuxInstallHelp(); }
+  }
+
+  const state = effectiveMode === "in-process"
+    ? await startInProcessTeam({ sessionId, task, lead, agents, subtasks, hubUrl })
+    : effectiveMode === "headless"
+      ? await startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile })
+      : effectiveMode === "wt"
+        ? await startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl })
+        : await startMuxTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl, teammateMode: effectiveMode });
+
+  if (!state) return fail("in-process supervisor 시작 실패");
+  state.sessionId = sessionId;
+  saveTeamState(state, sessionId);
+  if (typeof state.postSave === "function") state.postSave();
+  if (effectiveMode === "in-process") {
+    ok("네이티브 in-process 팀 시작 완료");
+    console.log(`  ${DIM}tmux 없이 실행됨 (직접 CLI 프로세스)${RESET}`);
+    console.log(`  ${DIM}제어: tfx multi send/control/tasks/status${RESET}\n`);
+  } else if (effectiveMode === "wt") {
+    ok("Windows Terminal wt 팀 시작 완료");
+    console.log(`  ${DIM}현재 pane 기준으로 ${state.layout} 분할 생성됨${RESET}`);
+    console.log(`  ${DIM}wt 모드는 자동 프롬프트 주입/Hub direct 제어(send/control)가 제한됩니다.${RESET}\n`);
+  }
+}

package/hub/team/headless.mjs

@@ -20,6 +20,7 @@ import {
   psmuxExec,
 } from "./psmux.mjs";
 import { HANDOFF_INSTRUCTION_SHORT, processHandoff } from "./handoff.mjs";
+import { getBackend } from "./backend.mjs";
 
 const RESULT_DIR = join(tmpdir(), "tfx-headless");
 
@@ -93,16 +94,9 @@ export function buildHeadlessCommand(cli, prompt, resultFile, opts = {}) {
 
   const cls = "Clear-Host; ";
 
-  switch (resolvedCli) {
-    case "codex":
-      return `${cls}codex exec (Get-Content -Raw '${promptFile}') -o '${resultFile}' --color never`;
-    case "gemini":
-      return `${cls}gemini -p (Get-Content -Raw '${promptFile}') -o text > '${resultFile}' 2>'${resultFile}.err'`;
-    case "claude":
-      return `${cls}claude -p (Get-Content -Raw '${promptFile}') --output-format text > '${resultFile}' 2>&1`;
-    default:
-      throw new Error(`지원하지 않는 CLI: ${resolvedCli} (원본: ${cli})`);
-  }
+  const backend = getBackend(resolvedCli);
+  const promptExpr = `(Get-Content -Raw '${promptFile}')`;
+  return `${cls}${backend.buildArgs(promptExpr, resultFile, opts)}`;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "7.2.2",
+  "version": "7.3.1",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {