triflux 3.2.0-dev.11 → 3.2.0-dev.12

package/hooks/hooks.json

@@ -24,6 +24,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pipeline-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/pipeline-stop.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// hooks/pipeline-stop.mjs — 파이프라인 진행 중 세션 중단 시 지속 프롬프트 주입
+//
+// Claude Code의 Stop 이벤트에서 실행.
+// 비터미널 단계의 파이프라인이 있으면 "작업 계속" 프롬프트를 반환한다.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const HUB_DB_PATH = join(homedir(), '.claude', 'cache', 'tfx-hub', 'state.db');
+const TERMINAL = new Set(['complete', 'failed']);
+
+async function getPipelineStopPrompt() {
+  if (!existsSync(HUB_DB_PATH)) return null;
+
+  try {
+    const { default: Database } = await import('better-sqlite3');
+    const { ensurePipelineTable, listPipelineStates } = await import(
+      join(process.env.CLAUDE_PLUGIN_ROOT || '.', 'hub', 'pipeline', 'state.mjs')
+    );
+
+    const db = new Database(HUB_DB_PATH, { readonly: true });
+    ensurePipelineTable(db);
+    const states = listPipelineStates(db);
+    db.close();
+
+    // 비터미널 단계의 활성 파이프라인 찾기
+    const active = states.filter((s) => !TERMINAL.has(s.phase));
+    if (active.length === 0) return null;
+
+    const lines = active.map((s) =>
+      `- 팀 ${s.team_name}: ${s.phase} 단계 (fix: ${s.fix_attempt}/${s.fix_max}, ralph: ${s.ralph_iteration}/${s.ralph_max})`
+    );
+
+    return `[tfx-multi 파이프라인 진행 중]
+활성 파이프라인이 있습니다:
+${lines.join('\n')}
+
+파이프라인을 이어서 진행하려면 /tfx-multi status 로 상태를 확인하세요.`;
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const prompt = await getPipelineStopPrompt();
+  if (prompt) {
+    // hook 출력으로 지속 프롬프트 전달
+    console.log(prompt);
+  }
+} catch {
+  // stop 훅 실패는 무시
+}

package/hub/bridge.mjs

@@ -304,27 +304,41 @@ async function cmdDeregister(args) {
 }
 
 async function cmdTeamInfo(args) {
-  const result = await post('/bridge/team/info', {
+  const body = {
     team_name: args.team,
     include_members: true,
     include_paths: true,
-  });
-  console.log(JSON.stringify(result || { ok: false, reason: 'hub_unavailable' }));
+  };
+  const result = await post('/bridge/team/info', body);
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — nativeProxy 직접 호출
+  const { teamInfo } = await import('./team/nativeProxy.mjs');
+  console.log(JSON.stringify(teamInfo(body)));
 }
 
 async function cmdTeamTaskList(args) {
-  const result = await post('/bridge/team/task-list', {
+  const body = {
     team_name: args.team,
     owner: args.owner,
     statuses: args.statuses ? args.statuses.split(',').map((status) => status.trim()).filter(Boolean) : [],
     include_internal: !!args['include-internal'],
     limit: parseInt(args.limit || '200', 10),
-  });
-  console.log(JSON.stringify(result || { ok: false, reason: 'hub_unavailable' }));
+  };
+  const result = await post('/bridge/team/task-list', body);
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — nativeProxy 직접 호출
+  const { teamTaskList } = await import('./team/nativeProxy.mjs');
+  console.log(JSON.stringify(teamTaskList(body)));
 }
 
 async function cmdTeamTaskUpdate(args) {
-  const result = await post('/bridge/team/task-update', {
+  const body = {
     team_name: args.team,
     task_id: args['task-id'],
     claim: !!args.claim,
@@ -338,20 +352,95 @@ async function cmdTeamTaskUpdate(args) {
     metadata_patch: args['metadata-patch'] ? parseJsonSafe(args['metadata-patch'], null) : undefined,
     if_match_mtime_ms: args['if-match-mtime-ms'] != null ? Number(args['if-match-mtime-ms']) : undefined,
     actor: args.actor,
-  });
-  console.log(JSON.stringify(result || { ok: false, reason: 'hub_unavailable' }));
+  };
+  const result = await post('/bridge/team/task-update', body);
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — nativeProxy 직접 호출
+  const { teamTaskUpdate } = await import('./team/nativeProxy.mjs');
+  console.log(JSON.stringify(teamTaskUpdate(body)));
 }
 
 async function cmdTeamSendMessage(args) {
-  const result = await post('/bridge/team/send-message', {
+  const body = {
     team_name: args.team,
     from: args.from,
     to: args.to || 'team-lead',
     text: args.text,
     summary: args.summary,
     color: args.color || 'blue',
+  };
+  const result = await post('/bridge/team/send-message', body);
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — nativeProxy 직접 호출
+  const { teamSendMessage } = await import('./team/nativeProxy.mjs');
+  console.log(JSON.stringify(teamSendMessage(body)));
+}
+
+function getHubDbPath() {
+  return join(homedir(), '.claude', 'cache', 'tfx-hub', 'state.db');
+}
+
+async function cmdPipelineState(args) {
+  // HTTP 우선
+  const result = await post('/bridge/pipeline/state', { team_name: args.team });
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — 직접 SQLite 접근
+  try {
+    const { default: Database } = await import('better-sqlite3');
+    const { ensurePipelineTable, readPipelineState } = await import('./pipeline/state.mjs');
+    const dbPath = getHubDbPath();
+    if (!existsSync(dbPath)) {
+      console.log(JSON.stringify({ ok: false, error: 'hub_db_not_found' }));
+      return;
+    }
+    const db = new Database(dbPath, { readonly: true });
+    ensurePipelineTable(db);
+    const state = readPipelineState(db, args.team);
+    db.close();
+    console.log(JSON.stringify(state
+      ? { ok: true, data: state }
+      : { ok: false, error: 'pipeline_not_found' }));
+  } catch (e) {
+    console.log(JSON.stringify({ ok: false, error: e.message }));
+  }
+}
+
+async function cmdPipelineAdvance(args) {
+  // HTTP 우선
+  const result = await post('/bridge/pipeline/advance', {
+    team_name: args.team,
+    phase: args.status, // --status를 phase로 재활용
   });
-  console.log(JSON.stringify(result || { ok: false, reason: 'hub_unavailable' }));
+  if (result) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  // Hub 미실행 fallback — 직접 SQLite 접근
+  try {
+    const { default: Database } = await import('better-sqlite3');
+    const { createPipeline } = await import('./pipeline/index.mjs');
+    const dbPath = getHubDbPath();
+    if (!existsSync(dbPath)) {
+      console.log(JSON.stringify({ ok: false, error: 'hub_db_not_found' }));
+      return;
+    }
+    const db = new Database(dbPath);
+    const pipeline = createPipeline(db, args.team);
+    const advanceResult = pipeline.advance(args.status);
+    db.close();
+    console.log(JSON.stringify(advanceResult));
+  } catch (e) {
+    console.log(JSON.stringify({ ok: false, error: e.message }));
+  }
 }
 
 async function cmdPing() {
@@ -397,9 +486,11 @@ export async function main(argv = process.argv.slice(2)) {
     case 'team-task-list': await cmdTeamTaskList(args); break;
     case 'team-task-update': await cmdTeamTaskUpdate(args); break;
     case 'team-send-message': await cmdTeamSendMessage(args); break;
+    case 'pipeline-state': await cmdPipelineState(args); break;
+    case 'pipeline-advance': await cmdPipelineAdvance(args); break;
     case 'ping': await cmdPing(args); break;
     default:
-      console.error('사용법: bridge.mjs <register|result|context|deregister|team-info|team-task-list|team-task-update|team-send-message|ping> [--옵션]');
+      console.error('사용법: bridge.mjs <register|result|context|deregister|team-info|team-task-list|team-task-update|team-send-message|pipeline-state|pipeline-advance|ping> [--옵션]');
       process.exit(1);
   }
 }

package/hub/pipeline/index.mjs

@@ -0,0 +1,121 @@
+// hub/pipeline/index.mjs — 파이프라인 매니저
+//
+// 상태(state.mjs) + 전이(transitions.mjs) 통합 인터페이스
+
+import { canTransition, transitionPhase, ralphRestart, TERMINAL } from './transitions.mjs';
+import {
+  ensurePipelineTable,
+  initPipelineState,
+  readPipelineState,
+  updatePipelineState,
+  removePipelineState,
+} from './state.mjs';
+
+/**
+ * 파이프라인 매니저 생성
+ * @param {object} db - better-sqlite3 인스턴스 (store.db)
+ * @param {string} teamName
+ * @param {object} opts - { fix_max?, ralph_max? }
+ * @returns {object} 파이프라인 API
+ */
+export function createPipeline(db, teamName, opts = {}) {
+  ensurePipelineTable(db);
+
+  // 기존 상태가 있으면 로드, 없으면 초기화
+  let state = readPipelineState(db, teamName);
+  if (!state) {
+    state = initPipelineState(db, teamName, opts);
+  }
+
+  return {
+    /**
+     * 현재 상태 조회
+     */
+    getState() {
+      state = readPipelineState(db, teamName) || state;
+      return { ...state };
+    },
+
+    /**
+     * 다음 단계로 전이 가능 여부
+     * @param {string} phase
+     */
+    canAdvance(phase) {
+      const current = readPipelineState(db, teamName);
+      return current ? canTransition(current.phase, phase) : false;
+    },
+
+    /**
+     * 다음 단계로 전이
+     * @param {string} nextPhase
+     * @returns {{ ok: boolean, state?: object, error?: string }}
+     */
+    advance(nextPhase) {
+      const current = readPipelineState(db, teamName);
+      if (!current) {
+        return { ok: false, error: `파이프라인 없음: ${teamName}` };
+      }
+
+      const result = transitionPhase(current, nextPhase);
+      if (!result.ok) return result;
+
+      state = updatePipelineState(db, teamName, result.state);
+      return { ok: true, state: { ...state } };
+    },
+
+    /**
+     * ralph loop 재시작 (plan부터 다시)
+     * @returns {{ ok: boolean, state?: object, error?: string }}
+     */
+    restart() {
+      const current = readPipelineState(db, teamName);
+      if (!current) {
+        return { ok: false, error: `파이프라인 없음: ${teamName}` };
+      }
+
+      const result = ralphRestart(current);
+      if (!result.ok) return result;
+
+      state = updatePipelineState(db, teamName, result.state);
+      return { ok: true, state: { ...state } };
+    },
+
+    /**
+     * artifact 저장 (plan_path, prd_path, verify_report 등)
+     * @param {string} key
+     * @param {*} value
+     */
+    setArtifact(key, value) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return;
+      const artifacts = { ...(current.artifacts || {}), [key]: value };
+      state = updatePipelineState(db, teamName, { artifacts });
+    },
+
+    /**
+     * 터미널 상태 여부
+     */
+    isTerminal() {
+      const current = readPipelineState(db, teamName);
+      return current ? TERMINAL.has(current.phase) : true;
+    },
+
+    /**
+     * 파이프라인 초기화 (리셋)
+     */
+    reset() {
+      state = initPipelineState(db, teamName, opts);
+      return { ...state };
+    },
+
+    /**
+     * 파이프라인 삭제
+     */
+    remove() {
+      return removePipelineState(db, teamName);
+    },
+  };
+}
+
+export { ensurePipelineTable } from './state.mjs';
+export { PHASES, TERMINAL, ALLOWED, canTransition } from './transitions.mjs';

package/hub/pipeline/state.mjs

@@ -0,0 +1,164 @@
+// hub/pipeline/state.mjs — Hub SQLite 파이프라인 상태 저장/로드
+//
+// store.mjs의 기존 SQLite 연결(db)을 활용한다.
+// pipeline_state 테이블은 schema.sql에 정의.
+
+/**
+ * pipeline_state 테이블 초기화 (store.db에 없으면 생성)
+ * @param {object} db - better-sqlite3 인스턴스
+ */
+export function ensurePipelineTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS pipeline_state (
+      team_name TEXT PRIMARY KEY,
+      phase TEXT NOT NULL DEFAULT 'plan',
+      fix_attempt INTEGER DEFAULT 0,
+      fix_max INTEGER DEFAULT 3,
+      ralph_iteration INTEGER DEFAULT 0,
+      ralph_max INTEGER DEFAULT 10,
+      artifacts TEXT DEFAULT '{}',
+      phase_history TEXT DEFAULT '[]',
+      created_at INTEGER,
+      updated_at INTEGER
+    )
+  `);
+}
+
+const STATEMENTS = new WeakMap();
+
+function getStatements(db) {
+  let s = STATEMENTS.get(db);
+  if (s) return s;
+
+  s = {
+    get: db.prepare('SELECT * FROM pipeline_state WHERE team_name = ?'),
+    insert: db.prepare(`
+      INSERT INTO pipeline_state (team_name, phase, fix_attempt, fix_max, ralph_iteration, ralph_max, artifacts, phase_history, created_at, updated_at)
+      VALUES (@team_name, @phase, @fix_attempt, @fix_max, @ralph_iteration, @ralph_max, @artifacts, @phase_history, @created_at, @updated_at)
+    `),
+    update: db.prepare(`
+      UPDATE pipeline_state SET
+        phase = @phase,
+        fix_attempt = @fix_attempt,
+        fix_max = @fix_max,
+        ralph_iteration = @ralph_iteration,
+        ralph_max = @ralph_max,
+        artifacts = @artifacts,
+        phase_history = @phase_history,
+        updated_at = @updated_at
+      WHERE team_name = @team_name
+    `),
+    remove: db.prepare('DELETE FROM pipeline_state WHERE team_name = ?'),
+    list: db.prepare('SELECT * FROM pipeline_state ORDER BY updated_at DESC'),
+  };
+  STATEMENTS.set(db, s);
+  return s;
+}
+
+function parseRow(row) {
+  if (!row) return null;
+  return {
+    ...row,
+    artifacts: JSON.parse(row.artifacts || '{}'),
+    phase_history: JSON.parse(row.phase_history || '[]'),
+  };
+}
+
+function serializeState(state) {
+  return {
+    team_name: state.team_name,
+    phase: state.phase || 'plan',
+    fix_attempt: state.fix_attempt ?? 0,
+    fix_max: state.fix_max ?? 3,
+    ralph_iteration: state.ralph_iteration ?? 0,
+    ralph_max: state.ralph_max ?? 10,
+    artifacts: JSON.stringify(state.artifacts || {}),
+    phase_history: JSON.stringify(state.phase_history || []),
+    created_at: state.created_at ?? Date.now(),
+    updated_at: state.updated_at ?? Date.now(),
+  };
+}
+
+/**
+ * 파이프라인 상태 초기화 (새 파이프라인)
+ * @param {object} db - better-sqlite3 인스턴스
+ * @param {string} teamName
+ * @param {object} opts - { fix_max?, ralph_max? }
+ * @returns {object} 초기 상태
+ */
+export function initPipelineState(db, teamName, opts = {}) {
+  const S = getStatements(db);
+  const now = Date.now();
+  const state = {
+    team_name: teamName,
+    phase: 'plan',
+    fix_attempt: 0,
+    fix_max: opts.fix_max ?? 3,
+    ralph_iteration: 0,
+    ralph_max: opts.ralph_max ?? 10,
+    artifacts: {},
+    phase_history: [],
+    created_at: now,
+    updated_at: now,
+  };
+
+  // 기존 상태가 있으면 삭제 후 재생성
+  S.remove.run(teamName);
+  S.insert.run(serializeState(state));
+  return state;
+}
+
+/**
+ * 파이프라인 상태 조회
+ * @param {object} db - better-sqlite3 인스턴스
+ * @param {string} teamName
+ * @returns {object|null}
+ */
+export function readPipelineState(db, teamName) {
+  const S = getStatements(db);
+  return parseRow(S.get.get(teamName));
+}
+
+/**
+ * 파이프라인 상태 업데이트 (부분 패치)
+ * @param {object} db - better-sqlite3 인스턴스
+ * @param {string} teamName
+ * @param {object} patch - 업데이트할 필드
+ * @returns {object|null} 업데이트된 상태
+ */
+export function updatePipelineState(db, teamName, patch) {
+  const S = getStatements(db);
+  const current = parseRow(S.get.get(teamName));
+  if (!current) return null;
+
+  const merged = {
+    ...current,
+    ...patch,
+    team_name: teamName, // team_name 변경 불가
+    updated_at: Date.now(),
+  };
+
+  S.update.run(serializeState(merged));
+  return merged;
+}
+
+/**
+ * 파이프라인 상태 삭제
+ * @param {object} db - better-sqlite3 인스턴스
+ * @param {string} teamName
+ * @returns {boolean}
+ */
+export function removePipelineState(db, teamName) {
+  const S = getStatements(db);
+  return S.remove.run(teamName).changes > 0;
+}
+
+/**
+ * 활성 파이프라인 목록
+ * @param {object} db - better-sqlite3 인스턴스
+ * @returns {object[]}
+ */
+export function listPipelineStates(db) {
+  const S = getStatements(db);
+  return S.list.all().map(parseRow);
+}

package/hub/pipeline/transitions.mjs

@@ -0,0 +1,114 @@
+// hub/pipeline/transitions.mjs — 파이프라인 단계 전이 규칙
+//
+// plan → prd → exec → verify → complete/fix
+// fix → exec/verify/complete/failed
+// complete, failed = 터미널 상태
+
+export const PHASES = ['plan', 'prd', 'exec', 'verify', 'fix', 'complete', 'failed'];
+
+export const TERMINAL = new Set(['complete', 'failed']);
+
+export const ALLOWED = {
+  'plan':     ['prd'],
+  'prd':      ['exec'],
+  'exec':     ['verify'],
+  'verify':   ['fix', 'complete', 'failed'],
+  'fix':      ['exec', 'verify', 'complete', 'failed'],
+  'complete': [],
+  'failed':   [],
+};
+
+/**
+ * 전이 가능 여부 확인
+ * @param {string} from - 현재 단계
+ * @param {string} to - 다음 단계
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  const targets = ALLOWED[from];
+  if (!targets) return false;
+  return targets.includes(to);
+}
+
+/**
+ * 상태 전이 실행 — fix loop 바운딩 포함
+ * @param {object} state - 파이프라인 상태 객체
+ * @param {string} nextPhase - 다음 단계
+ * @returns {{ ok: boolean, state?: object, error?: string }}
+ */
+export function transitionPhase(state, nextPhase) {
+  const current = state.phase;
+
+  if (!canTransition(current, nextPhase)) {
+    return {
+      ok: false,
+      error: `전이 불가: ${current} → ${nextPhase}. 허용: [${(ALLOWED[current] || []).join(', ')}]`,
+    };
+  }
+
+  const next = { ...state, phase: nextPhase, updated_at: Date.now() };
+
+  // fix 단계 진입 시 attempt 증가 + 바운딩
+  if (nextPhase === 'fix') {
+    next.fix_attempt = (state.fix_attempt || 0) + 1;
+    if (next.fix_attempt > (state.fix_max || 3)) {
+      return {
+        ok: false,
+        error: `fix loop 초과: ${next.fix_attempt}/${state.fix_max || 3}회. ralph loop로 승격 필요.`,
+      };
+    }
+  }
+
+  // fix → exec 재진입 시 (fix 후 재실행)
+  if (current === 'fix' && nextPhase === 'exec') {
+    // fix_attempt 유지 (이미 fix 진입 시 증가됨)
+  }
+
+  // verify → fix → ... → verify 반복 후 fix_max 초과 시 ralph loop
+  if (nextPhase === 'failed' && current === 'fix') {
+    // ralph loop 반복 증가
+    next.ralph_iteration = (state.ralph_iteration || 0) + 1;
+    if (next.ralph_iteration > (state.ralph_max || 10)) {
+      // 최종 실패 — ralph loop도 초과
+      next.phase = 'failed';
+    }
+  }
+
+  // phase_history 기록
+  const history = Array.isArray(state.phase_history) ? [...state.phase_history] : [];
+  history.push({ from: current, to: nextPhase, at: Date.now() });
+  next.phase_history = history;
+
+  return { ok: true, state: next };
+}
+
+/**
+ * ralph loop 재시작 전이
+ * fix_max 초과 시 plan으로 돌아가며 ralph_iteration 증가
+ * @param {object} state - 현재 상태
+ * @returns {{ ok: boolean, state?: object, error?: string }}
+ */
+export function ralphRestart(state) {
+  const iteration = (state.ralph_iteration || 0) + 1;
+  if (iteration > (state.ralph_max || 10)) {
+    return {
+      ok: false,
+      error: `ralph loop 초과: ${iteration}/${state.ralph_max || 10}회. 최종 실패.`,
+    };
+  }
+
+  const history = Array.isArray(state.phase_history) ? [...state.phase_history] : [];
+  history.push({ from: state.phase, to: 'plan', at: Date.now(), ralph_restart: true });
+
+  return {
+    ok: true,
+    state: {
+      ...state,
+      phase: 'plan',
+      fix_attempt: 0,
+      ralph_iteration: iteration,
+      phase_history: history,
+      updated_at: Date.now(),
+    },
+  };
+}

package/hub/schema.sql

@@ -78,3 +78,17 @@ CREATE INDEX IF NOT EXISTS idx_inbox_message ON message_inbox(message_id);
 CREATE INDEX IF NOT EXISTS idx_human_requests_state ON human_requests(state);
 CREATE INDEX IF NOT EXISTS idx_agents_status ON agents(status);
 CREATE INDEX IF NOT EXISTS idx_agents_lease ON agents(lease_expires_ms);
+
+-- 파이프라인 상태 테이블 (Phase 2)
+CREATE TABLE IF NOT EXISTS pipeline_state (
+  team_name TEXT PRIMARY KEY,
+  phase TEXT NOT NULL DEFAULT 'plan',
+  fix_attempt INTEGER DEFAULT 0,
+  fix_max INTEGER DEFAULT 3,
+  ralph_iteration INTEGER DEFAULT 0,
+  ralph_max INTEGER DEFAULT 10,
+  artifacts TEXT DEFAULT '{}',
+  phase_history TEXT DEFAULT '[]',
+  created_at INTEGER,
+  updated_at INTEGER
+);

package/hub/server.mjs

@@ -14,6 +14,15 @@ import { createRouter } from './router.mjs';
 import { createHitlManager } from './hitl.mjs';
 import { createPipeServer } from './pipe.mjs';
 import { createTools } from './tools.mjs';
+import {
+  ensurePipelineTable,
+  createPipeline,
+} from './pipeline/index.mjs';
+import {
+  readPipelineState,
+  initPipelineState,
+  listPipelineStates,
+} from './pipeline/state.mjs';
 import {
   teamInfo,
   teamTaskList,
@@ -240,6 +249,41 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             res.writeHead(404);
             return res.end(JSON.stringify({ ok: false, error: `Unknown team endpoint: ${path}` }));
           }
+
+          // ── 파이프라인 엔드포인트 ──
+          if (path === '/bridge/pipeline/state' && req.method === 'POST') {
+            ensurePipelineTable(store.db);
+            const { team_name } = body;
+            const state = readPipelineState(store.db, team_name);
+            res.writeHead(state ? 200 : 404);
+            return res.end(JSON.stringify(state
+              ? { ok: true, data: state }
+              : { ok: false, error: 'pipeline_not_found' }));
+          }
+
+          if (path === '/bridge/pipeline/advance' && req.method === 'POST') {
+            ensurePipelineTable(store.db);
+            const { team_name, phase } = body;
+            const pipeline = createPipeline(store.db, team_name);
+            const result = pipeline.advance(phase);
+            res.writeHead(result.ok ? 200 : 400);
+            return res.end(JSON.stringify(result));
+          }
+
+          if (path === '/bridge/pipeline/init' && req.method === 'POST') {
+            ensurePipelineTable(store.db);
+            const { team_name, fix_max, ralph_max } = body;
+            const state = initPipelineState(store.db, team_name, { fix_max, ralph_max });
+            res.writeHead(200);
+            return res.end(JSON.stringify({ ok: true, data: state }));
+          }
+
+          if (path === '/bridge/pipeline/list' && req.method === 'POST') {
+            ensurePipelineTable(store.db);
+            const states = listPipelineStates(store.db);
+            res.writeHead(200);
+            return res.end(JSON.stringify({ ok: true, data: states }));
+          }
         }
 
         if (path === '/bridge/context' && req.method === 'POST') {

package/hub/team/native.mjs

@@ -33,12 +33,16 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     agentName = "",
     leadName = "team-lead",
     mcp_profile = "auto",
+    pipelinePhase = "",
   } = opts;
 
   // 셸 이스케이프
   const escaped = subtask.replace(/'/g, "'\\''");
+  const pipelineHint = pipelinePhase
+    ? `\n파이프라인 단계: ${pipelinePhase}`
+    : '';
 
-  return `Bash 1회 실행 후 반드시 종료하라. 어떤 경우에도 hang하지 마라.
+  return `Bash 1회 실행 후 반드시 종료하라. 어떤 경우에도 hang하지 마라.${pipelineHint}
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
 

package/hub/tools.mjs

@@ -8,16 +8,25 @@ import {
   teamTaskUpdate,
   teamSendMessage,
 } from './team/nativeProxy.mjs';
+import {
+  ensurePipelineTable,
+  createPipeline,
+} from './pipeline/index.mjs';
+import {
+  readPipelineState,
+  initPipelineState,
+  listPipelineStates,
+} from './pipeline/state.mjs';
 
 /**
  * MCP 도구 목록 생성
  * @param {object} store  — createStore() 반환
  * @param {object} router — createRouter() 반환
- * @param {object} hitl   — createHitlManager() 반환
- * @param {object} pipe   — createPipeServer() 반환
- * @returns {Array<{name, description, inputSchema, handler}>}
- */
-export function createTools(store, router, hitl, pipe = null) {
+ * @param {object} hitl   — createHitlManager() 반환
+ * @param {object} pipe   — createPipeServer() 반환
+ * @returns {Array<{name, description, inputSchema, handler}>}
+ */
+export function createTools(store, router, hitl, pipe = null) {
   /** 도구 핸들러 래퍼 — 에러 처리 + MCP content 형식 변환 */
   function wrap(code, fn) {
     return async (args) => {
@@ -49,10 +58,10 @@ export function createTools(store, router, hitl, pipe = null) {
           heartbeat_ttl_ms: { type: 'integer', minimum: 10000, maximum: 7200000 },
         },
       },
-      handler: wrap('REGISTER_FAILED', (args) => {
-        const data = router.registerAgent(args);
-        return { ok: true, data };
-      }),
+      handler: wrap('REGISTER_FAILED', (args) => {
+        const data = router.registerAgent(args);
+        return { ok: true, data };
+      }),
     },
 
     // ── 2. status ──
@@ -122,10 +131,10 @@ export function createTools(store, router, hitl, pipe = null) {
       }),
     },
 
-    // ── 5. poll_messages ──
-    {
-      name: 'poll_messages',
-      description: 'Deprecated. poll_messages 대신 Named Pipe subscribe/publish 채널을 사용합니다',
+    // ── 5. poll_messages ──
+    {
+      name: 'poll_messages',
+      description: 'Deprecated. poll_messages 대신 Named Pipe subscribe/publish 채널을 사용합니다',
       inputSchema: {
         type: 'object',
         required: ['agent_id'],
@@ -137,34 +146,34 @@ export function createTools(store, router, hitl, pipe = null) {
           ack_ids:        { type: 'array', items: { type: 'string' }, maxItems: 100 },
           auto_ack:       { type: 'boolean', default: false },
         },
-      },
-      handler: wrap('POLL_DEPRECATED', async (args) => {
-        const replay = router.drainAgent(args.agent_id, {
-          max_messages: args.max_messages,
-          include_topics: args.include_topics,
-          auto_ack: args.auto_ack,
-        });
-        if (args.ack_ids?.length) {
-          router.ackMessages(args.ack_ids, args.agent_id);
-        }
-        return {
-          ok: false,
-          error: {
-            code: 'POLL_DEPRECATED',
-            message: 'poll_messages는 deprecated 되었습니다. pipe subscribe/publish 채널을 사용하세요.',
-          },
-          data: {
-            pipe_path: pipe?.path || null,
-            delivery_mode: 'pipe_push',
-            protocol: 'ndjson',
-            replay: {
-              messages: replay,
-              count: replay.length,
-            },
-            server_time_ms: Date.now(),
-          },
-        };
-      }),
+      },
+      handler: wrap('POLL_DEPRECATED', async (args) => {
+        const replay = router.drainAgent(args.agent_id, {
+          max_messages: args.max_messages,
+          include_topics: args.include_topics,
+          auto_ack: args.auto_ack,
+        });
+        if (args.ack_ids?.length) {
+          router.ackMessages(args.ack_ids, args.agent_id);
+        }
+        return {
+          ok: false,
+          error: {
+            code: 'POLL_DEPRECATED',
+            message: 'poll_messages는 deprecated 되었습니다. pipe subscribe/publish 채널을 사용하세요.',
+          },
+          data: {
+            pipe_path: pipe?.path || null,
+            delivery_mode: 'pipe_push',
+            protocol: 'ndjson',
+            replay: {
+              messages: replay,
+              count: replay.length,
+            },
+            server_time_ms: Date.now(),
+          },
+        };
+      }),
     },
 
     // ── 6. handoff ──
@@ -325,5 +334,81 @@ export function createTools(store, router, hitl, pipe = null) {
         return teamSendMessage(args);
       }),
     },
+
+    // ── 13. pipeline_state ──
+    {
+      name: 'pipeline_state',
+      description: '파이프라인 상태를 조회합니다 (--thorough 모드)',
+      inputSchema: {
+        type: 'object',
+        required: ['team_name'],
+        properties: {
+          team_name: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+        },
+      },
+      handler: wrap('PIPELINE_STATE_FAILED', (args) => {
+        ensurePipelineTable(store.db);
+        const state = readPipelineState(store.db, args.team_name);
+        return state
+          ? { ok: true, data: state }
+          : { ok: false, error: { code: 'PIPELINE_NOT_FOUND', message: `파이프라인 없음: ${args.team_name}` } };
+      }),
+    },
+
+    // ── 14. pipeline_advance ──
+    {
+      name: 'pipeline_advance',
+      description: '파이프라인을 다음 단계로 전이합니다 (전이 규칙 + fix loop 바운딩 적용)',
+      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'] },
+        },
+      },
+      handler: wrap('PIPELINE_ADVANCE_FAILED', (args) => {
+        ensurePipelineTable(store.db);
+        const pipeline = createPipeline(store.db, args.team_name);
+        return pipeline.advance(args.phase);
+      }),
+    },
+
+    // ── 15. pipeline_init ──
+    {
+      name: 'pipeline_init',
+      description: '새 파이프라인을 초기화합니다 (기존 상태 덮어쓰기)',
+      inputSchema: {
+        type: 'object',
+        required: ['team_name'],
+        properties: {
+          team_name: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+          fix_max: { type: 'integer', minimum: 1, maximum: 20, default: 3 },
+          ralph_max: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
+        },
+      },
+      handler: wrap('PIPELINE_INIT_FAILED', (args) => {
+        ensurePipelineTable(store.db);
+        const state = initPipelineState(store.db, args.team_name, {
+          fix_max: args.fix_max,
+          ralph_max: args.ralph_max,
+        });
+        return { ok: true, data: state };
+      }),
+    },
+
+    // ── 16. pipeline_list ──
+    {
+      name: 'pipeline_list',
+      description: '활성 파이프라인 목록을 조회합니다',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+      handler: wrap('PIPELINE_LIST_FAILED', () => {
+        ensurePipelineTable(store.db);
+        return { ok: true, data: listPipelineStates(store.db) };
+      }),
+    },
   ];
 }

package/package.json

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

package/scripts/tfx-route.sh

@@ -226,8 +226,9 @@ route_agent() {
       CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
       CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=300; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     verifier)
-      CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
-      CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=300; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+      CLI_TYPE="codex"; CLI_CMD="codex"
+      CLI_ARGS="exec --profile thorough ${codex_base} review"
+      CLI_EFFORT="thorough"; DEFAULT_TIMEOUT=1200; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     test-engineer)
       CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
       CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=300; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;

package/skills/tfx-multi/SKILL.md

@@ -6,17 +6,18 @@ triggers:
 argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
 ---
 
-# tfx-multi v2.2 — 슬림 래퍼 + 네비게이션 복원 기반 멀티-CLI 팀 오케스트레이터
+# tfx-multi v3 — 파이프라인 기반 멀티-CLI 팀 오케스트레이터
 
 > Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
 > Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,
 > 실제 작업은 `tfx-route.sh`가 수행한다. task 상태는 `team_task_list`를 truth source로 검증한다.
-> v2.2 현재 — 슬림 래퍼 Agent로 Shift+Down 네비게이션 복원, Opus 토큰 77% 절감.
+> v3 — `--quick`(기본, v2.2 호환) + `--thorough`(전체 파이프라인: plan→prd→exec→verify→fix loop).
 
 ## 사용법
 
 ```
-/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"
+/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"           # --quick (기본)
+/tfx-multi --thorough "인증 리팩터링 + UI 개선 + 보안 리뷰"  # 전체 파이프라인
 /tfx-multi --agents codex,gemini "프론트+백엔드"
 /tfx-multi --tmux "작업"         # 레거시 tmux 모드
 /tfx-multi status
@@ -60,7 +61,7 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
   (`bin/triflux.mjs` 절대경로는 triflux 패키지 루트 기준)
 - 그 외 → Phase 2 트리아지
 
-**--tmux 감지:** 입력에 `--tmux`가 포함되면 Phase 3-tmux로 분기.
+**--tmux/--psmux 감지:** 입력에 `--tmux` 또는 `--psmux`가 포함되면 Phase 3-mux로 분기. psmux가 primary (Windows).
 
 ### Phase 2: 트리아지 (tfx-auto와 동일)
 
@@ -96,6 +97,32 @@ Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하
 
 Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
 
+### Phase 2.5–2.6: 파이프라인 Plan/PRD (`--thorough` 전용)
+
+> `--quick`(기본) 모드에서는 이 단계를 건너뛰고 Phase 3으로 직행한다.
+> `--thorough` 모드에서만 실행된다.
+
+```
+[--thorough 모드 감지]
+
+Phase 2.5: Plan (Codex architect)
+  1. Hub pipeline 초기화:
+     Bash("node hub/bridge.mjs pipeline-advance --team ${teamName} --status plan")
+     — 또는 createPipeline(db, teamName) 직접 호출
+  2. Codex architect로 작업 분석 + 접근법 설계:
+     bash ~/.claude/scripts/tfx-route.sh architect "${task}" analyze
+  3. 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('plan_path', planOutputPath)
+  4. pipeline advance: plan → prd
+
+Phase 2.6: PRD (Codex analyst)
+  1. Codex analyst로 수용 기준 확정:
+     bash ~/.claude/scripts/tfx-route.sh analyst "${task}" analyze
+  2. 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('prd_path', prdOutputPath)
+  3. pipeline advance: prd → exec
+```
+
 ### Phase 3: Native Teams 실행 (v2.1 개편)
 
 트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
@@ -212,6 +239,37 @@ Shift+Down으로 다음 워커 (마지막→리드 wrap), Shift+Tab으로 이전
 (Shift+Up은 Claude Code 미지원 — 대부분 터미널에서 scroll-up으로 먹힘)"
 ```
 
+### Phase 3.5–3.7: Verify/Fix Loop (`--thorough` 전용)
+
+> `--quick`(기본) 모드에서는 이 단계를 건너뛰고 Phase 4로 직행한다.
+> `--thorough` 모드에서만 실행된다.
+
+```
+Phase 3.5: Verify (Codex review)
+  1. pipeline advance: exec → verify
+  2. Codex verifier로 결과 검증:
+     bash ~/.claude/scripts/tfx-route.sh verifier "결과 검증: ${task}" review
+     — verifier는 Codex --profile thorough review로 실행됨
+  3. 검증 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('verify_report', verifyOutputPath)
+  4. 통과 → pipeline advance: verify → complete → Phase 5 (cleanup)
+  5. 실패 → Phase 3.6
+
+Phase 3.6: Fix (Codex executor, max 3회)
+  1. pipeline advance: verify → fix
+     — fix_attempt 자동 증가, fix_max(3) 초과 시 전이 거부
+  2. fix_attempt > fix_max → Phase 3.7 (ralph loop) 또는 failed 보고 → Phase 5
+  3. Codex executor로 실패 항목 수정:
+     bash ~/.claude/scripts/tfx-route.sh executor "실패 항목 수정: ${failedItems}" implement
+  4. pipeline advance: fix → exec (재실행)
+  5. → Phase 3 (exec) → Phase 3.5 (verify) 재실행
+
+Phase 3.7: Ralph Loop (fix 3회 초과 시)
+  1. ralph_iteration 증가 (pipeline.restart())
+  2. ralph_iteration > ralph_max(10) → 최종 failed → Phase 5
+  3. fix_attempt 리셋, 전체 파이프라인 재시작 (Phase 2.5 plan부터)
+```
+
 ### Phase 4: 결과 수집 (truth source = team_task_list)
 
 1. 리드가 Step 3c에서 실행한 모든 백그라운드 Bash 프로세스 완료를 대기한다.
@@ -254,9 +312,12 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
    ```
 5. 종합 보고서를 출력한다.
 
-### Phase 3-tmux: 레거시 tmux 모드
---tmux 플래그 시 기존 v1 방식으로 실행: Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")
-이후 사용자에게 tmux 세션 연결 안내.
+### Phase 3-mux: 레거시 psmux/tmux 모드
+`--tmux` 또는 `--psmux` 플래그 시 pane 기반 실행. `detectMultiplexer()`가 psmux → tmux → wsl-tmux → git-bash-tmux 순으로 자동 감지.
+Windows에서는 **psmux가 1순위** (ADR-001).
+
+Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")
+이후 사용자에게 세션 연결 안내.
 
 ## 에이전트 매핑
 > 에이전트 매핑: codex/gemini → tfx-route.sh, claude → Agent(subagent_type) 직접 실행. 상세는 Phase 3c/3d 참조.
@@ -266,14 +327,15 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
 - **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
 - **codex/gemini CLI** — 해당 에이전트 사용 시
 - **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
-- **Hub 활성 상태** — Named Pipe(`\\.\pipe\triflux-{pid}`) 우선, HTTP `127.0.0.1:27888` fallback. `bridge.mjs`가 자동 선택.
+- **Hub 활성 상태** — Named Pipe(`\\.\pipe\triflux-{pid}`) 우선, HTTP `127.0.0.1:27888` fallback. `bridge.mjs`가 자동 선택. Hub 미실행 시 nativeProxy fallback.
+- **멀티플렉서** — psmux(Windows 1순위) / tmux / wsl-tmux / git-bash-tmux 자동 감지 (`--tmux`/`--psmux` 모드)
 - **출력 정책** — preflight는 비동기/요약 출력이 기본이며, 실패 시에만 상세 출력
 
 ## 에러 처리
 
 | 에러 | 처리 |
 |------|------|
-| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
+| TeamCreate 실패 / Agent Teams 비활성 | `--psmux/--tmux` 폴백 (Phase 3-mux로 전환) |
 | tfx-route.sh 없음 | `tfx setup` 실행 안내 |
 | CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
 | Codex 분류 실패 | Opus 직접 분류+분해 |
@@ -292,5 +354,6 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
 | `scripts/tfx-route.sh` | 팀 통합 라우터 (`TFX_TEAM_*`, task claim/complete, send-message, Named Pipe/HTTP bridge) |
 | `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
 | `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
+| `hub/pipeline/` | 파이프라인 상태 기계 (transitions, state, index) — `--thorough` 모드 |
 | `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
 | `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |