triflux 10.30.0 → 10.31.0

package/hub/server.mjs

@@ -2054,6 +2054,16 @@ export async function startHub({
   }, 60000);
   sessionTimer.unref();
 
+  const synapsePruneTimer = setInterval(() => {
+    try {
+      const { count } = synapseRegistry.pruneExpired();
+      if (count > 0) hubLog.info({ count }, "synapse.prune");
+    } catch (err) {
+      hubLog.warn({ err }, "synapse.prune_failed");
+    }
+  }, 60000);
+  synapsePruneTimer.unref();
+
   // 고아 node.exe 프로세스 + stale spawn 세션 주기적 정리 (5분마다)
   // TFX_DISABLE_ORPHAN_CLEANUP=1 로 비활성 (active SSH/swarm 세션 보호 회피용 hotfix gate)
   const orphanCleanupTimer = setInterval(
@@ -2288,6 +2298,7 @@ export async function startHub({
               router.stopSweeper();
               clearInterval(hitlTimer);
               clearInterval(sessionTimer);
+              clearInterval(synapsePruneTimer);
               clearInterval(rateLimitTimer);
               clearInterval(orphanCleanupTimer);
               if (idleTimer) {

package/hub/team/synapse-registry.mjs

@@ -5,6 +5,7 @@ const DEFAULT_LOCAL_HEARTBEAT_INTERVAL_MS = 5_000;
 const DEFAULT_LOCAL_TIMEOUT_MS = 30_000;
 const DEFAULT_REMOTE_HEARTBEAT_INTERVAL_MS = 15_000;
 const DEFAULT_REMOTE_TIMEOUT_MS = 90_000;
+const DEFAULT_EXPIRE_TIMEOUT_MS = 24 * 60 * 60 * 1000;
 // Interactive (Claude/Codex) sessions idle for long stretches; a 30s local
 // timeout produces stale false-positives. 5-minute TTL + an `idle` state
 // distinguishes "alive but inactive" from "presumed dead".
@@ -133,6 +134,7 @@ export function createSynapseRegistry(opts = {}) {
     remoteTimeoutMs = DEFAULT_REMOTE_TIMEOUT_MS,
     interactiveHeartbeatIntervalMs = DEFAULT_INTERACTIVE_HEARTBEAT_INTERVAL_MS,
     interactiveTimeoutMs = DEFAULT_INTERACTIVE_TIMEOUT_MS,
+    expireTimeoutMs = DEFAULT_EXPIRE_TIMEOUT_MS,
   } = opts;
 
   const sessions = new Map();
@@ -355,10 +357,89 @@ export function createSynapseRegistry(opts = {}) {
     return true;
   }
 
+  // stale/expired 세션이 expireTimeoutMs 넘게 누적되면 Map에서 제거.
+  // live(active/idle)는 lastHeartbeat가 오래돼도 보존 — git-preflight dirty-file 가드가 의존.
+  function pruneExpired(opts2 = {}) {
+    if (destroyed) return { removed: [], count: 0 };
+
+    const cutoff =
+      typeof opts2.olderThanMs === "number"
+        ? opts2.olderThanMs
+        : expireTimeoutMs;
+    const removed = [];
+    const currentTime = now();
+
+    for (const [sessionId, session] of sessions) {
+      if (
+        isLiveStatus(session.status) ||
+        currentTime - session.lastHeartbeat <= cutoff
+      ) {
+        continue;
+      }
+
+      stopMonitor(sessionId);
+      sessions.delete(sessionId);
+      removed.push(sessionId);
+      notifyRemoved(session);
+    }
+
+    if (removed.length > 0) persist();
+    return { removed, count: removed.length };
+  }
+
   function heartbeat(sessionId, partialMeta = null) {
     const normalized = normalizeSessionId(sessionId);
     const session = sessions.get(normalized);
-    if (!session) return false;
+    if (!session) {
+      // self-heal은 위치 정보(worktreePath 또는 cwd)가 있는 heartbeat에서만
+      // 발동한다. UserPromptSubmit heartbeat는 항상 worktreePath를 보내므로
+      // SessionStart register POST drop 복구 경로는 커버되고, taskSummary만 담은
+      // 빈약한 heartbeat로 위치 없는 가비지 세션이 register 되는 것은 막는다
+      // (그 경우는 기존대로 false → 400/heartbeat failed).
+      const hasLocator =
+        partialMeta &&
+        typeof partialMeta === "object" &&
+        !Array.isArray(partialMeta) &&
+        ((typeof partialMeta.worktreePath === "string" &&
+          partialMeta.worktreePath.length > 0) ||
+          (typeof partialMeta.cwd === "string" && partialMeta.cwd.length > 0));
+      const canSelfHeal = Boolean(normalized) && hasLocator;
+      if (!canSelfHeal) return false;
+
+      // 미등록 세션 heartbeat = SessionStart register POST가 drop된 경우.
+      // self-heal로 register 복구(영구 미등록 방지).
+      //
+      // sessionKind는 명시값이 없으면 "interactive"로 본다. 실제 복구 경로인
+      // heartbeatInteractiveSession은 worktreePath/host/taskSummary만 보내고
+      // sessionKind는 생략하는데, sanitizeSession 기본값("headless")으로 떨어지면
+      // 복구된 Claude 세션이 30초 local timeout을 받아 idle/5분 TTL을 잃고 곧장
+      // stale로 전이돼 getActive()/peer discovery에서 사라진다(이 PRD가 고치려던
+      // 원래 증상의 재현). heartbeat 기반 liveness로 살아나는 세션은 interactive다.
+      const sanitizedKind =
+        typeof partialMeta.sessionKind === "string"
+          ? partialMeta.sessionKind
+          : "interactive";
+      const healed = sanitizeSession(
+        {
+          ...partialMeta,
+          sessionId: normalized,
+          sessionKind: sanitizedKind,
+          status: "active",
+          lastHeartbeat: now(),
+        },
+        normalized,
+      );
+      if (!healed) return false;
+
+      sessions.set(normalized, healed);
+      startMonitor(normalized);
+      persist();
+      emitter?.emit("synapse.session.started", {
+        sessionId: normalized,
+        session: cloneSession(healed),
+      });
+      return true;
+    }
 
     const wasRemote = session.isRemote;
     const updated = { ...session, lastHeartbeat: now(), status: "active" };
@@ -492,6 +573,7 @@ export function createSynapseRegistry(opts = {}) {
   return Object.freeze({
     register,
     unregister,
+    pruneExpired,
     heartbeat,
     getActive,
     getAll,

package/hub/workers/codex-mcp.mjs

@@ -1,4 +1,7 @@
 // hub/workers/codex-mcp.mjs — Codex MCP 서버 래퍼
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
@@ -94,13 +97,78 @@ function normalizeStructuredContent(structuredContent, fallbackText = "") {
   return { threadId, content };
 }
 
-function buildCodexArguments(prompt, opts = {}) {
+/**
+ * Read a top-level TOML scalar (`key = "value"` / `key = 'value'` /
+ * `key = value`), tolerating an inline `# comment` and surrounding whitespace.
+ * Returns the trimmed value, or null when the key is absent/empty. Intentionally
+ * tiny — the per-profile files only carry `model` + `model_reasoning_effort`.
+ *
+ * @param {string} raw
+ * @param {string} key
+ * @returns {string|null}
+ */
+function readTomlScalar(raw, key) {
+  const re = new RegExp(
+    `^\\s*${key}\\s*=\\s*(?:"([^"\\n]*)"|'([^'\\n]*)'|([^#\\n]*?))\\s*(?:#.*)?$`,
+    "m",
+  );
+  const match = raw.match(re);
+  if (!match) return null;
+  const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+  return value || null;
+}
+
+/**
+ * Resolve a Codex effort profile name (e.g. "gpt55_high") to its concrete
+ * `model` + reasoning effort. SSOT = the per-profile file written by
+ * `tfx setup` at `~/.codex/<profile>.config.toml`. Falls back to deriving the
+ * effort from the `<...>_<effort>` naming convention when the file is absent.
+ *
+ * codex 0.137 removed `profile` from the Codex MCP tool schema, so we translate
+ * the profile into the still-accepted `model` + `config` fields instead of
+ * forwarding `profile` (which now hard-fails with "unknown field `profile`").
+ *
+ * @param {string} profileName
+ * @returns {{ model: string|null, reasoningEffort: string|null }}
+ */
+export function resolveCodexProfileConfig(profileName) {
+  const result = { model: null, reasoningEffort: null };
+  if (typeof profileName !== "string" || !profileName) return result;
+
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  try {
+    const raw = readFileSync(
+      join(codexHome, `${profileName}.config.toml`),
+      "utf8",
+    );
+    result.model = readTomlScalar(raw, "model");
+    result.reasoningEffort = readTomlScalar(raw, "model_reasoning_effort");
+  } catch {
+    // Profile file absent (non-file alias). Derive effort from the naming
+    // convention; leave model unset so codex uses its config.toml default.
+    const suffix = /_(xhigh|high|med|medium|low)$/.exec(profileName);
+    if (suffix) {
+      const map = {
+        xhigh: "xhigh",
+        high: "high",
+        med: "medium",
+        medium: "medium",
+        low: "low",
+      };
+      result.reasoningEffort = map[suffix[1]] || null;
+    }
+  }
+  return result;
+}
+
+export function buildCodexArguments(prompt, opts = {}) {
   const args = { prompt };
 
   if (typeof opts.cwd === "string" && opts.cwd) args.cwd = opts.cwd;
   if (typeof opts.model === "string" && opts.model) args.model = opts.model;
-  if (typeof opts.profile === "string" && opts.profile)
-    args.profile = opts.profile;
+  // NOTE: `profile` is intentionally NOT forwarded as a Codex tool argument.
+  // codex 0.137 dropped it from the tool schema; it is resolved into
+  // `model` + `config.model_reasoning_effort` just before return (see below).
   if (typeof opts.approvalPolicy === "string" && opts.approvalPolicy) {
     args["approval-policy"] = opts.approvalPolicy;
   }
@@ -120,6 +188,22 @@ function buildCodexArguments(prompt, opts = {}) {
     args["compact-prompt"] = opts.compactPrompt;
   }
 
+  // Map the effort profile to model + reasoning effort instead of forwarding the
+  // (0.137-rejected) `profile` field. Explicit opts.model wins over the profile;
+  // profile effort merges on top of any opts.config.
+  if (typeof opts.profile === "string" && opts.profile) {
+    const resolved = resolveCodexProfileConfig(opts.profile);
+    if (resolved.model && typeof args.model !== "string") {
+      args.model = resolved.model;
+    }
+    if (resolved.reasoningEffort) {
+      args.config = {
+        ...(args.config || {}),
+        model_reasoning_effort: resolved.reasoningEffort,
+      };
+    }
+  }
+
   return args;
 }
 

package/package.json

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

package/scripts/tfx-route.sh

@@ -123,7 +123,11 @@ _preflight_check_gh_auth
 # top-level sandbox/approval_mode와 의미가 다르다. 이 값이 "approve"이면
 # codex exec이 non-TTY subprocess에서 승인 대기로 stall하므로 감지 대상에서 제외.
 # (refs: tellang/triflux#66, Yeachan-Heo/oh-my-codex#1478)
-_CODEX_CONFIG="${HOME}/.codex/config.toml"
+# TFX_CODEX_CONFIG override: integration tests that run the full route script
+# point this at an isolated tmpdir config so the MCP config-swap never mutates
+# the real ~/.codex/config.toml (non-hermetic corruption guard). Defaults to the
+# real path for normal runs.
+_CODEX_CONFIG="${TFX_CODEX_CONFIG:-${HOME}/.codex/config.toml}"
 _CODEX_HAS_SANDBOX=""
 if [[ -f "$_CODEX_CONFIG" ]] && awk '
   /^\[{1,2}mcp_servers\..*\.tools\./ { in_mcp_tool=1; next }
@@ -460,6 +464,85 @@ prepend_codex_north_star() {
   rm -f "$tmp_file" 2>/dev/null || true
 }
 
+# prepend_skill: opt-in 으로 등록된 스킬의 SKILL.md 본문을 프롬프트 앞에 주입한다.
+# 활성 조건은 TFX_INJECT_SKILL env (tfx-auto 가 --skill <name> 으로 set). 미설정이면
+# 현행 동작 그대로 (no-op). CLI-agnostic — codex/agy 레인에서 동일하게 재사용한다.
+# 전달은 prepend_codex_north_star 와 동일하게 printf/cat → temp file 만 사용하므로
+# $ / 백슬래시(₩) 같은 특수문자를 셸 재확장 없이 리터럴로 보존한다 (parse-safe).
+# 스킬 경로: ${TFX_SKILLS_DIR:-<repo>/skills}/<name>/SKILL.md.
+prepend_skill() {
+  local prompt="${1:-}"
+  local skill_name="${TFX_INJECT_SKILL:-}"
+  if [[ -z "$skill_name" ]]; then
+    printf '%s' "$prompt"
+    return 0
+  fi
+  # 경로 탈출 방지: skill_name 은 skills/ 하위 단일 디렉토리 이름만 허용한다.
+  if [[ "$skill_name" == *"/"* || "$skill_name" == *".."* ]]; then
+    echo "[tfx-route] WARNING: TFX_INJECT_SKILL='${skill_name}' 에 경로 구분자/.. 포함 — 주입 거부" >&2
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  local skills_dir="${TFX_SKILLS_DIR:-}"
+  if [[ -z "$skills_dir" ]]; then
+    skills_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)/skills"
+  fi
+  local skill_file="${skills_dir}/${skill_name}/SKILL.md"
+  if [[ ! -r "$skill_file" ]]; then
+    echo "[tfx-route] WARNING: TFX_INJECT_SKILL='${skill_name}' 스킬을 찾지 못함 ($skill_file) — 주입 생략" >&2
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  local tmp_file
+  tmp_file="$(mktemp "${TFX_TMP:-${TMPDIR:-/tmp}}/tfx-skill-prompt.XXXXXX" 2>/dev/null)" || {
+    printf '%s' "$prompt"
+    return 0
+  }
+
+  if ! {
+    printf '%s\n' "--- SKILL: ${skill_name} (apply this methodology to the task below) ---"
+    cat "$skill_file"
+    if [[ -s "$skill_file" ]]; then
+      local last_byte
+      last_byte="$(tail -c 1 "$skill_file" 2>/dev/null || true)"
+      [[ -n "$last_byte" ]] && printf '\n'
+    fi
+    printf '%s\n' "--- END SKILL ---"
+    printf '%s' "$prompt"
+  } > "$tmp_file"; then
+    rm -f "$tmp_file" 2>/dev/null || true
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  cat "$tmp_file" 2>/dev/null || printf '%s' "$prompt"
+  rm -f "$tmp_file" 2>/dev/null || true
+}
+
+# append_agy_anti_overclaim: agy(Gemini 3.x) 레인 전용 완료/grounding 규율 블록을
+# 프롬프트 *뒤*에 붙인다. Gemini 3.x 는 과신(overconfidence) outlier 라 거짓 완료
+# 주장·환각이 잦다 (AA-Omniscience 실증). 부정 제약은 Gemini 3 공식 가이드 권고대로
+# 프롬프트 END 에 배치하고, blanket "do not guess" 대신 "주어진 context 로 추론 +
+# 정확한 abstention 우선" 형태로 적는다 (open-ended negative 는 역효과). TFX_AGY_ANTI_OVERCLAIM=0 으로 opt-out.
+append_agy_anti_overclaim() {
+  local prompt="${1:-}"
+  case "${TFX_AGY_ANTI_OVERCLAIM:-1}" in
+    0|false|FALSE|off|OFF|no|NO)
+      printf '%s' "$prompt"
+      return 0
+      ;;
+  esac
+
+  printf '%s' "$prompt"
+  printf '\n\n%s\n' "--- COMPLETION & GROUNDING DISCIPLINE (apply strictly) ---"
+  printf '%s\n' "- Claim done/fixed/passing ONLY after running the check in this turn and seeing its output. With no fresh evidence, report what is still unverified instead of asserting success."
+  printf '%s\n' "- Ground every answer in the provided context and the actual repository. If something is not verifiable from what you can see, say 'No Info / 확인 불가' and stop rather than inventing plausible-but-unconfirmed details."
+  printf '%s\n' "- Use the provided context for deductions and prefer accurate abstention over confident guessing."
+  printf '%s' "--- END DISCIPLINE ---"
+}
+
 read_probe_state() {
   local pid="$1"
   local state_file="${TFX_PROBE_STATE_FILE:-${TFX_PROBE_DIR}/${pid}.json}"
@@ -2674,6 +2757,14 @@ FALLBACK_EOF
       _codex_full_prompt_with_sentinel="$(prepend_codex_north_star "$FULL_PROMPT"; printf '%s' "$_codex_prompt_sentinel")"
       FULL_PROMPT="${_codex_full_prompt_with_sentinel%"$_codex_prompt_sentinel"}"
     fi
+    # Opt-in 스킬 주입 (TFX_INJECT_SKILL). north-star 와 동일한 sentinel 패턴으로
+    # trailing newline 을 보존한다. 미설정이면 prepend_skill 이 no-op.
+    if [[ -n "${TFX_INJECT_SKILL:-}" ]]; then
+      local _codex_skill_sentinel="__TFX_CODEX_SKILL_END_${$}_${RANDOM}__"
+      local _codex_skill_prompt
+      _codex_skill_prompt="$(prepend_skill "$FULL_PROMPT"; printf '%s' "$_codex_skill_sentinel")"
+      FULL_PROMPT="${_codex_skill_prompt%"$_codex_skill_sentinel"}"
+    fi
     codex_transport_effective="exec"
     if [[ "$TFX_CODEX_TRANSPORT" != "exec" ]]; then
       run_codex_mcp "$FULL_PROMPT" "$use_tee" || exit_code=$?
@@ -2778,6 +2869,18 @@ EOF
       _agy_full_prompt_with_sentinel="$(prepend_codex_north_star "$FULL_PROMPT"; printf '%s' "$_agy_prompt_sentinel")"
       FULL_PROMPT="${_agy_full_prompt_with_sentinel%"$_agy_prompt_sentinel"}"
     fi
+    # Opt-in 스킬 주입 (TFX_INJECT_SKILL) — codex 레인과 동일.
+    if [[ -n "${TFX_INJECT_SKILL:-}" ]]; then
+      local _agy_skill_sentinel="__TFX_AGY_SKILL_END_${$}_${RANDOM}__"
+      local _agy_skill_prompt
+      _agy_skill_prompt="$(prepend_skill "$FULL_PROMPT"; printf '%s' "$_agy_skill_sentinel")"
+      FULL_PROMPT="${_agy_skill_prompt%"$_agy_skill_sentinel"}"
+    fi
+    # agy(Gemini 3.x) anti-overclaim 규율 블록을 프롬프트 END 에 append. opt-out: TFX_AGY_ANTI_OVERCLAIM=0.
+    local _agy_aoc_sentinel="__TFX_AGY_AOC_END_${$}_${RANDOM}__"
+    local _agy_aoc_prompt
+    _agy_aoc_prompt="$(append_agy_anti_overclaim "$FULL_PROMPT"; printf '%s' "$_agy_aoc_sentinel")"
+    FULL_PROMPT="${_agy_aoc_prompt%"$_agy_aoc_sentinel"}"
     run_antigravity_exec "$FULL_PROMPT" "$use_tee" || exit_code=$?
     if [[ "$exit_code" -ne 0 && "$exit_code" -ne 124 ]]; then
       local agy_stderr_bytes=0

package/skills/tfx-auto/SKILL.md

@@ -28,7 +28,7 @@ triggers:
   - spec-panel
   - business-panel
   - index-repo
-argument-hint: "<command|task> [args...] [--cli auto|codex|antigravity|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-antigravity|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none]"
+argument-hint: "<command|task> [args...] [--cli auto|codex|antigravity|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-antigravity|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none] [--skill <name>]"
 ---
 
 # tfx-auto — 통합 CLI 오케스트레이터
@@ -169,6 +169,7 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 | `--no-claude-native` | false (기본) | Claude native sub-agent 경로 유지 | — |
 | `--no-claude-native` | true | Claude native 경로 disable, CLI 기반 worker 강제 | tfx-route.sh |
 | `--max-iterations` | `0` (기본, unlimited) | `--retry ralph`/`auto-escalate` 상한 | retry-state-machine.mjs |
+| `--skill` | `<name>` | `skills/<name>/SKILL.md` 본문을 codex/agy 프롬프트 앞에 주입 (`TFX_INJECT_SKILL`). 미지정 시 no-op | tfx-route.sh |
 
 ### `--risk-tier` 계약
 
@@ -204,6 +205,37 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 - `--retry ralph` → true ralph state machine (Phase 3, retry-state-machine.mjs)
 - `--retry auto-escalate` → CLI 승격 체인 (Phase 3)
 - `--max-iterations N` (N>0) → ralph/auto-escalate 에 상한 부여
+- `--skill <name>` → `TFX_INJECT_SKILL=<name>` 로 tfx-route.sh 에 전달. 스킬 파일 부재 시 warning 후 주입 생략 (fail-open, 작업은 계속)
+
+### 스킬 주입 (`--skill <name>`)
+
+codex/agy 워커 프롬프트 앞에 등록된 스킬의 방법론을 주입하는 **opt-in** 프레임워크. 설계 근거는 `decision-skill-passing` (omc 레퍼런스 + codex/agy 네이티브 스킬 조사):
+
+- **메커니즘**: `--skill <name>` → tfx-route.sh `TFX_INJECT_SKILL=<name>`. `skills/<name>/SKILL.md` 본문을 `--- SKILL: <name> (apply this methodology...) ---` delimited block 으로 프롬프트 앞에 prepend. codex·agy 레인 공통 (CLI-agnostic, `prepend_skill`).
+- **기본 off**: 미지정이면 no-op → 현행 동작 그대로. 회귀 위험 없음.
+- **파싱 안전**: prepend 는 `printf`/`cat` → temp file 만 사용. codex 는 argv `--` 뒤, agy 는 stdin `printf %s` 로 전달되므로 `$`(codex)·`₩`/백슬래시(agy) 같은 특수문자를 셸 재확장 없이 **리터럴 보존**. 스킬 본문을 그대로 넘겨도 깨지지 않음.
+- **네이티브 스킬을 안 쓰는 이유**: codex `$skill-name`/`/name` 슬래시와 agy `/name` 은 둘 다 **인터랙티브 TUI 전용** → headless one-shot 에서 named-skill 강제 호출 불가 (미문서). 그래서 prose 주입을 채택 (레퍼런스 omc 도 role .md 를 raw prepend, 네이티브 회피).
+
+#### 커맨드→스킬 매핑 (tfx-auto convention, opt-in)
+
+tfx-auto 가 커맨드/agent 별로 주입할 스킬을 고를 때 쓰는 **권고 테이블**. 기본은 매핑 없음 (명시 `--skill` 만 작동) — 부적절한 스킬이 모든 프롬프트에 새는 것을 막는다. 프로젝트가 명시적으로 활성화할 때만 아래를 적용해 `--skill` 을 자동 부여한다.
+
+| 커맨드/agent | 권고 스킬 | 비고 |
+|--------------|-----------|------|
+| (기본) | 없음 | explicit `--skill` 우선 |
+| 프로젝트 정의 | 프로젝트가 지정 | 활성화 시 tfx-auto 가 해당 `--skill` set |
+
+> 매핑된 스킬 파일이 없으면 `prepend_skill` 이 warning 후 주입을 생략한다 (fail-open). 존재하지 않는 매핑을 "주입됨"으로 가정하지 않는다.
+
+#### agy anti-overclaim (자동, agy 레인 전용)
+
+agy(Gemini 3.x) 레인은 `TFX_AGY_ANTI_OVERCLAIM`(기본 on) 으로 완료/grounding 규율 블록을 프롬프트 **END** 에 자동 append (`append_agy_anti_overclaim`). Gemini 3.x 과신(AA-Omniscience 실측: 정확도 53-56% 대비 환각률 88-91%) 대응:
+
+- fresh 증거 없이 done/fixed/passing 주장 금지.
+- 검증 불가 시 `No Info / 확인 불가` 후 중단 (날조 금지).
+- 추론은 주어진 context 로, confident guessing 보다 accurate abstention 우선.
+
+부정 제약은 Gemini 3 공식 가이드대로 **END 배치**하고 blanket "do not guess" 는 역효과라 피한다. opt-out: `TFX_AGY_ANTI_OVERCLAIM=0`.
 
 ### Retry state machine 계약 (legacy autoroute / persist 이관)
 

package/skills/tfx-goal-clarify/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: tfx-goal-clarify
+description: "자연어 아이디어를 Claude Code `/goal` 명령어 한 블록으로 변환하는 clarifier. 모호한 작업 설명을 받아 공식 3축(End state / Stated check / Constraints) + stop bound로 압축해 복붙 가능한 /goal 문자열을 출력. '/goal로 만들어', 'goal 프롬프트', 'goal 변환', 'clarify goal', 'goal 양식', '자율 작업 시작' 같은 요청에 사용."
+triggers:
+  - goal 프롬프트
+  - goal 변환
+  - clarify goal
+  - goal 양식
+  - /goal 만들어
+  - goal-clarify
+  - tfx-goal-clarify
+  - 자율 작업 만들어
+argument-hint: "<목표 자연어> [--tier 1|2|3]"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Write
+---
+
+# tfx-goal-clarify — 자연어 → `/goal` 블록 변환기
+
+> tfx-interview의 슬림 fork. **인터뷰 산출물을 Action Plan 대신 `/goal` 블록 한 덩어리로만** 출력한다.
+> 공식 `/goal` 3축(End state / Stated check / Constraints) + `or stop after N turns`를 강제한다.
+
+## 용도
+
+Claude Code 2.1.139+의 `/goal` 명령어에 넣을 프롬프트를 자연어 아이디어로부터 구조화한다. `/goal`은 평가자(Haiku)가 transcript만 보고 yes/no 판정하므로, **측정 불가능한 조건은 무한 루프 또는 환각 yes**를 유발한다. 이 스킬은 그 함정을 회피한다.
+
+**비교**:
+- `tfx-interview`: 일반 요구사항 인터뷰 → 전체 Action Plan 산출
+- `tfx-goal-clarify`: **/goal 블록 한 덩어리만** 산출 (5분 내 완료 목표)
+- `gstack-office-hours`: 제품 아이디어 단계 (코드 이전)
+
+## 입력 처리
+
+`ARGUMENTS: <자연어 목표>`가 들어오면 첫 입력으로 사용. 없으면 사용자에게 요청.
+
+`--tier N` 플래그:
+- `1` = one-liner (3턴 이내 작업)
+- `2` = standard 3-part (기본값, 10턴 이내)
+- `3` = 9-section (다중 모듈/다일 작업)
+
+## 워크플로우
+
+### Step 1: 분류 + 초기 ambiguity 측정
+
+코드베이스 컨텍스트 살펴보기 (선택적):
+```bash
+# 사용자가 어떤 repo에서 호출했는지 확인
+git rev-parse --show-toplevel 2>/dev/null
+```
+
+자연어 입력을 3축으로 분해:
+| 축 | 질문 | 점수 (0~1) |
+|----|------|-----------|
+| End state | 완료를 무엇으로 증명? | goal |
+| Check | Claude가 어떤 명령/출력으로 보여줄 수 있나? | constraints |
+| Constraints | 절대 건드리면 안 될 것은? | criteria |
+
+`ambiguity = 1 - (end_state×0.4 + check×0.3 + constraints×0.3)`
+
+Gemini 위임 (tfx-interview와 동일):
+```bash
+Bash("bash ~/.claude/scripts/tfx-route.sh gemini '<analysis prompt>'")
+```
+
+Gemini 미사용 환경(m5 등 SSH 원격)에서는 Claude가 직접 채점.
+
+### Step 2: 적응형 인터뷰 (AskUserQuestion 사용, Tier별 질문 수 가변)
+
+**반드시 Claude Code 네이티브 `AskUserQuestion` 도구를 사용**한다. 자유 텍스트 질의 금지 — 사용자가 옵션 중에서 선택하도록 구조화한다.
+
+**Tier별 필수 축**:
+| Tier | 핵심 축 (필수) | 보조 축 (조건부) | 질문 수 |
+|------|---------------|----------------|---------|
+| 1 | End state, Bound | — | 1~2 |
+| 2 | End state, Check, Constraints, Bound | Scope | 3~5 |
+| 3 | End state, Check, Constraints, Scope, Priority, Plan, Bound | Rollback, Output artifact | 5~8 |
+
+**ambiguity < 20% 도달 시 즉시 종료** (남은 질문 스킵).
+
+#### AskUserQuestion 호출 패턴 (예시)
+
+각 축마다 다음 형태로 호출. **options는 사용자 입력 기반으로 동적 생성** + 사용자가 "Other"로 직접 입력 가능.
+
+**Q1. End state (모든 Tier 필수)**
+```json
+{
+  "questions": [{
+    "question": "이 작업이 끝났다는 걸 어떤 단일 측정 가능한 결과로 증명하나요?",
+    "header": "End state",
+    "multiSelect": false,
+    "options": [
+      {"label": "테스트 exit code", "description": "예: pnpm test <path> exits 0"},
+      {"label": "패턴 카운트 0", "description": "예: rg \"legacy\" src returns 0 hits"},
+      {"label": "타입체크 통과", "description": "예: pnpm typecheck exits 0"},
+      {"label": "빌드 성공", "description": "예: pnpm build exits 0"}
+    ]
+  }]
+}
+```
+
+**Q2. Check 명령 (Tier 2/3)**
+사용자 End state 선택 후 그 결과를 어떻게 transcript에 노출시킬지 — 보통 자동 추론(End state가 이미 명령형이면 그대로 사용). 모호하면 명령 후보 3-4개 옵션.
+
+**Q3. Scope (Tier 2/3, 코드베이스 컨텍스트 있을 때만)**
+```json
+{
+  "questions": [{
+    "question": "변경 허용 범위는 어디까지인가요?",
+    "header": "Scope",
+    "multiSelect": true,
+    "options": [
+      {"label": "src/<module>/만", "description": "단일 모듈 한정"},
+      {"label": "src/ 전체", "description": "소스 전체"},
+      {"label": "tests/ 포함", "description": "테스트도 수정 가능"},
+      {"label": "package.json 가능", "description": "의존성 추가 허용"}
+    ]
+  }]
+}
+```
+
+**Q4. Constraints (Tier 2/3 필수)**
+```json
+{
+  "questions": [{
+    "question": "절대 변경하면 안 되는 것은 무엇인가요?",
+    "header": "Constraints",
+    "multiSelect": true,
+    "options": [
+      {"label": "공개 API 시그니처", "description": "props/exports 유지"},
+      {"label": "기존 테스트", "description": "tests/legacy/ 등 보호"},
+      {"label": "DB 스키마", "description": "migration 금지"},
+      {"label": "없음 (None)", "description": "제약 없이 진행"}
+    ]
+  }]
+}
+```
+
+**Q5. Priority (Tier 3만)**
+```json
+{
+  "questions": [{
+    "question": "충돌 시 어느 쪽을 우선하나요?",
+    "header": "Priority",
+    "multiSelect": false,
+    "options": [
+      {"label": "타입 안전 > 테스트 > 시각", "description": "타입체크 우선"},
+      {"label": "테스트 > 타입 > 시각", "description": "기존 동작 보존"},
+      {"label": "사용자 정의", "description": "직접 입력"}
+    ]
+  }]
+}
+```
+
+**Q6. Bound (모든 Tier 필수, 마지막)**
+```json
+{
+  "questions": [{
+    "question": "최대 얼마나 돌릴까요? (Stop 조건)",
+    "header": "Stop bound",
+    "multiSelect": false,
+    "options": [
+      {"label": "10 turns", "description": "단순 수정 작업"},
+      {"label": "20 turns", "description": "중간 규모 (기본 권장)"},
+      {"label": "30 turns", "description": "마이그레이션"},
+      {"label": "60 turns", "description": "다중 모듈 (Tier 3)"}
+    ]
+  }]
+}
+```
+
+**Q7. Rollback (Tier 3 선택)**
+실패 시 어떻게 복구할지 — git revert, checkpoint commit 빈도 등.
+
+**Q8. Output artifact (Tier 3 선택)**
+산출물 형태 — PR description, 보고서 파일, 단순 코드 변경 등.
+
+#### 적응형 종료 조건
+
+각 응답 후 ambiguity 재계산:
+```
+if ambiguity < 0.20:
+  → 즉시 Step 3 (남은 질문 스킵)
+elif 모든 필수 축 답변 완료:
+  → Step 3
+elif 질문 수 >= Tier별 상한:
+  → Step 3 (남은 ambiguity는 사용자가 직접 편집할 영역으로 표시)
+else:
+  → 다음 질문
+```
+
+#### Fallback: AskUserQuestion 미사용 환경 (Codex/Gemini CLI 등)
+
+자유 텍스트로 한 질문씩 던지되, 위 옵션 리스트를 보기로 제시.
+
+### Step 3: `/goal` 블록 조립
+
+**Tier 1 (one-liner)** — 단순 명령:
+```
+/goal <end_state> [or stop after N turns]
+```
+
+**Tier 2 (standard, 기본)**:
+```
+/goal
+End state: {end_state}
+Check: {check_command}
+Constraints: {constraints}
+Bound: or stop after {N} turns
+```
+
+**Tier 3 (9-section)** — 다중 모듈/긴 작업:
+```
+/goal
+GOAL: {goal}
+CONTEXT: {context}
+CONSTRAINTS: {constraints}
+PRIORITY: {priority}
+PLAN: {plan_steps}
+DONE WHEN: {done_when}
+VERIFY: {verify_commands}
+OUTPUT: {output_artifacts}
+STOP RULES: or stop after {N} turns
+```
+
+### Step 4: 사용자 표시 + 검증
+
+출력 형식 (반드시 이 순서):
+
+```
+📊 Ambiguity: {initial}% → {final}% (목표 < 20%)
+   - End state: {pct}%
+   - Check: {pct}%
+   - Constraints: {pct}%
+
+📋 4000자 한도: {used}/{4000} chars
+
+📦 /goal 블록 (Tier {N}):
+
+────────── 복붙 영역 ──────────
+{the assembled /goal block}
+─────────────────────────────────
+
+✅ 검증:
+   - 종료 상태가 측정 가능한가? {Y/N}
+   - Check 명령이 transcript에 결과를 남기는가? {Y/N}
+   - Stop bound가 있는가? {Y/N}
+   - 4000자 이내인가? {Y/N}
+```
+
+### Step 5: 저장 (선택)
+
+기본은 출력만. 사용자가 원하면 저장:
+- 위치: `.tfx/goals/goal-{timestamp}.txt`
+- 형식: 원본 자연어 + 인터뷰 응답 + 최종 /goal 블록
+
+## 출력 후 옵션 (AskUserQuestion)
+
+```
+질문: 이 /goal 블록을 어떻게 처리할까요?
+옵션:
+  - 클립보드 복사: 블록을 클립보드로 복사 (입력창에 붙여넣기만 하면 됨)
+  - 출력만: 화면 출력만 하고 종료
+  - 수정: 특정 축(End state/Check/Constraints) 재질문
+  - Tier 변경: 1↔2↔3 재조립
+```
+
+> `/goal`은 Claude Code 슬래시 명령어라 **에이전트가 세션 입력창에 대신 전송할 수 없다.**
+> 그래서 "바로 실행" 옵션은 두지 않는다. 사용자가 클립보드에서 입력창에 직접 붙여넣어 실행한다.
+
+### 클립보드 복사 실행 방법
+
+"클립보드 복사" 선택 시 `Bash`로 OS별 클립보드 명령에 블록을 파이프한다.
+블록에 백틱·따옴표가 섞이므로 **임시 파일을 거쳐** 복사한다 (인용 깨짐 방지).
+
+```bash
+# 1) 조립된 /goal 블록을 임시 파일로 기록 (Write 도구 또는 heredoc)
+cat > "${TMPDIR:-/tmp}/tfx-goal-block.txt" <<'GOAL_EOF'
+<the assembled /goal block>
+GOAL_EOF
+
+# 2) OS별 클립보드로 복사 (darwin 우선, fallback chain)
+f="${TMPDIR:-/tmp}/tfx-goal-block.txt"
+if   command -v pbcopy   >/dev/null 2>&1; then pbcopy < "$f"                      # macOS
+elif command -v wl-copy  >/dev/null 2>&1; then wl-copy < "$f"                     # Wayland
+elif command -v xclip    >/dev/null 2>&1; then xclip -selection clipboard < "$f"  # X11
+elif command -v clip.exe >/dev/null 2>&1; then clip.exe < "$f"                    # Windows/WSL
+else echo "클립보드 명령 없음 — 위 출력에서 수동 복사"; fi
+```
+
+복사 성공 시 `✅ 클립보드에 복사됨 — 입력창에 붙여넣어 실행하세요.` 를 출력한다.
+
+## 동작 규칙
+
+1. **출력 우선**: 최종 산출물은 항상 `/goal` 블록 한 덩어리. 부수 설명은 위/아래에만.
+2. **4000자 강제**: 한도 초과 시 자동으로 PLAN/CONTEXT를 압축.
+3. **Stop bound 강제**: 사용자가 명시 안 해도 `or stop after 20 turns`를 기본 삽입 (Tier 2/3).
+4. **Check 강제**: 평가자가 transcript만 보므로 Check 없는 블록은 거부.
+5. **Constraints 비어있어도 OK**: 'none' 명시.
+6. **언어**: 사용자가 한국어로 입력하면 인터뷰는 한국어, /goal 블록은 영어 (Claude Code가 영어 명령에 더 안정적).
+
+## 안티패턴 (자동 거부)
+
+다음 End state는 거부:
+- "production-ready", "better", "modern", "clean" — 주관적
+- "all tests pass" without 명시된 테스트 위치 — 범위 폭발
+- "refactor everything" — 범위 무제한
+
+거부 시 사용자에게:
+```
+⚠️ End state "{...}"는 평가자가 측정할 수 없습니다.
+   다음 중 어느 형태로 바꿀까요?
+   1) 명령어 exit code (예: pnpm test exits 0)
+   2) 파일/문자열 카운트 (예: rg X returns 0 hits)
+   3) 파일 변경 여부 (예: git diff --stat shows ≤3 files changed)
+```
+
+## Quick Examples
+
+### Tier 1 입력/출력
+```
+입력: "auth 테스트 다 통과시켜"
+출력: /goal pnpm test test/auth exits 0, or stop after 15 turns
+```
+
+### Tier 2 입력/출력
+```
+입력: "레거시 auth API 호출들을 v2로 마이그레이션"
+출력:
+/goal
+End state: src/legacy/auth/*.ts 의 모든 호출이 src/auth/v2 로 마이그레이션됨
+Check: `pnpm test src/auth` exits 0 AND `rg "legacy/auth" src` returns 0 hits
+Constraints: tests/legacy/는 수정 금지, package.json 의존성 추가 금지
+Bound: or stop after 30 turns
+```
+
+### Tier 3 입력/출력
+```
+입력: "users 모듈 전체를 새 design system으로 갈아엎고 PR 만들어"
+출력:
+/goal
+GOAL: src/users/** 의 모든 React 컴포넌트를 @company/ds-v3로 마이그레이션
+CONTEXT: 기존은 @company/ds-v2, 디자인 토큰은 docs/design/v3.md, 18개 컴포넌트
+CONSTRAINTS:
+  - tests/users/ snapshot 갱신 외 변경 금지
+  - props 시그니처 유지 (caller 영향 없음)
+  - i18n key 변경 금지
+PRIORITY: 시각적 회귀 < 타입 안전성 < 테스트 통과
+PLAN:
+  1. 컴포넌트 인벤토리 추출
+  2. v2→v3 mapping 표 생성
+  3. 각 컴포넌트 변환 + snapshot 갱신
+  4. PR description 작성
+DONE WHEN: 18/18 컴포넌트 마이그레이션 + 모든 snapshot 통과 + PR 본문 생성
+VERIFY: `pnpm typecheck` exits 0 AND `pnpm test src/users` exits 0 AND `rg "ds-v2" src/users` returns 0 hits
+OUTPUT: PR description in .claude/scratch/pr-users-ds-v3.md
+STOP RULES: or stop after 60 turns, or if token spend exceeds 500K
+```
+
+## 토큰 예산
+
+| 단계 | Claude | Gemini |
+|------|--------|--------|
+| 초기 분류 | ~0.5K | ~1K |
+| 3축 인터뷰 (Q1~Q3) | ~1K | ~3K |
+| /goal 블록 조립 | ~0.5K | ~1K |
+| **총합** | **~2K** | **~5K** |
+
+Gemini 없으면 Claude 단독 ~5K.
+
+## 사용 예
+
+```
+/tfx-goal-clarify "auth 마이그레이션"
+/tfx-goal-clarify "테스트 다 고쳐" --tier 1
+/tfx-goal-clarify "users 모듈 design system 갈아엎기" --tier 3
+/goal 변환 "스냅샷 갱신해서 CI 그린"
+```