triflux 10.20.0 → 10.20.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "triflux",
       "description": "Tri-CLI orchestrator for Claude Code. Routes tasks across Claude + Codex + Gemini with consensus intelligence, natural language routing, 42 skills, and cross-model review.",
-      "version": "10.20.0",
+      "version": "10.20.1",
       "author": {
         "name": "tellang"
       },
@@ -30,5 +30,5 @@
       ]
     }
   ],
-  "version": "10.20.0"
+  "version": "10.20.1"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.20.0",
+  "version": "10.20.1",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "author": {
     "name": "tellang"

package/bin/triflux.mjs

@@ -77,6 +77,7 @@ import {
   getVersion,
   getWindowsHubAutostartStatus,
   hasProfileSection,
+  isSetupUserStateFile,
   LEGACY_CODEX_MODELS,
   REQUIRED_CODEX_PROFILES,
   replaceProfileSection,
@@ -1206,6 +1207,7 @@ function cmdSetup(options = {}) {
       if (existsSync(refSrc)) {
         mkdirSync(refDst, { recursive: true });
         for (const refFile of readdirSync(refSrc)) {
+          if (isSetupUserStateFile(refFile)) continue;
           const rSrc = join(refSrc, refFile);
           const rDst = join(refDst, refFile);
           if (statSync(rSrc).isFile()) {

package/hooks/hook-registry.json

@@ -264,6 +264,19 @@
         "blocking": false,
         "description": "서브에이전트 결과 품질 체크"
       }
+    ],
+    "PreCompact": [
+      {
+        "id": "tfx-pre-compact-snapshot",
+        "source": "triflux",
+        "matcher": "*",
+        "command": "node \"${PLUGIN_ROOT}/hooks/pre-compact-snapshot.mjs\"",
+        "priority": 0,
+        "enabled": true,
+        "timeout": 3,
+        "blocking": false,
+        "description": "compact 직전 repo-local 진행 상태 스냅샷 주입 (#245)"
+      }
     ]
   }
 }

package/hooks/hooks.json

@@ -84,6 +84,18 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/pre-compact-snapshot.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// hooks/pre-compact-snapshot.mjs — PreCompact hook
+//
+// Compaction 직전에 짧은 상태 스냅샷을 주입한다. 민감 데이터는 읽지 않고,
+// repo-local 상태와 git 요약만 3KB 이하로 제한한다.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAX_CONTEXT_BYTES = 3000;
+const STALE_RUN_MS = 30 * 60 * 1000;
+const PROJECT_ROOT = process.env.CLAUDE_CWD || process.cwd();
+
+function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function git(args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: PROJECT_ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function summarizeGit() {
+  const branch =
+    git(["branch", "--show-current"]) || git(["rev-parse", "--short", "HEAD"]);
+  const status = git(["status", "--short"]);
+  const rows = status ? status.split(/\r?\n/).filter(Boolean) : [];
+  return {
+    branch: branch || "unknown",
+    dirty: rows.length,
+    sample: rows.slice(0, 8),
+  };
+}
+
+function readJsonIfSmall(path, maxBytes = 24_000) {
+  try {
+    if (!existsSync(path)) return null;
+    if (statSync(path).size > maxBytes) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function summarizeModeState(root) {
+  const stateDir = join(root, ".omx", "state");
+  if (!existsSync(stateDir)) return [];
+  try {
+    return readdirSync(stateDir)
+      .filter((name) => name.endsWith("-state.json"))
+      .flatMap((name) => {
+        const state = readJsonIfSmall(join(stateDir, name));
+        if (!state || state.active === false) return [];
+        return [
+          {
+            mode: state.mode || name.replace(/-state\.json$/, ""),
+            phase: state.current_phase || state.phase || null,
+            active: state.active !== false,
+          },
+        ];
+      })
+      .slice(0, 8);
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRetryState(input) {
+  const sessionId = input.session_id || input.sessionId || "";
+  if (!sessionId) return null;
+  const candidates = [
+    join(PROJECT_ROOT, ".omc", "state", `retry-${sessionId}.json`),
+    join(homedir(), ".omc", "state", `retry-${sessionId}.json`),
+  ];
+  for (const path of candidates) {
+    const state = readJsonIfSmall(path);
+    if (!state) continue;
+    return {
+      phase: state.phase || state.current_phase || null,
+      iteration: state.iteration ?? state.retry_count ?? null,
+      max: state.max_iterations ?? state.max ?? null,
+    };
+  }
+  return null;
+}
+
+function countStaleSwarmRuns(nowMs = Date.now()) {
+  const logsRoot = join(PROJECT_ROOT, ".triflux", "swarm-logs");
+  if (!existsSync(logsRoot)) return 0;
+  try {
+    return readdirSync(logsRoot, { withFileTypes: true }).filter((entry) => {
+      if (!entry.isDirectory() || !entry.name.startsWith("run-")) return false;
+      const eventPath = join(logsRoot, entry.name, "swarm-events.jsonl");
+      if (!existsSync(eventPath)) return false;
+      try {
+        return nowMs - statSync(eventPath).mtimeMs > STALE_RUN_MS;
+      } catch {
+        return false;
+      }
+    }).length;
+  } catch {
+    return 0;
+  }
+}
+
+function truncateUtf8(text, maxBytes) {
+  let output = text;
+  while (Buffer.byteLength(output, "utf8") > maxBytes) {
+    output = output.slice(0, Math.max(0, output.length - 200));
+  }
+  return output;
+}
+
+export function buildSnapshot(input = readStdinJson()) {
+  const gitState = summarizeGit();
+  const activeModes = summarizeModeState(PROJECT_ROOT);
+  const retry = summarizeRetryState(input);
+  const staleSwarmRuns = countStaleSwarmRuns();
+
+  const lines = [
+    "[triflux pre-compact snapshot]",
+    `cwd: ${PROJECT_ROOT}`,
+    `git: ${gitState.branch}; dirty=${gitState.dirty}`,
+  ];
+  if (gitState.sample.length) {
+    lines.push(`dirty_sample: ${gitState.sample.join(" | ")}`);
+  }
+  if (activeModes.length) {
+    lines.push(
+      `active_modes: ${activeModes
+        .map((m) => `${m.mode}${m.phase ? `:${m.phase}` : ""}`)
+        .join(", ")}`,
+    );
+  }
+  if (retry) {
+    lines.push(
+      `retry: phase=${retry.phase || "-"} iteration=${retry.iteration ?? "-"}/${retry.max ?? "-"}`,
+    );
+  }
+  if (staleSwarmRuns > 0) {
+    lines.push(`stale_swarm_runs: ${staleSwarmRuns}`);
+  }
+
+  return truncateUtf8(lines.join("\n"), MAX_CONTEXT_BYTES);
+}
+
+function main() {
+  const snapshot = buildSnapshot();
+  if (!snapshot.trim()) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreCompact",
+        additionalContext: snapshot,
+      },
+    }),
+  );
+}
+
+try {
+  if (import.meta.url.endsWith(process.argv[1]?.split(/[\\/]/).pop() || "")) {
+    main();
+  }
+} catch {
+  process.exit(0);
+}

package/hub/team/synapse-cli.mjs

@@ -4,7 +4,7 @@
 // so the CLI works even when Hub is offline.
 
 import { execFile } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
@@ -15,6 +15,15 @@ const DEFAULT_REGISTRY_CANDIDATES = [
   ".triflux/synapse/registry.json",
   join(homedir(), ".claude", "cache", "tfx-hub", "synapse-registry.json"),
 ];
+const DEFAULT_SWARM_LOGS_DIR = ".triflux/swarm-logs";
+const STALE_AFTER_MS = 30 * 60 * 1000;
+const STATUS_PRIORITY = {
+  active: 3,
+  running: 3,
+  completed: 2,
+  failed: 2,
+  stale: 1,
+};
 
 function gitExec(args, cwd) {
   return new Promise((res, rej) => {
@@ -55,10 +64,228 @@ function loadRegistrySnapshot(path) {
   }
 }
 
+function parseJsonLines(path) {
+  try {
+    return readFileSync(path, "utf8")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+function normalizeRunId(name) {
+  return String(name || "").replace(/^run-/, "");
+}
+
+function eventTimeMs(event) {
+  const ms = Date.parse(String(event?.ts || ""));
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+function deriveLogStatus(events, lastHeartbeatMs, nowMs) {
+  const stateEvents = events.filter((e) => e.event === "swarm_state");
+  const lastState = stateEvents[stateEvents.length - 1]?.to;
+  if (lastState === "completed" || lastState === "failed") return lastState;
+  if (events.some((e) => e.event === "integration_complete")) {
+    const lastIntegration = [...events]
+      .reverse()
+      .find((e) => e.event === "integration_complete");
+    if (
+      Array.isArray(lastIntegration?.failed) &&
+      lastIntegration.failed.length
+    ) {
+      return "failed";
+    }
+    return "completed";
+  }
+  if (nowMs - lastHeartbeatMs > STALE_AFTER_MS) return "stale";
+  return "active";
+}
+
+function buildLogSession(runDir, nowMs = Date.now()) {
+  const eventPath = join(runDir, "swarm-events.jsonl");
+  if (!existsSync(eventPath)) return null;
+  const events = parseJsonLines(eventPath);
+  if (events.length === 0) return null;
+
+  let statMs = 0;
+  try {
+    statMs = statSync(eventPath).mtimeMs;
+  } catch {}
+
+  const eventMs = events.map(eventTimeMs).filter((ms) => ms > 0);
+  const lastEventMs = eventMs.length ? Math.max(...eventMs) : statMs;
+  const launched = new Set();
+  const completed = new Set();
+  const failed = new Set();
+  for (const event of events) {
+    if (event.event === "shard_launched" && event.shard) {
+      launched.add(event.shard);
+    } else if (event.event === "shard_completed" && event.shard) {
+      completed.add(event.shard);
+    } else if (
+      (event.event === "shard_failed" ||
+        event.event === "shard_launch_failed") &&
+      event.shard
+    ) {
+      failed.add(event.shard);
+    }
+  }
+
+  const runId = normalizeRunId(runDir.split(/[\\/]/).pop());
+  const totalShards = launched.size || completed.size + failed.size;
+  const aliveWorkers = [...launched].filter(
+    (name) => !completed.has(name) && !failed.has(name),
+  ).length;
+
+  return {
+    sessionId: runId,
+    runId,
+    host: "-",
+    branch: "-",
+    dirtyFiles: [],
+    status: deriveLogStatus(events, lastEventMs || nowMs, nowMs),
+    taskSummary: "swarm log run",
+    source: "logs",
+    shards: totalShards ? `${completed.size}/${totalShards}` : "-",
+    workers: totalShards ? `${aliveWorkers} alive` : "-",
+    lastHeartbeat: lastEventMs || null,
+    logDir: runDir,
+  };
+}
+
+export function loadSwarmLogSessions(logsDir, opts = {}) {
+  const nowMs = opts.nowMs ?? Date.now();
+  const root = logsDir || DEFAULT_SWARM_LOGS_DIR;
+  if (!existsSync(root)) return [];
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith("run-"))
+      .map((entry) => buildLogSession(join(root, entry.name), nowMs))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function statusPriority(status) {
+  return STATUS_PRIORITY[status] || 0;
+}
+
+function mergeSession(existing, next) {
+  const status =
+    statusPriority(next.status) > statusPriority(existing.status)
+      ? next.status
+      : existing.status;
+  const source =
+    existing.source && next.source && existing.source !== next.source
+      ? "synapse + logs"
+      : existing.source || next.source || "synapse";
+  return {
+    ...next,
+    ...existing,
+    status,
+    source,
+    shards: next.shards || existing.shards,
+    workers: next.workers || existing.workers,
+    lastHeartbeat: Math.max(
+      Number(existing.lastHeartbeat || 0),
+      Number(next.lastHeartbeat || 0),
+    ),
+    logDir: existing.logDir || next.logDir,
+  };
+}
+
+export function mergeRegistryAndLogSessions(registrySessions, logSessions) {
+  const merged = new Map();
+  for (const session of registrySessions) {
+    const key = String(session.runId || session.sessionId || "");
+    if (!key) continue;
+    merged.set(key, {
+      ...session,
+      source: session.source || "synapse",
+      lastHeartbeat: session.lastHeartbeat || null,
+    });
+  }
+  for (const session of logSessions) {
+    const key = String(session.runId || session.sessionId || "");
+    if (!key) continue;
+    const existing = merged.get(key);
+    merged.set(key, existing ? mergeSession(existing, session) : session);
+  }
+  return [...merged.values()].sort((left, right) => {
+    const rightTs = Number(right.lastHeartbeat || 0);
+    const leftTs = Number(left.lastHeartbeat || 0);
+    return rightTs - leftTs;
+  });
+}
+
+function formatAge(ts, nowMs = Date.now()) {
+  if (!Number.isFinite(Number(ts)) || Number(ts) <= 0) return "-";
+  const seconds = Math.max(0, Math.round((nowMs - Number(ts)) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  return `${hours}h ago`;
+}
+
+function hasSwarmLogFields(sessions) {
+  return sessions.some(
+    (s) =>
+      s.source === "logs" ||
+      s.source === "synapse + logs" ||
+      s.runId ||
+      s.shards ||
+      s.workers,
+  );
+}
+
+function formatSwarmStatus(sessions) {
+  const nowMs = Date.now();
+  const rows = [];
+  rows.push(
+    "RUN_ID                 STATUS     SHARDS   WORKERS  LAST_HEARTBEAT  SOURCE",
+  );
+  rows.push(
+    "─────────────────────  ─────────  ───────  ───────  ──────────────  ──────────────",
+  );
+  for (const s of sessions) {
+    const id = String(s.runId || s.sessionId || "?")
+      .padEnd(21)
+      .slice(0, 21);
+    const status = String(s.status || "active")
+      .padEnd(9)
+      .slice(0, 9);
+    const shards = String(s.shards || "-")
+      .padEnd(7)
+      .slice(0, 7);
+    const workers = String(s.workers || "-")
+      .padEnd(7)
+      .slice(0, 7);
+    const heartbeat = formatAge(s.lastHeartbeat, nowMs).padEnd(14).slice(0, 14);
+    const source = String(s.source || "synapse").slice(0, 20);
+    rows.push(
+      `${id}  ${status}  ${shards}  ${workers}  ${heartbeat}  ${source}`,
+    );
+  }
+  return rows.join("\n");
+}
+
 function formatStatus(sessions) {
   if (!sessions.length) {
     return "no active sessions (synapse-registry empty)";
   }
+  if (hasSwarmLogFields(sessions)) return formatSwarmStatus(sessions);
   const rows = [];
   rows.push("SESSION                HOST    BRANCH    DIRTY   STATE    TASK");
   rows.push(
@@ -84,13 +311,22 @@ function formatStatus(sessions) {
 export async function cmdSynapseStatus(args = [], opts = {}) {
   const jsonOut = args.includes("--json") || opts.json;
   const explicit = extractFlag(args, "--registry");
+  const explicitLogsDir = extractFlag(args, "--logs-dir");
   const path = locateRegistryPath(explicit);
-  const sessions = loadRegistrySnapshot(path);
+  const registrySessions = loadRegistrySnapshot(path);
+  const logsDir = explicitLogsDir || DEFAULT_SWARM_LOGS_DIR;
+  const logSessions = loadSwarmLogSessions(logsDir);
+  const sessions = mergeRegistryAndLogSessions(registrySessions, logSessions);
 
   if (jsonOut) {
     process.stdout.write(
       JSON.stringify(
-        { registry: path, count: sessions.length, sessions },
+        {
+          registry: path,
+          logsDir: existsSync(logsDir) ? logsDir : null,
+          count: sessions.length,
+          sessions,
+        },
         null,
         2,
       ) + "\n",
@@ -98,13 +334,14 @@ export async function cmdSynapseStatus(args = [], opts = {}) {
     return;
   }
 
-  if (!path) {
+  if (!path && logSessions.length === 0) {
     process.stdout.write(
-      "no registry file found (looked for .triflux/synapse-registry.json)\n",
+      "no registry or swarm logs found (looked for .triflux/synapse-registry.json and .triflux/swarm-logs)\n",
     );
     return;
   }
-  process.stdout.write(`registry: ${path}\n`);
+  if (path) process.stdout.write(`registry: ${path}\n`);
+  if (logSessions.length > 0) process.stdout.write(`swarm logs: ${logsDir}\n`);
   process.stdout.write(`${formatStatus(sessions)}\n`);
 }
 

package/package.json

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

package/scripts/session-stale-cleanup.mjs

@@ -5,6 +5,7 @@
  * 새 세션 시작 시 이전 세션의 stale 상태를 정리한다:
  * 1. tfx-multi-state.json — 세션 간 상태 누수 방지 (#62)
  * 2. tfx-route-*-pids — 고아 워커 프로세스 정리 (#62 후속)
+ * 3. git fsmonitor--daemon 누적 감시 — threshold 초과 시 증거 기록 (#214)
  *
  * @see scripts/headless-guard.mjs — 상태 소비자
  * @see scripts/tfx-gate-activate.mjs — 상태 생산자 (ownerPid 기록)
@@ -13,14 +14,17 @@
 
 import { execSync } from "node:child_process";
 import {
+  appendFileSync,
   existsSync,
+  mkdirSync,
   readdirSync,
   readFileSync,
   statSync,
   unlinkSync,
 } from "node:fs";
-import { platform, tmpdir } from "node:os";
-import { join } from "node:path";
+import { homedir, platform, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { findFsmonitorDaemons } from "../hub/lib/process-utils.mjs";
 import { isProcessAlive } from "./lib/process-utils.mjs";
 
 const MULTI_STATE_FILE = join(tmpdir(), "tfx-multi-state.json");
@@ -32,6 +36,8 @@ const PROTECTED_ANCESTOR_NAMES = new Set([
   "gemini.exe",
 ]);
 const PID_REUSE_GRACE_MS = 1000;
+const DEFAULT_FSMONITOR_ALERT_THRESHOLD = 50;
+const FSMONITOR_STALE_MS = 24 * 60 * 60 * 1000;
 
 function normalizeName(name) {
   return String(name || "")
@@ -44,6 +50,33 @@ function parseCreationMs(value) {
   return Number.isFinite(ms) ? ms : null;
 }
 
+function parsePositiveInteger(value, fallback) {
+  const n = Number.parseInt(String(value ?? ""), 10);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function resolveHomeDir() {
+  return (
+    process.env.TRIFLUX_TEST_HOME ||
+    process.env.USERPROFILE ||
+    process.env.HOME ||
+    homedir()
+  );
+}
+
+function defaultFsmonitorAlertLogPath() {
+  return join(resolveHomeDir(), ".omc", "state", "fsmonitor-alert.log");
+}
+
+function summarizeFsmonitorDaemon(proc) {
+  return {
+    pid: proc.pid,
+    parentPid: proc.parentPid,
+    ageMs: Number.isFinite(proc.ageMs) ? proc.ageMs : null,
+    commandLine: String(proc.commandLine || "").slice(0, 200),
+  };
+}
+
 function collectWindowsProcessTable() {
   if (platform() !== "win32") return new Map();
   try {
@@ -243,9 +276,85 @@ function cleanupOrphanPidFiles() {
   }
 }
 
+export function monitorFsmonitorDaemons({
+  threshold = parsePositiveInteger(
+    process.env.TFX_FSMONITOR_ALERT_THRESHOLD,
+    DEFAULT_FSMONITOR_ALERT_THRESHOLD,
+  ),
+  logPath = process.env.TFX_FSMONITOR_ALERT_LOG ||
+    defaultFsmonitorAlertLogPath(),
+  findFn = findFsmonitorDaemons,
+  now = new Date(),
+  isWindows = platform() === "win32",
+} = {}) {
+  if (process.env.TFX_FSMONITOR_MONITOR === "0") {
+    return { checked: false, reason: "disabled" };
+  }
+  if (!isWindows) return { checked: false, reason: "non-windows" };
+
+  const effectiveThreshold = parsePositiveInteger(
+    threshold,
+    DEFAULT_FSMONITOR_ALERT_THRESHOLD,
+  );
+
+  try {
+    const daemons = findFn({
+      minAgeMs: 0,
+      nowMs: now.getTime(),
+      isWindows,
+    });
+    const total = daemons.length;
+    if (total < effectiveThreshold) {
+      return {
+        checked: true,
+        alert: false,
+        total,
+        threshold: effectiveThreshold,
+      };
+    }
+
+    const record = {
+      ts: now.toISOString(),
+      source: "session-start",
+      total,
+      threshold: effectiveThreshold,
+      stale24h: daemons.filter(
+        (proc) =>
+          Number.isFinite(proc.ageMs) && proc.ageMs >= FSMONITOR_STALE_MS,
+      ).length,
+      pids: daemons.slice(0, 20).map(summarizeFsmonitorDaemon),
+    };
+
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+    console.error(
+      `[session-stale-cleanup] git fsmonitor daemon threshold exceeded: total=${total} threshold=${effectiveThreshold} log=${logPath}`,
+    );
+
+    return {
+      checked: true,
+      alert: true,
+      total,
+      threshold: effectiveThreshold,
+      stale24h: record.stale24h,
+      logPath,
+    };
+  } catch (error) {
+    console.error(
+      `[session-stale-cleanup] fsmonitor monitor failed: ${error?.message || error}`,
+    );
+    return {
+      checked: false,
+      reason: "error",
+      error: error?.message || String(error),
+    };
+  }
+}
+
 export function main() {
   cleanupMultiState();
   cleanupOrphanPidFiles();
+  monitorFsmonitorDaemons();
 }
 
 const isDirectRun =

package/skills/tfx-harness/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: tfx-harness
+description: >
+  TFX workflow harness. Use as the single front door when the user asks which TFX/gstack/superpowers
+  skill should handle a task, wants issue-resolution routing, mentions 신규/계속/디버그/리서치/검증/배포/저장/복원,
+  or asks for a TFX harness that dispatches to office-hours, autoplan, writing-plans, tfx-auto, tfx-find,
+  tfx-research, review/qa, tfx-ship, ship, context-save, or context-restore.
+triggers:
+  - tfx-harness
+  - tfx
+  - harness
+  - 하네스
+  - 스킬 추천
+  - 어떤 스킬
+  - 작업 라우팅
+  - 이슈 해결
+  - workflow routing
+argument-hint: "<task or issue description>"
+---
+
+# tfx-harness — TFX Workflow Harness
+
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+> **Telemetry**
+>
+> - Skill: `tfx-harness`
+> - Description: `TFX workflow harness. Use as the single front door when the user asks which TFX/gstack/superpowers skill should handle a task, wants issue-resolution routing, mentions 신규/계속/디버그/리서치/검증/배포/저장/복원, or asks for a TFX harness that dispatches to office-hours, autoplan, writing-plans, tfx-auto, tfx-find, tfx-research, review/qa, tfx-ship, ship, context-save, or context-restore.`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
+
+
+
+## Contract
+
+This skill is the routing harness, not a replacement execution engine.
+Classify the user's task, dispatch to the smallest correct workflow chain, then stop this harness unless no downstream skill can be invoked.
+
+If `.claude/rules/tfx-routing.md` exists in the repo, treat it as the source of truth and reconcile this table against it. If the host cannot invoke another skill directly, state the exact next workflow and continue only with the nearest safe local equivalent.
+
+## Routing Table
+
+| Situation | Dispatch chain | Use when |
+| --- | --- | --- |
+| New product or idea | `/office-hours` -> `/autoplan` -> `/writing-plans` -> `/tfx-auto` | The problem, audience, or scope is not yet shaped. |
+| Continue prior work | `/gstack-context-restore` -> `/tfx-auto` | A checkpoint/session restore is the first necessary step. |
+| Debug or issue fix | `/tfx-find` -> `/superpowers:systematic-debugging` -> `/tfx-auto` | There is a bug, failing behavior, or unknown root cause. |
+| Research | `/tfx-research` or `/multilingual-parallel-research` | Use TFX for current/official/tool behavior; use multilingual for cross-language source gathering. |
+| Verification | `/superpowers:review` + `/gstack /qa` | Code judgment and browser/workflow gates are both needed. |
+| Triflux release | `/tfx-ship` | Shipping this repo or TFX-specific artifacts. |
+| General PR/deploy | `/ship` | Non-triflux PR/deploy workflow. Do not add AI attribution footer/trailer. |
+| Save or restore | `/gstack-context-save` or `/gstack-context-restore` | Preserve or reload session state. |
+
+## Decision Procedure
+
+1. Identify the dominant intent: new planning, continuation, debugging, research, verification, release, save/restore, or direct implementation.
+2. If the user asks only "which skill?", answer with the selected chain and one sentence of rationale.
+3. If the user asks to proceed, invoke the first skill in the selected chain and hand off the original task as arguments.
+4. For mixed requests, run prerequisites first: restore before execution, find/debug before fix, review/qa before ship, save after a meaningful stopping point.
+5. For direct implementation that does not fit a more specific lane, dispatch to `/tfx-auto`.
+
+## Issue-Resolution Recommendation
+
+For "이슈 해결" style prompts, default to:
+
+1. `/tfx-find` to map files, symbols, logs, and likely ownership.
+2. `/superpowers:systematic-debugging` to prove root cause before editing.
+3. `/tfx-auto` to implement the minimal fix.
+4. `/superpowers:review` and the repo's targeted tests or `/gstack /qa` to verify.
+
+Escalate to `/tfx-ship` or `/ship` only after fresh verification evidence exists.
+
+## Output Shape
+
+Keep the user-facing response short:
+
+```text
+[tfx-harness] lane: <lane>
+next: <workflow chain>
+reason: <one sentence>
+status: dispatching | recommendation-only | blocked
+```
+
+Do not claim natural-language auto-triggering is guaranteed by this skill alone. Explicit `/tfx-harness` invocation is deterministic; automatic routing from arbitrary phrasing depends on the host keyword/hook layer.

package/skills/tfx-harness/SKILL.md.tmpl

@@ -0,0 +1,75 @@
+---
+name: tfx-harness
+description: >
+  TFX workflow harness. Use as the single front door when the user asks which TFX/gstack/superpowers
+  skill should handle a task, wants issue-resolution routing, mentions 신규/계속/디버그/리서치/검증/배포/저장/복원,
+  or asks for a TFX harness that dispatches to office-hours, autoplan, writing-plans, tfx-auto, tfx-find,
+  tfx-research, review/qa, tfx-ship, ship, context-save, or context-restore.
+triggers:
+  - tfx-harness
+  - tfx
+  - harness
+  - 하네스
+  - 스킬 추천
+  - 어떤 스킬
+  - 작업 라우팅
+  - 이슈 해결
+  - workflow routing
+argument-hint: "<task or issue description>"
+---
+
+# {{SKILL_NAME}} — TFX Workflow Harness
+
+{{> base}}
+
+## Contract
+
+This skill is the routing harness, not a replacement execution engine.
+Classify the user's task, dispatch to the smallest correct workflow chain, then stop this harness unless no downstream skill can be invoked.
+
+If `.claude/rules/tfx-routing.md` exists in the repo, treat it as the source of truth and reconcile this table against it. If the host cannot invoke another skill directly, state the exact next workflow and continue only with the nearest safe local equivalent.
+
+## Routing Table
+
+| Situation | Dispatch chain | Use when |
+| --- | --- | --- |
+| New product or idea | `/office-hours` -> `/autoplan` -> `/writing-plans` -> `/tfx-auto` | The problem, audience, or scope is not yet shaped. |
+| Continue prior work | `/gstack-context-restore` -> `/tfx-auto` | A checkpoint/session restore is the first necessary step. |
+| Debug or issue fix | `/tfx-find` -> `/superpowers:systematic-debugging` -> `/tfx-auto` | There is a bug, failing behavior, or unknown root cause. |
+| Research | `/tfx-research` or `/multilingual-parallel-research` | Use TFX for current/official/tool behavior; use multilingual for cross-language source gathering. |
+| Verification | `/superpowers:review` + `/gstack /qa` | Code judgment and browser/workflow gates are both needed. |
+| Triflux release | `/tfx-ship` | Shipping this repo or TFX-specific artifacts. |
+| General PR/deploy | `/ship` | Non-triflux PR/deploy workflow. Do not add AI attribution footer/trailer. |
+| Save or restore | `/gstack-context-save` or `/gstack-context-restore` | Preserve or reload session state. |
+
+## Decision Procedure
+
+1. Identify the dominant intent: new planning, continuation, debugging, research, verification, release, save/restore, or direct implementation.
+2. If the user asks only "which skill?", answer with the selected chain and one sentence of rationale.
+3. If the user asks to proceed, invoke the first skill in the selected chain and hand off the original task as arguments.
+4. For mixed requests, run prerequisites first: restore before execution, find/debug before fix, review/qa before ship, save after a meaningful stopping point.
+5. For direct implementation that does not fit a more specific lane, dispatch to `/tfx-auto`.
+
+## Issue-Resolution Recommendation
+
+For "이슈 해결" style prompts, default to:
+
+1. `/tfx-find` to map files, symbols, logs, and likely ownership.
+2. `/superpowers:systematic-debugging` to prove root cause before editing.
+3. `/tfx-auto` to implement the minimal fix.
+4. `/superpowers:review` and the repo's targeted tests or `/gstack /qa` to verify.
+
+Escalate to `/tfx-ship` or `/ship` only after fresh verification evidence exists.
+
+## Output Shape
+
+Keep the user-facing response short:
+
+```text
+[tfx-harness] lane: <lane>
+next: <workflow chain>
+reason: <one sentence>
+status: dispatching | recommendation-only | blocked
+```
+
+Do not claim natural-language auto-triggering is guaranteed by this skill alone. Explicit `/tfx-harness` invocation is deterministic; automatic routing from arbitrary phrasing depends on the host keyword/hook layer.

package/skills/tfx-harness/skill.json

@@ -0,0 +1,16 @@
+{
+  "name": "tfx-harness",
+  "description": "TFX workflow harness. Use as the single front door when the user asks which TFX/gstack/superpowers skill should handle a task, wants issue-resolution routing, mentions 신규/계속/디버그/리서치/검증/배포/저장/복원, or asks for a TFX harness that dispatches to office-hours, autoplan, writing-plans, tfx-auto, tfx-find, tfx-research, review/qa, tfx-ship, ship, context-save, or context-restore.",
+  "triggers": [
+    "tfx-harness",
+    "tfx",
+    "harness",
+    "하네스",
+    "스킬 추천",
+    "어떤 스킬",
+    "작업 라우팅",
+    "이슈 해결",
+    "workflow routing"
+  ],
+  "argument_hint": "<task or issue description>"
+}