triflux 10.0.0 → 10.0.2

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';

package/hub/pipeline/gates/selfcheck.mjs

@@ -0,0 +1,82 @@
+// hub/pipeline/gates/selfcheck.mjs — Post-Execution Self-Check (Hallucination Detection)
+//
+// exec → verify → [selfcheck] → complete/fix
+// 4대 필수 질문 + 7대 할루시네이션 Red Flag 탐지
+
+export const RED_FLAGS = [
+  { id: 'test_pass_no_output',  pattern: /테스트\s*(?:가\s*)?통과/,  label: '"테스트 통과" (출력 없이)' },
+  { id: 'everything_works',     pattern: /모든\s*게?\s*작동/,        label: '"모든게 작동" (증거 없이)' },
+  { id: 'no_changes_with_diff', pattern: /변경\s*(?:사항\s*)?없/,    label: '"변경 없음" (diff 있는데)' },
+  { id: 'backward_compatible',  pattern: /호환성\s*(?:이\s*)?유지/,  label: '"호환성 유지" (검증 없이)' },
+  { id: 'performance_improved', pattern: /성능\s*(?:이\s*)?개선/,    label: '"성능 개선" (벤치마크 없이)' },
+  { id: 'security_enhanced',    pattern: /보안\s*(?:이\s*)?강화/,    label: '"보안 강화" (증거 없이)' },
+  { id: 'error_handling_done',  pattern: /에러\s*처리\s*(?:가\s*)?완료/, label: '"에러 처리 완료" (catch 블록만)' },
+];
+
+export const QUESTIONS = [
+  { id: 'tests_passing',    label: '모든 테스트 통과?',   evidenceKey: 'testOutput' },
+  { id: 'requirements_met', label: '모든 요구사항 충족?', evidenceKey: 'requirementChecklist' },
+  { id: 'no_assumptions',   label: '검증 없는 가정?',    evidenceKey: 'references' },
+  { id: 'evidence_provided', label: '증거 있는가?',       evidenceKey: 'artifacts' },
+];
+
+/**
+ * Red Flag 스캔 — 텍스트에서 할루시네이션 패턴 탐지
+ * @param {string} text - 스캔 대상 텍스트
+ * @param {object} context - { hasDiff?, evidence? }
+ * @returns {Array<{ id: string, label: string }>}
+ */
+function detectRedFlags(text, context = {}) {
+  const flags = [];
+  const evidence = context.evidence || {};
+
+  for (const rf of RED_FLAGS) {
+    if (!rf.pattern.test(text)) continue;
+
+    // "변경 없음"은 실제 diff가 있을 때만 Red Flag
+    if (rf.id === 'no_changes_with_diff' && !context.hasDiff) continue;
+
+    // "테스트 통과"는 testOutput 증거가 없을 때만 Red Flag
+    if (rf.id === 'test_pass_no_output' && evidence.testOutput) continue;
+
+    // 기타 Red Flag는 해당 id의 반증이 있으면 스킵
+    if (evidence[rf.id]) continue;
+
+    flags.push({ id: rf.id, label: rf.label });
+  }
+
+  return flags;
+}
+
+/**
+ * Self-Check 실행
+ * @param {string|object} execResult - 실행 결과 (텍스트 또는 객체)
+ * @param {string|object} verifyResult - 검증 결과 (텍스트 또는 객체)
+ * @param {object} requirements - { hasDiff?, evidence? }
+ * @param {boolean} [requirements.hasDiff] - diff 존재 여부
+ * @param {object} [requirements.evidence] - { testOutput, requirementChecklist, references, artifacts }
+ * @returns {{ passed: boolean, score: number, flags: Array, checklist: Array }}
+ */
+export function runSelfCheck(execResult, verifyResult, requirements = {}) {
+  const normalize = (v) => typeof v === 'string' ? v : (v != null ? JSON.stringify(v) : '');
+  const text = [normalize(execResult), normalize(verifyResult)].join('\n');
+
+  const flags = detectRedFlags(text, requirements);
+
+  const evidence = requirements.evidence || {};
+  const checklist = QUESTIONS.map(q => {
+    const ev = evidence[q.evidenceKey];
+    const passed = ev != null && (typeof ev === 'string' ? ev.trim().length > 0 : true);
+    return { id: q.id, label: q.label, passed, evidence: ev || null };
+  });
+
+  const allQuestionsPassed = checklist.every(q => q.passed);
+  const passed = flags.length === 0 && allQuestionsPassed;
+
+  // 점수: 기본 100, Red Flag당 -15, 실패 질문당 -20
+  const flagPenalty = flags.length * 15;
+  const questionPenalty = checklist.filter(q => !q.passed).length * 20;
+  const score = Math.max(0, 100 - flagPenalty - questionPenalty);
+
+  return { passed, score, flags, checklist };
+}

package/hub/pipeline/index.mjs

@@ -0,0 +1,318 @@
+// hub/pipeline/index.mjs — 파이프라인 매니저
+//
+// 상태(state.mjs) + 전이(transitions.mjs) 통합 인터페이스
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+import { canTransition, transitionPhase, ralphRestart, TERMINAL } from './transitions.mjs';
+import {
+  ensurePipelineTable,
+  initPipelineState,
+  readPipelineState,
+  updatePipelineState,
+  removePipelineState,
+} from './state.mjs';
+import { runConfidenceCheck } from './gates/confidence.mjs';
+import { runSelfCheck } from './gates/selfcheck.mjs';
+import { classifyIntent as _classifyIntent } from '../intent.mjs';
+// deslop gate: 호출자가 scanDirectory/detectSlop 결과를 전달
+
+/**
+ * 파이프라인 매니저 생성
+ * @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 } };
+    },
+
+    /**
+     * DAG 컨텍스트를 파이프라인 상태에 저장
+     * @param {{ dag_width: number, levels: Record<number, string[]>, edges: Array<{from:string, to:string}>, max_complexity: string, taskResults: Record<string, *> }} dagContext
+     */
+    setDagContext(dagContext) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return;
+      const artifacts = { ...(current.artifacts || {}), dagContext };
+      state = updatePipelineState(db, teamName, { artifacts });
+    },
+
+    /**
+     * DAG 컨텍스트 조회 (편의 메서드)
+     * @returns {{ dag_width: number, levels: Record<number, string[]>, edges: Array<{from:string, to:string}>, max_complexity: string, taskResults: Record<string, *> } | null}
+     */
+    getDagContext() {
+      const current = readPipelineState(db, teamName) || state;
+      return current?.artifacts?.dagContext || null;
+    },
+
+    /**
+     * 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 });
+    },
+
+    /**
+     * 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;
+    },
+
+    /**
+     * 터미널 상태 여부
+     */
+    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);
+    },
+
+    /**
+     * Confidence Gate 실행 + 자동 전이
+     * prd → confidence → exec/failed
+     * @param {string|object} planArtifact
+     * @param {object} context - { checks?, codebaseFiles?, existingTests? }
+     * @returns {{ ok: boolean, gate: object, state?: object, error?: string }}
+     */
+    runConfidenceGate(planArtifact, context = {}) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return { ok: false, error: `파이프라인 없음: ${teamName}` };
+
+      if (current.phase !== 'confidence') {
+        return { ok: false, error: `confidence gate는 confidence 단계에서만 실행 가능 (현재: ${current.phase})` };
+      }
+
+      const gate = runConfidenceCheck(planArtifact, context);
+      this.setArtifact('confidence_result', gate);
+
+      if (gate.decision === 'abort') {
+        const result = this.advance('failed');
+        return { ok: true, gate, state: result.state };
+      }
+
+      // proceed 또는 alternative → exec로 전이
+      const result = this.advance('exec');
+      return { ok: result.ok, gate, state: result.state, error: result.error };
+    },
+
+    /**
+     * Deslop Gate 실행 + 자동 전이
+     * exec → deslop → verify
+     * 호출자가 미리 deslop 결과를 생성하여 전달.
+     * @param {object} [deslopResult] - scanDirectory() 또는 detectSlop() 결과
+     * @returns {{ ok: boolean, gate: object, state?: object, error?: string }}
+     */
+    runDeslopGate(deslopResult = null) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return { ok: false, error: `파이프라인 없음: ${teamName}` };
+
+      if (current.phase !== 'deslop') {
+        return { ok: false, error: `deslop gate는 deslop 단계에서만 실행 가능 (현재: ${current.phase})` };
+      }
+
+      const gate = deslopResult || { files: [], summary: { total: 0, clean: 0 } };
+      this.setArtifact('deslop_result', gate);
+
+      // deslop은 항상 verify로 전이 (정보 제공 게이트, 차단 없음)
+      const result = this.advance('verify');
+      return { ok: result.ok, gate, state: result.state, error: result.error };
+    },
+
+    /**
+     * Self-Check Gate 실행 + 자동 전이
+     * verify → selfcheck → complete/fix
+     * @param {string|object} execResult
+     * @param {string|object} verifyResult
+     * @param {object} requirements - { hasDiff?, evidence? }
+     * @returns {{ ok: boolean, gate: object, state?: object, error?: string }}
+     */
+    runSelfCheckGate(execResult, verifyResult, requirements = {}) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return { ok: false, error: `파이프라인 없음: ${teamName}` };
+
+      if (current.phase !== 'selfcheck') {
+        return { ok: false, error: `selfcheck gate는 selfcheck 단계에서만 실행 가능 (현재: ${current.phase})` };
+      }
+
+      const gate = runSelfCheck(execResult, verifyResult, requirements);
+      this.setArtifact('selfcheck_result', gate);
+
+      if (gate.passed) {
+        const result = this.advance('complete');
+        return { ok: result.ok, gate, state: result.state, error: result.error };
+      }
+
+      // Red Flag 탐지 또는 필수 질문 실패 → fix
+      const result = this.advance('fix');
+      return { ok: result.ok, gate, state: result.state, error: result.error };
+    },
+  };
+}
+
+// ── 토큰 벤치마크 훅 ──
+
+let _tokenSnapshotMod = null;
+
+async function loadTokenSnapshot() {
+  if (_tokenSnapshotMod) return _tokenSnapshotMod;
+  try {
+    _tokenSnapshotMod = await import('../../scripts/token-snapshot.mjs');
+  } catch {
+    _tokenSnapshotMod = null;
+  }
+  return _tokenSnapshotMod;
+}
+
+/**
+ * 파이프라인 시작 시 토큰 스냅샷 캡처
+ * @param {string} label - 스냅샷 라벨 (e.g. teamName + timestamp)
+ * @returns {Promise<{label: string, snapshot: object}|null>}
+ */
+export async function benchmarkStart(label) {
+  const mod = await loadTokenSnapshot();
+  if (!mod?.takeSnapshot) return null;
+  try {
+    const snapshot = mod.takeSnapshot(label);
+    return { label, snapshot };
+  } catch { return null; }
+}
+
+/**
+ * 파이프라인 종료 시 diff 계산 + 결과 저장
+ * @param {string} preLabel - 시작 스냅샷 라벨
+ * @param {string} postLabel - 종료 스냅샷 라벨
+ * @param {object} options - { agent?, cli?, id? }
+ * @returns {Promise<object|null>} diff 결과
+ */
+export async function benchmarkEnd(preLabel, postLabel, options = {}) {
+  const mod = await loadTokenSnapshot();
+  if (!mod?.takeSnapshot || !mod?.computeDiff) return null;
+  try {
+    // 종료 스냅샷 캡처
+    mod.takeSnapshot(postLabel);
+    // diff 계산 (결과는 DIFFS_DIR에 자동 저장됨)
+    const diff = mod.computeDiff(preLabel, postLabel, options);
+
+    // 추가로 타임스탬프 기반 사본 저장
+    const diffsDir = join(homedir(), '.omc', 'state', 'cx-auto-tokens', 'diffs');
+    mkdirSync(diffsDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const outPath = join(diffsDir, `${ts}.json`);
+    writeFileSync(outPath, JSON.stringify(diff, null, 2));
+
+    return diff;
+  } catch { return null; }
+}
+
+/**
+ * 트리아지 통합: quickClassify 고신뢰 시 Codex 분류 스킵 판정
+ * @param {string} prompt
+ * @param {number} [threshold=0.8]
+ * @returns {{ skip: boolean, routing: object|null, classification: object }}
+ */
+export function triageWithIntent(prompt, threshold = 0.8) {
+  const classification = _classifyIntent(prompt);
+  if (classification.confidence >= threshold) {
+    return { skip: true, routing: classification.routing, classification };
+  }
+  return { skip: false, routing: null, classification };
+}
+
+export { ensurePipelineTable } from './state.mjs';
+export { PHASES, TERMINAL, ALLOWED, canTransition } from './transitions.mjs';
+export { CRITERIA, runConfidenceCheck } from './gates/confidence.mjs';
+export { RED_FLAGS, QUESTIONS, runSelfCheck } from './gates/selfcheck.mjs';
+export { detectSlop, autoFixSlop, scanDirectory } from '../quality/deslop.mjs';
+export { quickClassify, classifyIntent, INTENT_CATEGORIES } from '../intent.mjs';

package/hub/pipeline/state.mjs

@@ -0,0 +1,191 @@
+// hub/pipeline/state.mjs — Hub SQLite 파이프라인 상태 저장/로드
+//
+// store.mjs의 기존 SQLite 연결(db)을 활용한다.
+// pipeline_state 테이블은 schema.sql에 정의.
+
+import { join } from 'node:path';
+
+import { TFX_STATE_DIR, ensureTfxDirs } from '../paths.mjs';
+
+/**
+ * 파이프라인 상태 DB 경로를 계산한다.
+ * @param {string} baseDir
+ * @returns {string}
+ */
+export function getPipelineStateDbPath(baseDir) {
+  return join(baseDir, TFX_STATE_DIR, 'state.db');
+}
+
+/**
+ * 파이프라인 상태 DB 경로와 .tfx 디렉토리를 준비한다.
+ * @param {string} baseDir
+ * @returns {string}
+ */
+export function ensurePipelineStateDbPath(baseDir) {
+  ensureTfxDirs(baseDir);
+  return getPipelineStateDbPath(baseDir);
+}
+
+/**
+ * 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 = {}) {
+  return db.transaction(() => {
+    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) {
+  return db.transaction(() => {
+    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);
+}