triflux 10.0.0 → 10.0.1

package/CLAUDE.md

@@ -0,0 +1,171 @@
+# triflux — Claude Code 운영 가이드
+
+<core-systems>
+## 핵심 스킬 시스템 (항상 인지)
+
+이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
+
+| 시스템 | 접두사 | 용도 | 스킬 수 |
+|--------|--------|------|---------|
+| **triflux** | `/tfx-*` | CLI 라우팅, 멀티모델 오케스트레이션, 스웜, 원격 실행 | ~40개 |
+| **gstack** | `/` (접두사 없음) | QA, ship, investigate, design, review, checkpoint | ~35개 |
+| **omc** | `/oh-my-claudecode:*` | autopilot, ralph, team, ultrawork, ccg | ~25개 |
+
+스킬을 모르면 자연어 라우팅(아래)으로 자동 매핑된다.
+세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+</core-systems>
+
+<routing>
+## 자연어 → 스킬 라우팅
+
+사용자가 스킬명을 모르더라도 자연어로 요청하면 아래 규칙에 따라 적절한 스킬을 호출한다.
+
+### 행동 유형 → 스킬 매핑
+
+| 의도 | 자연어 신호 | 스킬 |
+|------|-----------|------|
+| 구현/수정 | 만들어, 고쳐, 구현해, 짜줘, 수정해, 바꿔 | tfx-auto |
+| 리뷰 | 봐줘, 리뷰해, 검토해, 괜찮아? | tfx-review |
+| 분석 | 분석해, 어떻게 돌아가?, 구조가 뭐야 | tfx-analysis |
+| 계획 | 계획, 어떻게 하지, 설계해 | tfx-plan |
+| 검색 | 찾아, 어디있어, 파일 찾아 | tfx-find |
+| 리서치 (빠른) | 검색해줘, 찾아봐, 공식문서, 이거 뭐야 | tfx-research |
+| 리서치 (자율) | 자율 리서치, 검색하고 정리해, research and plan | tfx-autoresearch |
+| 테스트 | 테스트, 검증, 돌려봐, QA | tfx-qa |
+| 정리 | 정리해, 슬롭 제거, 클린업 | tfx-prune |
+| 토론 | 뭐가 나을까, 비교해, A vs B | tfx-debate |
+
+### 깊이 수정자
+
+| 수정자 | 신호 | 효과 |
+|--------|------|------|
+| 기본 | (없음), 빠르게, 간단히 | Light 스킬 |
+| 깊이 | 제대로, 꼼꼼히, 철저히 | Deep 스킬 (tfx-deep-*). 예외: tfx-deep-interview는 Gemini 단독 |
+| 합의 | 3자, 교차, 다각도 | consensus 프로토콜 |
+| 반복 | 끝까지, 멈추지마, ralph | persist 모드 |
+| 자율 | 알아서, 자동으로, autopilot | autopilot 모드 |
+
+### CLI 라우팅
+
+headless-guard가 `codex exec` / `gemini -y -p` 직접 호출을 차단한다. tfx 스킬 경유 필수.
+
+**Layer 1 — Light** (tfx-route.sh → 단일 CLI)
+
+| 스킬 | CLI | 용도 |
+|------|-----|------|
+| tfx-auto | 자동 | 통합 진입점 |
+| tfx-codex | Codex | Codex 전용 |
+| tfx-gemini | Gemini | Gemini 전용 |
+| tfx-autopilot | Codex→검증 | 단일 파일, 5분 이내 |
+| tfx-autoroute | 자동 승격 | 실패→더 강한 모델 |
+
+**Layer 2 — Deep** (headless 3-CLI 합의)
+
+tfx-deep-review, tfx-deep-qa, tfx-deep-plan, tfx-deep-research, tfx-consensus, tfx-debate, tfx-panel, tfx-fullcycle, tfx-persist
+
+**Layer 3 — Remote/병렬**
+
+| 스킬 | 용도 |
+|------|------|
+| tfx-multi | 2+개 태스크 headless 병렬 |
+| tfx-codex-swarm | PRD별 worktree + Codex 다중 (로컬 전용) |
+| tfx-remote-spawn | Claude Code 원격 세션 (SSH, setup 필수) |
+
+**Claude 네이티브** (CLI 불필요): tfx-find, tfx-forge, tfx-prune, tfx-index, tfx-setup, tfx-doctor, tfx-hooks, tfx-hub
+
+자원 우선순위: remote-spawn > codex-swarm > multi > Light > 로컬 단독
+
+### 충돌 해소
+
+- ralph = persist alias
+- "auto" 단독 → tfx-auto. "알아서 해" → tfx-autopilot
+- "코드에서 찾아" → tfx-find. "알아봐" → tfx-research
+- 복합 의도: "구현하고 리뷰까지" → tfx-auto → cross-review hook
+</routing>
+
+<session-context>
+## 맥락 이탈 판단
+
+현재 세션 맥락과 무관한 요청이 감지되면 psmux 격리를 제안한다.
+
+| 확신도 | 신호 | 행동 |
+|--------|------|------|
+| 확실 | "새 탭", "별도로", "새 세션" | 바로 psmux spawn |
+| 높음 | 다른 프로젝트/스택 언급 | 분리 제안 |
+| 중간 | 작업 유형 전환 | 분리 제안 + 현재 세션 옵션 |
+| 낮음 | 현재 작업 연장 | 세션 유지 |
+</session-context>
+
+<psmux-wt>
+## psmux/WT 규칙
+
+psmux 세션·WT 패인을 생성/조작/정리할 때 `tfx-psmux-rules` 스킬을 참조한다.
+WT 프리징 방지: exit → sleep 2 → kill 순서. 바로 kill하지 않는다.
+
+### wt.exe → wt-manager 경유
+
+safety-guard가 `wt.exe`, `wt new-tab`, `wt split-pane`, `Start-Process wt`를 차단한다.
+`hub/team/wt-manager.mjs`의 API를 사용한다.
+
+| 용도 | API |
+|------|-----|
+| 새 탭 | `createTab({ title, command, profile, cwd })` |
+| 패인 분할 | `splitPane({ direction: 'H'\|'V', title, command })` |
+| 다중 배치 | `applySplitLayout([{ title, command, direction }])` |
+| 탭 정리 | `closeTab(title)` / `closeStale({ olderThanMs, titlePattern })` |
+
+차단과 대안은 항상 쌍으로 존재해야 한다. 차단만 추가하고 대안을 안 만들면 데드락.
+
+### psmux에서 Codex 실행
+
+| 방식 | 동작 | 이유 |
+|------|------|------|
+| `codex` (interactive) | 불가 | psmux에서 TTY를 못 잡음 |
+| `codex < prompt.md` | 불가 | "stdin is not a terminal" |
+| `codex exec "$(cat prompt.md)" -s danger-full-access --dangerously-bypass-approvals-and-sandbox` | 사용 | 유일한 안전 경로 |
+
+`codex exec`는 config.toml `approval_mode`를 무시하므로 `--dangerously-bypass-approvals-and-sandbox` 필수.
+`-s` 유효값: read-only, workspace-write, danger-full-access.
+</psmux-wt>
+
+<codex-config>
+## Codex config.toml
+
+config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
+
+| config.toml에 있으면 | CLI에서 생략 |
+|---------------------|-------------|
+| `sandbox = "elevated"` | `--full-auto` |
+| `approval_mode = "full-auto"` | `--full-auto` |
+
+안전 패턴: config.toml에 기본값을 두고, CLI에서는 `--profile` 선택만 한다.
+</codex-config>
+
+<remote>
+## 원격 실행
+
+### 스킬 구분
+
+| 스킬 | 대상 | 방식 |
+|------|------|------|
+| tfx-codex-swarm | 로컬 전용 | 로컬 worktree + psmux |
+| tfx-remote-spawn | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
+
+codex를 SSH 너머로 직접 실행하지 않는다. config.toml 충돌 + TTY 문제.
+원격에서 codex가 필요하면: remote-spawn → Claude Code → Claude가 내부에서 codex 호출.
+
+### SSH 패턴
+
+- 인라인 쿼팅 대신 scp + `pwsh -File` 패턴 사용
+- SSH 전송 중 `$var` 전개 주의, PowerShell 변수는 인라인 불가
+- `~` → `$HOME` 변환 필수, 원격 기본 셸 = PowerShell
+</remote>
+
+<cross-review>
+## 교차 검증
+
+- Claude 작성 코드 → Codex 리뷰
+- Codex 작성 코드 → Claude 리뷰
+- 동일 모델 self-approve 하지 않는다
+- git commit 전 미검증 파일 감지 시 nudge
+</cross-review>

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <strong>Tri-CLI Orchestration with Consensus Intelligence</strong><br>
-  <em>Claude + Codex + Gemini — natural language routing, cross-model review, 38 skills with Deep/Light variants.</em>
+  <em>Claude + Codex + Gemini — natural language routing, cross-model review, 42 skills with Deep/Light variants.</em>
 </p>
 
 <p align="center">
@@ -75,12 +75,24 @@ tfx setup
 
 # Remote — spawn Claude sessions on other machines
 /tfx-remote-setup                                # interactive host wizard (Tailscale + SSH)
-/tfx-remote-spawn "run security review on ultra4" # spawn on remote host
+/tfx-remote-spawn "run security review on my-server" # spawn on remote host
 ```
 
 ---
 
-## What's New in v9
+## What's New in v10
+
+**triflux v10** completes the **4-Lake Roadmap** — a systematic hardening of every layer from CLI stability to remote multi-agent orchestration.
+
+### v10 Highlights
+
+- **Lake 1: CLI Stability** — Retry, stall detection, version cache. Zero silent failures
+- **Lake 2: Plugin Isolation** — cli-adapter-base, team-bridge, pack.mjs sync
+- **Lake 3: Remote Infrastructure** — SSH keepalive/retry, hosts.json capability routing, remote handoff, MCP singleton daemon
+- **Lake 4: Token Optimization** — Skill template engine, shared segments, manifest separation. 62% prompt token reduction
+- **Lake 5: Agent Mesh** — Message routing, per-agent queues, heartbeat monitoring, Conductor integration
+
+### v9 (carried forward)
 
 **triflux v9** introduces **Harness-Native Intelligence** — speak naturally, and triflux routes to the right skill automatically. Cross-model review ensures no model approves its own work.
 
@@ -141,7 +153,7 @@ Phase 3: Resolution (if consensus < 70%)
 |-------|------|-------------|--------|
 | `tfx-research` | Light | Quick web search via Exa/Brave/Tavily auto-selection | ~5K |
 | `tfx-deep-research` | Deep | Multi-source parallel search with 3-CLI cross-validation | ~50K |
-| `tfx-codebase-search` | Light | Fast codebase exploration via Haiku agent | ~3K |
+| `tfx-find` | Light | Fast codebase search — files, symbols, patterns via Haiku | ~3K |
 | `tfx-autoresearch` | Light | Autonomous web research to structured report | ~15K |
 
 ### Analysis
@@ -155,9 +167,9 @@ Phase 3: Resolution (if consensus < 70%)
 
 | Skill | Type | Description | Tokens |
 |-------|------|-------------|--------|
-| `tfx-autopilot` | Light | Simple autonomous task execution | ~10K |
-| `tfx-deep-autopilot` | Deep | Full 5-phase pipeline: Expand → Plan → Execute → QA → Validate | ~80K |
-| `tfx-auto` | — | Unified CLI orchestrator with command shortcuts | varies |
+| `tfx-autopilot` | Light | Simple autonomous task execution (single file, <5min) | ~10K |
+| `tfx-fullcycle` | Deep | Full pipeline: Design → Plan → Execute → QA → Verify | ~80K |
+| `tfx-auto` | — | Unified CLI orchestrator with command shortcuts + auto-triage | varies |
 
 ### QA & Verification
 
@@ -191,8 +203,9 @@ Phase 3: Resolution (if consensus < 70%)
 
 | Skill | Type | Description | Tokens |
 |-------|------|-------------|--------|
-| `tfx-persist` | Deep | 3-party verified persistence loop until done (`/tfx-ralph` compat alias) | varies |
-| `tfx-sisyphus` | Light | Auto-routing execution with model escalation | varies |
+| `tfx-persist` | Deep | 3-party verified persistence loop until done | varies |
+| `tfx-ralph` | — | Alias for `tfx-persist` | varies |
+| `tfx-autoroute` | Light | Auto-routing with model escalation on failure | varies |
 
 ### Meta & Utility
 
@@ -201,7 +214,8 @@ Phase 3: Resolution (if consensus < 70%)
 | `tfx-index` | Light | 94% token reduction via project indexing (58K→3K) | ~2K |
 | `tfx-forge` | Light | Create new skills interactively | ~10K |
 | `tfx-interview` | Light | Socratic requirements exploration | ~15K |
-| `tfx-deslop` | Deep | AI slop removal with 3-party consensus | ~10K |
+| `tfx-deep-interview` | Deep | Socratic deep interview with ambiguity gating | ~25K |
+| `tfx-prune` | Light | AI slop removal — dead code, over-abstraction cleanup | ~10K |
 
 ### Infrastructure
 
@@ -210,13 +224,16 @@ Phase 3: Resolution (if consensus < 70%)
 | `tfx-consensus` | Core consensus engine (internal, used by all Deep skills) |
 | `tfx-hub` | MCP message bus management |
 | `tfx-multi` | Multi-CLI team orchestration |
+| `tfx-codex-swarm` | Parallel Codex sessions via worktree + psmux |
+| `tfx-swarm` | Unified swarm orchestration |
 | `tfx-setup` | Initial setup wizard |
 | `tfx-doctor` | Diagnostics and auto-repair |
-| `tfx-profile` | Codex CLI profile management |
+| `tfx-hooks` | Claude Code hook priority manager |
+| `tfx-profile` | Codex/Gemini CLI profile management |
 | `tfx-codex` | Codex-only orchestrator |
 | `tfx-gemini` | Gemini-only orchestrator |
 | `tfx-auto-codex` | Codex-lead orchestrator |
-| `tfx-remote-spawn` | Remote session management via psmux |
+| `tfx-remote-spawn` | Remote session management via psmux + SSH |
 | `tfx-remote-setup` | Remote host setup wizard (Tailscale + SSH) |
 
 ---
@@ -326,9 +343,9 @@ tfx setup
 
 ## Research Foundation
 
-The v8 skill suite was designed after comprehensive reverse-engineering of 37 cloned repositories across the Claude Code ecosystem:
+The v8 skill suite was inspired by patterns and ideas from across the Claude Code ecosystem:
 
-| Project | Stars | Key Insight Adopted |
+| Project | Stars | Inspiration |
 |---------|-------|-------------------|
 | everything-claude-code | 114K | Instinct-based learning patterns |
 | Superpowers | 93K | TDD enforcement, composable skills |
@@ -363,7 +380,7 @@ The v8 skill suite was designed after comprehensive reverse-engineering of 37 cl
 
 ## QoS Dashboard
 
-Monitor orchestration health at `http://localhost:27888/dashboard`.
+Monitor orchestration health via the built-in QoS Dashboard (run `tfx doctor` for URL).
 
 - **AIMD Batch Sizing** — Auto-scales parallel tasks based on success rates
 - **Token Savings** — Real-time tracking of Claude tokens saved

package/bin/triflux.mjs

@@ -284,6 +284,16 @@ function handleFatalError(error, { json = false } = {}) {
   process.exit(exitCode);
 }
 
+function renderErrorMessage(message, fallback = "unknown error") {
+  if (typeof message === "string") {
+    const normalized = message.trim().toLowerCase();
+    if (normalized.length > 0 && normalized !== "undefined" && normalized !== "null") {
+      return message.trim();
+    }
+  }
+  return fallback;
+}
+
 function which(cmd) {
   try {
     const result = process.platform === "win32"
@@ -706,11 +716,45 @@ function previewMcpRegistrationActions(mcpUrl) {
   return actions;
 }
 
+function previewClaudeRoutingAction() {
+  const globalClaudePath = join(CLAUDE_DIR, "CLAUDE.md");
+  const projectClaudePath = join(PKG_ROOT, "CLAUDE.md");
+  const projectContent = existsSync(projectClaudePath)
+    ? readFileSync(projectClaudePath, "utf8")
+    : "";
+  const projectSection = extractMarkdownSection(projectContent, TFX_SECTION_HEADING);
+
+  if (!projectSection) {
+    return {
+      type: "claude-guidance",
+      path: globalClaudePath,
+      source: projectClaudePath,
+      change: "skip",
+      reason: "project-section-missing",
+    };
+  }
+
+  const globalContent = existsSync(globalClaudePath)
+    ? readFileSync(globalClaudePath, "utf8")
+    : "";
+  const preview = ensureTfxSection(globalContent, { scope: "global", projectSection });
+
+  return {
+    type: "claude-guidance",
+    path: globalClaudePath,
+    source: projectClaudePath,
+    change: preview.changed ? (existsSync(globalClaudePath) ? "update" : "create") : "noop",
+    heading: TFX_SECTION_HEADING,
+    summary: TFX_GLOBAL_SUMMARY_SECTION,
+  };
+}
+
 function buildSetupDryRunPlan() {
   const actions = [
     ...SYNC_MAP.map(({ src, dst, label }) => describeSyncAction(src, dst, label)),
     ...listSkillSyncActions(),
   ];
+  actions.push(previewClaudeRoutingAction());
   const codexProfiles = previewCodexProfiles();
   actions.push({
     type: "codex-profiles",
@@ -742,6 +786,12 @@ function cmdSetup(options = {}) {
   for (const target of SYNC_MAP) {
     syncFile(target.src, target.dst, target.label);
   }
+  {
+    const claudeGuide = ensureGlobalClaudeRoutingSection();
+    if (!claudeGuide.ok) warn(`CLAUDE.md 라우팅 섹션 확인 실패: ${claudeGuide.reason}`);
+    else if (claudeGuide.changed) ok("CLAUDE.md: 전역 triflux 라우팅 요약 갱신");
+    else ok("CLAUDE.md: 전역 triflux 라우팅 요약 유지");
+  }
 
   // 스킬 동기화 (~/.claude/skills/{name}/SKILL.md)
   const skillsSrc = join(PKG_ROOT, "skills");
@@ -838,8 +888,9 @@ function cmdSetup(options = {}) {
 
   const codexProfileResult = ensureCodexProfiles();
   if (!codexProfileResult.ok) {
-    warn(`Codex profiles 설정 실패: ${codexProfileResult.message}`);
-    summary.push({ item: "Codex profiles", status: "⚠️", detail: codexProfileResult.message });
+    const reason = renderErrorMessage(codexProfileResult.message);
+    warn(`Codex profiles 설정 실패: ${reason}`);
+    summary.push({ item: "Codex profiles", status: "⚠️", detail: reason });
   } else if (codexProfileResult.changed > 0) {
     ok(`Codex profiles: ${codexProfileResult.changed}개 반영됨 (~/.codex/config.toml)`);
     summary.push({ item: "Codex profiles", status: "✅", detail: `${codexProfileResult.changed}개 반영됨` });
@@ -851,8 +902,9 @@ function cmdSetup(options = {}) {
   // Gemini 프로필
   const geminiResult = ensureGeminiProfiles();
   if (!geminiResult.ok) {
-    warn(`Gemini profiles 설정 실패: ${geminiResult.message}`);
-    summary.push({ item: "Gemini profiles", status: "⚠️", detail: geminiResult.message });
+    const reason = renderErrorMessage(geminiResult.message);
+    warn(`Gemini profiles 설정 실패: ${reason}`);
+    summary.push({ item: "Gemini profiles", status: "⚠️", detail: reason });
   } else if (geminiResult.created) {
     ok(`Gemini profiles: ${geminiResult.count}개 생성됨 (~/.gemini/triflux-profiles.json)`);
     summary.push({ item: "Gemini profiles", status: "✅", detail: `${geminiResult.count}개 생성됨` });
@@ -1320,6 +1372,11 @@ async function cmdDoctor(options = {}) {
     for (const target of SYNC_MAP) {
       syncFile(target.src, target.dst, target.label);
     }
+    {
+      const claudeGuide = ensureGlobalClaudeRoutingSection();
+      if (!claudeGuide.ok) warn(`CLAUDE.md 라우팅 섹션 확인 실패: ${claudeGuide.reason}`);
+      else if (claudeGuide.changed) ok("CLAUDE.md: 전역 triflux 라우팅 요약 갱신");
+    }
     // 스킬 동기화
     const fSkillsSrc = join(PKG_ROOT, "skills");
     const fSkillsDst = join(CLAUDE_DIR, "skills");
@@ -1340,7 +1397,7 @@ async function cmdDoctor(options = {}) {
     }
     const profileFix = ensureCodexProfiles();
     if (!profileFix.ok) {
-      warn(`Codex Profiles 자동 복구 실패: ${profileFix.message}`);
+      warn(`Codex Profiles 자동 복구 실패: ${renderErrorMessage(profileFix.message)}`);
     } else if (profileFix.changed > 0) {
       ok(`Codex Profiles: ${profileFix.changed}개 반영됨`);
     } else {

package/hooks/agent-route-guard.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// hooks/agent-route-guard.mjs — PreToolUse:Agent 훅
+// 서브에이전트 스폰 시 triflux 컨텍스트를 구조화 JSON으로 주입한다.
+// - subagent_type별 최적 라우팅 가이드
+// - tfx-multi 활성 상태 시 headless dispatch 강제
+// - 프로젝트 컨텍스트 자동 첨부
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const TFX_MULTI_STATE = join(tmpdir(), "tfx-multi-state.json");
+const EXPIRE_MS = 30 * 60 * 1000; // 30분
+
+// 서브에이전트 타입별 라우팅 힌트
+const AGENT_HINTS = {
+  "general-purpose": "범용 에이전트. tfx 스킬이 활성이면 스킬 MD의 라우팅을 우선한다.",
+  Explore: "탐색 전용. 파일 수정 불가. Glob/Grep/Read만 사용.",
+  Plan: "설계 전용. 파일 수정 불가. 구현 계획 반환.",
+  "oh-my-claudecode:executor": "OMC executor. triflux 프로젝트에서는 tfx-auto 라우팅을 우선.",
+  "oh-my-claudecode:code-reviewer": "OMC 리뷰어. 교차 리뷰 시 CLAUDE.md 교차 검증 규칙 준수.",
+  "oh-my-claudecode:architect": "OMC 아키텍트. READ-ONLY.",
+  "oh-my-claudecode:debugger": "OMC 디버거. 근본 원인 분석 집중.",
+  "oh-my-claudecode:test-engineer": "OMC 테스트. npm test 실행 후 결과 반환.",
+};
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function getTfxMultiState() {
+  if (!existsSync(TFX_MULTI_STATE)) return null;
+  try {
+    const state = JSON.parse(readFileSync(TFX_MULTI_STATE, "utf8"));
+    if (Date.now() - state.activatedAt > EXPIRE_MS) return null;
+    return state.active ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildContext(agentType, prompt) {
+  const parts = [];
+
+  // 1. tfx-multi 활성 상태 확인
+  const multiState = getTfxMultiState();
+  if (multiState) {
+    parts.push(
+      "[tfx-multi ACTIVE] headless dispatch 모드. " +
+        "CLI 작업은 Bash(tfx-route.sh)를 통해 실행하세요."
+    );
+  }
+
+  // 2. 에이전트 타입별 힌트
+  const hint = AGENT_HINTS[agentType];
+  if (hint) {
+    parts.push(`[Agent:${agentType}] ${hint}`);
+  }
+
+  // 3. 프로젝트 컨텍스트
+  parts.push(
+    "triflux 프로젝트: subagent_type 미지정 시 'general-purpose' 기본. " +
+      "tfx-* 스킬 활성 시 스킬 MD 라우팅 우선."
+  );
+
+  return parts.join("\n");
+}
+
+function main() {
+  const raw = readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  if (input.tool_name !== "Agent") process.exit(0);
+
+  const toolInput = input.tool_input || {};
+  const agentType = toolInput.subagent_type || toolInput.agent || "general-purpose";
+  const prompt = toolInput.prompt || "";
+
+  const context = buildContext(agentType, prompt);
+
+  // 구조화된 hookSpecificOutput 반환
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      additionalContext: context,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+try {
+  main();
+} catch {
+  // 훅 실패 시 블로킹하지 않음
+  process.exit(0);
+}

package/hooks/cross-review-tracker.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// hooks/cross-review-tracker.mjs — PostToolUse:Edit|Write 훅
+//
+// 파일 수정을 추적하여 교차 리뷰 미검증 파일을 감지한다.
+// CLAUDE.md 규칙: "Claude 작성 코드 → Codex 리뷰, Codex 작성 → Claude 리뷰"
+//
+// 동작:
+//   1. Edit/Write 성공 시 수정된 파일 경로를 상태 파일에 누적
+//   2. 일정 수(REVIEW_THRESHOLD) 이상 미검증 파일이 쌓이면 nudge 메시지 주입
+//   3. git commit 전 미검증 파일 경고
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { tmpdir } from "node:os";
+
+const STATE_DIR = join(tmpdir(), "tfx-cross-review");
+const STATE_FILE = join(STATE_DIR, "pending-review.json");
+const REVIEW_THRESHOLD = 5; // 이 수 이상 미검증 파일 → nudge
+const EXPIRE_MS = 60 * 60 * 1000; // 1시간 후 자동 만료
+
+// 코드 파일만 추적 (설정/문서/빌드 산출물 제외)
+const CODE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
+  ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h",
+  ".vue", ".svelte", ".sh", ".bash", ".ps1",
+]);
+
+function isCodeFile(filePath) {
+  if (!filePath) return false;
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  return CODE_EXTENSIONS.has(ext);
+}
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) {
+    return { files: {}, startedAt: Date.now() };
+  }
+  try {
+    const state = JSON.parse(readFileSync(STATE_FILE, "utf8"));
+    // 만료 체크
+    if (Date.now() - state.startedAt > EXPIRE_MS) {
+      return { files: {}, startedAt: Date.now() };
+    }
+    return state;
+  } catch {
+    return { files: {}, startedAt: Date.now() };
+  }
+}
+
+function saveState(state) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function main() {
+  const raw = readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || "";
+  if (toolName !== "Edit" && toolName !== "Write") process.exit(0);
+
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || "";
+
+  if (!filePath || !isCodeFile(filePath)) process.exit(0);
+
+  // 프로젝트 루트 기준 상대 경로
+  const cwd = input.cwd || process.cwd();
+  const relPath = relative(cwd, filePath) || filePath;
+
+  // 상태 갱신: 파일 추가
+  const state = loadState();
+  state.files[relPath] = {
+    tool: toolName,
+    modifiedAt: Date.now(),
+    reviewed: false,
+  };
+  saveState(state);
+
+  // 미검증 파일 수 체크
+  const unreviewed = Object.entries(state.files).filter(
+    ([, v]) => !v.reviewed
+  );
+  const count = unreviewed.length;
+
+  if (count >= REVIEW_THRESHOLD) {
+    // nudge 메시지 주입
+    const fileList = unreviewed
+      .slice(0, 8)
+      .map(([f]) => `  - ${f}`)
+      .join("\n");
+
+    const output = {
+      systemMessage:
+        `[교차 리뷰 nudge] 미검증 코드 파일 ${count}개:\n${fileList}\n` +
+        (count > 8 ? `  ... 외 ${count - 8}개\n` : "") +
+        `커밋 전 교차 리뷰를 권장합니다. (Claude→Codex 또는 Codex→Claude)`,
+    };
+    process.stdout.write(JSON.stringify(output));
+  }
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}