데이터 흐름 지도Data Flow Map

아키텍처Architecture

회장의 한 줄 지시가 어디로 흘러가고, 각 구간에 어떤 컴포넌트·메소드가 있는지. 구조는 코드(server/src/) 가 단일 진실원, 이 페이지는 그 위에 얹은 지도.How a single chairman directive flows, and what components/methods live in each region. Source code is the single source of truth; this page maps over it.

전체 흐름Overall Flow

A→B 로 진입한 뒤, B 는 C(전략)와 D(토론)로 갈라지고, 둘 다 E(실행)로 모인다. E→F→다시 회장.A→B; from B it branches to C (strategy) and D (debate); both converge at E (exec), then E→F→back to the chairman.

구간별 상세Region Detail

각 구간이 가진 컴포넌트, 핵심 메소드(파일 위치 포함), 안전장치. 이슈 번호(G177/G178/G179 등)는 server/src/ 코드의 같은 마커와 매칭된다.Per-region: components, key methods (with file refs), safety mechanisms. Issue numbers (G177/G178/G179) match markers in server/src/.

입력 — 회장 → 서버Intake — Chairman → Server

회장 모바일/웹에서 지시 → Supabase Realtime → 서버 수신 + H2 직렬화 큐Chairman from mobile/web → Supabase Realtime → server pickup + H2 serialized queue

컴포넌트Components

iOS 앱 (Swift)iOS app (Swift)Android 앱 (Kotlin)Android app (Kotlin)웹 대시보드 (Next.js)Web dashboard (Next.js)Supabase Realtime 채널Supabase Realtime channelTOTP 페어링 (5분 만료)TOTP pairing (5-min expiry)H2 큐 (직렬화)H2 queue (serialization)

핵심 메소드 / 함수Key methods / functions

subscribeToMessages()supabase.ts회장 메시지 Realtime 구독Realtime subscribe to chairman msgs
processMessage()index.tsagent_id=chairman 만 파이프라인 트리거Only chairman triggers pipeline
workQueue / setImmediate drainindex.ts실행 중 신규 메시지 → 큐, 끝나면 자동 dequeueIn-flight → enqueue, auto-drain on done
insertMessage() insertMessageWithFullContent()supabase.ts
generatePairingCode()pairing.ts모바일↔서버 TOTP 발급Mobile↔server TOTP
workflow-watchdog (20분)workflow-watchdog.ts큐 hang 강제 리셋Force reset on queue hang

파일Files

server/src/index.ts server/src/orchestrator/supabase.ts server/src/orchestrator/pairing.ts server/src/orchestrator/workflow-watchdog.ts

C4I 파이프라인C4I Pipeline

군사 지휘체계 + 컴파일러 IR + OS 커널 syscall + 원자력 안전 + 항공관제 핸드오프 → 7단계Military C4I + compiler IR + OS syscall + nuclear safety + ATC handoff → 7 stages

컴포넌트Components

7 Phase: Intake→CEO→C-Level→Leader→Worker→Review→Report7 Phases핸드오프 3단계 (request/accept/confirm)Handoff 3-step (request/accept/confirm)Task Strip (작업 추적)Task Strip (task tracking)안돈 (이상 → 일시정지)Andon (anomaly → pause)SCRAM (전체 즉시 중단)SCRAM (full halt)Watch Cycle (3교대 예산)Watch Cycle (3-shift budget)Silent Running (API 장애 자동 폴백)Silent Running (API failover)ViewHolder 풀 (순차 슬롯)ViewHolder pool (sequential slots)

핵심 메소드 / 함수Key methods / functions

runPipeline()pipeline/orchestrator.ts회장 메시지 → 전 단계 실행Chairman msg → run all phases
executeDirective() processOrderFromPlan() preflightDirective()pipeline/orchestrator.ts
phaseIntake/CEO/CLevel/Leader/Worker/Review/Report()pipeline/phase-*.ts
triggerScram() isScramActive()pipeline/safety.ts
checkBudgetGate() recordTokensConsumed()pipeline/watch-cycle.ts
createHandoff() confirmHandoff()pipeline/handoff.ts
getSilentRunningState() activate()pipeline/silent-running.ts
getStrip() escalateStrip()pipeline/task-strip.ts

파일Files

server/src/pipeline/orchestrator.ts server/src/pipeline/phase-intake.ts server/src/pipeline/phase-ceo.ts server/src/pipeline/phase-clevel.ts server/src/pipeline/phase-leader.ts server/src/pipeline/phase-worker.ts server/src/pipeline/phase-review.ts server/src/pipeline/phase-report.ts server/src/pipeline/safety.ts server/src/pipeline/watch-cycle.ts server/src/pipeline/handoff.ts server/src/pipeline/task-strip.ts

안전장치SafetyG177 git 체크포인트 (order별 commit + 손상 시 reset)G177 git checkpointG179 watch-cycle 예산 DB 영속화G179 watch-cycle persistence

전략 — CEO + CouncilStrategy — CEO + Council

상시 CEO + 24/7 C-레벨 회의방 + 도메인 옵저버. 합의불가 → 회장 결재 에스컬레이션Always-on CEO + 24/7 C-level council + domain observers. No-consensus → chairman escalation

컴포넌트Components

CEO Agent (상시 가동)CEO Agent (always-on)Council Reflection Loop (60초 주기)Council Reflection Loop (60s)Domain Observer (C-레벨별 1개)Domain Observer (1 per C-level)4단계 에스컬레이션 (간부→C→Council→회장)4-tier escalationSpec Issuer (PM 문서 자동 발급)Spec Issuer (auto PM docs)C-레벨 6종: CTO/COO/CFO/CMO/CPO/CISO6 C-levels: CTO/COO/CFO/CMO/CPO/CISO

핵심 메소드 / 함수Key methods / functions

analyzeProjectAndProposeHires()ceo-agent.tsC-레벨 동적 고용 판단Dynamic C-level hiring
startCouncil() stopCouncil()clevel-council.ts
runCouncilReactions() recordDecision() escalateToChairman()clevel-council.ts
startCouncilReflectionLoop()clevel-council.ts60초마다 워커 활동 요약 → Council 게시Every 60s: worker activity summary → Council
persistCouncilCursor() loadCouncilCursor()clevel-council.ts반성 커서 DB 영속화 (G179)Reflection cursor persistence
startAllObservers() startDomainObserver()clevel-observer.ts
observerPostGate()clevel-observer.ts시간당 게시 상한 (G179, 기본 20/h)Hourly post cap
postToCouncil() reportToCouncil()clevel-council.ts / observer.ts
Phase A1 / B1 / B2 분리 발급spec-issuer.tsspec/tasks/wbs/gantt/raci/risk/status 9문서 병렬Parallel spec/tasks/wbs/gantt/raci/risk/status

파일Files

server/src/orchestrator/ceo-agent.ts server/src/orchestrator/clevel-council.ts server/src/orchestrator/clevel-observer.ts server/src/orchestrator/spec-issuer.ts

안전장치SafetyG179 Observer 게시 상한 + Council 커서 영속화G179 Observer post cap + Council cursor persistence

토론 시스템 — 충돌 해소Debate — Conflict Resolution

2+ C-레벨 충돌 / 워커 반복 실패 → 다이아몬드 토론 → 합의 → DELEGATE. MVVM: Consigliere=DB, NodeTree=DAO, debate.ts=ViewModel2+ C-level conflict / worker repeated fail → diamond debate → consensus → DELEGATE. MVVM split.

컴포넌트Components

DebateQueue (우선순위 + 선점)DebateQueue (priority + preemption)debateLoop (최대 20 라운드)debateLoop (max 20 rounds)NodeTree (Consigliere DAO, 자체 상태 0)NodeTree (DAO, zero own state)DebateConsigliere (append-only ledger)DebateConsigliere (append-only ledger)Input/Output Filter (-c 컨텍스트 제거)Input/Output Filter (no -c bloat)자동 합의 게이트 (bigram 80%)Auto-consensus gate (bigram 80%)중간 선생(레벨 가지치기) + 최고선생(최종 통합)Mid teacher + Top teacher (G174)

핵심 메소드 / 함수Key methods / functions

requestDebate()debate.ts큐 적재 + CD04 markerEnqueue + CD04 marker
processNextDebate()debate.ts큐에서 꺼내 실행. hydrate 로 신규/재개 통합Dequeue + hydrate (new/resume unified)
debateLoop()debate.ts의견→게이트→합의→DELEGATE→테스트 루프opinions→gate→consensus→DELEGATE→test loop
collectOpinions() buildConsensus() executeProposal() runTests()debate.ts
checkConsensusGate() enforceTokenBudget() estimateTokens()debate-filter.ts
escalateDebateAbort()debate.ts정체/예산 abort → 회장 alert (G175/G176)Stagnation/budget abort → chairman alert
NodeTree.createRoot / addChild / computeStatus / prunenode-tree.ts
DebateConsigliere.append() flushToDb() hydrate()debate-consigliere.ts라운드별 증분 영속화 + 부팅 복원 (G178)Per-round incremental persist + boot hydrate
pruneWithIntermediateTeacher() finalTeacherMazeSolve()debate.tsCanvas Teacher Layer (G174)Canvas Teacher Layer
DebateQueue.enqueue() enqueueExisting() dequeue()debate-queue.tsenqueueExisting = 재개용 id 보존enqueueExisting = preserve id for resume
scanAndResumeIncompleteDebates()debate.ts부팅 시 미완료 토론 재등록 (G178)Boot: re-enqueue incomplete debates
insertDebateStub() saveDebateLog()debate.ts시작 stub + 종료 upsert (ended_at 마감)Start stub + end upsert (ended_at)

파일Files

server/src/orchestrator/debate.ts server/src/orchestrator/debate-consigliere.ts server/src/orchestrator/debate-queue.ts server/src/orchestrator/node-tree.ts server/src/orchestrator/debate-filter.ts

안전장치SafetyG175 정체 감지 (K=3라운드 무진전 → abort)G175 stagnation detectionG176 누적 토큰 상한 (기본 120K → abort)G176 cumulative token ceilingG178 크래시 복구 (라운드별 ledger flush, 부팅 시 hydrate)G178 crash recovery

실행 + 검증 — 워커 → 빌드Execution + Validation — Worker → Build

에이전트 LLM 호출 → 코드 생성 → BuildValidator 검증 → git 체크포인트(생성 프로젝트). 손상 시 직전 시점으로 resetAgent LLM call → code → BuildValidator → git checkpoint. Reset on corruption

컴포넌트Components

Worker Agent (Haiku, 몽키코더)Worker Agent (Haiku, executor)Leader Agent (Sonnet, 설계)Leader Agent (Sonnet, design)C-Level Agent (Opus, 전략)C-Level Agent (Opus, strategy)AgentAdapter 패턴 (Claude / Ollama / 미래 모델 교체)AgentAdapter (Claude/Ollama/future swap)ViewHolder 풀 (순차 슬롯, 메모리 보호)ViewHolder pool (sequential, memory-safe)BuildValidator (iOS swiftc+xcodebuild, Android Gradle)BuildValidatorGenerate-Verify 분리 (Evaluator)Generate-Verify splitphantom_success 감지 (filesModified=0 → retry)phantom_success detectionGit Checkpoint (생성 프로젝트, bigbossos 레포 미접촉)Git Checkpoint (gen project only)

핵심 메소드 / 함수Key methods / functions

callAgent() callAgentsParallel()llm.ts
callDirectorStateless()llm.ts-p 신선 컨텍스트, Consigliere로 system prompt 주입Fresh -p, Consigliere-injected
callClaude()llm.ts
parseDelegates()llm.tsDELEGATE 태그 파싱 (3-Layer agent_id 분기)Parse DELEGATE (3-layer)
AgentAdapter.invoke()pipeline/adapter.tsSilent Running 시 자동 폴백 라우팅Silent Running auto-fallback routing
buildValidateIOS() buildValidateAndroid()project-validator.ts
reviewSingleResult()pipeline/phase-review.tsphantom_success / disk / build / errors 6단계 검사6-stage check
initCheckpointRepo() commitCheckpoint() resetToLastCheckpoint()git-checkpoint.ts생성 프로젝트 git 격리 (G177)Generated project git, isolated
detectBasenameCollisions()pipeline/orchestrator.tsG87 워커 출력 충돌 감지G87 collision detect
scaffoldProjectAgent() writeIOSScaffold() writeAndroidScaffold()scaffolding-agent.tsCapomastro 본체 — 결정론적 뼈대Capomastro core — deterministic skeleton

파일Files

server/src/orchestrator/llm.ts server/src/orchestrator/git-checkpoint.ts server/src/orchestrator/project-validator.ts server/src/orchestrator/scaffolding-agent.ts server/src/orchestrator/ide-blueprint.ts server/src/pipeline/adapter.ts server/src/pipeline/adapters/claude-cli.ts server/src/pipeline/adapters/ollama.ts

안전장치SafetyG177 손상 감지(buildErrors+overall=fail) → 직전 체크포인트로 hard resetG177 reset to last checkpoint on corruption

메모리 · 영속화 · 보고Memory · Persistence · Reporting

Consigliere(RAG+BM25) + server_runtime_state(런타임 키-값) + 4홉 상향 보고 → 회장 응답Consigliere(RAG+BM25) + server_runtime_state + 4-hop upward report → reply

컴포넌트Components

Consigliere (RAG + BM25, 단일 진실원)Consigliere (RAG + BM25, single source of truth)Soldato (Gemma 4 31B, 로컬 폴백)Soldato (Gemma 4 31B, local failover)server_runtime_state (범용 키-값 DB)server_runtime_state (generic KV DB)debates / debate_consigliere_entries DBdebates / debate_consigliere_entries DB4홉 보고 체인 (Worker→Leader→C→CEO→회장)4-hop chainRealtime 응답 → 모바일/웹 동시 표시Realtime reply → mobile/web simultaneous

핵심 메소드 / 함수Key methods / functions

consigliereIndex() consigliereSearch() consigliereEmbed()consigliere.ts
consigliereSelfContext() consigliereSessionContext()consigliere.ts
phaseReport() buildFullReportChain()pipeline/phase-report.ts
saveDebateLog() insertDebateStub()debate.ts
loadWatchState() persistWatchState()pipeline/watch-cycle.ts당일 예산 DB 영속화 (G179)Daily budget DB persistence
insertMessage()supabase.ts회장에게 응답 → Realtime → 모바일/웹Reply → Realtime → mobile/web
getSilentRunningState() activate() deactivate()pipeline/silent-running.tsSoldato 자동 전환 (침묵 항해)Soldato auto-switch (silent running)

파일Files

server/src/orchestrator/consigliere.ts server/src/pipeline/phase-report.ts server/src/pipeline/watch-cycle.ts server/src/pipeline/silent-running.ts supabase/migrations/072_crash_recovery.sql supabase/migrations/059_debate_consigliere_entries.sql

안전장치SafetyG178 라운드별 ledger DB flush + 부팅 hydrateG178 per-round ledger flush + boot hydrateG179 server_runtime_state 영속화 (watch-cycle / Council 커서)G179 server_runtime_state persistence

패밀리 — 핵심 시스템The Family — Core Systems

마피아 메타포의 작명은 진심으로 — 각각 조직에서 다른 역할을 맡는다. Consigliere(기억), Capomastro(현장 감독), Soldato(로컬 일꾼).The mafia naming is earnest — each plays a different role: Consigliere (memory), Capomastro (master builder), Soldato (local soldier).

Consigliere

조직의 기억 — Advisor / MemoryThe Family's Memory — Advisor

모든 토론·결정·코드 맥락의 단일 진실원(Single Source of Truth). 에이전트 호출마다 컨텍스트가 부풀어 토큰을 낭비하던 구조를 해체 — Consigliere 가 시스템 프롬프트에 필요한 맥락만 주입하고, 에이전트는 매번 신선한 `-p` 세션으로 호출된다. I63 MVVM 리팩터의 핵심.Single source of truth for debates, decisions, and code context. Replaced the bloated -c context model: Consigliere injects only what's needed into the system prompt, agents run fresh -p sessions every time. Core of the I63 MVVM refactor.

메커니즘Mechanism

BM25 (텍스트 매칭) + 임베딩(Ollama) 하이브리드 검색 — Ollama 부재 시 BM25 폴백Hybrid BM25 + embedding (Ollama) — falls back to BM25 if Ollama absent
인덱싱 대상: docs/, server/src/, 토론 결과 MD 내보내기, 코드 변경 디프Indexes docs/, server/src/, debate MD exports, code diffs
DebateConsigliere — 토론 단위 append-only ledger (별도 클래스). 라운드마다 DB 증분 flush 로 크래시 복구(G178) 보장DebateConsigliere — per-debate append-only ledger; per-round incremental DB flush for crash recovery (G178)
sequence + parent_sequence 로 인과 그래프 + 시간 순서 보장. NodeTree 가 이걸 read-only 로 쿼리해서 트리 파생sequence + parent_sequence guarantee causal graph + temporal order; NodeTree queries read-only to derive the tree
보안 모순 감지 + 임베딩 실패 시 거짓양성 방지(consigliereEmbedded 플래그)Security contradiction detection + embedded-flag guards false positives when embedding fails

핵심 메소드Key methods

consigliereIndex()consigliere.ts주기 인덱싱Periodic indexing
consigliereSearch()consigliere.tsBM25+임베딩 검색BM25+embedding search
consigliereEmbed()consigliere.ts
consigliereSelfContext()consigliere.ts에이전트 호출용 컨텍스트 패키지Agent context package
consigliereSessionContext()consigliere.ts
DebateConsigliere.append() flushToDb() hydrate()debate-consigliere.ts토론 단위 ledger + 크래시 복구Per-debate ledger + crash recovery
isConsigliereAvailable()consigliere.ts

파일Files

server/src/orchestrator/consigliere.ts server/src/orchestrator/debate-consigliere.ts supabase/migrations/059_debate_consigliere_entries.sql

소속 구간Region: MEMORY

Capomastro

현장 감독 — Master BuilderThe Master Builder

프로젝트 뼈대를 결정론적으로 생성하는 스캐폴드 시스템. 초기엔 Go 바이너리(별도 레포)였으나 FEAT-A1 에서 TypeScript 직접 생성 + IDE Recipe MD 결정론적 실행 모델로 재설계 — LLM 출력의 비결정성을 제거하고 빌드 검증 가능한 뼈대를 보장한다.Deterministic scaffold system for project skeletons. Originally a Go binary in a separate repo, FEAT-A1 redesigned it as TypeScript-direct generation + IDE-Recipe-MD deterministic execution — removed LLM non-determinism and guaranteed build-verifiable skeletons.

메커니즘Mechanism

TypeScript 직접 생성: iOS pbxproj, Android Gradle, Multiplatform 등 9 플랫폼 뼈대TypeScript-direct: iOS pbxproj, Android Gradle, Multiplatform — 9 platforms
IDE Recipe MD: Xcode 12종 · Android Studio 7종 · VSCode 3종 · Terminal 52종+ 결정론적 스크립트IDE Recipe MD: 12 Xcode + 7 Android Studio + 3 VSCode + 52+ Terminal recipes
LLM fallback: Recipe 미커버 케이스만 LLM 호출 → 검증 후 Recipe 로 승격(증류)LLM fallback only for uncovered cases → promoted to Recipe after verification
iOS 멱등성(`ios/<any>/pbxproj` 재실행 안전, G83), Android 의존성 자동 주입(navigation-compose/room/security-crypto)iOS idempotency (G83), Android dependency auto-inject
파이프라인은 Capomastro 출력 후 BuildValidator 로 즉시 검증 — Generate-Verify 분리Pipeline runs BuildValidator immediately after — Generate-Verify split

핵심 메소드Key methods

scaffoldProjectAgent()scaffolding-agent.ts진입점 — 플랫폼별 분기Entry — platform dispatch
writeIOSScaffold()scaffolding-agent.tsiOS Swift+pbxproj 결정론 생성iOS deterministic Swift+pbxproj
writeAndroidScaffold()scaffolding-agent.tsAndroid Kotlin+GradleAndroid Kotlin+Gradle
syncAllBlueprints()ide-blueprint.tsIDE Recipe 캐시 동기화IDE Recipe cache sync
IDE Recipe interpreteride-recipe.tsRecipe MD 결정론적 실행Recipe MD deterministic exec

파일Files

server/src/orchestrator/scaffolding-agent.ts server/src/orchestrator/ide-blueprint.ts server/recipes/

소속 구간Region: EXECUTION

Soldato

로컬 일꾼 — Pizza (Gemma)The Local Soldier — Pizza (Gemma)

회장의 API 의존성에서 조직을 해방하는 로컬 LLM. Claude API 연속 실패 시 자동으로 Soldato 어댑터로 전환되는 침묵 항해(Silent Running) 모드를 통해 작업이 멈추지 않는다. Gemma 4 31B 베이스, 코드네임 Pizza.Local LLM that frees the family from API dependence. Silent Running mode auto-switches to Soldato adapter on consecutive Claude API failures — work never stops. Gemma 4 31B base, codenamed Pizza.

메커니즘Mechanism

3-티어 (Lite / Main / Pro), 풀파이프 Opus급 96% 목표, 타겟 24GB 환경(75% 유저)3-tier (Lite/Main/Pro), 96% Opus-grade target, 24GB target env (75% of users)
Silent Running: 연속 실패 → SR02 마커 emit → getEffectiveAdapter() 가 soldato 반환 → graceful fallbackSilent Running: consecutive fails → SR02 marker → getEffectiveAdapter() returns soldato → graceful fallback
Ollama 어댑터로 호출 (claude-cli 와 동일 인터페이스 — Agent Adapter 패턴)Called via Ollama adapter (same interface as claude-cli via Agent Adapter)
미등록 어댑터 참조 시 normal adapter 로 graceful fallback (G158 수정)Graceful fallback to normal adapter if unregistered (G158 fix)
KV cache 최적화 6종 (16 에이전트 96GB 권장 구성)6 KV cache optimizations (recommended: 16 agents on 96GB)

핵심 메소드Key methods

getSilentRunningState()pipeline/silent-running.ts
activate() deactivate()pipeline/silent-running.ts
getEffectiveAdapter()pipeline/adapter.tsSR 활성 시 soldato 반환Returns soldato when SR active
AgentAdapter.invoke() (ollama 어댑터)pipeline/adapters/ollama.ts

파일Files

server/src/pipeline/silent-running.ts server/src/pipeline/adapter.ts server/src/pipeline/adapters/ollama.ts

소속 구간Region: MEMORY

토론 시스템 — 라운드 흐름Debate — Round Flow

debateLoop() 한 라운드의 내부 처리. 자동 합의 게이트로 LLM 호출 1건 절약, 라운드 끝마다 ledger 를 DB 에 증분 flush, 그리고 정체/비용/최대 라운드 세 가지 안전 가드.Inside one debateLoop round. Auto-consensus gate saves an LLM call; per-round ledger flush; three safety guards (stagnation/cost/max-rounds).