@triflux/core 10.0.0-alpha.1

package/hub/lib/process-utils.mjs

@@ -0,0 +1,361 @@
+// hub/lib/process-utils.mjs
+// 프로세스 관련 공유 유틸리티
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { IS_WINDOWS, killProcess } from "../platform.mjs";
+
+const CLEANUP_SCRIPT_DIR = join(tmpdir(), "tfx-process-utils");
+const SCAN_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "scan-processes.ps1");
+const TREE_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "get-ancestor-tree.ps1");
+
+// 스크립트 버전 — 내용 변경 시 증가하여 캐시된 스크립트를 갱신
+const SCRIPT_VERSION = 3;
+const VERSION_FILE = join(CLEANUP_SCRIPT_DIR, ".version");
+
+/**
+ * 주어진 PID의 프로세스가 살아있는지 확인한다.
+ * EPERM: 프로세스는 존재하지만 signal 권한 없음 → alive
+ * ESRCH: 프로세스가 존재하지 않음 → dead
+ */
+export function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    if (e?.code === 'EPERM') return true;
+    if (e?.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+/**
+ * 동기적 sleep. Atomics.wait 우선, 불가 시 busy-wait 폴백.
+ */
+function sleepSyncMs(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* spin */ }
+  }
+}
+
+/**
+ * 고아 PID 목록에 SIGTERM → 3초 대기 → SIGKILL 에스컬레이션을 적용한다.
+ * PID 재사용 레이스 방어: SIGTERM 전 alive 확인, SIGKILL 전 재검증.
+ * @param {number[]} orphanPids
+ * @param {Map<number, {ppid: number, name: string}>} [procMap] PID 재사용 감지용 스냅샷
+ * @returns {number} killed count
+ */
+function killWithEscalation(orphanPids, procMap) {
+  if (orphanPids.length === 0) return 0;
+
+  // SIGTERM 전 alive 스냅샷 — 이미 죽은 PID는 카운트에서 제외
+  const aliveBeforeKill = new Set(orphanPids.filter(pid => isPidAlive(pid)));
+
+  for (const pid of aliveBeforeKill) {
+    killProcess(pid, { signal: "SIGTERM" });
+  }
+
+  sleepSyncMs(3000);
+
+  let killed = 0;
+  for (const pid of aliveBeforeKill) {
+    if (isPidAlive(pid)) {
+      // PID 재사용 방어: procMap이 있으면 스캔 시점의 ppid와 현재 ppid 비교
+      // ppid가 변경되었으면 PID가 재사용된 것이므로 kill하지 않���
+      if (procMap) {
+        const snapshot = procMap.get(pid);
+        if (snapshot) {
+          try {
+            const current = execSync(
+              IS_WINDOWS
+                ? `powershell -NoProfile -WindowStyle Hidden -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction SilentlyContinue).ParentProcessId"`
+                : `ps -o ppid= -p ${pid}`,
+              { encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+            );
+            const currentPpid = Number.parseInt(current.trim(), 10);
+            if (Number.isFinite(currentPpid) && currentPpid !== snapshot.ppid) {
+              continue; // PID 재사용 감지 — skip
+            }
+          } catch {
+            // 조회 실패 시 안전하게 skip
+            continue;
+          }
+        }
+      }
+      killProcess(pid, { signal: "SIGKILL", force: true });
+    }
+    if (!isPidAlive(pid)) killed++;
+  }
+  return killed;
+}
+
+/**
+ * PowerShell 헬퍼 스크립트를 임시 디렉토리에 생성한다.
+ * bash의 $_ 이스케이핑 문제를 피하기 위해 -File로 실행.
+ */
+function ensureHelperScripts() {
+  mkdirSync(CLEANUP_SCRIPT_DIR, { recursive: true });
+
+  // 버전 체크 — 스크립트 갱신 필요 여부
+  let needsUpdate = true;
+  try {
+    if (existsSync(VERSION_FILE)) {
+      const cached = Number.parseInt(readFileSync(VERSION_FILE, "utf8").trim(), 10);
+      if (cached === SCRIPT_VERSION) needsUpdate = false;
+    }
+  } catch {}
+
+  if (needsUpdate) {
+    // 기존 스크립트 삭제 후 재생성
+    try { unlinkSync(SCAN_SCRIPT_PATH); } catch {}
+    try { unlinkSync(TREE_SCRIPT_PATH); } catch {}
+  }
+
+  if (!existsSync(TREE_SCRIPT_PATH)) {
+    writeFileSync(TREE_SCRIPT_PATH, [
+      "param([int]$StartPid)",
+      "$p = $StartPid",
+      "for ($i = 0; $i -lt 10; $i++) {",
+      "    if ($p -le 0) { break }",
+      "    Write-Output $p",
+      '    $parent = (Get-CimInstance Win32_Process -Filter "ProcessId=$p" -ErrorAction SilentlyContinue).ParentProcessId',
+      "    if ($null -eq $parent -or $parent -le 0) { break }",
+      "    $p = $parent",
+      "}",
+    ].join("\n"), "utf8");
+  }
+
+  if (!existsSync(SCAN_SCRIPT_PATH)) {
+    // CLI + 쉘 + 런타임 전체를 스캔하여 PID,ParentPID,Name 출력
+    // codex/claude/pwsh/uvx 누락 시 중간 프로세스가 alive 판정되어 고아 트리 전체가 보호됨
+    // 예: WT(dead)→pwsh(alive,미스캔)→codex→cmd→node — pwsh에서 isPidAlive=true로 끊김
+    writeFileSync(SCAN_SCRIPT_PATH, [
+      "$ErrorActionPreference = 'SilentlyContinue'",
+      "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='bash.exe' OR Name='cmd.exe' OR Name='codex.exe' OR Name='claude.exe' OR Name='pwsh.exe' OR Name='uvx.exe'\" | ForEach-Object {",
+      '    Write-Output "$($_.ProcessId),$($_.ParentProcessId),$($_.Name)"',
+      "}",
+    ].join("\n"), "utf8");
+  }
+
+  if (needsUpdate) {
+    writeFileSync(VERSION_FILE, String(SCRIPT_VERSION), "utf8");
+  }
+}
+
+/**
+ * PID → 루트 조상까지의 체인에서 살아있는 조상이 있는지 확인한다.
+ * 프로세스 맵을 사용하여 O(depth) 탐색.
+ * @param {number} pid
+ * @param {Map<number, {ppid: number, name: string}>} procMap
+ * @param {Set<number>} protectedPids
+ * @returns {boolean} true = 보호됨 (활성 조상 체인이 있음)
+ */
+function hasLiveAncestorChain(pid, procMap, protectedPids) {
+  const visited = new Set();
+  let current = pid;
+
+  while (current > 0 && !visited.has(current)) {
+    visited.add(current);
+
+    if (protectedPids.has(current)) return true;
+
+    const info = procMap.get(current);
+    if (!info) {
+      // 프로세스 맵에 없음 → 살아있는지 직접 확인
+      return isPidAlive(current);
+    }
+
+    const ppid = info.ppid;
+    if (!Number.isFinite(ppid) || ppid <= 0) {
+      // 루트 프로세스 (ppid=0) — 시스템 프로세스이므로 보호
+      return true;
+    }
+
+    // 부모가 맵에 없고 죽었으면 → 고아 체인
+    if (!procMap.has(ppid) && !isPidAlive(ppid)) return false;
+
+    current = ppid;
+  }
+
+  return false;
+}
+
+// kill 대상 프로세스 이름 (Windows)
+// codex/claude도 포함: protectedPids + hasLiveAncestorChain이 활성 인스턴스를 보호하므로
+// 고아(부모 dead + 자식 dead)만 kill됨. pwsh.exe는 사용자 인터랙티브 쉘이므로 제외.
+const KILLABLE_NAMES = new Set([
+  "node.exe", "bash.exe", "cmd.exe", "uvx.exe",
+  "codex.exe", "claude.exe",
+]);
+
+/**
+ * 고아 프로세스 트리를 정리한다 (node.exe + bash.exe + cmd.exe + uvx.exe).
+ * Windows 전용 — Agent 서브프로세스가 MCP 서버, bash 래퍼, cmd 래퍼를 남기는 문제 대응.
+ *
+ * 전략: 부모 체인을 루트까지 추적하여, 체인 중간에 죽은 프로세스가 있으면
+ * 해당 프로세스 아래의 전체 트리를 고아로 판정하고 정리.
+ * 스캔 범위에는 codex/claude/pwsh도 포함하여 체인 추적 정확도를 높인다.
+ *
+ * 보호 대상: 현재 프로세스 조상 트리, Hub PID
+ * @returns {{ killed: number, remaining: number }}
+ */
+export function cleanupOrphanNodeProcesses() {
+  if (!IS_WINDOWS) return cleanupOrphansUnix();
+
+  ensureHelperScripts();
+
+  const myPid = process.pid;
+
+  // Hub PID 보호
+  let hubPid = null;
+  try {
+    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    if (existsSync(hubPidPath)) {
+      const hubInfo = JSON.parse(readFileSync(hubPidPath, "utf8"));
+      hubPid = Number(hubInfo?.pid);
+    }
+  } catch {}
+
+  // 보호 PID 세트: 현재 프로세스 + Hub + 현재 프로세스의 조상 트리
+  const protectedPids = new Set();
+  protectedPids.add(myPid);
+  if (Number.isFinite(hubPid) && hubPid > 0) protectedPids.add(hubPid);
+
+  try {
+    const treeOutput = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${TREE_SCRIPT_PATH}" -StartPid ${myPid}`,
+      { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    for (const line of treeOutput.split(/\r?\n/)) {
+      const pid = Number.parseInt(line.trim(), 10);
+      if (Number.isFinite(pid) && pid > 0) protectedPids.add(pid);
+    }
+  } catch {}
+
+  // 전체 프로세스 맵 구축 (node + bash + cmd + codex + claude + pwsh + uvx)
+  const procMap = new Map();
+  try {
+    const output = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${SCAN_SCRIPT_PATH}"`,
+      { encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+
+    for (const line of output.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [pidStr, ppidStr, name] = trimmed.split(",");
+      const pid = Number.parseInt(pidStr, 10);
+      const ppid = Number.parseInt(ppidStr, 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        procMap.set(pid, { ppid, name: name || "unknown" });
+      }
+    }
+  } catch {}
+
+  // 고아 판정 + 정리 (SIGTERM → 3s → SIGKILL 에스컬레이션)
+  // CLI 도구(codex/claude/pwsh)는 체인 추적용으로만 스캔 — kill 대상에서 제외
+  const orphanPids = [];
+  for (const [pid, info] of procMap) {
+    if (protectedPids.has(pid)) continue;
+    if (!KILLABLE_NAMES.has(info.name?.toLowerCase())) continue;
+    if (hasLiveAncestorChain(pid, procMap, protectedPids)) continue;
+    orphanPids.push(pid);
+  }
+
+  const killed = killWithEscalation(orphanPids, procMap);
+
+  // 남은 프로세스 수 확인
+  let remaining = 0;
+  try {
+    const countOutput = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -Command "(Get-Process node -ErrorAction SilentlyContinue).Count"`,
+      { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    remaining = Number.parseInt(countOutput.trim(), 10) || 0;
+  } catch {}
+
+  return { killed, remaining };
+}
+
+/**
+ * Unix/macOS 고아 프로세스 정리.
+ * `ps -eo pid,ppid,comm` 기반 프로세스 맵 → 동일한 조상 체인 판정 → SIGKILL 에스컬레이션.
+ * @returns {{ killed: number, remaining: number }}
+ */
+function cleanupOrphansUnix() {
+  const myPid = process.pid;
+
+  // Hub PID 보호
+  const protectedPids = new Set();
+  protectedPids.add(myPid);
+  try {
+    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    if (existsSync(hubPidPath)) {
+      const hubPid = Number(JSON.parse(readFileSync(hubPidPath, "utf8"))?.pid);
+      if (Number.isFinite(hubPid) && hubPid > 0) protectedPids.add(hubPid);
+    }
+  } catch {}
+
+  // 현재 프로세스의 조상 트리 보호
+  try {
+    let current = myPid;
+    for (let i = 0; i < 10; i++) {
+      protectedPids.add(current);
+      const output = execSync(`ps -o ppid= -p ${current}`, {
+        encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      });
+      const ppid = Number.parseInt(output.trim(), 10);
+      if (!Number.isFinite(ppid) || ppid <= 1) break;
+      current = ppid;
+    }
+  } catch {}
+
+  // 프로세스 맵 구축 (런타임 + CLI — 체인 추적 정확도를 위해 CLI도 포함)
+  const procMap = new Map();
+  try {
+    const output = execSync("ps -eo pid,ppid,comm", {
+      encoding: "utf8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"],
+    });
+    for (const line of output.split("\n").slice(1)) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 3) continue;
+      const pid = Number.parseInt(parts[0], 10);
+      const ppid = Number.parseInt(parts[1], 10);
+      const name = parts.slice(2).join(" ");
+      if (Number.isFinite(pid) && pid > 0 && /^(node|bash|sh|python|codex|claude|uvx)/.test(name)) {
+        procMap.set(pid, { ppid, name });
+      }
+    }
+  } catch {}
+
+  // kill 대상: node, python, codex, claude, uvx — bash/sh는 사용자 인터랙티브 쉘 가능성
+  const killableUnix = /^(node|python|codex|claude|uvx)/;
+
+  // 고아 판정 + SIGKILL 에스컬레이션
+  const orphanPids = [];
+  for (const [pid, info] of procMap) {
+    if (protectedPids.has(pid)) continue;
+    if (!killableUnix.test(info.name)) continue;
+    if (hasLiveAncestorChain(pid, procMap, protectedPids)) continue;
+    orphanPids.push(pid);
+  }
+
+  const killed = killWithEscalation(orphanPids, procMap);
+
+  let remaining = 0;
+  try {
+    const output = execSync("ps -eo comm | grep -c '^node$'", {
+      encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    });
+    remaining = Number.parseInt(output.trim(), 10) || 0;
+  } catch {}
+
+  return { killed, remaining };
+}

package/hub/middleware/request-logger.mjs

@@ -0,0 +1,81 @@
+/**
+ * Hub HTTP 서버 요청 로깅 미들웨어.
+ *
+ * raw http.createServer에 맞춘 래퍼. Express가 아닌 triflux Hub 전용.
+ *
+ * 사용법 (server.mjs에서):
+ *   import { wrapRequestHandler } from './middleware/request-logger.mjs';
+ *   const httpServer = createHttpServer(wrapRequestHandler(originalHandler));
+ *
+ * 각 요청에 correlationId를 할당하고, 응답 완료 시 구조화 로그를 남긴다.
+ * health/status 체크는 로깅을 건너뛴다.
+ */
+import { withRequestContext, getCorrelationId } from '../../scripts/lib/context.mjs';
+import { createModuleLogger } from '../../scripts/lib/logger.mjs';
+
+const log = createModuleLogger('hub');
+
+const SKIP_PATHS = new Set(['/health', '/healthz', '/status', '/ready']);
+
+/**
+ * 원본 request handler를 래핑하여 로깅 + 컨텍스트 전파를 추가한다.
+ *
+ * @param {function(import('http').IncomingMessage, import('http').ServerResponse): void} handler
+ * @returns {function(import('http').IncomingMessage, import('http').ServerResponse): void}
+ */
+export function wrapRequestHandler(handler) {
+  return (req, res) => {
+    const path = getRequestPath(req.url);
+
+    if (SKIP_PATHS.has(path)) {
+      return handler(req, res);
+    }
+
+    const correlationId =
+      req.headers['x-correlation-id'] ||
+      req.headers['x-request-id'] ||
+      undefined; // withRequestContext will generate one
+
+    withRequestContext(
+      {
+        correlationId,
+        method: req.method,
+        path,
+      },
+      () => {
+        const startTime = process.hrtime.bigint();
+
+        // 응답 헤더에 상관 ID 포함
+        const cid = getCorrelationId();
+        if (cid) res.setHeader('X-Correlation-ID', cid);
+
+        // 응답 완료 시 로깅
+        res.on('finish', () => {
+          const duration = Number(process.hrtime.bigint() - startTime) / 1_000_000;
+          const level = res.statusCode >= 500 ? 'error'
+            : res.statusCode >= 400 ? 'warn'
+            : 'info';
+
+          log[level](
+            {
+              status: res.statusCode,
+              duration: Math.round(duration * 100) / 100,
+              contentLength: res.getHeader('content-length') || 0,
+            },
+            'http.response',
+          );
+        });
+
+        handler(req, res);
+      },
+    );
+  };
+}
+
+function getRequestPath(url = '/') {
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname;
+  } catch {
+    return String(url).replace(/\?.*/, '') || '/';
+  }
+}

package/hub/paths.mjs

@@ -0,0 +1,30 @@
+// hub/paths.mjs — triflux 워킹 디렉토리 경로 상수
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const TFX_WORK_DIR = '.tfx';
+export const TFX_PLANS_DIR = join(TFX_WORK_DIR, 'plans');
+export const TFX_REPORTS_DIR = join(TFX_WORK_DIR, 'reports');
+export const TFX_HANDOFFS_DIR = join(TFX_WORK_DIR, 'handoffs');
+export const TFX_LOGS_DIR = join(TFX_WORK_DIR, 'logs');
+export const TFX_STATE_DIR = join(TFX_WORK_DIR, 'state');
+export const TFX_FULLCYCLE_DIR = join(TFX_WORK_DIR, 'fullcycle');
+
+/**
+ * triflux 워킹 디렉토리 구조를 보장한다.
+ * @param {string} baseDir
+ */
+export function ensureTfxDirs(baseDir) {
+  for (const relativeDir of [
+    TFX_WORK_DIR,
+    TFX_PLANS_DIR,
+    TFX_REPORTS_DIR,
+    TFX_HANDOFFS_DIR,
+    TFX_LOGS_DIR,
+    TFX_STATE_DIR,
+    TFX_FULLCYCLE_DIR,
+  ]) {
+    mkdirSync(join(baseDir, relativeDir), { recursive: true });
+  }
+}

package/hub/pipeline/gates/confidence.mjs

@@ -0,0 +1,56 @@
+// hub/pipeline/gates/confidence.mjs — Pre-Execution Confidence Gate
+//
+// plan → prd → [confidence] → exec
+// 5단계 확신도 검증: >=90% proceed / 70-89% alternative / <70% abort
+
+export const CRITERIA = [
+  { id: 'no_duplicate',  label: '중복 구현 없는지?', weight: 0.25 },
+  { id: 'architecture',  label: '아키텍처 준수?',    weight: 0.25 },
+  { id: 'docs_verified', label: '공식 문서 확인?',   weight: 0.20 },
+  { id: 'oss_reference', label: 'OSS 레퍼런스?',    weight: 0.15 },
+  { id: 'root_cause',    label: '근본 원인 파악?',   weight: 0.15 },
+];
+
+/**
+ * 확신도 검증 실행
+ * @param {string|object} planArtifact - plan 단계에서 생성된 구현 계획
+ * @param {object} context - { checks?, codebaseFiles?, existingTests? }
+ * @param {object} [context.checks] - 각 기준별 점수 (boolean 또는 0-1 숫자)
+ * @returns {{ score: number, breakdown: Array, decision: string, reasoning: string }}
+ */
+export function runConfidenceCheck(planArtifact, context = {}) {
+  if (!planArtifact) {
+    return {
+      score: 0,
+      breakdown: CRITERIA.map(c => ({ id: c.id, label: c.label, weight: c.weight, score: 0, passed: false })),
+      decision: 'abort',
+      reasoning: 'planArtifact가 제공되지 않았습니다.',
+    };
+  }
+
+  const checks = context.checks || {};
+
+  const breakdown = CRITERIA.map(c => {
+    const raw = checks[c.id];
+    const score = typeof raw === 'number' ? Math.max(0, Math.min(1, raw)) : (raw ? 1 : 0);
+    return { id: c.id, label: c.label, weight: c.weight, score, passed: score >= 0.7 };
+  });
+
+  const totalScore = Math.round(
+    breakdown.reduce((sum, b) => sum + b.score * b.weight, 0) * 100,
+  );
+
+  let decision, reasoning;
+  if (totalScore >= 90) {
+    decision = 'proceed';
+    reasoning = `확신도 ${totalScore}%: 모든 기준 충족. 실행 진행.`;
+  } else if (totalScore >= 70) {
+    decision = 'alternative';
+    reasoning = `확신도 ${totalScore}%: 일부 기준 미달. 대안 검토 필요.`;
+  } else {
+    decision = 'abort';
+    reasoning = `확신도 ${totalScore}%: 기준 미달. 실행 중단.`;
+  }
+
+  return { score: totalScore, breakdown, decision, reasoning, needsReview: decision === 'alternative' };
+}

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

@@ -0,0 +1,5 @@
+// hub/pipeline/gates/index.mjs — Quality Gates re-export
+
+export { CRITERIA, runConfidenceCheck } from './confidence.mjs';
+export { RED_FLAGS, QUESTIONS, runSelfCheck } from './selfcheck.mjs';
+export { STAGE_THRESHOLDS, evaluateQualityBranch, evaluateConsensus } from './consensus.mjs';