triflux 7.2.1 → 7.3.0

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,154 @@
+// 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,319 @@
+// 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'];
+
+/** 특성 벡터 키워드 (32차원, 에이전트 타입 기반) */
+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',
+];
+
+/**
+ * 텍스트에서 32차원 특성 벡터 추출
+ * @param {string} text
+ * @returns {number[]} 32-dim binary feature vector
+ */
+function extractFeatures(text) {
+  const lower = text.toLowerCase();
+  return FEATURE_KEYWORDS.map((kw) => (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/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.1",
+  "version": "7.3.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/setup.mjs

@@ -171,6 +171,11 @@ const SYNC_MAP = [
     dst: join(CLAUDE_DIR, "scripts", "lib", "keyword-rules.mjs"),
     label: "lib/keyword-rules.mjs",
   },
+  {
+    src: join(PLUGIN_ROOT, "hub", "team", "agent-map.json"),
+    dst: join(CLAUDE_DIR, "hub", "team", "agent-map.json"),
+    label: "hub/team/agent-map.json",
+  },
   {
     src: join(PLUGIN_ROOT, "scripts", "headless-guard.mjs"),
     dst: join(CLAUDE_DIR, "scripts", "headless-guard.mjs"),

package/scripts/tfx-route.sh

@@ -574,6 +574,14 @@ route_agent() {
   local codex_base="--dangerously-bypass-approvals-and-sandbox --skip-git-repo-check"
   local map_file
   map_file="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../hub/team/agent-map.json"
+  # ── breadcrumb 폴백 (synced 환경: ~/.claude/scripts/) ──
+  if [[ ! -f "$map_file" && -n "$TFX_PKG_ROOT" ]]; then
+    map_file="$TFX_PKG_ROOT/hub/team/agent-map.json"
+  fi
+  if [[ ! -f "$map_file" ]]; then
+    echo "ERROR: agent-map.json 미발견 (경로: $map_file, TFX_PKG_ROOT=${TFX_PKG_ROOT:-unset})" >&2
+    exit 1
+  fi
 
   # ── CLI_TYPE: 단일 소스 (agent-map.json) ──
   local _raw_type