deuk-agent-flow 4.2.7 → 5.0.2

package/scripts/cli-utils.ts

@@ -0,0 +1,1560 @@
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, unlinkSync, rmSync, statSync } from "fs";
+import { basename, dirname, relative, resolve, sep, win32, posix } from "path";
+import { homedir } from "os";
+import { pathToFileURL, fileURLToPath } from "url";
+import { createInterface } from "readline";
+import { createHash } from "crypto";
+import YAML from "yaml";
+
+// Loose options bag — all CLI functions accept this so callers don't need to list every key.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CliOpts = Record<string, any>;
+
+// #622: cli-ticket-home.mjs registers itself here at import time to avoid a static
+// circular import (home imports utils). detectConsumerTicketDir uses it when present.
+let _ticketHomeModule = null;
+export function registerTicketHomeModule(mod) { _ticketHomeModule = mod; }
+function ticketHomeModule() {
+  if (!_ticketHomeModule) throw new Error("ticket home module not registered");
+  return _ticketHomeModule;
+}
+
+/** Converts an absolute path to a clickable file:/// URI */
+export function toFileUri(absPath) {
+  return pathToFileURL(absPath).href;
+}
+
+/** Converts an absolute path to a vscode://file/ URI (clickable in VSCode terminal) */
+export function toVscodeFileUri(absPath) {
+  const posixPath = absPath.replace(/\\/g, "/");
+  const normalized = posixPath.startsWith("/") ? posixPath : `/${posixPath}`;
+  return `vscode://file${normalized}`;
+}
+
+/** writeFileSync wrapper that always normalizes to LF before writing */
+export function writeFileLF(path: string, content: string, encoding: BufferEncoding = "utf8") {
+  const normalized = String(content).replace(/\r\n/g, "\n");
+  writeFileSync(path, normalized, encoding);
+}
+
+// #713: The deuk home root fragment (the directory name under the user home / workspace).
+// Holds deuk-family-wide assets (tickets/registry/...). VALUE switched .deuk-agent→.deuk
+// (#710 renamed the symbol AGENT_ROOT_DIR→DEUK_ROOT_DIR; #713 flips the value). The legacy
+// ~/.deuk-agent directory is migrated to ~/.deuk by init auto-migration (cli-init-migrate).
+// The AGENT_ROOT_DIR alias is removed — all .ts call sites use DEUK_ROOT_DIR.
+export const DEUK_ROOT_DIR = ".deuk";
+export const WORKSPACE_MARKER_FILE = ".deuk-workspace-id";
+export const TICKET_SUBDIR = "tickets";
+export const RULES_SUBDIR = "rules";
+export const WORKFLOW_MODE_PLAN = "plan";
+export const WORKFLOW_MODE_EXECUTE = "execute";
+
+// #710: relative path under the deuk root. The SINGLE place that joins DEUK_ROOT_DIR with
+// sub-segments — callers pass fragments only (TICKET_SUBDIR, ...) and never re-assemble the
+// root themselves. Replaces the assembled constants (TICKET_DIR_NAME/PLAN_LINKS_DIR/...) that
+// baked the root into SSOT and forced double-assembly across call sites (708 design).
+export function deukRel(...segments: string[]): string {
+  return makePath(DEUK_ROOT_DIR, ...segments);
+}
+
+export const TICKET_INDEX_FILENAME = "INDEX.json";
+export const TICKET_LIST_FILENAME = "TICKET_LIST.md";
+export const DOCS_SUBDIR = "docs";
+export const PLANS_SUBDIR = "plan";
+
+// #713: SINGLE source of truth for everything about the OLD (.deuk-agent-era) layout.
+// All legacy-cleanup / scan-exclude / migration code reads from this one object instead of
+// scattered consts — add a future legacy name here once and every site follows. These are the
+// OLD names (fixed); they must NEVER follow DEUK_ROOT_DIR (the current ".deuk"), or cleanup
+// code would start treating the new dir as legacy and delete it. `dirs` = old directory names
+// that purge/scan/ignore logic must recognize (most-specific first).
+export const LEGACY_DEUK = {
+  rootDir: ".deuk-agent",
+  templateDir: ".deuk-agent-templates",
+  ticketDir: ".deuk-agent-ticket",
+  ticketDirPlural: ".deuk-agent-tickets",
+  configFile: ".deuk-agent-rule.config.json",
+  ticketGroupRoot: "ticket",
+  dirs: [
+    ".deuk-agent-templates",
+    ".deuk-agent-tickets",
+    ".deuk-agent-ticket",
+    ".deuk-agent",
+  ],
+} as const;
+
+export const ARCHIVE_YEAR_MONTH_RE = /^\d{4}-\d{2}$/;
+export const ARCHIVE_DAY_RE = /^\d{2}$/;
+
+const LEGACY_TICKET_GROUPS = new Set<string>([
+  LEGACY_DEUK.ticketDir,
+  LEGACY_DEUK.ticketDirPlural,
+  "ticket",
+  "tickets"
+]);
+
+/**
+ * Computes the canonical repository-relative path for a ticket based on its state.
+ */
+export function computeTicketPath(entry) {
+  // #080: paths are relative to the TICKET ROOT (the home store key dir,
+  // ~/.deuk-agent/tickets/{key}/). The legacy `.deuk-agent/tickets/` prefix dates
+  // from in-workspace storage; keeping it nested every self-heal/create one level
+  // deeper inside the store ({key}/.deuk-agent/tickets/main/...).
+  const isArchived = entry.status === "archived";
+  const group = normalizeTicketGroup(entry.group, "sub");
+  const fileStem = entry.fileName
+    ? String(entry.fileName).replace(/\.md$/i, "")
+    : entry.id;
+
+  if (!isArchived && group === TICKET_SUBDIR) {
+    return `${fileStem}.md`;
+  }
+
+  if (isArchived && entry.archiveYearMonth) {
+    return ["archive", group, entry.archiveYearMonth, `${fileStem}.md`].join("/");
+  }
+
+  const parts = [
+    isArchived ? "archive" : null,
+    group,
+    `${fileStem}.md`
+  ].filter(Boolean);
+  return parts.join("/");
+}
+
+export function normalizeTicketGroup(rawGroup, fallback = "sub") {
+  const value = String(rawGroup || "").trim();
+  if (!value) return fallback;
+  if (value.includes("/") || value.startsWith("TICKET-") && value.includes(".md")) return fallback;
+  if (value.endsWith(".md")) return fallback;
+  if (value.endsWith(".markdown")) return fallback;
+  if (LEGACY_TICKET_GROUPS.has(value)) return fallback;
+  return value;
+}
+
+export const CONFIG_FILENAME = "config.json";
+export const GLOBAL_CONFIG_DIR_NAME = "deuk-agent-flow";
+export const GLOBAL_CONFIG_FILENAME = "config.json";
+export const INIT_CONFIG_VERSION = 1;
+
+export const WORKSPACE_KINDS = [
+  { label: "Product planning / strategy / specs", value: "planning" },
+  { label: "Software engineering / coding", value: "coding" },
+  { label: "Systems engineering / operations", value: "systems" },
+  { label: "Research / analysis / knowledge work", value: "research" },
+  { label: "Mixed team workspace", value: "mixed" },
+  { label: "Other / decide later", value: "other" },
+];
+
+export const STACKS = [
+  { label: "Not primarily a code repo", value: "none" },
+  { label: "Web / product app", value: "web" },
+  { label: "Backend / service / API", value: "backend" },
+  { label: "Unity / game / simulation", value: "unity" },
+  { label: "Data / ML / analysis", value: "data" },
+  { label: "Infrastructure / platform / SRE", value: "infra" },
+  { label: "Hybrid / multiple stacks", value: "hybrid" },
+  { label: "Other / skip", value: "other" },
+];
+
+export const AGENT_TOOLS = [
+  { label: "OpenAI Codex", value: "codex" },
+  { label: "GitHub Copilot", value: "copilot" },
+  { label: "Claude Code", value: "claude" },
+  { label: "Cursor", value: "cursor" },
+  { label: "Gemini / Antigravity", value: "gemini" },
+  { label: "Windsurf", value: "windsurf" },
+  { label: "JetBrains AI Assistant", value: "jetbrains" },
+];
+
+export const SPOKE_REGISTRY = [
+  { id: "cursor", detect: (cwd) => existsSync(makePath(cwd, ".cursor")), legacy: ".cursorrules", target: ".cursor/rules/deuk-agent.mdc", format: "mdc" },
+  { id: "claude", detect: (cwd) => existsSync(makePath(cwd, "CLAUDE.md")) || existsSync(makePath(cwd, ".claude")), legacy: "CLAUDE.md", target: ".claude/rules/deuk-agent.md", format: "markdown" },
+  { id: "copilot", detect: (cwd, tools = []) => tools.includes("copilot") || existsSync(makePath(cwd, ".github")), legacy: null, target: ".github/copilot-instructions.md", format: "markdown" },
+  { id: "codex", detect: (cwd, tools = []) => tools.includes("codex") || existsSync(makePath(cwd, ".codex")), legacy: null, target: ".codex/AGENTS.md", format: "markdown" },
+  { id: "windsurf", detect: (cwd) => existsSync(makePath(cwd, ".windsurf")), legacy: ".windsurfrules", target: ".windsurf/rules/deuk-agent.md", format: "markdown" },
+  { id: "jetbrains", detect: (cwd) => existsSync(makePath(cwd, ".aiassistant")) || existsSync(makePath(cwd, ".idea")), legacy: null, target: ".aiassistant/rules/deuk-agent.md", format: "markdown" },
+  { id: "antigravity", detect: (cwd, tools = []) => tools.includes("gemini") || existsSync(makePath(cwd, "GEMINI.md")) || existsSync(makePath(cwd, ".gemini")) || existsSync(makePath(cwd, ".mcp.json")), legacy: "AGENTS.md", target: "GEMINI.md", format: "markdown" }
+];
+
+export const DOC_LANGUAGE_CHOICES = [
+  { label: "Auto (match system locale)", value: "auto" },
+  { label: "Korean", value: "ko" },
+  { label: "English", value: "en" },
+];
+
+export function normalizeDocsLanguage(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized || normalized === "auto") return "auto";
+  if (normalized.startsWith("ko") || normalized === "kr" || normalized === "korean") return "ko";
+  if (normalized.startsWith("en") || normalized === "english") return "en";
+  return "auto";
+}
+
+export function inferDocsLanguageFromEnv(env = process.env) {
+  // 1) POSIX 환경변수 우선(Linux/macOS, 또는 사용자가 Windows에서 명시 설정한 경우).
+  const posix = String(env.LANG || env.LC_ALL || env.LC_MESSAGES || "").toLowerCase();
+  if (posix) return posix.includes("ko") ? "ko" : "en";
+  // 2) Windows 등 LANG 부재 환경: Node가 OS 로케일을 반영하는 Intl로 폴백.
+  try {
+    const osLocale = String(Intl.DateTimeFormat().resolvedOptions().locale || "").toLowerCase();
+    if (osLocale.includes("ko")) return "ko";
+    if (osLocale) return "en";
+  } catch {
+    // Intl 미지원(초경량 런타임) 시 최종 폴백으로.
+  }
+  // 3) 최종 폴백.
+  return "en";
+}
+
+export function inferDocsLanguageFromText(text) {
+  const src = String(text || "");
+  const hangulCount = (src.match(/[\u3131-\u318e\uac00-\ud7a3]/g) || []).length;
+  if (hangulCount >= 2) return "ko";
+
+  const latinWords = src.match(/[A-Za-z][A-Za-z'-]*/g) || [];
+  if (latinWords.length >= 2) return "en";
+
+  return null;
+}
+
+export function resolveDocsLanguage(value, env = process.env) {
+  const normalized = normalizeDocsLanguage(value);
+  if (normalized === "auto") return inferDocsLanguageFromEnv(env);
+  return normalized;
+}
+
+export function selectLocalizedTemplatePath(baseDir, templateName, docsLanguage = "en") {
+  const normalized = resolveDocsLanguage(docsLanguage);
+  const localizedName = `${templateName.replace(/\.md$/i, "")}.${normalized}.md`;
+  const localizedPath = makePath(baseDir, localizedName);
+  if (existsSync(localizedPath)) return localizedPath;
+  return makePath(baseDir, templateName);
+}
+
+export function loadInitConfig(cwd, opts: CliOpts = {}) {
+  const targets = [
+    getUserInitConfigPath()
+  ].filter(Boolean);
+
+  for (const target of targets) {
+    if (!existsSync(target)) continue;
+    try {
+      const j = JSON.parse(readFileSync(target, "utf8"));
+      if (j.version !== INIT_CONFIG_VERSION) continue;
+      if (!j.docsLanguage) j.docsLanguage = "auto";
+      const workflowMode = normalizeWorkflowMode(j.workflowMode ?? j.approvalState);
+      j.workflowMode = workflowMode;
+      j.approvalState = workflowMode === WORKFLOW_MODE_EXECUTE ? "approved" : "pending";
+      if (j.scmIgnoreDeukAgent === undefined) j.scmIgnoreDeukAgent = !Boolean(j.shareTickets);
+      j.configPath = target;
+      j.configScope = "user";
+      return j;
+    } catch (err) {
+      if (process.env.DEBUG) console.warn(`[DEBUG] Failed to parse config ${target}:`, err);
+    }
+  }
+  return null;
+}
+
+export function writeInitConfig(cwd, opts) {
+  const p = getUserInitConfigPath(opts);
+  const dir = dirname(p);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const existing = loadInitConfig(cwd) || {};
+  const workflowMode = normalizeWorkflowMode(opts.workflowMode ?? opts.workflow ?? opts.approvalState ?? opts.approval);
+  const data = {
+    version: INIT_CONFIG_VERSION,
+    workflowMode,
+    approvalState: workflowMode === WORKFLOW_MODE_EXECUTE ? "approved" : "pending",
+    workspaceKind: opts.workspaceKind ?? opts.kind ?? existing.workspaceKind ?? existing.kind,
+    stack: opts.stack ?? existing.stack,
+    kind: opts.workspaceKind ?? opts.kind ?? existing.workspaceKind ?? existing.kind,
+    agentTools: opts.agentTools ?? existing.agentTools,
+    docsLanguage: normalizeDocsLanguage(opts.docsLanguage ?? existing.docsLanguage ?? "auto"),
+    scmIgnoreDeukAgent: opts.scmIgnoreDeukAgent ?? existing.scmIgnoreDeukAgent ?? !Boolean(opts.shareTickets ?? existing.shareTickets ?? false),
+    shareTickets: opts.shareTickets ?? existing.shareTickets ?? false,
+    contextMcp: opts.contextMcp ?? existing.contextMcp ?? "skip",
+    remoteSync: opts.remoteSync ?? existing.remoteSync ?? false,
+    pipelineUrl: opts.pipelineUrl,
+    ignoreDirs: opts.ignoreDirs || existing.ignoreDirs || DEFAULT_IGNORE_DIRS,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(p, JSON.stringify(data, null, 2), "utf8");
+}
+
+// Single source of truth for the current user's home directory. Every home-derived
+// path (global agent pointers, Claude settings hook, workspace registry) must route
+// through here so platform/env home policy lives in one place instead of being
+// sprawled across call sites with divergent fallbacks.
+//
+// process.env.HOME is intentionally NOT consulted: the ~/bin/node wrapper delegates
+// to the Windows node.exe, so homedir() already resolves to the shared Windows home
+// (C:\Users\joy) under both Windows and WSL. Honoring env.HOME would make a native
+// WSL node pick /home/joy and break that shared-home contract. Tests inject opts.homeDir.
+export function resolveUserHome(opts: CliOpts = {}) {
+  return opts.homeDir || homedir();
+}
+
+// The project's single path-construction primitive. Joins segments and normalizes
+// the result to the target platform's convention (canonical form = platform-native:
+// win32 -> "\\", posix -> "/"), regardless of how the inputs were stored ??mixed or
+// foreign separators are accepted. platform defaults to the running platform; pass
+// opts.platform to build a path for another platform deterministically (used by
+// tests so they compare via this same function and stay platform-agnostic).
+export function makePath(...args) {
+  // Variadic drop-in for path.join: makePath(a, b, c). Also accepts a single
+  // segments array and/or a trailing { platform } options object:
+  //   makePath([a, b], { platform: "win32" })  |  makePath(a, b, { platform })
+  let opts: CliOpts = {};
+  if (args.length > 1 && args[args.length - 1] && typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1])) {
+    opts = args.pop();
+  }
+  const segments = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
+  const platform = opts.platform || process.platform;
+  const mod = platform === "win32" ? win32 : posix;
+  // Swap the *foreign* separator to the target's (no collapsing ??keeps leading
+  // "\\\\" UNC prefixes like \\wsl.localhost\... intact); the join then normalizes.
+  const foreign = platform === "win32" ? /\//g : /\\/g;
+  const parts = segments
+    .map(part => String(part ?? ""))
+    .filter(part => part.length > 0)
+    .map(part => part.replace(foreign, mod.sep));
+  return mod.join(...parts);
+}
+
+// #709: Single source of truth for the package root. Historically 10 call sites computed
+// this five different ways (dirname(dirname(import.meta.url)), makePath(__dirname, ".."),
+// resolve(dirname(fileURLToPath()), ".."), ...). Those bake in a fixed directory depth, so
+// the tsc build output (scripts/out/scripts/) shifted the depth and broke docs/ resolution
+// ("CLI surface document not found: scripts/out/docs/..."). This walks UP from the caller's
+// file looking for the package.json marker, so it returns the SAME root whether the code runs
+// from source (scripts/) or build output (scripts/out/scripts/) — location-independent.
+let _packageRootCache: string | null = null;
+export function resolvePackageRoot(opts: CliOpts = {}): string {
+  if (opts.packageRoot) return opts.packageRoot;
+  if (!opts.noCache && _packageRootCache) return _packageRootCache;
+  const startFile = opts.fromUrl ? fileURLToPath(opts.fromUrl) : fileURLToPath(import.meta.url);
+  let dir = dirname(startFile);
+  // Walk up until a package.json is found; stop at filesystem root.
+  while (true) {
+    if (existsSync(makePath(dir, "package.json"))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached root without a marker — fall back to original dir
+    dir = parent;
+  }
+  if (!opts.noCache) _packageRootCache = dir;
+  return dir;
+}
+
+// #632: OS-agnostic basename. path.basename uses the CURRENT runtime's separator, so
+// under a POSIX node (WSL / Git Bash) it cannot split a Windows path — basename(
+// "D:\\workspace\\DeukPack") wrongly returns "workspaceDeukPack". normalizeRegistryPath
+// emits Windows-style paths regardless of runtime, so any code deriving a name from one
+// (e.g. computeTicketKey) must split on BOTH separators. Mirrors makePath's cross-OS intent.
+export function basenameAnyOS(value) {
+  return String(value ?? "").split(/[\\/]/).filter(Boolean).pop() || "";
+}
+
+export function getUserConfigDir(opts: CliOpts = {}) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const homeDir = resolveUserHome(opts);
+
+  if (platform === "win32") {
+    const base = env.APPDATA || makePath([homeDir, "AppData", "Roaming"], { platform });
+    return makePath([base, GLOBAL_CONFIG_DIR_NAME], { platform });
+  }
+
+  const base = env.XDG_CONFIG_HOME || makePath([homeDir, ".config"], { platform });
+  return makePath([base, GLOBAL_CONFIG_DIR_NAME], { platform });
+}
+
+export function getUserInitConfigPath(opts: CliOpts = {}) {
+  return makePath([getUserConfigDir(opts), GLOBAL_CONFIG_FILENAME], opts);
+}
+
+// Global, workspace-independent directory for user-forked/custom skills.
+// Lives alongside the global config so personalized skills follow the user
+// across every workspace (win: %APPDATA%\deuk-agent-flow\skills,
+// posix: $XDG_CONFIG_HOME|~/.config/deuk-agent-flow/skills).
+export function getUserSkillsDir(opts: CliOpts = {}) {
+  return makePath([resolveUserHome(opts), DEUK_ROOT_DIR, "skills"], opts);
+}
+
+// Global, workspace-independent path for skill install state (the `installed`
+// array). Lives next to the global skills dir so a skill installed once shows
+// the same state across every editor/workspace. Exposure stays per-workspace
+// because it is physically injected into agent rule files.
+export function getUserSkillsConfigPath(opts: CliOpts = {}) {
+  return makePath([resolveUserHome(opts), DEUK_ROOT_DIR, "skills.json"], opts);
+}
+
+export function getWorkspaceInitConfigPath(cwd) {
+  return makePath(cwd, deukRel(CONFIG_FILENAME));
+}
+
+export function migrateWorkspaceInitConfigToUserConfig(cwd, opts: CliOpts = {}) {
+  const workspaceConfig = getWorkspaceInitConfigPath(cwd);
+  if (!existsSync(workspaceConfig)) return false;
+
+  const dryRun = Boolean(opts.dryRun);
+  const silent = Boolean(opts.silent);
+
+  if (!dryRun) unlinkSync(workspaceConfig);
+  if (!silent) {
+    const relWorkspaceConfig = toRepoRelativePath(cwd, workspaceConfig);
+    console.log(`[MIGRATE] ${dryRun ? "Would remove" : "Removed"} legacy workspace config: ${relWorkspaceConfig}`);
+  }
+  return dryRun ? "dry-run-remove-workspace-config" : "removed-workspace-config";
+}
+
+export function normalizeWorkflowMode(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return WORKFLOW_MODE_PLAN;
+  if (["execute", "approved", "approval", "apply", "apply-changes"].includes(normalized)) {
+    return WORKFLOW_MODE_EXECUTE;
+  }
+  if (["plan", "pending", "review", "prepare", "prepare-only"].includes(normalized)) {
+    return WORKFLOW_MODE_PLAN;
+  }
+  return normalized === WORKFLOW_MODE_EXECUTE ? WORKFLOW_MODE_EXECUTE : WORKFLOW_MODE_PLAN;
+}
+
+export function isWorkflowExecute(opts: CliOpts = {}, savedConfig = null) {
+  return normalizeWorkflowMode(
+    opts.workflowMode ??
+    opts.workflow ??
+    opts.approval ??
+    opts.approvalState ??
+    savedConfig?.workflowMode ??
+    savedConfig?.approvalState
+  ) === WORKFLOW_MODE_EXECUTE;
+}
+
+/**
+ * Resolves the final workflow mode by checking opts, then saved config, with fallback.
+ */
+export function resolveWorkflowMode(opts: CliOpts = {}, savedConfig = null) {
+  return normalizeWorkflowMode(
+    opts.workflowMode ??
+    opts.workflow ??
+    opts.approval ??
+    opts.approvalState ??
+    savedConfig?.workflowMode ??
+    savedConfig?.approvalState
+  );
+}
+
+/**
+ * Strips dynamically appended rule modules from content.
+ */
+export function pruneRuleModules(content) {
+  const marker = "<!-- RULE MODULE: ";
+  const idx = content.indexOf(marker);
+  if (idx !== -1) {
+    return content.substring(0, idx).trimEnd();
+  }
+  return content.trimEnd();
+}
+
+/**
+ * Higher-order function to wrap interactive readline sessions.
+ */
+export async function withReadline(callback) {
+  if (!process.stdout.isTTY) {
+    throw new Error("Interactive terminal required.");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await callback(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+export function toPosixPath(p) {
+  return p.replace(/\\/g, "/");
+}
+
+export function toRepoRelativePath(cwd, absPath) {
+  return toPosixPath(relative(cwd, absPath));
+}
+
+/** ?덉??ㅽ듃由?湲곕컲 ?뚰겕?ㅽ럹?댁뒪 猷⑦듃 湲곗? ?곷?寃쎈줈 ??留곹겕/寃쎈줈 異쒕젰???ъ슜 */
+// #746: 티켓은 홈 스토어(~/.deuk/tickets/{uuid}/, 보통 C:)에 살고 워크스페이스 cwd는
+// 다른 드라이브(D:)일 수 있다. 그 경우 relative(wsRoot, abs)는 상대경로를 만들지 못하고
+// "C:/..." 절대경로로 폴백하는데, 그 drive-prefixed 링크는 채팅·webview 어느 쪽에서도
+// 열리지 않는다(클릭 실측). 카드 링크(formatTicketFlowLine)와 동일하게 drive-letter만
+// 떼어낸 슬래시-루트 절대경로("C:/Users/..." → "/Users/...")로 통일하면 양쪽에서 열린다.
+// NOTE(후속): 같은 드라이브일 때 ../상대경로 최적화·linux 동작은 별도 티켓에서 고민.
+export function toWsRelativePath(_cwd, absPath) {
+  return toPosixPath(makePath(resolve(absPath))).replace(/^[a-zA-Z]:/, "");
+}
+
+// Hangul syllable \u2192 Latin transliteration (Revised Romanization, simplified).
+// Used as a fallback so non-ASCII titles still produce a usable slug.
+const HANGUL_CHO = ["g","kk","n","d","tt","r","m","b","pp","s","ss","","j","jj","ch","k","t","p","h"];
+const HANGUL_JUNG = ["a","ae","ya","yae","eo","e","yeo","ye","o","wa","wae","oe","yo","u","wo","we","wi","yu","eu","ui","i"];
+const HANGUL_JONG = ["","g","kk","gs","n","nj","nh","d","l","lg","lm","lb","ls","lt","lp","lh","m","b","bs","s","ss","ng","j","ch","k","t","p","h"];
+
+export function hangulToRoman(input) {
+  let out = "";
+  for (const ch of String(input || "")) {
+    const code = ch.codePointAt(0);
+    if (code >= 0xac00 && code <= 0xd7a3) {
+      const offset = code - 0xac00;
+      const cho = Math.floor(offset / 588);
+      const jung = Math.floor((offset % 588) / 28);
+      const jong = offset % 28;
+      out += HANGUL_CHO[cho] + HANGUL_JUNG[jung] + HANGUL_JONG[jong];
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+function asciiSlug(input) {
+  return String(input || "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function toSlug(input) {
+  const slug = asciiSlug(input);
+  if (slug) return slug;
+  // Fallback: transliterate Hangul, then slug again. Keeps Korean titles usable.
+  return asciiSlug(hangulToRoman(input));
+}
+
+function normalizeWorkspaceLookup(input) {
+  return String(input || "")
+    .toLowerCase()
+    .normalize("NFKC")
+    .replace(/[\s._/\-]+/g, "")
+    .replace(/[^a-z0-9\u3131-\u318e\uac00-\ud7a3]/g, "");
+}
+
+function splitWorkspaceNameParts(input) {
+  return String(input || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .map(part => part.trim())
+    .filter(Boolean);
+}
+
+export function buildWorkspaceAliases(id, workspacePath, extraAliases = []) {
+  const baseName = basename(workspacePath);
+  const rawNames = [id, baseName, ...extraAliases].map(value => String(value || "").trim()).filter(Boolean);
+  const aliases = new Set(rawNames);
+  for (const rawName of rawNames) {
+    const slug = toSlug(rawName);
+    if (slug) aliases.add(slug);
+
+    const parts = splitWorkspaceNameParts(rawName);
+    if (parts.length > 1) {
+      aliases.add(parts.join(" "));
+      aliases.add(parts.join("-"));
+    }
+    if (parts.length > 1 && parts[0].toLowerCase() === "deuk") {
+      const withoutDeukParts = parts.slice(1);
+      const withoutDeuk = withoutDeukParts.join("-");
+      if (withoutDeuk) {
+        aliases.add(withoutDeuk);
+        aliases.add(withoutDeukParts.join(" "));
+      }
+      // The bare last part (e.g. "flow", "pack") stays available for explicit
+      // `--workspace <name>` queries, which are intentional and exact-matched.
+      // It is filtered out of prompt-scan aliases (buildPromptWorkspaceAliases)
+      // so it cannot hijack free-form prompt text.
+      const lastPart = parts[parts.length - 1];
+      if (lastPart) aliases.add(lastPart);
+    }
+    if (parts.length > 2 && parts[0].toLowerCase() === "deuk" && parts[1].toLowerCase() === "ai") {
+      const withoutDeukAiParts = parts.slice(2);
+      const withoutDeukAi = withoutDeukAiParts.join("-");
+      if (withoutDeukAi) {
+        aliases.add(withoutDeukAi);
+        aliases.add(withoutDeukAiParts.join(" "));
+      }
+    }
+  }
+  return Array.from(aliases);
+}
+
+export function buildPromptWorkspaceAliases(workspace) {
+  const promptAliases = new Set();
+  const rawCanonicalNames = [workspace?.id, basename(workspace?.path || "")]
+    .map(value => String(value || "").trim())
+    .filter(Boolean);
+
+  for (const rawName of rawCanonicalNames) {
+    promptAliases.add(rawName);
+    const slug = toSlug(rawName);
+    if (slug) promptAliases.add(slug);
+
+    const parts = splitWorkspaceNameParts(rawName);
+    if (parts.length > 1) {
+      promptAliases.add(parts.join(" "));
+      promptAliases.add(parts.join("-"));
+    }
+  }
+
+  // Existing registry data may contain over-generic single-word aliases
+  // (e.g. "Flow", "Pack") that would match unrelated free-form prompt text and
+  // redirect to the wrong workspace. Only accept registry aliases specific
+  // enough for prompt matching: multi-token (space/hyphen) or sharing the
+  // canonical id/basename stem.
+  const canonicalSlugs = rawCanonicalNames.map(name => toSlug(name)).filter(Boolean);
+  const isSpecificPromptAlias = (alias) => {
+    if (/[\s-]/.test(alias)) return true;
+    const slug = toSlug(alias);
+    if (!slug) return false;
+    // Accept only if the alias equals or is more specific than (contains) a
+    // canonical slug. Reject bare fragments like "flow" that are merely a
+    // substring of the canonical id ("deukagentflow").
+    return canonicalSlugs.some(canonical => slug === canonical || slug.includes(canonical));
+  };
+  for (const registryAlias of workspace?.registryAliases || []) {
+    const trimmed = String(registryAlias || "").trim();
+    if (trimmed && isSpecificPromptAlias(trimmed)) promptAliases.add(trimmed);
+  }
+
+  return Array.from(promptAliases);
+}
+
+export function hasWorkspaceMarker(candidatePath) {
+  return existsSync(makePath(candidatePath, WORKSPACE_MARKER_FILE)) ||
+    existsSync(makePath(candidatePath, DEUK_ROOT_DIR));
+}
+
+function hasLocalProjectBoundary(candidatePath) {
+  return existsSync(makePath(candidatePath, ".git")) ||
+    existsSync(makePath(candidatePath, "AGENTS.md")) ||
+    existsSync(makePath(candidatePath, "PROJECT_RULE.md")) ||
+    existsSync(makePath(candidatePath, "package.json"));
+}
+
+function directProjectRoot(startDir) {
+  const current = resolve(startDir);
+  if (hasWorkspaceMarker(current)) return current;
+  const parent = dirname(current);
+  if (parent !== current && hasWorkspaceMarker(parent)) return parent;
+  return null;
+}
+
+export function normalizeRegistryPath(value) {
+  let p = String(value || "").trim();
+  // WSL2: /mnt/d/... ??D:\...
+  const wsl2 = p.match(/^\/mnt\/([a-zA-Z])(\/.*)?$/);
+  if (wsl2) p = wsl2[1].toUpperCase() + ":" + (wsl2[2] || "\\").replace(/\//g, "\\");
+  // WSL1 / Git Bash: /d/... ??D:\...
+  const wsl1 = p.match(/^\/([a-zA-Z])(\/.*)?$/);
+  if (wsl1) p = wsl1[1].toUpperCase() + ":" + (wsl1[2] || "\\").replace(/\//g, "\\");
+  // Windows drive letter: normalize to uppercase
+  p = p.replace(/^([a-z]):/, (_, d) => d.toUpperCase() + ":");
+  // #632: a drive-letter path (e.g. D:\workspace\DeukPack) is ABSOLUTE on Windows, but
+  // POSIX resolve() — what runs under WSL / Git Bash — does not recognize "X:\" as a root
+  // and treats the whole string as relative, prepending process.cwd() and mangling the
+  // backslashes into one segment (".../scripts/workspaceDeukPack"). That poisons the
+  // ticketKey and makes reconcile fire every command. Resolve drive-letter paths with the
+  // win32 resolver so they stay absolute and segmented regardless of the host OS.
+  if (/^[A-Za-z]:[\\/]/.test(p)) return win32.resolve(p);
+  return resolve(p);
+}
+
+function hashWorkspacePath(value) {
+  return createHash("sha256").update(normalizeRegistryPath(String(value || "")), "utf8").digest("hex");
+}
+
+export function getSiblingWorkspaceRegistryRoot(homeDir = resolveUserHome()) {
+  return makePath(homeDir, ".agent-flow", "workspace");
+}
+
+export function getSiblingWorkspaceRegistryGroupPath(parentRoot, opts: CliOpts = {}) {
+  const homeDir = resolveUserHome(opts);
+  return makePath(getSiblingWorkspaceRegistryRoot(homeDir), hashWorkspacePath(parentRoot));
+}
+
+export function loadRegistrySiblingWorkspaceCandidates(startDir, opts: CliOpts = {}) {
+  const current = resolve(startDir);
+  const currentRoot = directProjectRoot(current);
+  const parentRoot = currentRoot ? dirname(currentRoot) : dirname(current);
+  const registryDir = getSiblingWorkspaceRegistryGroupPath(parentRoot, opts);
+  if (!existsSync(registryDir)) return null;
+
+  const workspaces = [];
+  try {
+    for (const entry of readdirSync(registryDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const registryPath = makePath(registryDir, entry.name);
+      let record = null;
+      try {
+        record = JSON.parse(readFileSync(registryPath, "utf8"));
+      } catch {
+        continue;
+      }
+      const workspacePath = normalizeRegistryPath(String(record?.path || ""));
+      const id = String(record?.name || basename(workspacePath)).trim();
+      if (!id || !workspacePath || !hasWorkspaceMarker(workspacePath)) continue;
+      // #080: the user home dir owns ~/.deuk-agent (the STORE) and so passes the marker
+      // check above — but home and anything inside the store are never workspaces.
+      // Stale "joy"/".deuk-agent" records otherwise hijack workspace dispatch.
+      if (isInsideHomeStore(workspacePath)) continue;
+      const registryAliases = Array.isArray(record?.aliases)
+        ? record.aliases.map(value => String(value || "").trim()).filter(Boolean)
+        : [];
+      workspaces.push({
+        id,
+        path: workspacePath,
+        aliases: buildWorkspaceAliases(id, workspacePath, registryAliases),
+        registryAliases,
+        registryPath
+      });
+    }
+  } catch {
+    return null;
+  }
+
+  if (workspaces.length === 0) return null;
+  return { path: registryDir, root: parentRoot, workspaces, discovered: false, registry: true };
+}
+
+// #638: the workspace candidate source is the home ticket store itself —
+// ~/.deuk-agent/tickets/{uuid}/workspace.json. Each folder is self-describing
+// ({uuid,path,name}); the folder's existence IS the registration (single source of
+// truth). No ~/.agent-flow registry, no registry.json fallback — those caches went
+// stale and spawned ambiguous ghosts. A folder without workspace.json simply isn't
+// a candidate yet; it self-heals into one the next time a command runs in it (reconcile
+// writes workspace.json). One readdir + one small JSON per workspace (tens, not
+// thousands) — negligible cost, nothing to drift.
+export function loadAllRegistryWorkspaceCandidates(opts: CliOpts = {}) {
+  const homeDir = resolveUserHome(opts);
+  const ticketsRoot = makePath([homeDir, DEUK_ROOT_DIR, "tickets"], opts);
+  if (!existsSync(ticketsRoot)) return null;
+
+  const byPath = new Map();
+  try {
+    for (const ent of readdirSync(ticketsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!ent.isDirectory()) continue;
+      const dir = makePath(ticketsRoot, ent.name);
+
+      // Authoritative, self-describing source: workspace.json. No fallback.
+      let workspacePath = "", name = "", aliases = [];
+      try {
+        const meta = JSON.parse(readFileSync(makePath(dir, "workspace.json"), "utf8"));
+        workspacePath = normalizeRegistryPath(String(meta?.path || ""));
+        name = String(meta?.name || "").trim();
+        if (Array.isArray(meta?.aliases)) aliases = meta.aliases.map(a => String(a || "").trim()).filter(Boolean);
+      } catch { continue; }  // no workspace.json → not a candidate yet
+
+      // Path must still exist with a workspace marker, and not be the home store.
+      if (!workspacePath || !hasWorkspaceMarker(workspacePath)) continue;
+      if (isInsideHomeStore(workspacePath)) continue;
+      // #638: the user home dir is NOT where workspaces live. Past cwd-fallback bugs
+      // minted ghost markers at ~/{Name} (e.g. C:\Users\joy\DeukAgentFlow) that
+      // collide by name with the real D:\workspace\{Name}. A workspace directly under
+      // the home dir is never a real candidate — exclude it.
+      if (isHomeDirectChild(workspacePath, opts)) continue;
+      if (!name) name = basename(workspacePath);
+
+      byPath.set(workspacePath, {
+        id: name,
+        path: workspacePath,
+        aliases: buildWorkspaceAliases(name, workspacePath, aliases),
+        registryAliases: aliases,
+      });
+    }
+  } catch {
+    return null;
+  }
+
+  // #638: drop nested ghosts — a workspace path that sits INSIDE another candidate's
+  // path (e.g. D:\workspace\DeukAgentFlow\DeukAgentFlow under D:\workspace\DeukAgentFlow)
+  // is an accidental nested registration, not a real workspace. Keep only top-level paths.
+  const all = Array.from(byPath.values());
+  const paths = all.map(w => w.path);
+  const kept = all.filter(w => !paths.some(p =>
+    p !== w.path && (w.path === p + "/" || w.path.startsWith(p + "/") || w.path.startsWith(p + "\\"))
+  ));
+
+  const workspaces = kept.sort((a, b) => a.id.localeCompare(b.id));
+  if (workspaces.length === 0) return null;
+  return { path: ticketsRoot, root: ticketsRoot, workspaces, discovered: false, registry: true, global: true };
+}
+
+export function discoverSiblingWorkspaces(startDir) {
+  const current = resolve(startDir);
+  const currentRoot = directProjectRoot(current);
+  const discoveryRoot = currentRoot ? dirname(currentRoot) : dirname(current);
+  const workspaces = [];
+
+  try {
+    for (const item of readdirSync(discoveryRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!item.isDirectory() || item.name.startsWith(".")) continue;
+      const workspacePath = makePath(discoveryRoot, item.name);
+      if (!hasWorkspaceMarker(workspacePath)) continue;
+      workspaces.push({
+        id: item.name,
+        path: workspacePath,
+        aliases: buildWorkspaceAliases(item.name, workspacePath),
+        registryAliases: []
+      });
+    }
+  } catch {
+    return null;
+  }
+
+  if (workspaces.length === 0) return null;
+  return { path: null, root: discoveryRoot, workspaces, discovered: true };
+}
+
+export function loadSiblingWorkspaceCandidates(startDir) {
+  return loadRegistrySiblingWorkspaceCandidates(startDir) || discoverSiblingWorkspaces(startDir);
+}
+
+export function loadWorkspaceCandidates(startDir, opts: CliOpts = {}) {
+  // #645: SSOT-only, NO fallback. The only source of workspace candidates is the
+  // home ticket store's workspace.json records (loadAllRegistryWorkspaceCandidates).
+  // Every cwd-based fallback (sibling scan, ~/.agent-flow cache) was a ghost
+  // factory — a command run in any directory would "discover" and register it.
+  // A workspace exists iff it was explicitly registered via `init`. If nothing is
+  // registered yet, there are simply no candidates — we never invent them from cwd.
+  return loadAllRegistryWorkspaceCandidates(opts);
+}
+
+function workspaceQueryMatches(query, workspace) {
+  const normalizedQuery = normalizeWorkspaceLookup(query);
+  if (!normalizedQuery) return false;
+  for (const alias of workspace.aliases || []) {
+    const normalizedAlias = normalizeWorkspaceLookup(alias);
+    if (!normalizedAlias) continue;
+    if (normalizedQuery === normalizedAlias) return true;
+  }
+  return false;
+}
+
+export function findPromptWorkspaceMatches(prompt, candidates) {
+  const normalizedPrompt = normalizeWorkspaceLookup(prompt);
+  if (!normalizedPrompt || !candidates?.workspaces?.length) return [];
+
+  const matches = [];
+  for (const workspace of candidates.workspaces) {
+    let bestAliasLength = 0;
+    for (const alias of workspace.aliases || []) {
+      const normalizedAlias = normalizeWorkspaceLookup(alias);
+      if (normalizedAlias && normalizedPrompt.includes(normalizedAlias)) {
+        bestAliasLength = Math.max(bestAliasLength, normalizedAlias.length);
+      }
+    }
+    if (bestAliasLength > 0) matches.push({ workspace, bestAliasLength });
+  }
+  if (matches.length === 0) return [];
+
+  const mostSpecificAliasLength = Math.max(...matches.map(match => match.bestAliasLength));
+  return matches
+    .filter(match => match.bestAliasLength === mostSpecificAliasLength)
+    .map(match => match.workspace)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+
+// Resolves a stable session identifier from agent-injected environment variables.
+// Priority: explicit arg → Claude Code → Codex → Antigravity → VSCODE_PID → "default".
+// Each supported agent injects a per-session UUID so concurrent agents on the same
+// machine get independent flow-cookies and claim files without manual --session-id.
+export function resolveSessionId(explicitId) {
+  if (explicitId) return String(explicitId).trim().slice(0, 36);
+  const raw =
+    process.env.CLAUDE_CODE_SESSION_ID    ||
+    process.env.CODEX_THREAD_ID           ||
+    process.env.ANTIGRAVITY_TRAJECTORY_ID ||
+    process.env.VSCODE_PID               ||
+    "";
+  return raw.trim().slice(0, 36) || "default";
+}
+
+// #675: touch-file cookie — cookie-{workspaceId}-{ticketId}-{sessionId}
+// Lives in ~/.deuk-agent/ (home root). File existence = session owns workspace+ticket.
+// No JSON content; all info is in the filename. TTL via statSync().mtimeMs.
+// Replaces both flow-cookie-*.json AND claim-*.json.
+
+const COOKIE_PREFIX = "cookie-";
+const COOKIE_TTL_MS = 30 * 60 * 1000;
+
+function sanitizeCookieSegment(s) {
+  return String(s || "").toLowerCase().replace(/[^a-z0-9\-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "x";
+}
+
+function cookieHomeDir(opts: CliOpts = {}) {
+  return makePath([resolveUserHome(opts), DEUK_ROOT_DIR], opts);
+}
+
+export function writeCookieFile(workspaceId, ticketId, sessionId, opts: CliOpts = {}) {
+  const dir = cookieHomeDir(opts);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const wp = sanitizeCookieSegment(workspaceId);
+  const tid = sanitizeCookieSegment(ticketId || "none");
+  const sid = sanitizeCookieSegment(sessionId);
+  const p = makePath([dir, `${COOKIE_PREFIX}${wp}-${tid}-${sid}`], opts);
+  writeFileSync(p, "", "utf8");
+}
+
+export function readCookieFile(sessionId, opts: CliOpts = {}) {
+  const dir = cookieHomeDir(opts);
+  if (!existsSync(dir)) return null;
+  const sid = sanitizeCookieSegment(sessionId);
+  const files = readdirSync(dir).filter(f => f.startsWith(COOKIE_PREFIX) && f.endsWith(`-${sid}`));
+  for (const f of files) {
+    const parts = f.slice(COOKIE_PREFIX.length).split("-");
+    // format: {wp}-{tid}-{sid} where sid can contain dashes — find by suffix match
+    const suffix = `-${sid}`;
+    const body = f.slice(COOKIE_PREFIX.length, f.length - suffix.length);
+    const dashIdx = body.indexOf("-");
+    if (dashIdx < 0) continue;
+    const wp = body.slice(0, dashIdx);
+    const tid = body.slice(dashIdx + 1);
+    const p = makePath([dir, f], opts);
+    try {
+      const mtime = statSync(p).mtimeMs;
+      if (Date.now() - mtime > COOKIE_TTL_MS) { try { unlinkSync(p); } catch { } continue; }
+    } catch { continue; }
+    return { workspaceId: wp, ticketId: tid === "none" ? null : tid, sessionId: sid, path: p };
+  }
+  return null;
+}
+
+export function releaseCookieFile(sessionId, opts: CliOpts = {}) {
+  const dir = cookieHomeDir(opts);
+  if (!existsSync(dir)) return;
+  const sid = sanitizeCookieSegment(sessionId);
+  const files = readdirSync(dir).filter(f => f.startsWith(COOKIE_PREFIX) && f.endsWith(`-${sid}`));
+  for (const f of files) { try { unlinkSync(makePath([dir, f], opts)); } catch { } }
+}
+
+export function listCookiesByTicket(workspaceId, ticketId, opts: CliOpts = {}) {
+  const dir = cookieHomeDir(opts);
+  if (!existsSync(dir)) return [];
+  const wp = sanitizeCookieSegment(workspaceId);
+  const tid = sanitizeCookieSegment(ticketId || "none");
+  const prefix = `${COOKIE_PREFIX}${wp}-${tid}-`;
+  return readdirSync(dir)
+    .filter(f => f.startsWith(prefix))
+    .map(f => {
+      const sid = f.slice(prefix.length);
+      const p = makePath([dir, f], opts);
+      try { const mtime = statSync(p).mtimeMs; if (Date.now() - mtime > COOKIE_TTL_MS) { try { unlinkSync(p); } catch { } return null; } return { sessionId: sid, path: p, mtime }; } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+// Legacy compat shims — used by resolveWorkspaceTarget call sites
+export function getWorkspaceCookiePath(_cwd, sessionId, opts: CliOpts = {}) {
+  const sid = sanitizeCookieSegment(resolveSessionId(sessionId));
+  const dir = cookieHomeDir(opts);
+  // Return a glob-friendly sentinel; actual file is found via readCookieFile
+  return makePath([dir, `${COOKIE_PREFIX}*-*-${sid}`], opts);
+}
+
+export function readWorkspaceCookie(_cwd, sessionId, opts: CliOpts = {}) {
+  const sid = resolveSessionId(sessionId);
+  const cookie = readCookieFile(sid, opts);
+  if (!cookie) return null;
+  // Find the registry workspace by id to get the path
+  const candidates = opts.candidates || loadAllRegistryWorkspaceCandidates(opts);
+  const matched = candidates?.workspaces?.find(w =>
+    sanitizeCookieSegment(w.id) === cookie.workspaceId || sanitizeCookieSegment(w.path) === cookie.workspaceId
+  );
+  return matched ? { workspacePath: matched.path, workspaceId: matched.id } : null;
+}
+
+export function writeWorkspaceCookie(_cwd, sessionId, targetPath, opts: CliOpts = {}) {
+  const sid = resolveSessionId(sessionId);
+  // Derive workspaceId from registry match or basename
+  const candidates = opts.candidates || loadAllRegistryWorkspaceCandidates(opts);
+  const absPath = normalizeRegistryPath(targetPath);
+  const matched = candidates?.workspaces?.find(w => w.path === absPath);
+  const workspaceId = matched?.id || basename(absPath);
+  // Preserve existing ticketId if cookie already exists for this session
+  const existing = readCookieFile(sid, opts);
+  releaseCookieFile(sid, opts);
+  writeCookieFile(workspaceId, existing?.ticketId || null, sid, opts);
+}
+
+export function resolveWorkspaceTarget(startDir, query, opts: CliOpts = {}) {
+  // #645: SSOT-only (workspace.json records). No cwd-based sibling fallback.
+  // #685: LangGraph 진입 원칙 — workspace는 사람이 --workspace로 명시한다. sessionId
+  // 쿠키로 "지난번 워크스페이스"를 추측하는 폴백은 제거됨(env 미전파 환경에서 default로
+  // 무너지는 근원). query가 없으면 추측하지 않고 missing-query 노드로 떨어진다.
+  const candidates = opts.candidates || loadAllRegistryWorkspaceCandidates(opts);
+
+  if (!candidates) return null;
+  const rawQuery = String(query || "").trim();
+  if (!rawQuery) {
+    // workspace is resolved ONLY from an explicit query. No cookie/cwd inference.
+    return { candidates, target: null, reason: "missing-query" };
+  }
+
+  const matches = candidates.workspaces
+    .filter(workspace => workspaceQueryMatches(rawQuery, workspace))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  if (matches.length === 0) return { candidates, target: null, reason: "no-match" };
+  if (matches.length > 1) {
+    // Normalized lookup collapses separators, so distinct names like
+    // ".deuk-agent" (home store) and "DeukAgent" (workspace) both reduce to
+    // "deukagent" and tie. Break the tie with a case-insensitive exact match
+    // on an original (non-normalized) alias before declaring it ambiguous.
+    const exact = matches.filter(workspace =>
+      (workspace.aliases || []).some(
+        alias => String(alias).toLowerCase() === rawQuery.toLowerCase()
+      )
+    );
+    if (exact.length === 1) {
+      return { candidates, target: exact[0], reason: "matched", score: 100 };
+    }
+    return { candidates, target: null, reason: "ambiguous", matches };
+  }
+
+  return { candidates, target: matches[0], reason: "matched", score: 100 };
+}
+
+export function buildWorkspaceGuide(startDir, opts: CliOpts = {}) {
+  const hostContext = resolveWorkspaceContext(startDir);
+  // #645: SSOT-only (workspace.json records). No cwd-based sibling fallback.
+  const candidates = loadAllRegistryWorkspaceCandidates(opts);
+  const explicitQuery = opts.workspace || "";
+  const prompt = opts.prompt || "";
+  let resolution = explicitQuery ? resolveWorkspaceTarget(startDir, explicitQuery, { candidates }) : null;
+  let promptMatches = [];
+  let recommendedTarget = resolution?.target || null;
+  let reason = "";
+
+  if (recommendedTarget) {
+    reason = `explicit workspace matched: ${explicitQuery}`;
+  } else if (candidates?.workspaces?.length && prompt) {
+    promptMatches = findPromptWorkspaceMatches(prompt, candidates);
+    if (promptMatches.length === 1) {
+      recommendedTarget = promptMatches[0];
+      reason = `prompt matched workspace alias: ${recommendedTarget.id}`;
+    } else if (promptMatches.length > 1) {
+      reason = `prompt matched multiple workspaces: ${promptMatches.map(workspace => workspace.id).join(", ")}`;
+    }
+  }
+
+  if (!reason) {
+    if (!candidates?.workspaces?.length) reason = "no sibling workspace candidates found";
+    else reason = "no explicit workspace target detected";
+  }
+
+  return {
+    hostWorkspace: {
+      label: hostContext.breadcrumb,
+      path: hostContext.root
+    },
+    candidates: candidates?.workspaces || [],
+    recommendedTarget,
+    reason,
+    requiresConfirmation: !recommendedTarget && Boolean(candidates?.workspaces?.length > 1),
+    promptMatches
+  };
+}
+
+export function requireNonEmptySlug(input, fieldName = "value") {
+  const slug = toSlug(input);
+  if (slug) return slug;
+
+  const received = String(input || "").trim() || "(empty)";
+  throw new Error(
+    `[VALIDATION FAILED] ${fieldName} must produce a non-empty ASCII slug. ` +
+    `Received: ${JSON.stringify(received)}. ` +
+    `Use an ASCII title such as "basic-protocol-pack-unpack-test-redefinition".`
+  );
+}
+
+export function toSnakeCaseKey(input) {
+  return toSlug(input).replace(/-/g, "_");
+}
+
+export function formatTimestampForFile(d = new Date()) {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  const ss = String(d.getSeconds()).padStart(2, "0");
+  return `${y}${m}${day}-${hh}${mm}${ss}`;
+}
+
+export function makeEntryId() {
+  return `000-generated-${Date.now().toString(36)}`;
+}
+
+export function findFileRecursively(dir, fileName) {
+  if (!existsSync(dir)) return null;
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const res = makePath(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursively(res, fileName);
+      if (found) return found;
+    } else if (entry.name === fileName) {
+      return res;
+    }
+  }
+  return null;
+}
+
+export function detectProjectFromBody(body) {
+  const content = String(body || "");
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const l = line.trim();
+    if (l.toLowerCase().startsWith("project:")) {
+      return l.split(":")[1].trim();
+    }
+    if (l.startsWith("# Project:") || l.startsWith("## Project:")) {
+      return l.split(":")[1].trim();
+    }
+  }
+  return "global";
+}
+
+export function deriveTopicFromBaseName(baseName) {
+  const raw = String(baseName || "").split(".")[0];
+  // Remove trailing timestamp if present (e.g. title-20260426-071208)
+  const parts = raw.split("-");
+  if (parts.length >= 3) {
+    const last = parts[parts.length - 1];
+    const prev = parts[parts.length - 2];
+    if (last.length === 6 && prev.length === 8) {
+      return parts.slice(0, -2).join("-");
+    }
+  }
+  return toSlug(raw) || raw.toLowerCase();
+}
+
+export function resolveReferencedTicketPath(opts) {
+  if (!opts.ref) return null;
+  const refAbs = makePath(opts.cwd, opts.ref);
+  if (!existsSync(refAbs)) {
+    throw new Error("--ref file not found: " + opts.ref);
+  }
+  return toRepoRelativePath(opts.cwd, refAbs);
+}
+
+export function inferRefTitleAndTopic(opts) {
+  if (!opts.ref) return null;
+  const refAbs = makePath(opts.cwd, opts.ref);
+
+  let body = "";
+  try {
+    body = readFileSync(refAbs, "utf8");
+  } catch (err) {
+    if (process.env.DEBUG) console.warn(`[DEBUG] Failed to read ref ${refAbs}:`, err);
+    return null;
+  }
+
+  const lines = body.split("\n");
+  let title = "";
+  for (const line of lines) {
+    const l = line.trim();
+    if (l.startsWith("## Task:")) {
+      title = l.replace("## Task:", "").trim();
+      break;
+    }
+    if (l.startsWith("# ")) {
+      title = l.replace("# ", "").trim();
+      break;
+    }
+  }
+
+  const base = basename(refAbs).split(".")[0];
+  const finalTitle = title || base;
+  return {
+    title: String(finalTitle).trim(),
+    slug: toSlug(finalTitle),
+  };
+}
+
+export function parseFrontMatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines.length < 3 || lines[0].trim() !== "---") {
+    return { meta: {}, content, parseError: null };
+  }
+
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+
+  if (endIdx === -1) return { meta: {}, content, parseError: null };
+
+  const metaStr = lines.slice(1, endIdx).join("\n");
+  const bodyStr = lines.slice(endIdx + 1).join("\n");
+  try {
+    const meta = YAML.parse(metaStr);
+    return { meta: meta || {}, content: bodyStr, parseError: null };
+  } catch (err) {
+    return { meta: {}, content: bodyStr, parseError: err.message || "invalid frontmatter" };
+  }
+}
+
+// Strip a leading frontmatter block from content so that round-tripping through
+// parseFrontMatter ??stringifyFrontMatter never produces a double-frontmatter file.
+export function stripLeadingFrontMatter(content) {
+  const original = String(content || "");
+  // Skip leading whitespace/newlines: parseFrontMatter leaves a blank line in
+  // front of any second frontmatter block (e.g. a duplicated header from a broken
+  // migration), so the "---" we want to strip is not necessarily at index 0.
+  const s = original.replace(/^\s+/, "");
+  if (!s.startsWith("---")) return original;
+  const rest = s.slice(3);
+  const end = rest.search(/\n---(\s*\n|$)/);
+  if (end === -1) return original;
+  return rest.slice(end + 4).replace(/^\n+/, "");
+}
+
+export function stringifyFrontMatter(meta, content) {
+  const cleanMeta = sanitizeFrontMatterMeta(meta);
+  const yamlStr = YAML.stringify(cleanMeta).trim();
+  const cleanContent = stripLeadingFrontMatter(content);
+  // Double newline after frontmatter to ensure markdown rendering integrity
+  return `---\n${yamlStr}\n---\n\n\n${cleanContent.trim()}\n`;
+}
+
+export function sanitizeFrontMatterMeta(meta: CliOpts = {}) {
+  const cleanMeta = { ...meta };
+  for (const key of [
+    "path",
+    "absPath",
+    "absolutePath",
+    "relativePath",
+    "sourcePath",
+    "targetPath",
+    "workspacePath",
+    "rulesPath",
+    "ticketPath",
+    "docmeta"
+  ]) {
+    delete cleanMeta[key];
+  }
+  // Remove redundant or default fields to keep frontmatter slim
+  if (cleanMeta.project === 'global') delete cleanMeta.project;
+  if (!cleanMeta.submodule) delete cleanMeta.submodule;
+  
+  // Normalize date format if it looks like an ISO string
+  if (typeof cleanMeta.createdAt === 'string' && cleanMeta.createdAt.includes('T')) {
+    cleanMeta.createdAt = cleanMeta.createdAt.replace('T', ' ').split('.')[0];
+  }
+  return cleanMeta;
+}
+
+/**
+ * Returns true if semver a is less than b
+ */
+export function semverLt(a, b) {
+  const pa = String(a || "0").replace(/[^0-9.]/g, "").split(".").map(Number);
+  const pb = String(b || "0").replace(/[^0-9.]/g, "").split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const na = pa[i] ?? 0, nb = pb[i] ?? 0;
+    if (na !== nb) return na < nb;
+  }
+  return false;
+}
+
+export async function checkUpdateNotifier() {
+  try {
+    const { fileURLToPath } = await import("url");
+    const pkgPath = makePath(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const currentVersion = pkg.version;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 800);
+    if (typeof timeoutId.unref === "function") timeoutId.unref();
+    const res = await fetch("https://registry.npmjs.org/deuk-agent-flow/latest", {
+      signal: controller.signal
+    }).finally(() => {
+      clearTimeout(timeoutId);
+    });
+    if (res.ok) {
+      const data = await res.json() as CliOpts;
+      // Only notify when registry version is strictly newer than local (handles local dev symlink case)
+      if (data.version && semverLt(currentVersion, data.version)) {
+        console.warn(`\n\x1b[33m?뮕 Update available! ${currentVersion} ??${data.version}\x1b[0m`);
+        console.warn(`\x1b[36mRun 'npm install -g deuk-agent-flow', then 'deuk-agent-flow init' from the repo or workspace root.\x1b[0m\n`);
+      }
+    }
+  } catch(e) {
+    // Ignore timeout or network errors silently
+  }
+}
+
+export const DEFAULT_IGNORE_DIRS = ["node_modules", ".git", DEUK_ROOT_DIR, "tmp", "temp", ".tmp", ".cache"];
+
+/**
+ * Resolves all potential ticket directories for a given path.
+ * Returns { primary, legacy: [] }
+ */
+export function resolveTicketSystemPaths(cwd) {
+  return {
+    primary: makePath(cwd, DEUK_ROOT_DIR, TICKET_SUBDIR),
+    legacy: []
+  };
+}
+
+// Finds the nearest ancestor that owns a .deuk-agent dir (the workspace root).
+// Exported so commands can locate the workspace WITHOUT going through
+// detectConsumerTicketDir (which now returns the home ticket dir, #622).
+export function findWorkspaceRoot(startDir) {
+  // #080: the user home dir owns ~/.deuk-agent (the ticket STORE, not a workspace
+  // marker). Climbing past a non-workspace cwd must never land on home — that minted
+  // a "joy"-style ghost workspace and nested ticket dirs inside the store.
+  const home = resolve(resolveUserHome());
+  let curr = resolve(startDir);
+  while (curr && curr !== dirname(curr)) {
+    if (curr === home) return null;
+    if (hasWorkspaceMarker(curr)) return curr;
+    if (hasLocalProjectBoundary(curr) && curr !== resolve(startDir)) return null;
+    curr = dirname(curr);
+  }
+  if (curr !== home && hasWorkspaceMarker(curr)) return curr;
+  return null;
+}
+
+// #622/#623: ticket data lives in ~/.deuk-agent/tickets/{ticketKey}/, NOT in the
+// workspace git tree. detectConsumerTicketDir is a PURE READ — it resolves the home
+// ticket dir for the workspace WITHOUT side effects (no marker creation, no file
+// moves, no registry writes). The actual migration (reconcile) is triggered once on
+// ticket-command entry and on init via ensureWorkspaceMigrated() (#623), so the many
+// detect callers (index/scan/parser/document reads) never mutate state.
+export function detectConsumerTicketDir(startDir, opts: CliOpts = {}) {
+  const root = findWorkspaceRoot(startDir);
+  if (!root) return null;
+  // #626: findWorkspaceRoot walks ANCESTORS for a .deuk-agent dir. From a non-workspace
+  // cwd (e.g. %TEMP%\foo) it climbs all the way to ~/.deuk-agent and returns the HOME
+  // dir itself — which is the ticket STORE, not a workspace. Treating it as one yields a
+  // doubled `tickets/.deuk-agent/tickets/main` path and scatters reads. A non-workspace
+  // cwd has no ticket dir to read: return null rather than mis-resolving onto the store.
+  try {
+    const home = ticketHomeModule();
+    if (home.isHomeStoreRoot(root, opts)) return null;
+  } catch { /* fall through to legacy resolution below */ }
+  try {
+    const home = ticketHomeModule();
+    // Resolve the home ticket dir from already-known state only. Prefer the registry
+    // entry (keyed by the existing marker id); fall back to basename when not yet
+    // migrated. Crucially, this reads — it does not create a marker or move files.
+    return home.resolveHomeTicketDirForWorkspace(root, opts);
+  } catch {
+    // If home resolution fails for any reason, fall back to the in-workspace path
+    // so the tool keeps working rather than losing the ticket system entirely.
+    return resolveTicketSystemPaths(root).primary;
+  }
+}
+
+// The WORKSPACE root (where .deuk-agent lives) — distinct from where tickets are
+// stored. Since #622 moved ticket storage to home, this must use findWorkspaceRoot
+// directly; deriving it from detectConsumerTicketDir would now yield the home dir
+// and corrupt every workspace breadcrumb/identity that depends on it.
+export function resolveConsumerTicketRoot(startDir, opts: CliOpts = {}) {
+  return findWorkspaceRoot(startDir);
+}
+
+// #080: true when cwd is the user's ~/.deuk-agent store or anywhere inside it. The
+// store holds ticket data ({key}/...), NOT workspaces; registering any path under it
+// nests tickets/{key}/.deuk-agent/tickets and mints ghost keys. Mirrors the home guard
+// in cli-ticket-home.isHomeStoreRoot but lives here to avoid a circular import.
+function isInsideHomeStore(cwd, opts: CliOpts = {}) {
+  const here = normalizeRegistryPath(resolve(String(cwd || "")));
+  const home = normalizeRegistryPath(resolveUserHome(opts));
+  if (here === home) return true;
+  const store = normalizeRegistryPath(makePath([resolveUserHome(opts), DEUK_ROOT_DIR], opts));
+  return here === store || here.startsWith(store + "/");
+}
+
+// #638: true when path is a DIRECT child of the user home dir (e.g. ~/DeukAgentFlow).
+// Workspaces live in project dirs (D:\workspace\...), never directly under home;
+// such paths are ghost markers minted by past cwd-fallback bugs.
+export function isHomeDirectChild(p, opts: CliOpts = {}) {
+  // normalizeRegistryPath already yields the canonical (Windows-style) path; do NOT
+  // run it through path.resolve under POSIX node — that mangles "C:\..\.." (#632).
+  const here = normalizeRegistryPath(String(p || ""));
+  const home = normalizeRegistryPath(resolveUserHome(opts));
+  for (const sep of ["/", "\\"]) {
+    if (here.startsWith(home + sep)) {
+      const rest = here.slice(home.length + 1);
+      return rest.length > 0 && !rest.includes("/") && !rest.includes("\\");
+    }
+  }
+  return false;
+}
+
+// #626: the authoritative answer to "is this cwd a real workspace I may register?".
+// findWorkspaceRoot only finds an ancestor that ALREADY owns a .deuk-agent marker, so
+// callers used `findWorkspaceRoot(cwd) || cwd` to also cover first-time registration —
+// but that `|| cwd` fallback turns ANY cwd (a %TEMP% dir, an arbitrary subfolder) into
+// a "workspace", spawning ghost ticketKeys and scattering tickets. Replace that pattern
+// with this: return the marker-owning root if one exists; otherwise accept cwd ONLY when
+// it is itself a project boundary (.git / package.json / AGENTS.md / PROJECT_RULE.md) —
+// i.e. a place worth migrating on first run. Return null for everything else so reconcile
+// is skipped rather than minting a ghost. An explicit --workspace always wins.
+export function resolveRealWorkspaceRoot(cwd, opts: CliOpts = {}) {
+  if (opts && opts.workspace) return normalizeRegistryPath(opts.workspace);
+  // #080: NEVER register anything inside the home ticket store (~/.deuk-agent).
+  // Each {key}/ folder there carries its own .deuk-agent subtree, so findWorkspaceRoot
+  // would treat it as a workspace and recurse — nesting tickets/{key}/.deuk-agent/tickets
+  // and spawning ghost keys. Guard the whole store subtree up front.
+  if (isInsideHomeStore(cwd, opts)) return null;
+  // #645: a workspace is ONLY a directory that already owns a .deuk-agent marker
+  // (findWorkspaceRoot walks up to find one). We do NOT promote a bare cwd to a new
+  // workspace just because it looks like a project boundary — that cwd-promotion was
+  // a ghost factory. New workspaces are created exclusively by `deuk-agent-flow init`,
+  // which writes the marker; thereafter findWorkspaceRoot finds it. No marker → null.
+  return findWorkspaceRoot(cwd) || null;
+}
+
+export function resolveWorkspaceContext(startDir = "") {
+  // #633: NO cwd fallback. If startDir has no real .deuk-agent workspace marker,
+  // root is "" — we must NOT treat the cwd (e.g. the home dir C:\Users\joy) as a
+  // workspace, which would surface a bogus "joy" breadcrumb and drive maintenance
+  // into null-path crashes. Callers that genuinely need a path fall back themselves.
+  const root = resolveConsumerTicketRoot(startDir) || "";
+  return {
+    root,
+    breadcrumb: root ? basename(root) : ""
+  };
+}
+
+export function isInsideGitWorkTree(cwd) {
+  let curr = resolve(cwd);
+  while (curr && curr !== dirname(curr)) {
+    if (isGitWorkTreeMarker(makePath(curr, ".git"))) return true;
+    curr = dirname(curr);
+  }
+  return isGitWorkTreeMarker(makePath(curr, ".git"));
+}
+
+function resolveGitWorkTreeRoot(startDir) {
+  let curr = resolve(startDir);
+  while (curr && curr !== dirname(curr)) {
+    if (isGitWorkTreeMarker(makePath(curr, ".git"))) return curr;
+    curr = dirname(curr);
+  }
+  if (isGitWorkTreeMarker(makePath(curr, ".git"))) return curr;
+  return null;
+}
+
+function isGitWorkTreeMarker(gitMarkerPath) {
+  if (!existsSync(gitMarkerPath)) return false;
+  const markerStat = statSync(gitMarkerPath);
+  if (!markerStat.isDirectory()) return markerStat.isFile();
+  return existsSync(makePath(gitMarkerPath, "HEAD")) || existsSync(makePath(gitMarkerPath, "commondir"));
+}
+
+/**
+ * Unified workspace/submodule discovery.
+ */
+export function discoverAllWorkspaces(baseCwd, ignoreDirs = DEFAULT_IGNORE_DIRS, out: Set<string> = new Set<string>()) {
+  if (!existsSync(baseCwd)) return Array.from(out);
+
+  const paths = resolveTicketSystemPaths(baseCwd);
+  const isWorkspaceRoot = existsSync(paths.primary) || paths.legacy.length > 0;
+  if (isWorkspaceRoot) {
+    out.add(baseCwd);
+    // Stop descending once a workspace root is found.
+    // This prevents nested child workspaces from being treated as independent roots.
+    return Array.from(out);
+  }
+
+  try {
+    const entries = readdirSync(baseCwd, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      if (ignoreDirs.includes(ent.name) || ent.name.startsWith(".deuk-agent")) continue;
+      discoverAllWorkspaces(makePath(baseCwd, ent.name), ignoreDirs, out);
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.warn(`[DEBUG] Failed to read directory ${baseCwd}:`, err);
+  }
+  return Array.from(out);
+}
+
+async function probeMcpUrl(url) {
+  const methods = ["HEAD", "GET"];
+
+  for (const method of methods) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1000);
+    try {
+      const res = await fetch(url, { method, signal: controller.signal });
+      if (res.body?.cancel) await res.body.cancel().catch(() => {});
+      if (res.ok || res.status === 405) return true;
+    } catch (err) {
+      if (process.env.DEBUG) console.warn(`[DEBUG] SSE ${method} ping failed for ${url}:`, err);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if the deuk-agent-context MCP server is active for the given workspace.
+ * Detects .mcp.json, .cursor/mcp.json, or .vscode/mcp.json and pings SSE servers if applicable.
+ */
+export function collectMcpConfigStatuses(cwd) {
+  const mcpPaths = [
+    makePath(cwd, ".mcp.json"),
+    makePath(cwd, ".cursor", "mcp.json"),
+    makePath(cwd, ".vscode", "mcp.json")
+  ];
+  const statuses = [];
+  for (const p of mcpPaths) {
+    if (existsSync(p)) {
+      try {
+        const config = JSON.parse(readFileSync(p, "utf8"));
+        const servers = config.mcpServers || config.servers || {};
+        const deuk = servers["deuk-agent-context"] || servers["deuk_agent_context"];
+        if (deuk) {
+          statuses.push({
+            path: p,
+            transport: deuk.command ? "stdio" : (deuk.url ? "sse" : "unknown"),
+            command: deuk.command || "",
+            url: deuk.url || ""
+          });
+        }
+      } catch (err) {
+        if (process.env.DEBUG) console.warn(`[DEBUG] Failed to parse MCP config ${p}: ${err.message}`);
+        continue;
+      }
+    }
+  }
+  return statuses;
+}
+
+/**
+ * Checks if the deuk-agent-context MCP server is active for the given workspace.
+ * Detects .mcp.json, .cursor/mcp.json, or .vscode/mcp.json and pings SSE servers if applicable.
+ */
+export async function isMcpActive(cwd) {
+  const statuses = collectMcpConfigStatuses(cwd);
+  for (const status of statuses) {
+    if (status.command) return true; // Stdio is managed by IDE
+    if (status.url && await probeMcpUrl(status.url)) return true;
+  }
+  return false;
+}
+
+