@flextudio/scenario 0.1.0

package/scripts/build-skill-payload.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// build-skill-payload — cli 자산 생성기.
+//
+// 계약 단일 진실원본(core/contract.mjs + schema/v1 + examples + catalog/rules)을
+// ~/.claude/skills/scenario-gen/ 동형 레이아웃의 정적 자산으로 펼친다.
+// prepack 단계에서 자동 실행 (postpack 이 정리). 멱등.
+//
+// 출력 위치:
+//   <package-root>/skill/
+//     ├── schemas/{ <name>.schema.json, ..., index.json }
+//     ├── docs/   { <name>.md,         ..., index.json }
+//     ├── patterns/{ <tier>/<name>.json, ..., index.json }
+//     ├── examples/{ <rel>.json,       ..., index.json }
+//     ├── skill-guides/{ <name>.md,    ..., index.json }   (있을 때만)
+//     ├── catalog.json
+//     ├── rules.md
+//     ├── README.md
+//     ├── design-rules.md
+//     └── design-system.md
+//
+// 정적 자산 (SKILL.md, references/) 은 건드리지 않음.
+
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync,
+  cpSync, statSync, readdirSync, rmSync,
+} from "node:fs";
+import { join, dirname, resolve, relative, basename, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 경로
+// ─────────────────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = dirname(__dirname);
+// cli/ 는 repo 루트 바로 아래 → 한 단계 위가 CONTRACT_ROOT.
+const CONTRACT_ROOT = resolve(PACKAGE_ROOT, "..");
+const SKILL_DST = join(PACKAGE_ROOT, "skill");
+// 패턴 단일 진실원본 = core/contract.mjs (@flextudio/contract-core). MCP 비의존.
+const CORE_CONTRACT_MJS = join(CONTRACT_ROOT, "core", "contract.mjs");
+
+const log = (m) => process.stdout.write(`[build-skill-payload] ${m}\n`);
+const warn = (m) => process.stderr.write(`[build-skill-payload] ${m}\n`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// build 산물 식별 — postpack 이 청소할 대상. 정적 자산 (SKILL.md, references/)
+// 은 보존.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BUILD_ARTIFACTS = [
+  "schemas",
+  "docs",
+  "patterns",
+  "examples",
+  "skill-guides",
+  "catalog.json",
+  "rules.md",
+  "README.md", // 출력명은 README.md, 소스는 spec/skill-readme.md (repo 루트 README 아님)
+  "design-rules.md",
+  "design-system.md",
+  "intent-rules.md",
+  "intent-system.md",
+];
+
+function clearBuildArtifacts() {
+  for (const name of BUILD_ARTIFACTS) {
+    const p = join(SKILL_DST, name);
+    if (existsSync(p)) {
+      rmSync(p, { recursive: true, force: true });
+    }
+  }
+}
+
+function ensureDir(p) { mkdirSync(p, { recursive: true }); }
+
+function writeJson(p, obj) {
+  ensureDir(dirname(p));
+  writeFileSync(p, JSON.stringify(obj, null, 2) + "\n", "utf-8");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 진실원본 sanity
+// ─────────────────────────────────────────────────────────────────────────────
+
+function assertSource(p, label) {
+  if (!existsSync(p)) {
+    warn(`✘ ${label} 없음: ${p}`);
+    process.exit(2);
+  }
+}
+
+assertSource(join(CONTRACT_ROOT, "schema/v1"), "schema/v1");
+assertSource(join(CONTRACT_ROOT, "spec", "catalog.json"), "spec/catalog.json");
+assertSource(join(CONTRACT_ROOT, "spec", "rules.md"), "spec/rules.md");
+// skill README 는 repo 루트 README(생성무관 내용 다수) 와 분리된 생성전용 소스.
+assertSource(join(CONTRACT_ROOT, "spec", "skill-readme.md"), "spec/skill-readme.md");
+assertSource(join(CONTRACT_ROOT, "examples"), "examples");
+assertSource(CORE_CONTRACT_MJS, "core/contract.mjs");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 동적 import — patterns 는 core/contract.mjs 의 listPatterns/getPattern 을
+// 그대로 사용 (단일 진실원본 = @flextudio/contract-core).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const contract = await import(pathToFileURL(CORE_CONTRACT_MJS).href);
+const { listPatterns, getPattern } = contract;
+
+if (typeof listPatterns !== "function" || typeof getPattern !== "function") {
+  warn("✘ core/contract.mjs 에서 listPatterns/getPattern 을 찾지 못함");
+  process.exit(2);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 메인
+// ─────────────────────────────────────────────────────────────────────────────
+
+log(`SKILL_DST     = ${SKILL_DST}`);
+log(`CONTRACT_ROOT = ${CONTRACT_ROOT}`);
+ensureDir(SKILL_DST);
+clearBuildArtifacts();
+
+// 1. catalog / rules / README / design-rules / design-system
+//    원본은 spec/ 아래지만 skill 출력은 flat 유지 (SKILL.md 가 평면 경로로 참조).
+cpSync(join(CONTRACT_ROOT, "spec", "catalog.json"), join(SKILL_DST, "catalog.json"));
+cpSync(join(CONTRACT_ROOT, "spec", "rules.md"),     join(SKILL_DST, "rules.md"));
+cpSync(join(CONTRACT_ROOT, "spec", "skill-readme.md"), join(SKILL_DST, "README.md"));
+
+const DESIGN_RULES_SRC = join(CONTRACT_ROOT, "schema/v1/design-system/DESIGN.md");
+const DESIGN_SYS_SRC   = join(CONTRACT_ROOT, "schema/v1/design-system/README.md");
+const INTENT_RULES_SRC = join(CONTRACT_ROOT, "runtime/v1/intent-system/INTENT.md");
+const INTENT_SYS_SRC   = join(CONTRACT_ROOT, "runtime/v1/intent-system/README.md");
+if (existsSync(INTENT_RULES_SRC)) cpSync(INTENT_RULES_SRC, join(SKILL_DST, "intent-rules.md"));
+if (existsSync(INTENT_SYS_SRC))   cpSync(INTENT_SYS_SRC,   join(SKILL_DST, "intent-system.md"));
+if (existsSync(DESIGN_RULES_SRC)) cpSync(DESIGN_RULES_SRC, join(SKILL_DST, "design-rules.md"));
+if (existsSync(DESIGN_SYS_SRC))   cpSync(DESIGN_SYS_SRC,   join(SKILL_DST, "design-system.md"));
+
+log(`top-level: catalog.json, rules.md, README.md(←spec/skill-readme.md), design-rules.md, design-system.md, intent-rules.md, intent-system.md`);
+
+// 2. schemas/ — schema/v1/**/*.schema.json
+const SCHEMA_SRC = join(CONTRACT_ROOT, "schema/v1");
+const SCHEMA_DST = join(SKILL_DST, "schemas");
+ensureDir(SCHEMA_DST);
+
+function walkFiles(dir, predicate, baseDir = dir, acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkFiles(full, predicate, baseDir, acc);
+    else if (entry.isFile() && predicate(full, entry.name)) {
+      acc.push(relative(baseDir, full).split(sep).join("/"));
+    }
+  }
+  return acc;
+}
+
+const schemaRelFiles = walkFiles(SCHEMA_SRC, (_, n) => n.endsWith(".schema.json"));
+const schemaIndex = [];
+for (const rel of schemaRelFiles) {
+  const src = join(SCHEMA_SRC, rel);
+  const dst = join(SCHEMA_DST, rel);
+  ensureDir(dirname(dst));
+  cpSync(src, dst);
+  let meta = { name: rel.replace(/\.schema\.json$/, ""), path: rel };
+  try {
+    const j = JSON.parse(readFileSync(src, "utf-8"));
+    if (j.title)       meta.title       = j.title;
+    if (j.description) meta.description = j.description;
+    if (j.$id)         meta.$id         = j.$id;
+  } catch { /* ignore */ }
+  schemaIndex.push(meta);
+}
+writeJson(join(SCHEMA_DST, "index.json"), { count: schemaIndex.length, schemas: schemaIndex });
+log(`schemas/    : ${schemaIndex.length} schemas`);
+
+// 3. docs/ — schema/v1/**/*.md (단 design-system/ 은 top-level 로 별도 처리)
+const DOCS_DST = join(SKILL_DST, "docs");
+ensureDir(DOCS_DST);
+const docRelFiles = walkFiles(
+  SCHEMA_SRC,
+  (full, n) => n.endsWith(".md") && !full.includes(`${sep}design-system${sep}`),
+);
+const docsIndex = [];
+for (const rel of docRelFiles) {
+  const src = join(SCHEMA_SRC, rel);
+  const dst = join(DOCS_DST, rel);
+  ensureDir(dirname(dst));
+  cpSync(src, dst);
+  docsIndex.push({ path: rel });
+}
+writeJson(join(DOCS_DST, "index.json"), { count: docsIndex.length, docs: docsIndex });
+log(`docs/       : ${docsIndex.length} docs`);
+
+// 4. patterns/ — core/contract.listPatterns/getPattern 단일 진실원본.
+const PATTERNS_DST = join(SKILL_DST, "patterns");
+ensureDir(PATTERNS_DST);
+
+// listPatterns 반환 shape: { total, returned, byTier, filter, patterns: [...] }
+const patternList = listPatterns();
+const patternsIndex = [];
+let patternCount = 0;
+for (const entry of patternList.patterns || []) {
+  // listPatterns 반환 shape 는 contract.mjs 가 결정. 일반적으로 { tier, name, ... }.
+  const tier = entry.tier || "atom";
+  const name = entry.name;
+  if (!name) continue;
+  try {
+    const body = getPattern({ tier, name });
+    const dst = join(PATTERNS_DST, tier, `${name}.json`);
+    writeJson(dst, body);
+    patternsIndex.push({ tier, name, path: `${tier}/${name}.json`, ...stripBulk(entry) });
+    patternCount += 1;
+  } catch (e) {
+    warn(`! pattern ${tier}/${name} 추출 실패: ${e.message}`);
+  }
+}
+writeJson(join(PATTERNS_DST, "index.json"), { count: patternsIndex.length, patterns: patternsIndex });
+log(`patterns/   : ${patternCount} patterns`);
+
+function stripBulk(o) {
+  // index 에는 메타만 — 본문이 큰 필드 제거.
+  const skip = new Set(["body", "content", "controls", "fragment", "scenario", "materialize"]);
+  const out = {};
+  for (const [k, v] of Object.entries(o || {})) {
+    if (skip.has(k)) continue;
+    if (typeof v === "function") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// 5. examples/ — examples/**/*.json + index 메타.
+const EX_SRC = join(CONTRACT_ROOT, "examples");
+const EX_DST = join(SKILL_DST, "examples");
+ensureDir(EX_DST);
+const exRelFiles = walkFiles(EX_SRC, (_, n) => n.endsWith(".json"));
+const exIndex = [];
+for (const rel of exRelFiles) {
+  const src = join(EX_SRC, rel);
+  const dst = join(EX_DST, rel);
+  ensureDir(dirname(dst));
+  cpSync(src, dst);
+  const meta = { id: rel.replace(/\.json$/, ""), path: rel };
+  try {
+    const j = JSON.parse(readFileSync(src, "utf-8"));
+    if (j.fScenarioName) meta.title = j.fScenarioName;
+    if (j.Steps && typeof j.Steps === "object") {
+      meta.stepCount = Object.keys(j.Steps).length;
+      const types = new Set();
+      const controlTypes = {};
+      for (const step of Object.values(j.Steps)) {
+        collectControlTypes(step.Contents, controlTypes);
+        if (step.FixedContentsTop) collectControlTypes(step.FixedContentsTop, controlTypes);
+        if (step.FixedContentsBottom) collectControlTypes(step.FixedContentsBottom, controlTypes);
+      }
+      meta.controlTypes = controlTypes;
+
+      // 구조 태그 — 예제가 쓰는 pattern 호출 수집 (도메인이 아닌 구조로 선택하도록).
+      // 패턴명은 section 4 의 patternsIndex 에서 도출 (하드코딩 회피).
+      const patternNames = new Set(patternsIndex.map((p) => p.name));
+      const usedPatterns = new Set();
+      const scanPatterns = (node) => {
+        if (Array.isArray(node)) { node.forEach(scanPatterns); return; }
+        if (node && typeof node === "object") {
+          const keys = Object.keys(node);
+          if (keys.length === 1 && patternNames.has(keys[0])) usedPatterns.add(keys[0]);
+          for (const v of Object.values(node)) scanPatterns(v);
+        }
+      };
+      for (const step of Object.values(j.Steps)) {
+        scanPatterns(step.Contents);
+        scanPatterns(step.FixedContentsTop);
+        scanPatterns(step.FixedContentsBottom);
+      }
+      if (usedPatterns.size) meta.patterns = [...usedPatterns].sort();
+    }
+  } catch { /* ignore */ }
+  exIndex.push(meta);
+}
+// README 도 examples/ 디렉토리 안에 있으면 같이 복사 (md).
+const exReadme = join(EX_SRC, "README.md");
+if (existsSync(exReadme)) cpSync(exReadme, join(EX_DST, "README.md"));
+writeJson(join(EX_DST, "index.json"), { count: exIndex.length, examples: exIndex });
+log(`examples/   : ${exIndex.length} examples`);
+
+function collectControlTypes(groups, acc) {
+  if (!Array.isArray(groups)) return;
+  for (const g of groups) {
+    const children = g?.Contents || g?.Children || [];
+    if (Array.isArray(children)) {
+      for (const c of children) {
+        const t = c?.ControlType;
+        if (typeof t === "string") acc[t] = (acc[t] || 0) + 1;
+        // group/container 도 재귀.
+        if (c?.Contents || c?.Children) collectControlTypes([c], acc);
+      }
+    }
+  }
+}
+
+// 6. skill-guides/ — skill-guides/**/*.md (화면 생성 보편 가이드) + index 메타.
+//    진실원본: <CONTRACT_ROOT>/skill-guides/ (루트 별도 관리 폴더, 순수 스킬 자산).
+//    디렉토리가 없으면 조용히 skip (optional).
+const GUIDES_SRC = join(CONTRACT_ROOT, "skill-guides");
+if (existsSync(GUIDES_SRC)) {
+  const GUIDES_DST = join(SKILL_DST, "skill-guides");
+  ensureDir(GUIDES_DST);
+  const guideRelFiles = walkFiles(GUIDES_SRC, (_, n) => n.endsWith(".md"));
+  const guideIndex = [];
+  for (const rel of guideRelFiles) {
+    const src = join(GUIDES_SRC, rel);
+    const dst = join(GUIDES_DST, rel);
+    ensureDir(dirname(dst));
+    cpSync(src, dst);
+    if (rel.toLowerCase() === "readme.md") continue; // index 에는 항목 파일만
+    const meta = { id: rel.replace(/\.md$/, ""), path: rel };
+    try {
+      // 첫 H1 을 title, 인용(>) 첫 줄을 summary 로.
+      const lines = readFileSync(src, "utf-8").split("\n");
+      const h1 = lines.find((l) => /^#\s+/.test(l));
+      if (h1) meta.title = h1.replace(/^#\s+/, "").trim();
+      const quote = lines.find((l) => /^>\s+/.test(l));
+      if (quote) meta.summary = quote.replace(/^>\s+/, "").trim();
+    } catch { /* ignore */ }
+    guideIndex.push(meta);
+  }
+  writeJson(join(GUIDES_DST, "index.json"), { count: guideIndex.length, guides: guideIndex });
+  log(`skill-guides/: ${guideIndex.length} items`);
+} else {
+  log(`skill-guides/: 없음 (skip)`);
+}
+
+// 7. SKILL.md 본문은 별도로 관리 — 정적이라 건드리지 않음.
+//    단 build 산물이 들어왔는지 sanity 한 줄.
+const SKILL_MD = join(SKILL_DST, "SKILL.md");
+if (!existsSync(SKILL_MD)) {
+  warn(`! SKILL.md 없음: ${SKILL_MD} — W6 에서 작성 필요`);
+}
+
+log(`done.`);

package/scripts/cleanup.mjs

@@ -0,0 +1,166 @@
+// scenario-gen 의 사용자 머신 산출물 cleanup — `flex-scenario uninstall`(cmdUninstall) 과
+// 직접 실행(디버깅)에서 호출. (npm 7+ 는 preuninstall lifecycle 을 실행하지 않는다 —
+// 삭제 시점은 cmdUninstall 이 만든다.)
+//
+// 2026-06-09 멀티 에이전트: 스킬/커맨드는 "설치한 폴더" 로컬에 에이전트별 레이아웃으로 깔린다
+// (claude=.claude, codex=.agents, antigravity=.agent). 전역 receipt 의 installs[]=[{dir,agent}]
+// 를 읽어 각 (폴더, 에이전트) 의 자산만 정리한다.
+//   ※ "현재 폴더(cwd)" 는 정리 대상에 넣지 않는다 — repo 에서 uninstall 시 벤치가 깐
+//     자산을 오삭제할 위험. init/postinstall 은 항상 receipt 에 기록되므로 installs 만으로 충분하다.
+//
+// 스코프 (2026-06-10):
+//   here — receipt 중 dir 일치 항목만 정리 + receipt 에서 제거 (CLI·~/.flex-scenario 유지)
+//   all  — receipt 의 모든 항목 정리 + receipt installs 비움 (CLI·~/.flex-scenario 유지)
+//   full — all + 전역 ~/.flex-scenario/ 삭제 (contract-root·receipt) → .bak 있으면 복원
+//
+// 모든 동작은 best-effort — 실패해도 throw 하지 않고 stderr 경고만 출력.
+// (cleanup 부분 실패가 뒤따르는 npm uninstall 단계를 막으면 안 됨.)
+
+import { existsSync, rmSync, renameSync, readFileSync, writeFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  skillPaths,
+  FLEX_HOME, FLEX_HOME_BAK, INSTALL_RECEIPT,
+} from "./install-paths.mjs";
+
+function safeRm(p) {
+  if (!existsSync(p)) return false;
+  try {
+    rmSync(p, { recursive: true, force: true });
+    return true;
+  } catch (e) {
+    process.stderr.write(`[scenario-gen cleanup] rm ${p} 실패: ${e.message}\n`);
+    return false;
+  }
+}
+
+function safeRestoreBak(bak, dst) {
+  if (!existsSync(bak)) return false;
+  try {
+    // 목적지가 비어 있어야 rename 가능 — cleanup 1단계에서 이미 제거됨.
+    renameSync(bak, dst);
+    return true;
+  } catch (e) {
+    process.stderr.write(`[scenario-gen cleanup] restore ${bak} → ${dst} 실패: ${e.message}\n`);
+    return false;
+  }
+}
+
+// receipt 에서 정리 대상 (폴더, 에이전트) 목록을 만든다.
+// (전역 FLEX_HOME 을 지우면 receipt 도 사라지므로 반드시 삭제 전에 호출할 것.)
+//   - 신버전: receipt.installs = [{dir, agent}]
+//   - 구버전: receipt.skillDirs = [dir]  → claude 로 간주
+// cmdUninstall 이 "현재 폴더 설치 여부" 판정(메뉴 항목 노출)에도 쓴다 — export.
+export function collectInstalls() {
+  const out = new Map(); // key=`${dir}::${agent}`
+  const add = (dir, agent) => {
+    const d = resolve(dir);
+    out.set(`${d}::${agent}`, { dir: d, agent });
+  };
+  try {
+    if (existsSync(INSTALL_RECEIPT)) {
+      const receipt = JSON.parse(readFileSync(INSTALL_RECEIPT, "utf-8"));
+      if (Array.isArray(receipt.installs)) {
+        for (const it of receipt.installs) {
+          if (it && typeof it.dir === "string") add(it.dir, it.agent || "claude");
+        }
+      } else if (Array.isArray(receipt.skillDirs)) {
+        for (const d of receipt.skillDirs) if (typeof d === "string") add(d, "claude");
+      }
+    }
+  } catch { /* 손상된 receipt 는 무시 */ }
+  return [...out.values()];
+}
+
+// 심링크 차이로 같은 폴더가 다른 문자열이 되는 것 방지 (예: macOS /tmp → /private/tmp).
+// 경로가 더 이상 존재하지 않으면 lexical 값 그대로 비교.
+function realpathOrSelf(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+// dir 의 설치 항목 — dir 가 receipt 에 기록된 설치 폴더 **자신**일 때만 매치.
+// 하위/부모 폴더는 불인정 — 다른 위치에서 실행했다고 엉뚱한 설치를 지우는 의외성 방지.
+// 심링크 차이로 같은 폴더가 다른 문자열이 되는 것만 realpath 로 정규화해 흡수.
+// 반환 항목의 dir 는 receipt 에 기록된 값 그대로 — cleanup 의 here 필터(t.dir 비교)와 일치.
+// cmdUninstall 의 here 스코프 판정에 쓴다 — export.
+export function findInstallAt(dir) {
+  const d = realpathOrSelf(resolve(dir));
+  return collectInstalls().find((t) => realpathOrSelf(t.dir) === d) ?? null;
+}
+
+// 부분 정리(here/all) 후 receipt 를 잔여 목록으로 재기록 — 다음 uninstall/doctor 가
+// 정확한 잔여 설치 목록을 본다. best-effort.
+function rewriteReceiptInstalls(remaining) {
+  try {
+    if (!existsSync(INSTALL_RECEIPT)) return;
+    const receipt = JSON.parse(readFileSync(INSTALL_RECEIPT, "utf-8"));
+    receipt.installs = remaining.map(({ dir, agent }) => ({ dir, agent }));
+    receipt.skillDirs = [...new Set(remaining.map((x) => x.dir))]; // 구버전 호환 필드
+    writeFileSync(INSTALL_RECEIPT, JSON.stringify(receipt, null, 2) + "\n", "utf-8");
+  } catch (e) {
+    process.stderr.write(`[scenario-gen cleanup] receipt 갱신 실패: ${e.message}\n`);
+  }
+}
+
+// scope: "here"(dir 일치 항목만) | "all"(모든 설치 폴더) | "full"(all + ~/.flex-scenario).
+// 기본 full — 기존 호출(직접 실행 디버깅·bench)과 동작 호환.
+export function cleanup({ verbose = true, scope = "full", dir } = {}) {
+  const log = (msg) => { if (verbose) process.stdout.write(msg + "\n"); };
+
+  // FLEX_HOME 삭제 전에 정리 대상 목록 확보 (receipt 가 FLEX_HOME 안에 있음).
+  const all = collectInstalls();
+  const dirKey = dir ? resolve(dir) : null;
+  const targets = scope === "here" ? all.filter((t) => t.dir === dirKey) : all;
+
+  log("");
+  log(
+    "✔ scenario-gen 정리" +
+    (scope === "here" ? `  (현재 폴더만: ${dirKey})` : scope === "all" ? "  (모든 설치 폴더)" : ""),
+  );
+
+  let removedAny = false;
+  let restoredAny = false;
+  for (const { dir, agent } of targets) {
+    const { DOT_DIR, SKILL_DST, SKILL_BAK, COMMAND_DST, COMMAND_BAK } = skillPaths(dir, agent);
+    const skillRemoved    = safeRm(SKILL_DST);
+    const commandRemoved  = COMMAND_DST ? safeRm(COMMAND_DST) : false;
+    const skillRestored   = safeRestoreBak(SKILL_BAK, SKILL_DST);
+    const commandRestored = COMMAND_BAK ? safeRestoreBak(COMMAND_BAK, COMMAND_DST) : false;
+    removedAny  = removedAny  || skillRemoved  || commandRemoved;
+    restoredAny = restoredAny || skillRestored || commandRestored;
+    if (skillRemoved || commandRemoved || skillRestored || commandRestored) {
+      log(`  - ${DOT_DIR}  (${agent})`);
+      log(`      skills/scenario-gen   ${skillRemoved ? "삭제됨" : "(없음)"}${skillRestored ? "  → .bak 복원" : ""}`);
+      if (COMMAND_DST) {
+        log(`      flex-spec command     ${commandRemoved ? "삭제됨" : "(없음)"}${commandRestored ? "  → .bak 복원" : ""}`);
+      }
+    }
+  }
+
+  // 전역 ~/.flex-scenario (contract-root·receipt) — full 에서만 삭제.
+  // here/all 은 CLI 가 남으므로 contract-root(validate 진실원본)를 유지하고 receipt 만 갱신.
+  let flexRemoved = false;
+  let flexRestored = false;
+  if (scope === "full") {
+    flexRemoved  = safeRm(FLEX_HOME);
+    flexRestored = safeRestoreBak(FLEX_HOME_BAK, FLEX_HOME);
+    log(`  - ${FLEX_HOME}  ${flexRemoved ? "삭제됨" : "(없음)"}${flexRestored ? "  → .bak 복원" : ""}`);
+  } else {
+    rewriteReceiptInstalls(all.filter((t) => !targets.includes(t)));
+  }
+
+  if (!removedAny && !flexRemoved) {
+    log("  (정리할 설치 흔적이 없습니다.)");
+  }
+  if (restoredAny || flexRestored) {
+    log("  ↳ 이전 설치 .bak 을 원위치로 복원했습니다.");
+  }
+
+  return { targets, removedAny, restoredAny, flexRemoved, flexRestored };
+}
+
+// 직접 실행 가능 — 디버깅 / 수동 cleanup 용.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  cleanup({ verbose: true });
+}

package/scripts/install-paths.mjs

@@ -0,0 +1,146 @@
+// scenario-gen 패키지가 사용자 머신에 깔거나 지우는 모든 경로.
+// postinstall / cleanup / bin 의 init·uninstall 이 모두 이 한 곳에서
+// 동일 경로를 보아야 한다 — 경로 불일치는 dirty leftover 의 가장 흔한 원인.
+//
+// 2026-06-08 설치 모델 변경: 스킬/커맨드(.claude 자산)는 전역 ~/.claude 가 아니라
+// "설치한 폴더" 로컬(<targetDir>/.claude)에 깐다. 다른 폴더에서 쓰려면 그 폴더에서
+// `flex-scenario init` 을 다시 실행해 그 폴더의 .claude 로 복제한다. 전역 ~/.claude 는
+// 건드리지 않는다. contract-root·receipt(.flex-scenario 자산)는 전역 ~/.flex-scenario
+// 에 유지 — 여러 폴더가 schema 진실원본을 공유(없으면 글로벌 패키지 내부 contract-data 폴백).
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// package root = scripts/ 의 부모.
+export const PACKAGE_ROOT = dirname(__dirname);
+
+// ── 패키지 안 원본 (npm pack 시 동봉되는 위치 · 불변) ─────────────────────────
+export const SKILL_SRC = join(PACKAGE_ROOT, "skill");
+// /flex-spec 슬래시 커맨드 진실원본 — 패키지 안 cli/commands/ (git 추적, .claude 밖).
+// files=["commands"] 로 동봉되고 postinstall 이 <타겟>/.claude/commands/ 로 깐다.
+// (repo .claude/commands/ 는 SOURCE-MAP 전파로 동기화되는 gitignore 미러.)
+export const COMMAND_SRC = join(PACKAGE_ROOT, "commands", "flex-spec.md");
+export const CONTRACT_DATA_SRC = join(PACKAGE_ROOT, "contract-data");
+
+export const HOME = homedir();
+
+// ── 설치 타겟 폴더 결정 ──────────────────────────────────────────────────────
+// 스킬/커맨드는 "명령 친 폴더" 에 깐다 (그 폴더 안에 .claude/.agents/.agent 생성).
+// 우선순위:
+//   1. FLEX_SCENARIO_INSTALL_DIR — `flex-scenario init` 이 process.cwd() 를 명시 전달
+//   2. INIT_CWD                  — npm i -g 가 "사용자가 명령 친 폴더" 로 설정
+//   3. process.cwd()             — 최후 폴백
+// (npm i -g 자동 postinstall 의 process.cwd() 는 글로벌 패키지 디렉토리라 사용자 폴더가 아님.)
+export function resolveInstallDir() {
+  const cand =
+    process.env.FLEX_SCENARIO_INSTALL_DIR ||
+    process.env.INIT_CWD ||
+    process.cwd();
+  return resolve(cand);
+}
+
+// ── 에이전트 프로필 ──────────────────────────────────────────────────────────
+// 어느 에이전트(claude / codex / antigravity)용으로 자산을 까느냐에 따라
+// .claude / .agents / .agent 레이아웃이 다르다. 경로 규약이 바뀌면 이 테이블 한 곳만 고친다.
+//   skillRel   : <base>/ 아래 스킬 디렉토리(scenario-gen) 상대경로
+//   commandRel : 슬래시/워크플로 파일 상대경로 (null = 그 에이전트엔 커맨드 없음)
+//   bin        : PATH 에서 찾을 CLI 실행 파일명 (null = IDE 앱 등 PATH 점검 비대상) — doctor 가 사용
+// (2026-06-09 기준 — Codex: 공식 `.agents/skills`(복수) + prompts deprecated → $flex-spec 명시호출.
+//  Antigravity 2.0(Gemini 3.5 Flash): 워크스페이스 `.agent/skills`(단수) + `.agent/workflows/<n>.md`→/<n>.)
+export const AGENTS = {
+  claude: {
+    label: "Claude Code",
+    bin: "claude",
+    skillRel:   ["claude", "skills", "scenario-gen"],   // .claude/skills/scenario-gen
+    commandRel: ["claude", "commands", "flex-spec.md"], // .claude/commands/flex-spec.md
+  },
+  codex: {
+    label: "OpenAI Codex",
+    bin: "codex",
+    // scenario-gen 스킬 하나만. 스펙 경로는 그 안 references/spec-evolve 로 처리
+    //   (별도 flex-spec 진입점 없이 "스펙으로 만들어줘" 로 발동).
+    skillRel:   ["agents", "skills", "scenario-gen"],   // .agents/skills/scenario-gen
+    commandRel: null,
+  },
+  antigravity: {
+    label: "Google Antigravity",
+    bin: null, // IDE 앱 — PATH 바이너리 점검 비대상
+    // 현행 Antigravity 워크스페이스 스킬 경로는 .agents/skills/ (복수). `.agent`(단수)는 구버전.
+    // (글로벌은 ~/.gemini/antigravity/skills/ — 우리는 프로젝트 로컬만 깐다.)
+    // scenario-gen 스킬 하나만 — Codex 와 동일하게 별도 flex-spec 진입점 없음.
+    skillRel:   ["agents", "skills", "scenario-gen"],   // .agents/skills/scenario-gen
+    commandRel: null,
+  },
+};
+export const AGENT_KEYS = Object.keys(AGENTS);
+export const DEFAULT_AGENT = "claude";
+
+// 자유 입력(env/플래그/대화형 번호)을 정규 키로. 미인식이면 null.
+export function resolveAgent(raw) {
+  const a = String(raw ?? "").toLowerCase().trim();
+  if (!a) return null;
+  if (["1", "claude", "cc", "claude-code"].includes(a)) return "claude";
+  if (["2", "codex", "openai"].includes(a)) return "codex";
+  if (["3", "antigravity", "ag", "anti", "gemini"].includes(a)) return "antigravity";
+  if (["4", "later", "skip", "none", "나중에"].includes(a)) return "later";
+  return null;
+}
+
+// ── 스킬/커맨드 목적지 (프로젝트 로컬: <targetDir>/.<agent>/…) ─────────────────
+// 스킬은 디렉토리째 백업/교체, 커맨드는 다른 파일과 공유하는 디렉토리라 파일만 백업/교체.
+// dotDir 는 base 바로 아래의 점-디렉토리(.claude / .agents / .agent) — 로그·doctor 용.
+export function skillPaths(targetDir, agent = DEFAULT_AGENT) {
+  const prof = AGENTS[agent] || AGENTS[DEFAULT_AGENT];
+  const skillDst = join(targetDir, "." + prof.skillRel[0], ...prof.skillRel.slice(1));
+  const cmdDst = prof.commandRel
+    ? join(targetDir, "." + prof.commandRel[0], ...prof.commandRel.slice(1))
+    : null;
+  return {
+    AGENT:       agent,
+    DOT_DIR:     join(targetDir, "." + prof.skillRel[0]),
+    SKILL_DST:   skillDst,
+    SKILL_BAK:   skillDst + ".bak",
+    COMMAND_DST: cmdDst,
+    COMMAND_BAK: cmdDst ? cmdDst + ".bak" : null,
+  };
+}
+
+// ── 전역 .flex-scenario 자산 (모든 폴더 공유 · homedir 고정) ──────────────────
+export const FLEX_HOME = join(HOME, ".flex-scenario");
+export const FLEX_HOME_BAK = join(HOME, ".flex-scenario.bak");
+export const CONTRACT_DATA_DST = join(FLEX_HOME, "contract-root");
+export const INSTALL_RECEIPT = join(FLEX_HOME, "install-receipt.json");
+export const TOKEN_PATH = join(FLEX_HOME, "token.json");
+
+// ── dev 환경 판별 ────────────────────────────────────────────────────────────
+// PACKAGE_ROOT 의 조상(최대 6단계)에 workspaces 필드를 가진 package.json 이 있으면
+// repo 워크스페이스 dev 실행으로 본다. 전역 설치 경로(nvm / /usr/local / homebrew)에선
+// 6단계 안에 workspaces manifest 가 나올 수 없다. env override(npm_config_global,
+// FLEX_SCENARIO_FORCE_POSTINSTALL / FLEX_SCENARIO_FORCE_UNINSTALL)는 호출자 책임.
+// postinstall(설치 skip)과 bin 의 uninstall(전역 npm 패키지 불가침)이 공유한다.
+export function isWorkspaceDevEnv() {
+  let dir = resolve(PACKAGE_ROOT, "..");
+  for (let i = 0; i < 6; i += 1) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      try {
+        const meta = JSON.parse(readFileSync(pj, "utf-8"));
+        const ws = meta.workspaces;
+        const flatWs = Array.isArray(ws) ? ws : (ws?.packages ?? []);
+        if (Array.isArray(flatWs) && flatWs.some((p) => typeof p === "string")) {
+          // 워크스페이스 root 발견 → dev 환경.
+          return true;
+        }
+      } catch { /* not JSON, continue */ }
+    }
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}