triflux 4.2.10 → 5.0.1

package/README.ko.md

@@ -40,17 +40,23 @@
 
 ---
 
-## v4의 새로운 기능
-
-**triflux v4**는 단순한 라우터를 넘어 **고성능 오케스트레이션 허브**로 진화했습니다. 상주형(resident) 서비스, 네임드 파이프(Named Pipe) IPC, 그리고 고도화된 태스크 파이프라인을 통해 [Claude Code](https://claude.ai/code) 환경에서 가장 안정적인 멀티모델 경험을 제공합니다.
-
-### 주요 특징
-
-- **Hub IPC 아키텍처** — Named Pipe 및 HTTP MCP 브리지를 활용한 초고속 상주형 허브 서버.
-- **파이프라인 `--thorough`** — `plan` → `prd` → `exec` → `verify` → `fix`로 이어지는 다단계 작업 생명주기.
-- **위임(Delegator) MCP** — 에이전트와 유연하게 상호작용할 수 있는 전용 MCP 도구(`delegate`, `reply`, `status`).
-- **psmux / Windows 네이티브** — `tmux` (WSL)와 `psmux` (Windows Terminal 네이티브)를 모두 지원하는 하이브리드 세션 관리.
-- **QoS 대시보드** — AIMD 기반 동적 배치 사이징 및 실시간 상태 모니터링.
+## v5의 새로운 기능
+
+**triflux v5**는 v4의 오케스트레이션 기반을 유지하면서 파이프라인을 더 똑똑하고, 더 phase-aware하게, 더 협업적으로 발전시켰습니다. 멀티태스크 오케스트레이션에서는 이제 `--thorough`가 기본 경로이므로, 계획, 승인, 검증, 복구가 기본값으로 활성화됩니다.
+
+### 주요 특징
+
+- **`--thorough` 기본화** — 멀티태스크 오케스트레이션은 기본적으로 `plan` → `prd` → `exec` → `verify` → `fix` 전체 파이프라인을 실행합니다. 경량 경로가 필요할 때만 `--quick`을 명시합니다.
+- **Opus × Codex Scout 계획 협업** — `plan` 단계에서 Opus가 설계를 주도하고 Codex scout 워커가 코드베이스를 병렬 탐색한 뒤 최종 계획에 반영합니다.
+- **DAG 기반 라우팅 휴리스틱** — `dag_width`와 `complexity`를 함께 반영해 `quick_single`, `thorough_single`, `quick_team`, `thorough_team`, `batch_single` 전략 중 하나를 선택합니다.
+- **피드백 루프 복원** — 워커는 여러 차례 재실행될 수 있고, 최종 완료 전 리드의 피드백을 다시 받아 반영할 수 있습니다.
+- **HITL 승인 게이트** — `pipeline_advance_gated`를 통해 단계 전이 전에 사람 승인 체크포인트를 삽입합니다.
+- **Phase-aware MCP 필터링** — 파이프라인 단계에 따라 MCP 노출을 조정해 `plan`, `prd`, `verify`는 읽기 중심으로 유지하고 `exec`는 더 넓은 도구 세트를 사용합니다.
+- **Plan 파일 영속화** — 최종 계획 Markdown을 `.tfx/plans/{team}-plan.md`에 저장하고 파이프라인 artifact로 추적합니다.
+- **Hub IPC 아키텍처** — Named Pipe 및 HTTP MCP 브리지를 활용한 초고속 상주형 허브 서버.
+- **위임(Delegator) MCP** — 에이전트와 유연하게 상호작용할 수 있는 전용 MCP 도구(`delegate`, `reply`, `status`).
+- **psmux / Windows 네이티브** — `tmux` (WSL)와 `psmux` (Windows Terminal 네이티브)를 모두 지원하는 하이브리드 세션 관리.
+- **QoS 대시보드** — AIMD 기반 동적 배치 사이징 및 실시간 상태 모니터링.
 - **21종 이상의 전문 에이전트** — `scientist-deep`부터 `spark_fast`까지, 작업에 최적화된 에이전트 라인업.
 
 ---
@@ -95,35 +101,39 @@ npm install -g triflux
 tfx setup
 ```
 
-### 3. 사용 방법
-
-```bash
-# 자동 모드 — 허브를 통한 병렬 실행
-/tfx-auto "인증 리팩터링 + UI 업데이트 + 테스트 추가"
-
-# 파이프라인 모드 — 정밀한 다단계 실행
-/tfx-auto --thorough "복잡한 데이터 마이그레이션 구현"
-
-# 직접 위임
-/tfx-delegate "최신 React 패턴 조사" --provider gemini
-```
-
----
-
-## 파이프라인: `--thorough` 모드
-
-v4 파이프라인은 복잡한 엔지니어링 작업을 위해 설계된 강력한 실행 루프를 제공합니다.
-
-| 단계 | 설명 |
-|------|------|
-| **plan** | 해결책을 설계하고 의존성을 식별합니다. |
-| **prd** | 상세한 기술 명세서(Technical Spec / PRD)를 생성합니다. |
-| **exec** | 실제 코드 구현을 수행합니다. |
-| **verify** | 테스트를 실행하고 구현 결과가 PRD와 일치하는지 검증합니다. |
-| **fix** | (루프) 검증 단계에서 발견된 실패를 자동으로 수정합니다 (최대 3회). |
-| **ralph** | (재시작) 수정 루프 실패 시, 새로운 통찰을 바탕으로 `plan`부터 다시 시작합니다 (최대 10회). |
-
----
+### 3. 사용 방법
+
+```bash
+# 자동 모드 — 허브를 통한 thorough 멀티태스크 오케스트레이션
+/tfx-auto "인증 리팩터링 + UI 업데이트 + 테스트 추가"
+
+# quick 모드 — 전체 계획/검증 루프 생략
+/tfx-auto --quick "작은 회귀 버그 수정"
+
+# 직접 위임
+/tfx-delegate "최신 React 패턴 조사" --provider gemini
+```
+
+v5에서는 멀티태스크 오케스트레이션이 기본적으로 `--thorough`로 실행되며, 더 가벼운 경로가 필요할 때 `--quick`을 사용합니다.
+
+---
+
+## 파이프라인: `--thorough` 모드
+
+v5 파이프라인은 복잡한 엔지니어링 작업에서 기본이 되는 thorough 실행 루프입니다. Plan 산출물은 영속화되고, PRD 핸드오프에는 사람 승인 게이트를 둘 수 있으며, verify/fix 단계는 워커 피드백 루프를 복원합니다.
+
+| 단계 | 설명 |
+|------|------|
+| **plan** | Opus가 설계를 주도하고 Codex scout가 병렬 탐색을 수행하며, 계획 산출물을 파일로 영속화합니다. |
+| **prd** | 상세한 기술 명세서(Technical Spec / PRD)를 생성하고 승인 체크포인트를 준비합니다. |
+| **exec** | 실제 코드 구현을 수행합니다. |
+| **verify** | 테스트를 실행하고 구현 결과가 PRD와 일치하는지 검증합니다. |
+| **fix** | (루프) 검증 단계에서 발견된 실패를 리드 피드백과 함께 재실행하여 수정합니다 (최대 3회). |
+| **ralph** | (재시작) 수정 루프 실패 시, 새로운 통찰을 바탕으로 `plan`부터 다시 시작합니다 (최대 10회). |
+
+Phase-aware MCP 필터링으로 `plan`, `prd`, `verify`는 읽기 중심으로 제한되며, `prd` → `exec` 전이는 `pipeline_advance_gated`로 승인 대기를 걸 수 있습니다.
+
+---
 
 ## 위임(Delegator) MCP
 
@@ -155,9 +165,9 @@ MCP 도구를 통해 허브와 직접 상호작용하세요.
 
 ---
 
-## 보안
-
-triflux v4는 안전한 전문 개발 환경을 위해 설계되었습니다.
+## 보안
+
+triflux v5는 안전한 전문 개발 환경을 위해 설계되었습니다.
 
 - **허브 토큰 인증** — `TFX_HUB_TOKEN`을 이용한 보안 IPC (Bearer 인증).
 - **Localhost 전용** — 허브가 기본적으로 `127.0.0.1`에만 바인딩되어 외부 접근을 차단합니다.

package/README.md

@@ -40,17 +40,23 @@
 
 ---
 
-## What's New in v4?
-
-**triflux v4** evolves from a simple router into a **high-performance orchestration hub**. It introduces resident services, named-pipe IPC, and advanced task pipelines to provide the most stable multi-model experience for [Claude Code](https://claude.ai/code).
-
-### Key Features
-
-- **Hub IPC Architecture** — Lightning-fast resident Hub server with Named Pipe & HTTP MCP bridge.
-- **Pipeline `--thorough`** — Multi-phase task lifecycle: `plan` → `prd` → `exec` → `verify` → `fix`.
-- **Delegator MCP** — Native MCP tools (`delegate`, `reply`, `status`) for seamless agent interaction.
-- **psmux / Windows Native** — Hybrid support for `tmux` (WSL) and `psmux` (Windows Terminal native).
-- **QoS Dashboard** — Real-time health monitoring with AIMD-based dynamic batch sizing.
+## What's New in v5?
+
+**triflux v5** keeps the v4 orchestration foundation intact while making the pipeline smarter, more phase-aware, and more collaborative. For multi-task orchestration, `--thorough` is now the default path, so planning, approval, verification, and recovery stay on by default instead of being bolted on later.
+
+### Key Features
+
+- **`--thorough` by Default** — Multi-task orchestration now defaults to the full `plan` → `prd` → `exec` → `verify` → `fix` pipeline. Reach for `--quick` only when you explicitly want the lighter path.
+- **Opus × Codex Scout Planning** — In `plan`, Opus leads architecture decisions while Codex scout workers explore the codebase in parallel and feed findings back into the final plan.
+- **DAG-based Routing Heuristics** — Routing now considers both `dag_width` and `complexity` to choose between `quick_single`, `thorough_single`, `quick_team`, `thorough_team`, and `batch_single`.
+- **Restored Feedback Loop** — Workers can be re-run for multiple iterations and receive lead feedback before final completion.
+- **HITL Approval Gate** — `pipeline_advance_gated` inserts a human approval checkpoint before gated phase transitions.
+- **Phase-aware MCP Filtering** — MCP exposure changes by pipeline phase so `plan`, `prd`, and `verify` stay read-focused while `exec` keeps broader tooling.
+- **Persistent Plan Files** — Final plan markdown is saved to `.tfx/plans/{team}-plan.md` and tracked as a pipeline artifact.
+- **Hub IPC Architecture** — Lightning-fast resident Hub server with Named Pipe & HTTP MCP bridge.
+- **Delegator MCP** — Native MCP tools (`delegate`, `reply`, `status`) for seamless agent interaction.
+- **psmux / Windows Native** — Hybrid support for `tmux` (WSL) and `psmux` (Windows Terminal native).
+- **QoS Dashboard** — Real-time health monitoring with AIMD-based dynamic batch sizing.
 - **21+ specialized agents** — From `scientist-deep` to `spark_fast`, each optimized for specific tasks.
 
 ---
@@ -95,35 +101,39 @@ Synchronize scripts, register skills to Claude Code, and configure the HUD.
 tfx setup
 ```
 
-### 3. Usage
-
-```bash
-# Auto mode — Parallel execution via Hub
-/tfx-auto "refactor auth + update UI + add tests"
-
-# Pipeline mode — Thorough multi-phase execution
-/tfx-auto --thorough "implement complex data migration"
-
-# Direct Delegation
-/tfx-delegate "research latest React patterns" --provider gemini
-```
-
----
-
-## Pipeline: `--thorough` Mode
-
-The v4 Pipeline provides a robust execution loop designed for complex engineering tasks.
-
-| Phase | Description |
-|-------|-------------|
-| **plan** | Architect the solution and identify dependencies. |
-| **prd** | Generate a detailed Technical Specification / PRD. |
-| **exec** | Perform the actual code implementation. |
-| **verify** | Run tests and verify the implementation against the PRD. |
-| **fix** | (Loop) Automatically fix failures identified in the verify phase (Max 3). |
-| **ralph** | (Reset) If the fix loop fails, restart from `plan` with new insights (Max 10). |
-
----
+### 3. Usage
+
+```bash
+# Auto mode — Thorough multi-task orchestration via Hub
+/tfx-auto "refactor auth + update UI + add tests"
+
+# Quick mode — Skip the full planning/verification loop
+/tfx-auto --quick "fix a small regression"
+
+# Direct Delegation
+/tfx-delegate "research latest React patterns" --provider gemini
+```
+
+In v5, multi-task orchestration defaults to `--thorough`; use `--quick` when you explicitly want the lighter path.
+
+---
+
+## Pipeline: `--thorough` Mode
+
+The v5 pipeline is the default thorough execution loop for complex engineering work. Plan artifacts are persisted, PRD handoff can be gated by human approval, and verify/fix restores the worker feedback loop.
+
+| Phase | Description |
+|-------|-------------|
+| **plan** | Opus-led solution design with parallel Codex scout exploration and a persisted plan artifact. |
+| **prd** | Generate a detailed Technical Specification / PRD and prepare the approval checkpoint. |
+| **exec** | Perform the actual code implementation. |
+| **verify** | Run tests and verify the implementation against the PRD. |
+| **fix** | (Loop) Re-run workers with lead feedback to fix failures identified in the verify phase (Max 3). |
+| **ralph** | (Reset) If the fix loop fails, restart from `plan` with new insights (Max 10). |
+
+Phase-aware MCP filtering keeps `plan`, `prd`, and `verify` read-heavy, while the `prd` → `exec` handoff can be gated through `pipeline_advance_gated`.
+
+---
 
 ## Delegator MCP
 
@@ -155,9 +165,9 @@ Interact with the Hub directly through MCP tools.
 
 ---
 
-## Security
-
-triflux v4 is designed for secure, professional environments:
+## Security
+
+triflux v5 is designed for secure, professional environments:
 
 - **Hub Token Auth** — Secure IPC using `TFX_HUB_TOKEN` (Bearer Auth).
 - **Localhost Only** — Default Hub binding to `127.0.0.1` prevents external access.

package/bin/tfx-doctor.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-doctor — triflux doctor 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/tfx-setup.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-setup — triflux setup 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/triflux.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, rmSync, statSync, openSync, closeSync } from "fs";
 import { join, dirname } from "path";

package/hub/pipeline/index.mjs

@@ -2,6 +2,9 @@
 //
 // 상태(state.mjs) + 전이(transitions.mjs) 통합 인터페이스
 
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
 import { canTransition, transitionPhase, ralphRestart, TERMINAL } from './transitions.mjs';
 import {
   ensurePipelineTable,
@@ -92,6 +95,22 @@ export function createPipeline(db, teamName, opts = {}) {
       state = updatePipelineState(db, teamName, { artifacts });
     },
 
+    /**
+     * Plan 파일을 .tfx/plans/{teamName}-plan.md 에 기록하고
+     * artifact('plan_path')에 절대 경로를 저장한다.
+     * @param {string} content - Plan markdown 내용
+     * @returns {string} 절대 경로
+     */
+    writePlanFile(content) {
+      const safeName = teamName.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_');
+      const planDir = resolve(process.cwd(), '.tfx', 'plans');
+      mkdirSync(planDir, { recursive: true });
+      const planPath = join(planDir, `${safeName}-plan.md`);
+      writeFileSync(planPath, content, 'utf8');
+      this.setArtifact('plan_path', planPath);
+      return planPath;
+    },
+
     /**
      * 터미널 상태 여부
      */

package/hub/team/native.mjs

@@ -10,9 +10,17 @@ import * as fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
-export const SLIM_WRAPPER_SUBAGENT_TYPE = "slim-wrapper";
-const ROUTE_LOG_RE = /\[tfx-route\]/i;
+const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
+export const SLIM_WRAPPER_SUBAGENT_TYPE = "slim-wrapper";
+/** scout 역할 기본 설정 — read-only 탐색 전용 */
+export const SCOUT_ROLE_CONFIG = {
+  cli: "codex",
+  role: "scientist",
+  mcp_profile: "analyze",
+  maxIterations: 2,
+  readOnly: true,
+};
+const ROUTE_LOG_RE = /\[tfx-route\]/i;
 const ROUTE_COMMAND_RE = /(?:^|[\s"'`])(?:bash\s+)?(?:[^"'`\s]*\/)?tfx-route\.sh\b/i;
 const ROUTE_PROMPT_RE = /tfx-route\.sh/i;
 const DIRECT_TOOL_BYPASS_RE = /\b(?:Read|Edit|Write)\s*\(/;
@@ -143,9 +151,10 @@ function getRouteTimeout(role, _mcpProfile) {
  * @param {number} [opts.workerIndex] — 검색 힌트 회전에 사용할 워커 인덱스(1-based)
  * @param {string} [opts.searchTool] — 전용 검색 도구 힌트(brave-search|tavily|exa)
  * @param {number} [opts.bashTimeout] — (deprecated, async에서는 무시됨)
+ * @param {number} [opts.maxIterations=3] — 피드백 루프 최대 반복 횟수
  * @returns {string} 슬림 래퍼 프롬프트
  */
-export function buildSlimWrapperPrompt(cli, opts = {}) {
+export function buildSlimWrapperPrompt(cli, opts = {}) {
   const {
     subtask,
     role = "executor",
@@ -157,30 +166,36 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     workerIndex,
     searchTool = "",
     pipelinePhase = "",
+    maxIterations = 3,
   } = opts;
 
   const routeTimeoutSec = getRouteTimeout(role, mcp_profile);
   const escaped = subtask.replace(/'/g, "'\\''");
-  const pipelineHint = pipelinePhase
-    ? `\n파이프라인 단계: ${pipelinePhase}`
-    : '';
-  const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
+  const pipelineHint = pipelinePhase
+    ? `\n파이프라인 단계: ${pipelinePhase}`
+    : '';
+  const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
+  const scoutConstraint = (role === "scout" || role === "scientist")
+    ? "\n이 워커는 scout(탐색 전용)이다. 코드를 수정하거나 파일을 생성하지 마라. 기존 코드를 읽고 분석하여 보고만 하라."
+    : "";
 
   // Bash 도구 timeout (모두 600초 이내)
   const launchTimeoutMs = 15000;   // Step 1: fork + job_id 반환
   const waitTimeoutMs = 570000;    // Step 2: 내부 폴링 (540초 대기 + 여유)
   const resultTimeoutMs = 30000;   // Step 3: 결과 읽기
 
-  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async):
-1. --async로 백그라운드 시작 → JOB_ID 수신
-2. --job-wait로 완료 대기 (내부 15초 간격 폴링, 최대 540초)
-3. "still_running"이면 Step 2 반복, "done"이면 --job-result로 결과 수집
-4. TaskUpdate + SendMessage → 종료${pipelineHint}
+  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async + feedback):
+MAX_ITERATIONS = ${maxIterations}
+ITERATION = 0${pipelineHint}
 
-[HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
-Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
-코드를 직접 읽거나 수정하면 안 된다. 반드시 아래 Bash 명령(tfx-route.sh)을 통해 Codex/Gemini에 위임하라.
-이 규칙을 위반하면 작업 실패로 간주한다.
+Step 0 — 시작 보고 (턴 경계 생성):
+TaskUpdate(taskId: "${taskId}", status: "in_progress")
+SendMessage(type: "message", recipient: "${leadName}", content: "작업 시작: ${agentName}", summary: "task ${taskId} started")
+
+[HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
+Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
+코드를 직접 읽거나 수정하면 안 된다. 반드시 아래 Bash 명령(tfx-route.sh)을 통해 Codex/Gemini에 위임하라.
+이 규칙을 위반하면 작업 실패로 간주한다.${scoutConstraint}
 
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
@@ -193,29 +208,64 @@ Step 2 — 완료 대기 (내부 폴링, 최대 540초):
 Bash(command: 'bash ${ROUTE_SCRIPT} --job-wait JOB_ID 540', timeout: ${waitTimeoutMs})
 → 주기적 "waiting elapsed=Ns progress=NB" 출력 후 최종 상태:
   "done" → Step 3으로
-  "timeout" 또는 "failed ..." → Step 4로 (실패 보고)
+  "timeout" 또는 "failed ..." → Step 4로 (실패 상태로)
   "still_running ..." → Step 2 반복 (같은 명령 재실행)
 
 Step 3 — 결과 수집:
 Bash(command: 'bash ${ROUTE_SCRIPT} --job-result JOB_ID', timeout: ${resultTimeoutMs})
-→ 출력이 워커 실행 결과이다.
+→ RESULT에 저장.
 
-Step 4 — Claude Code 태스크 동기화 (반드시 실행):
+Step 4 — 결과 보고 (턴 경계 생성, TaskUpdate 하지 않음):
 "done"이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "완료: ${agentName}", summary: "task ${taskId} success")
+  SendMessage(type: "message", recipient: "${leadName}", content: "결과 (iteration ITERATION): ${agentName} 성공\\n{결과 요약}", summary: "task ${taskId} iteration ITERATION done")
 "timeout" 또는 "failed"이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "상태 메시지"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (상태)", summary: "task ${taskId} failed")
+  SendMessage(type: "message", recipient: "${leadName}", content: "결과 (iteration ITERATION): ${agentName} 실패\\n{에러 요약}", summary: "task ${taskId} iteration ITERATION failed")
 TFX_NEEDS_FALLBACK 출력 감지 시:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "fallback", reason: "claude-native"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "fallback 필요: ${agentName} — claude-native 역할은 Claude Agent로 위임 필요", summary: "task ${taskId} fallback")
-
-Step 5 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
-}
-
-/**
- * v3 하이브리드 래퍼 프롬프트 생성
+  → Step 6으로 즉시 이동 (fallback은 재실행 불가)
+
+Step 5 — 피드백 대기:
+SendMessage 후 너는 IDLE 상태가 된다. 리드의 응답을 기다려라.
+수신 메시지에 따라:
+  - "재실행:" 포함 → ITERATION++ → ITERATION < MAX_ITERATIONS이면 메시지의 지시를 반영하여 Step 1로. ITERATION >= MAX_ITERATIONS이면 Step 6으로 (반복 한도 초과)
+  - "승인" 또는 기타 → Step 6으로
+  - 메시지 없이 팀이 삭제되면 자동 종료 (처리 불필요)
+
+Step 6 — 최종 종료 (반드시 실행):
+TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"|"failed"|"fallback", iterations: ITERATION})
+SendMessage(type: "message", recipient: "${leadName}", content: "최종 완료: ${agentName} (ITERATION회 실행)", summary: "task ${taskId} final")
+→ 종료. 이후 추가 도구 호출 금지.`;
+}
+
+/**
+ * scout 파견용 프롬프트 생성
+ * @param {object} opts
+ * @param {string} opts.question — 탐색 질문
+ * @param {string} [opts.scope] — 탐색 범위 힌트 (파일 패턴)
+ * @param {string} [opts.teamName] — 팀 이름
+ * @param {string} [opts.taskId] — 태스크 ID
+ * @param {string} [opts.agentName] — 에이전트 이름
+ * @param {string} [opts.leadName] — 리드 이름
+ * @returns {string} slim wrapper 프롬프트
+ */
+export function buildScoutDispatchPrompt(opts = {}) {
+  const { question, scope = "", teamName, taskId, agentName, leadName } = opts;
+  const subtask = scope
+    ? `${question} 탐색 범위: ${scope}`
+    : question;
+  return buildSlimWrapperPrompt("codex", {
+    subtask,
+    role: "scientist",
+    teamName,
+    taskId,
+    agentName,
+    leadName,
+    mcp_profile: "analyze",
+    maxIterations: SCOUT_ROLE_CONFIG.maxIterations,
+  });
+}
+
+/**
+ * v3 하이브리드 래퍼 프롬프트 생성
  * psmux pane 기반 비동기 실행 + polling 패턴.
  * Agent가 idle 상태를 유지하여 인터럽트 수신이 가능하다.
  *

package/hub/team/routing.mjs

@@ -0,0 +1,154 @@
+/**
+ * 라우팅 결정 함수
+ * @param {object} opts
+ * @param {Array<{id:string, description?:string, agent?:string, depends_on?:string[], complexity?:string}>} opts.subtasks
+ * @param {string} opts.graph_type - "INDEPENDENT" | "SEQUENTIAL" | "DAG"
+ * @param {boolean} opts.thorough - thorough 모드 여부
+ * @returns {{
+ *   strategy: "quick_single" | "thorough_single" | "quick_team" | "thorough_team" | "batch_single",
+ *   reason: string,
+ *   dag_width: number,
+ *   max_complexity: string
+ * }}
+ */
+export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
+  const N = subtasks.length;
+  if (N === 0) {
+    return { strategy: 'quick_single', reason: 'empty_subtasks', dag_width: 0, max_complexity: 'S' };
+  }
+
+  const dag_width = computeDagWidth(subtasks, graph_type);
+  const max_complexity = getMaxComplexity(subtasks);
+  const isHighComplexity = ['L', 'XL'].includes(max_complexity);
+  const allSameAgent = new Set(subtasks.map((s) => s.agent)).size === 1;
+  const allSmall = subtasks.every((s) => normalizeComplexity(s.complexity) === 'S');
+
+  // N==1: 단일 태스크
+  if (N === 1) {
+    if (thorough || isHighComplexity) {
+      return {
+        strategy: 'thorough_single',
+        reason: 'single_high_complexity',
+        dag_width,
+        max_complexity,
+      };
+    }
+    return {
+      strategy: 'quick_single',
+      reason: 'single_low_complexity',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // dag_width==1: 사실상 순차 -> single
+  if (dag_width === 1) {
+    if (thorough || isHighComplexity) {
+      return {
+        strategy: 'thorough_single',
+        reason: 'sequential_chain',
+        dag_width,
+        max_complexity,
+      };
+    }
+    return {
+      strategy: 'quick_single',
+      reason: 'sequential_chain',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // 동일 에이전트 + 모두 S: 프롬프트 병합 -> batch single
+  if (allSameAgent && allSmall) {
+    return {
+      strategy: 'batch_single',
+      reason: 'same_agent_small_batch',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // dag_width >= 2: 팀
+  if (thorough || isHighComplexity) {
+    return {
+      strategy: 'thorough_team',
+      reason: 'parallel_high_complexity',
+      dag_width,
+      max_complexity,
+    };
+  }
+  return {
+    strategy: 'quick_team',
+    reason: 'parallel_low_complexity',
+    dag_width,
+    max_complexity,
+  };
+}
+
+/**
+ * DAG 폭 계산 - 레벨별 최대 병렬 태스크 수
+ * @param {Array<{id:string, depends_on?:string[]}>} subtasks
+ * @param {string} graph_type
+ * @returns {number}
+ */
+function computeDagWidth(subtasks, graph_type) {
+  if (graph_type === 'SEQUENTIAL') return 1;
+  if (graph_type === 'INDEPENDENT') return subtasks.length;
+
+  // DAG: 레벨별 계산 (순환 의존 방어)
+  const levels = {};
+  const visiting = new Set();
+
+  function getLevel(task) {
+    if (levels[task.id] !== undefined) return levels[task.id];
+    if (visiting.has(task.id)) {
+      levels[task.id] = 0; // 순환 끊기
+      return 0;
+    }
+    if (!task.depends_on || task.depends_on.length === 0) {
+      levels[task.id] = 0;
+      return 0;
+    }
+    visiting.add(task.id);
+    const depLevels = task.depends_on.map((depId) => {
+      const dep = subtasks.find((s) => s.id === depId);
+      return dep ? getLevel(dep) : 0;
+    });
+    visiting.delete(task.id);
+    levels[task.id] = Math.max(...depLevels) + 1;
+    return levels[task.id];
+  }
+
+  subtasks.forEach(getLevel);
+
+  const levelCounts = {};
+  for (const level of Object.values(levels)) {
+    levelCounts[level] = (levelCounts[level] || 0) + 1;
+  }
+  return Math.max(...Object.values(levelCounts), 1);
+}
+
+/**
+ * 최대 복잡도 추출
+ * @param {Array<{complexity?:string}>} subtasks
+ * @returns {"S" | "M" | "L" | "XL"}
+ */
+function getMaxComplexity(subtasks) {
+  const order = { S: 0, M: 1, L: 2, XL: 3 };
+  let max = 'S';
+  for (const s of subtasks) {
+    const complexity = normalizeComplexity(s.complexity);
+    if (order[complexity] > order[max]) max = complexity;
+  }
+  return max;
+}
+
+/**
+ * complexity 기본값 보정
+ * @param {string | undefined} complexity
+ * @returns {"S" | "M" | "L" | "XL"}
+ */
+function normalizeComplexity(complexity) {
+  return ['S', 'M', 'L', 'XL'].includes(complexity) ? complexity : 'M';
+}

package/hub/tools.mjs

@@ -472,7 +472,72 @@ export function createTools(store, router, hitl, pipe = null) {
       }),
     },
 
-    // ── 19. pipeline_list ──
+    // ── 19. pipeline_advance_gated (HITL 승인 게이트) ──
+    {
+      name: 'pipeline_advance_gated',
+      description: 'HITL 승인 게이트가 포함된 파이프라인 전이. 지정 단계로의 전이 전 사용자 승인을 요청하고, 승인 후 전이를 실행합니다. deadline 초과 시 default_action에 따라 자동 처리됩니다.',
+      inputSchema: {
+        type: 'object',
+        required: ['team_name', 'phase'],
+        properties: {
+          team_name: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+          phase: { type: 'string', enum: ['plan', 'prd', 'exec', 'verify', 'fix', 'complete', 'failed'] },
+          prompt: { type: 'string', description: '사용자에게 표시할 승인 요청 메시지' },
+          deadline_ms: { type: 'integer', minimum: 5000, maximum: 600000, default: 120000 },
+          default_action: { type: 'string', enum: ['timeout_continue', 'timeout_abort'], default: 'timeout_continue' },
+          requester_agent: { type: 'string', description: '요청자 에이전트 이름' },
+        },
+      },
+      handler: wrap('PIPELINE_ADVANCE_GATED_FAILED', (args) => {
+        ensurePipelineTable(store.db);
+        const pipeline = createPipeline(store.db, args.team_name);
+
+        // 전이 가능 여부 사전 확인
+        if (!pipeline.canAdvance(args.phase)) {
+          const current = pipeline.getState();
+          return {
+            ok: false,
+            error: {
+              code: 'TRANSITION_BLOCKED',
+              message: `전이 불가: ${current.phase} → ${args.phase}`,
+            },
+          };
+        }
+
+        // HITL 승인 요청 생성
+        const approvalPrompt = args.prompt || `파이프라인 ${args.team_name}: ${pipeline.getState().phase} → ${args.phase} 전이를 승인하시겠습니까?`;
+        const deadlineMs = args.deadline_ms || 120000;
+        const now = Date.now();
+
+        const hitlResult = hitl.requestHumanInput({
+          requester_agent: args.requester_agent || `pipeline:${args.team_name}`,
+          kind: 'approval',
+          prompt: approvalPrompt,
+          deadline_ms: now + deadlineMs,
+          default_action: args.default_action || 'timeout_continue',
+        });
+
+        if (!hitlResult.ok) {
+          return hitlResult;
+        }
+
+        return {
+          ok: true,
+          data: {
+            pending: true,
+            request_id: hitlResult.data.request_id,
+            team_name: args.team_name,
+            target_phase: args.phase,
+            current_phase: pipeline.getState().phase,
+            deadline_ms: now + deadlineMs,
+            default_action: args.default_action || 'timeout_continue',
+            message: `승인 대기 중. ID: ${hitlResult.data.request_id}. ${Math.round(deadlineMs / 1000)}초 후 ${args.default_action || 'timeout_continue'} 자동 실행.`,
+          },
+        };
+      }),
+    },
+
+    // ── 20. pipeline_list ──
     {
       name: 'pipeline_list',
       description: '활성 파이프라인 목록을 조회합니다',

package/hud/hud-qos-status.mjs

@@ -1046,15 +1046,15 @@ function expireStaleCodexBuckets(buckets) {
 // ============================================================================
 // Codex 세션 JSONL에서 실제 rate limits 추출
 // 한계: rate_limits는 세션별 스냅샷이므로 여러 세션 간 토큰 합산은 불가.
-// 오늘 날짜의 모든 세션 파일을 스캔해 가장 최신 rate_limits 버킷을 수집한다.
-// (단일 파일 즉시 return 방식에서 → 당일 전체 스캔 후 최신 데이터 우선 병합으로 변경)
+// 최근 7일간 세션 파일을 스캔해 가장 최신 rate_limits 버킷을 수집한다.
+// 합성 버킷(token_count 기반)은 2일 이내 데이터만 허용하여 stale 방지.
 // ============================================================================
 function getCodexRateLimits() {
   const now = new Date();
-  let syntheticBucket = null; // 오늘 token_count에서 합성 (행 활성화 + 토큰 데이터용)
+  let syntheticBucket = null; // 최근 token_count에서 합성 (행 활성화 + 토큰 데이터용)
 
-  // 2일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
-  for (let dayOffset = 0; dayOffset <= 1; dayOffset++) {
+  // 7일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
+  for (let dayOffset = 0; dayOffset <= 6; dayOffset++) {
     const d = new Date(now.getTime() - dayOffset * 86_400_000);
     const sessDir = join(
       homedir(), ".codex", "sessions",
@@ -1086,8 +1086,8 @@ function getCodexRateLimits() {
                 contextWindow: evt.payload?.info?.model_context_window,
                 timestamp: evt.timestamp,
               };
-            } else if (dayOffset === 0 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
-              // 오늘 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용)
+            } else if (dayOffset <= 1 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
+              // 2일 이내 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용, stale 방지)
               syntheticBucket = {
                 limitId: "codex", limitName: "codex-session",
                 primary: null, secondary: null,
@@ -1102,7 +1102,7 @@ function getCodexRateLimits() {
         }
       } catch { /* 파일 읽기 실패 무시 */ }
     }
-    // 실제 rate_limits 발견 → 오늘 토큰 데이터 병합 후 즉시 반환
+    // 실제 rate_limits 발견 → 토큰 데이터 병합 후 즉시 반환
     if (Object.keys(mergedBuckets).length > 0) {
       if (syntheticBucket) {
         const main = mergedBuckets.codex || mergedBuckets[Object.keys(mergedBuckets)[0]];

package/package.json

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

package/scripts/lib/mcp-filter.mjs

@@ -127,6 +127,31 @@ const PROFILE_DEFINITIONS = Object.freeze({
   }),
 });
 
+/**
+ * 파이프라인 단계별 MCP 서버/도구 제한 (post-filter).
+ * role-based 프로필 위에 추가 적용. 빈 배열 = 전체 차단, 미정의 = 제한 없음.
+ */
+export const PHASE_OVERRIDES = Object.freeze({
+  plan: Object.freeze({
+    description: '계획 단계: 읽기 전용 탐색만 허용',
+    allowedServers: Object.freeze(['context7']),
+    blockedServers: Object.freeze(['playwright', 'tavily', 'exa']),
+  }),
+  prd: Object.freeze({
+    description: 'PRD 단계: 읽기 전용 탐색 + 문서 조회',
+    allowedServers: Object.freeze(['context7', 'brave-search']),
+    blockedServers: Object.freeze(['playwright']),
+  }),
+  exec: Object.freeze({
+    description: '실행 단계: 프로필 기반 전체 허용 (제한 없음)',
+  }),
+  verify: Object.freeze({
+    description: '검증 단계: 읽기 전용 + 분석 도구',
+    allowedServers: Object.freeze(['context7', 'brave-search', 'exa']),
+    blockedServers: Object.freeze(['playwright']),
+  }),
+});
+
 export const LEGACY_PROFILE_ALIASES = Object.freeze({
   implement: 'executor',
   analyze: 'analyze',
@@ -553,13 +578,23 @@ export function buildMcpPolicy(options = {}) {
   const inventoryIndex = buildInventoryIndex(inventory);
   const resolvedOptions = { ...options, inventory, inventoryIndex };
   const resolvedProfile = resolveMcpProfile(options.agentType, options.requestedProfile);
-  const allowedServers = resolveAllowedServers(resolvedOptions);
+  let allowedServers = resolveAllowedServers(resolvedOptions);
   const hint = buildPromptHint(resolvedOptions);
+
+  // Phase-aware post-filter: 파이프라인 단계별 서버 제한 적용
+  const phase = options.phase;
+  const phaseOverride = phase && PHASE_OVERRIDES[phase];
+  if (phaseOverride && phaseOverride.blockedServers) {
+    const blocked = new Set(phaseOverride.blockedServers);
+    allowedServers = allowedServers.filter((s) => !blocked.has(s));
+  }
+
   return {
     requestedProfile: typeof options.requestedProfile === 'string' && options.requestedProfile
       ? options.requestedProfile
       : 'auto',
     resolvedProfile,
+    resolvedPhase: phase || null,
     allowedServers,
     hint,
     geminiAllowedServers: getGeminiAllowedServers(resolvedOptions),
@@ -577,14 +612,18 @@ function shellArray(name, values) {
 }
 
 export function toShellExports(policy) {
-  return [
+  const lines = [
     `MCP_PROFILE_REQUESTED=${shellEscape(policy.requestedProfile)}`,
     `MCP_RESOLVED_PROFILE=${shellEscape(policy.resolvedProfile)}`,
     `MCP_HINT=${shellEscape(policy.hint)}`,
     shellArray('GEMINI_ALLOWED_SERVERS', policy.geminiAllowedServers),
     shellArray('CODEX_CONFIG_FLAGS', policy.codexConfigOverrides.flatMap((override) => ['-c', override])),
     `CODEX_CONFIG_JSON=${shellEscape(JSON.stringify(policy.codexConfig))}`,
-  ].join('\n');
+  ];
+  if (policy.resolvedPhase) {
+    lines.push(`MCP_PIPELINE_PHASE=${shellEscape(policy.resolvedPhase)}`);
+  }
+  return lines.join('\n');
 }
 
 function parseCliArgs(argv) {
@@ -636,6 +675,9 @@ function parseCliArgs(argv) {
       case '--worker-index':
         args.workerIndex = Number.parseInt(next(), 10);
         break;
+      case '--phase':
+        args.phase = next();
+        break;
       default:
         throw new Error(`알 수 없는 옵션: ${token}`);
     }

package/skills/tfx-auto/SKILL.md

@@ -32,14 +32,20 @@ argument-hint: "<command|task> [args...]"
 > 2. **비용**: Codex 우선 → Gemini → Claude 최후 수단. `claude` 선택 전 "Codex로 가능한가?" 재확인.
 > 3. **DAG**: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. `.omc/context/{sid}/` 생성, context_output 저장, 실패 시 후속 SKIP.
 > 4. **트리아지**: Codex `--full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
+> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
 
 ## 모드
 
 | 입력 형식 | 모드 | 트리아지 |
 |-----------|------|----------|
-| `/implement JWT 추가` | 커맨드 숏컷 | 없음 (즉시 실행) |
-| `/tfx-auto "리팩터링 + UI"` | 자동 | Codex 분류 → Opus 분해 |
-| `/tfx-auto 3:codex "리뷰"` | 수동 | Opus 분해만 |
+| `/implement JWT 추가` | 커맨드 숏컷 (quick) | 없음 (즉시 실행) |
+| `/tfx-auto "리팩터링 + UI"` | 자동 (quick) | Codex 분류 → Opus 분해 |
+| `/tfx-auto -t "리팩터링 + UI"` | 자동 (thorough) | Codex 분류 → Opus 분해 → Pipeline |
+| `/tfx-auto --thorough "리팩터링"` | 자동 (thorough) | `-t` 동일 |
+| `/tfx-auto 3:codex "리뷰"` | 수동 (quick) | Opus 분해만 |
+
+> **tfx-auto는 `--quick`이 기본.** 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문.
+> 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(`--thorough`)이 적용된다.
 
 ## 커맨드 숏컷
 
@@ -100,25 +106,77 @@ argument-hint: "<command|task> [args...]"
 
 **수동 모드 (`N:agent_type`):** Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.
 
+## --thorough 모드
+
+`-t` 또는 `--thorough` 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.
+
+```
+분기점은 "실행 전략"이지 "계획"이 아님:
+
+TRIAGE
+  │
+  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
+  │                                                      │
+  │                                      ┌───────────────┤
+  │                                      │               │
+  │                                  [1 task]        [2+ tasks]
+  │                                      │               │
+  │                                  AUTO 직접 실행   TEAM EXEC (multi Phase 3)
+  │                                      │               │
+  │                                      └───────┬───────┘
+  │                                              │
+  │                                          VERIFY → FIX loop → COMPLETE
+  │
+  └─ [quick] → [1 task] → fire-and-forget
+               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
+```
+
+### 단일 태스크 thorough
+
+1. `Bash("node hub/bridge.mjs pipeline-init --team ${sid}")` — 파이프라인 초기화 (phase: plan)
+2. Plan: Codex architect → 결과를 `pipeline.writePlanFile()` 저장
+3. PRD: Codex analyst → acceptance criteria 확정
+4. `pipeline_advance_gated` → [Approval Gate] → 사용자 승인 대기
+5. Exec: tfx-auto 직접 실행 (아래 "실행" 섹션)
+6. Verify: Codex verifier → 검증
+7. 실패 시 Fix loop (최대 3회) → Exec 재실행
+8. Complete
+
+### 멀티 태스크 thorough
+
+Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
+서브태스크 배열 + `thorough: true` 신호를 함께 전달하여 multi 측에서 verify/fix를 수행.
+
 ## 멀티 태스크 라우팅 (트리아지 후)
 
-> **트리아지 결과 서브태스크가 2개 이상이면 tfx-multi Native Teams 모드로 자동 전환한다.**
+> **트리아지 결과에 따라 실행 경로 결정.**
 
-| 서브태스크 수 | 실행 경로 | 이유 |
-|--------------|----------|------|
-| 1개 | tfx-auto 직접 실행 (아래 "실행" 섹션) | 팀 오버헤드 불필요, 경량 fire-and-forget |
-| 2개+ | **tfx-multi Phase 3** (TeamCreate → TaskCreate → Agent 래퍼) | Shift+Down 네비게이션, 상태 추적, fallback |
+| 조건 | 실행 경로 | 이유 |
+|------|----------|------|
+| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | 팀 오버헤드 불필요 |
+| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | plan→exec→verify 단일 경로 |
+| 2개+ + quick | tfx-multi Phase 3 (TeamCreate 직행) | Shift+Down, 상태 추적 |
+| 2개+ + thorough | Plan/PRD/Approval 후 → tfx-multi Phase 3 + verify/fix | 전체 파이프라인 |
 
-**전환 방법:** 트리아지 완료 후 서브태스크 배열을 그대로 tfx-multi Phase 3에 전달한다.
-tfx-multi의 Phase 2(트리아지)는 건너뛰고 Phase 3a(TeamCreate)부터 시작한다.
+**전환 방법:** 트리아지 완료 후 서브태스크 배열 + thorough 플래그를 tfx-multi Phase 3에 전달.
+tfx-multi의 Phase 2(트리아지)는 건너뛰고, thorough 시 Phase 2.5-2.6도 건너뛴다 (auto에서 이미 수행).
 
 ```
+thorough = args에 -t 또는 --thorough 포함
+
 if subtasks.length >= 2:
-  → tfx-multi Phase 3 실행 (트리아지 결과 재사용)
-  → TeamCreate → TaskCreate × N → Agent 래퍼 spawn (Phase 3a~3c)
-  → Phase 4 결과 수집 → Phase 5 정리
+  if thorough:
+    → Pipeline init → Plan → PRD → Approval (tfx-auto에서 수행)
+    → tfx-multi Phase 3 실행 ({ subtasks, thorough: true })
+    → Phase 3.5 verify → Phase 3.6 fix loop → Phase 5 정리
+  else:
+    → tfx-multi Phase 3 실행 ({ subtasks, thorough: false })
+    → Phase 4 결과 수집 → Phase 5 정리
 else:
-  → tfx-auto 직접 실행 (아래)
+  if thorough:
+    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
+  else:
+    → tfx-auto 직접 실행 (아래)
 ```
 
 ## 실행

package/skills/tfx-multi/SKILL.md

@@ -11,7 +11,7 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 > Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
 > Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,
 > 실제 작업은 `tfx-route.sh`가 수행한다. task 상태는 `team_task_list`를 truth source로 검증한다.
-> v3 — `--quick`(기본) + `--thorough`(전체 파이프라인: plan→prd→exec→verify→fix loop).
+> v3 — `--thorough`(기본: plan→prd→exec→verify→fix loop) + `--quick`(경량 모드).
 
 > **Lead 고토큰 MCP 직접 사용 금지**
 > Lead(Claude Opus)는 웹 서치(brave-search, exa, tavily), 외부 서비스(Notion, Jira/Confluence, Calendar, Gmail),
@@ -21,8 +21,8 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 ## 사용법
 
 ```
-/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"           # --quick (기본)
-/tfx-multi --thorough "인증 리팩터링 + UI 개선 + 보안 리뷰"  # 전체 파이프라인
+/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"           # --thorough (기본)
+/tfx-multi --quick "인증 리팩터링 + UI 개선 + 보안 리뷰"    # 경량 모드 (plan/verify 생략)
 /tfx-multi --agents codex,gemini "프론트+백엔드"
 /tfx-multi --tmux "작업"         # 레거시 tmux 모드
 /tfx-multi status
@@ -48,11 +48,17 @@ preflight와 Agent 생성을 병렬로 실행하여 사용자 체감 지연을
 ```
 ""(빈 문자열)          → 사용자에게 작업 입력 요청
 "3:codex 리뷰"         → 수동 모드: N=3, agent=codex
-"인증 + UI + 테스트"    → 자동 모드: Codex 분류 → Opus 분해
+"인증 + UI + 테스트"    → 자동 모드 (--thorough 기본): Codex 분류 → Opus 분해 → Pipeline
+"--quick 인증 + UI"    → 경량 모드: plan/verify 생략, 즉시 실행
 "--tmux 인증 + UI"     → Phase 3-mux 분기
 "status" / "stop"      → Bash("node bin/triflux.mjs multi {cmd}") 직행
 ```
 
+**모드 결정:**
+- `--quick` 명시 → quick 모드 (Phase 2.5-2.6, 3.5-3.7 생략)
+- `--thorough` 명시 또는 플래그 없음 → thorough 모드 (기본, 전체 파이프라인)
+- 커맨드 숏컷 (tfx-auto 경유 단일 실행) → quick 유지 (오버헤드 불필요)
+
 ### Phase 2: 트리아지 (tfx-auto와 동일)
 
 **자동 모드:**
@@ -62,9 +68,9 @@ preflight와 Agent 생성을 병렬로 실행하여 사용자 체감 지연을
 
 **수동 모드:** Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
 
-### Phase 2.5–2.6 + 3.5–3.7: `--thorough` 파이프라인
+### Phase 2.5–2.6 + 3.5–3.7: 파이프라인 (기본)
 
-> `--quick`(기본)에서는 건너뛴다. `--thorough` 모드에서만 실행.
+> `--thorough`(기본) 모드에서 실행된다. `--quick` 플래그 시 건너뛴다.
 > 상세는 → [`references/thorough-pipeline.md`](references/thorough-pipeline.md) 참조.
 
 ### Phase 3: Native Teams 실행

package/skills/tfx-multi/references/thorough-pipeline.md

@@ -1,24 +1,63 @@
-# --thorough 파이프라인 상세
+# 파이프라인 상세 (thorough 기본)
 
-> `--quick`(기본) 모드에서는 이 파일의 내용이 적용되지 않는다.
-> `--thorough` 모드에서만 Phase 2.5-2.6과 Phase 3.5-3.7이 실행된다.
+> `--thorough`(기본) 모드에서 Phase 2.5-2.6과 Phase 3.5-3.7이 실행된다.
+> `--quick` 플래그 시 이 파일의 내용은 적용되지 않는다.
+> tfx-auto 경유 시: `-t`/`--thorough` 플래그가 있을 때만 파이프라인이 활성화된다.
 
-## Phase 2.5: Plan (Codex architect)
+## Phase 2.5: Plan (Opus Lead + Codex Scout 협업)
 
-1. Hub pipeline 초기화:
-   ```bash
-   Bash("node hub/bridge.mjs pipeline-advance --team ${teamName} --status plan")
-   ```
-   — 또는 createPipeline(db, teamName) 직접 호출
-2. Codex architect로 작업 분석 + 접근법 설계:
-   ```bash
-   bash ~/.claude/scripts/tfx-route.sh architect "${task}" analyze
-   ```
-3. 결과를 파이프라인 artifact에 저장:
-   ```
-   pipeline.setArtifact('plan_path', planOutputPath)
-   ```
-4. pipeline advance: plan → prd
+> 기존: Codex architect(단독, one-shot)
+> 변경: Opus 설계 주도 + Codex scout(병렬 탐색) → 합산 판단 → 최종 계획
+
+### Step 2.5.1: Opus 과제 분석 → 탐색 목록 생성
+
+Lead(Opus)가 과제를 분석하고, 설계에 필요한 정보 탐색 목록을 인라인 생성한다:
+
+```json
+{
+  "questions": [
+    { "id": "q1", "question": "현재 인증 미들웨어 구조와 세션 관리 방식", "scope": "src/middleware/auth*" },
+    { "id": "q2", "question": "DB 스키마와 마이그레이션 현황", "scope": "db/migrations/" }
+  ]
+}
+```
+
+탐색 목록은 3-7개 항목 권장. 과도하면 Codex 비용이 아닌 Lead 컨텍스트가 팽창.
+
+### Step 2.5.2: Codex Scout 병렬 파견
+
+각 탐색 항목마다 Codex scout를 파견하여 코드베이스 탐색:
+
+```bash
+# 각 question마다 병렬 실행
+for each question:
+  bash ~/.claude/scripts/tfx-route.sh scientist "${question.question}. 탐색 범위: ${question.scope}" analyze
+```
+
+**scout 실행 규칙:**
+- scout는 **read-only** — 코드 수정 금지, 탐색+보고만
+- 병렬 실행 (run_in_background=true)
+- scope 힌트로 탐색 범위를 제한하여 정확도 향상
+- MCP 프로필: `analyze` (읽기 전용 도구만)
+- 팀 모드 시: slim wrapper Agent로 spawn (Shift+Down 네비게이션)
+- 단일 모드 시: tfx-route.sh 직접 호출
+
+### Step 2.5.3: Opus 종합 판단 → 최종 계획 작성
+
+Lead(Opus)가 scout 보고를 종합하고, 전략적 설계 결정을 내린다:
+
+1. scout 결과 수집 (모든 scout 완료 대기)
+2. 아키텍처 선택, 트레이드오프 판단, 리스크 평가
+3. 최종 계획 작성
+4. `pipeline.writePlanFile(planContent)` 저장
+5. pipeline advance: plan → prd
+
+### Step 2.5.4: 추가 질의 루프 (선택)
+
+계획 작성 중 추가 정보 필요 시:
+- 팀 모드: 피드백 루프(Phase 0 구현)를 활용하여 scout에 "재실행:" 메시지 전송
+- 단일 모드: 추가 tfx-route.sh 호출
+- maxIterations 내에서 반복 가능 (기본 2회)
 
 ## Phase 2.6: PRD (Codex analyst)