workq-mcp 0.1.0 → 0.1.2

package/lib/analyze-repo.mjs

@@ -0,0 +1,1126 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".next",
+  ".playwright-mcp",
+  ".turbo",
+  ".workq",
+  "build",
+  "coverage",
+  "dist",
+  "dist-e2e",
+  "node_modules",
+  "output",
+  "playwright-report",
+  "test-results",
+  "out"
+]);
+
+const TEXT_EXTENSIONS = new Set([
+  ".css",
+  ".html",
+  ".js",
+  ".json",
+  ".jsx",
+  ".md",
+  ".mjs",
+  ".sql",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".yml",
+  ".yaml"
+]);
+
+const DOC_BASENAMES = new Set([
+  "README.md",
+  "FEATURES.md",
+  "USE_CASES.md",
+  "CLAUDE.md",
+  "CHANGELOG.md",
+  "TODOS.md",
+  "QA_CHECKLIST.md"
+]);
+
+const SECRET_LINE = /(api[_-]?key|secret|token|password|passwd|pat|github_pat|ghp_|sk-[a-z0-9])/i;
+const URL_RE = /https?:\/\/[^\s)"'<>]+/g;
+
+function normalizePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function safeRead(filePath, maxBytes = 180_000) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > maxBytes) return "";
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function safeJson(filePath) {
+  try {
+    return JSON.parse(safeRead(filePath, 500_000));
+  } catch {
+    return null;
+  }
+}
+
+function walkRepo(rootDir, maxFiles = 2500) {
+  const files = [];
+  const stack = [rootDir];
+  while (stack.length && files.length < maxFiles) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => b.name.localeCompare(a.name));
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relative = normalizePath(path.relative(rootDir, fullPath));
+      if (entry.isDirectory()) {
+        if (!shouldIgnoreDirectory(entry.name)) stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!TEXT_EXTENSIONS.has(ext)) continue;
+      files.push(relative);
+      if (files.length >= maxFiles) break;
+    }
+  }
+  return files.sort();
+}
+
+function shouldIgnoreDirectory(name) {
+  return IGNORE_DIRS.has(name) || /^\.workq[-_]/.test(name) || name === ".gstack";
+}
+
+function redactLine(line) {
+  if (SECRET_LINE.test(line)) return "";
+  return line.replace(URL_RE, (url) => url.replace(/[?&](token|key|secret|code|state)=[^&\s]+/gi, ""));
+}
+
+function cleanText(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => redactLine(line).trim())
+    .filter(Boolean)
+    .filter((line) => !line.startsWith("```"))
+    .join("\n");
+}
+
+function extractDocLines(text, limit = 24) {
+  const cleaned = cleanText(text);
+  const lines = cleaned
+    .split(/\r?\n/)
+    .filter((line) => /^#{1,3}\s+/.test(line) || /^[-*]\s+/.test(line) || /^[가-힣A-Za-z0-9].{20,}$/.test(line))
+    .map((line) => line.replace(/^#{1,6}\s+/, "").replace(/^[-*]\s+/, ""))
+    .filter((line) => line.length <= 220);
+  return lines.slice(0, limit);
+}
+
+function firstParagraph(text) {
+  const cleaned = cleanText(text);
+  const paragraph = cleaned
+    .split(/\n\s*\n/)
+    .map((part) => part.replace(/^#\s+.*$/m, "").trim())
+    .find((part) => part.length >= 30);
+  return paragraph ? paragraph.split(/\r?\n/).join(" ").slice(0, 420) : "";
+}
+
+function compactText(value, maxLength = 180) {
+  const normalized = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) return normalized;
+  const cutoff = normalized.slice(0, maxLength + 1);
+  const sentenceBreak = Math.max(cutoff.lastIndexOf("."), cutoff.lastIndexOf("다."), cutoff.lastIndexOf("?"), cutoff.lastIndexOf("!"));
+  if (sentenceBreak >= Math.floor(maxLength * 0.55)) return cutoff.slice(0, sentenceBreak + 1).trim();
+  const spaceBreak = cutoff.lastIndexOf(" ");
+  const end = spaceBreak >= Math.floor(maxLength * 0.65) ? spaceBreak : maxLength;
+  return `${cutoff.slice(0, end).trim()}...`;
+}
+
+function hasHangul(value) {
+  return /[가-힣]/.test(value);
+}
+
+function titleCase(value) {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function findFiles(files, patterns, limit = 8) {
+  return files.filter((file) => patterns.some((pattern) => pattern.test(file))).slice(0, limit);
+}
+
+function hasAny(files, patterns) {
+  return findFiles(files, patterns, 1).length > 0;
+}
+
+function extractUrlsFromDocs(docs) {
+  const urls = [];
+  for (const doc of docs) {
+    for (const match of doc.text.matchAll(URL_RE)) {
+      const url = match[0].replace(/[),.]+$/, "");
+      if (!urls.includes(url)) urls.push(url);
+    }
+  }
+  return urls;
+}
+
+function extractUrlsFromFiles(rootDir, files, maxFiles = 320) {
+  const urls = [];
+  for (const file of files.slice(0, maxFiles)) {
+    const ext = path.extname(file).toLowerCase();
+    if (!TEXT_EXTENSIONS.has(ext)) continue;
+    const text = cleanText(safeRead(path.join(rootDir, file), 120_000));
+    for (const match of text.matchAll(URL_RE)) {
+      const url = match[0].replace(/[),.]+$/, "");
+      if (!urls.includes(url)) urls.push(url);
+    }
+  }
+  return urls;
+}
+
+function inferProductionUrl(urls) {
+  return (
+    urls.find((url) => /:\/\/(?!staging\.)(?!dev\.)(?!preview\.)[^/]*nado\.ai\.kr\/?$/i.test(url)) ??
+    urls.find((url) => /:\/\/[^/]*nado\.ai\.kr\/?$/i.test(url)) ??
+    urls.find((url) => /:\/\/[^/]*(azurestaticapps|web\.core\.windows|vercel)\./i.test(url)) ??
+    ""
+  );
+}
+
+function scriptCommand(packageJson, names) {
+  const scripts = packageJson?.scripts ?? {};
+  for (const name of names) {
+    if (scripts[name]) return `npm run ${name}`;
+  }
+  return "";
+}
+
+function buildMachineSpec({ nodeKey, type, status, productState, source, confidence, terms, rules, examples, rationale }) {
+  return {
+    schema: "human_intent_machine_validation_v1",
+    terms: {
+      product_state_node: "A Work Q product-state map node used to classify reports and guide local agent work.",
+      observed_evidence: "Behavior grounded in repository files inspected during local bootstrap.",
+      owner_intent_gap: "A behavior or policy that cannot be safely inferred from code and must stay input_required or decision_needed.",
+      ...terms
+    },
+    variables: {
+      node_key: nodeKey,
+      type,
+      status,
+      product_state: productState,
+      source,
+      confidence
+    },
+    preconditions: ["repository identity has been verified before local bootstrap output is trusted"],
+    rules: [
+      {
+        if: "a report expectation is directly covered by this approved verified node and contradicts observed behavior",
+        then: "classify the report as bug evidence for the linked behavior"
+      },
+      {
+        if: "the report asks for behavior not present in this node or connected evidence",
+        then: "classify it as spec_gap, enhancement, input_required, or decision_needed instead of inventing product intent"
+      },
+      {
+        if: "evidence is stale, ambiguous, or only appears in old docs",
+        then: "lower confidence and require owner review before implementation"
+      },
+      ...rules
+    ],
+    outcomes: [productState, status],
+    invariants: [
+      "Code behavior is evidence, not automatically approved product intent.",
+      "Unknown product decisions remain explicit and blocked.",
+      "The node_key must remain stable so future tasks can reference the same behavior."
+    ],
+    failure_semantics: {
+      missing_evidence: "lower confidence and request repository analysis or owner clarification",
+      ambiguous_intent: "create or keep an input_required or decision_needed node",
+      conflicting_evidence: "classify as spec_conflict and require owner decision before implementation"
+    },
+    examples,
+    rationale
+  };
+}
+
+function makeNode({
+  node_key,
+  type = "feature",
+  title,
+  summary,
+  status = "approved",
+  product_state = "verified",
+  confidence = 0.82,
+  source = "workq-local-bootstrap",
+  evidence = [],
+  terms = {},
+  rules = [],
+  examples = [],
+  rationale = [],
+  display
+}) {
+  return {
+    node_key,
+    type,
+    title,
+    summary,
+    status,
+    product_state,
+    confidence,
+    source,
+    metadata: {
+      ...(display ? { display } : {}),
+      evidence,
+      machine_spec: buildMachineSpec({
+        nodeKey: node_key,
+        type,
+        status,
+        productState: product_state,
+        source,
+        confidence,
+        terms,
+        rules,
+        examples: examples.length ? examples : [{ given: title, expect: summary }],
+        rationale: rationale.length ? rationale : [summary]
+      })
+    }
+  };
+}
+
+function makeEdge(from_node_key, to_node_key, type, label, evidence) {
+  return { from_node_key, to_node_key, type, label, evidence };
+}
+
+function addNode(nodes, node) {
+  if (nodes.some((existing) => existing.node_key === node.node_key)) return;
+  nodes.push(node);
+}
+
+function addConfiguredNodeIfEvidence(nodes, files, config, language) {
+  const evidence = findFiles(files, config.patterns, config.limit ?? 8);
+  if (!evidence.length) return null;
+  const ko = language === "ko";
+  addNode(
+    nodes,
+    makeNode({
+      node_key: config.node_key,
+      type: config.type ?? "feature",
+      title: ko ? config.title_ko : config.title_en,
+      summary: ko ? config.summary_ko : config.summary_en,
+      confidence: config.confidence ?? 0.84,
+      evidence,
+      display: {
+        ko: { title: config.title_ko, summary: config.summary_ko },
+        en: { title: config.title_en, summary: config.summary_en }
+      },
+      terms: config.terms ?? {},
+      rules: config.rules ?? [],
+      examples: config.examples ?? [],
+      rationale: config.rationale ?? []
+    })
+  );
+  return evidence;
+}
+
+function addFeatureIfEvidence(nodes, files, config, language) {
+  return Boolean(addConfiguredNodeIfEvidence(nodes, files, config, language));
+}
+
+function hasNode(nodes, nodeKey) {
+  return nodes.some((node) => node.node_key === nodeKey);
+}
+
+function edgeExists(edges, fromNodeKey, toNodeKey, type) {
+  return edges.some((edge) => edge.from_node_key === fromNodeKey && edge.to_node_key === toNodeKey && edge.type === type);
+}
+
+function specificFeatureConfigs(packageName) {
+  const configs = [];
+  if (packageName === "work-q") {
+    configs.push(
+      {
+        node_key: "feature.report_intake",
+        title_ko: "리포트 접수와 첨부",
+        title_en: "Report intake and attachments",
+        summary_ko: "사용자는 URL, 실제/기대 동작, 재현 단계, 오류 로그, 스크린샷을 제출하고 Work Q는 이를 중복 없이 접수한다.",
+        summary_en: "Users submit URL, actual/expected behavior, repro steps, logs, and screenshots; Work Q stores the intake without duplicate submissions.",
+        patterns: [/^src\/app\/page\.tsx$/, /^src\/app\/api\/\[\.\.\.path\]\/route\.ts$/, /^src\/lib\/artifacts\.ts$/]
+      },
+      {
+        node_key: "feature.report_classification",
+        title_ko: "리포트 명세 기반 분류",
+        title_en: "Spec-based report classification",
+        summary_ko: "리포트의 기대 동작을 기능명세 지도와 비교해 버그, 기획부재, 기능충돌, 개선, 정보부족, 재현불가로 분류한다.",
+        summary_en: "Compares report expectations against the product map to classify bug, spec gap, conflict, enhancement, needs-info, or not-reproduced.",
+        patterns: [/^src\/lib\/store\.ts$/, /^src\/lib\/ai\.ts$/, /^src\/app\/api\/\[\.\.\.path\]\/route\.ts$/]
+      },
+      {
+        node_key: "feature.owner_decision_gate",
+        title_ko: "소유자 결정 게이트",
+        title_en: "Owner decision gate",
+        summary_ko: "기획부재, 기능충돌, 개선 요청은 자동 수정하지 않고 소유자가 승인, 거절, 보류할 때까지 큐에서 멈춘다.",
+        summary_en: "Spec gaps, conflicts, and enhancements stay blocked until the owner approves, rejects, or holds them.",
+        patterns: [/^src\/app\/page\.tsx$/, /^src\/lib\/store\.ts$/]
+      },
+      {
+        node_key: "feature.desktop_agent_mcp_queue",
+        title_ko: "데스크톱 에이전트 MCP 큐",
+        title_en: "Desktop agent MCP queue",
+        summary_ko: "로컬 Codex/Claude가 MCP로 작업을 claim하고, 재현, 수정, 테스트, 완료 결과를 Work Q에 기록한다.",
+        summary_en: "Local Codex or Claude agents claim tasks over MCP, reproduce, patch, test, and post completion back to Work Q.",
+        patterns: [/^src\/lib\/local-agent\.ts$/, /^packages\/workq-mcp\/bin\/workq\.mjs$/, /^src\/app\/api\/\[\.\.\.path\]\/route\.ts$/]
+      },
+      {
+        node_key: "feature.product_state_map",
+        title_ko: "기능명세 지도와 제품 기억",
+        title_en: "Product state map and memory",
+        summary_ko: "기능, 유즈케이스, 결정, 근거, 관계를 노드와 엣지로 저장해 사람이 읽고 AI가 검증할 기준 명세로 사용한다.",
+        summary_en: "Stores features, use cases, decisions, evidence, and relationships as nodes and edges for humans and AI validation.",
+        patterns: [/^src\/app\/page\.tsx$/, /^src\/lib\/store\.ts$/, /^packages\/workq-mcp\/lib\/analyze-repo\.mjs$/]
+      },
+      {
+        node_key: "feature.local_project_binding",
+        title_ko: "로컬 프로젝트 신원 검증",
+        title_en: "Local project identity binding",
+        summary_ko: "프로젝트 키, 로컬 git root, origin remote, 브랜치를 검증해 에이전트가 엉뚱한 레포를 고치지 않게 한다.",
+        summary_en: "Verifies project key, local git root, origin remote, and branch so agents do not patch the wrong repository.",
+        patterns: [/^src\/lib\/local-agent\.ts$/, /^src\/lib\/store\.ts$/, /^packages\/workq-mcp\/bin\/workq\.mjs$/]
+      }
+    );
+  }
+
+  if (packageName === "type") {
+    configs.push(
+      {
+        node_key: "feature.typing_engine",
+        title_ko: "한글/영문 타자 입력 엔진",
+        title_en: "Korean and English typing engine",
+        summary_ko: "한글 2벌식과 영문 QWERTY 입력을 정규화하고 자리 조합, WPM, 정확도, 오타율을 계산해 연습 화면의 기준 지표로 사용한다.",
+        summary_en: "Normalizes Korean 2-set and English QWERTY input, then computes key-position groups, WPM, accuracy, and typo rate for practice sessions.",
+        patterns: [/^src\/typing\.js$/, /^src\/text-normalize\.js$/, /^src\/main\.js$/],
+        terms: { typing_engine: "Input normalization and scoring logic for typing practice." }
+      },
+      {
+        node_key: "feature.learning_curriculum_word_pools",
+        title_ko: "240일 커리큘럼과 자리별 단어 풀",
+        title_en: "240-day curriculum and key-position word pools",
+        summary_ko: "배우기 메뉴는 240일 단계형 경로를 제공하고, 단어 연습은 검수 시드와 공개 원전에서 생성한 자리별 한글/영문 단어 풀을 사용한다.",
+        summary_en: "The learn menu exposes a 240-day path, and word practice uses reviewed seeds plus public-domain corpus generated into key-position word pools.",
+        patterns: [/^src\/data\.js$/, /^src\/generated\/word-pools\.js$/, /^src\/content\/reviewed-word-seeds\.js$/]
+      },
+      {
+        node_key: "feature.short_sentence_practice",
+        title_ko: "짧은 문장 연습",
+        title_en: "Short sentence practice",
+        summary_ko: "검수된 한글/영문 격언과 문장을 한 문장씩 제시하고, 사용자는 입력 완료 후 Enter로 다음 문장에 진입한다.",
+        summary_en: "Presents reviewed Korean and English aphorisms one prompt at a time; after typing, Enter advances to the next sentence.",
+        patterns: [/reviewed-short-aphorisms\.js$/, /^src\/generated\/quotes\.js$/]
+      },
+      {
+        node_key: "feature.long_classics_practice",
+        title_ko: "긴 고전 본문 연습",
+        title_en: "Long-form classic text practice",
+        summary_ko: "이용조건을 확인한 한글/영문 고전 전문을 정적 자산으로 보관하고, 사용자는 작품별 페이지를 넘기며 긴 글을 완주한다.",
+        summary_en: "Stores licensed public classic texts as static assets so users can type complete long-form works page by page.",
+        patterns: [/^src\/classics\.js$/, /^src\/content\/classics\//, /^src\/generated\/classic-catalog\.js$/]
+      },
+      {
+        node_key: "feature.acid_rain_typing_game",
+        title_ko: "산성비 스타일 타자 게임",
+        title_en: "Falling-word typing game",
+        summary_ko: "선택한 언어와 자리 조합 단어가 떨어지고, 점수에 따라 단계와 압박이 올라가며 특수 단어 효과가 게임 상태를 바꾼다.",
+        summary_en: "Drops words matching the selected language and key-position filter, raises pressure by score, and applies special word effects to game state.",
+        patterns: [/^src\/game\.js$/]
+      },
+      {
+        node_key: "feature.account_records_ranking",
+        title_ko: "계정, 연습 기록, 랭킹 API",
+        title_en: "Accounts, practice records, and ranking API",
+        summary_ko: "간단한 계정 로그인, 세션 저장, 랭킹은 Azure Functions API와 Table Storage를 통해 관리하고 브라우저에는 최근 기록을 캐시한다.",
+        summary_en: "Simple account login, session persistence, and rankings are handled by Azure Functions plus Table Storage, with recent results cached in the browser.",
+        patterns: [/^api\/src\/functions\/index\.js$/, /api\/package\.json$/, /^src\/main\.js$/]
+      }
+    );
+  }
+
+  if (packageName === "english-learning" || packageName === "nado-language") {
+    configs.push(
+      {
+        node_key: "feature.reading_articles",
+        title_ko: "읽기 자료와 아티클 관리",
+        title_en: "Reading materials and article management",
+        summary_ko: "Read 탭과 아티클 상세 화면은 샘플/커스텀/책 챕터 자료를 보여주고, 선택 표현, 최근 읽기, 다음 자료 흐름을 관리한다.",
+        summary_en: "The Read tab and article detail screen manage sample, custom, and chapter materials, selected expressions, recent reading, and next-material flow.",
+        patterns: [/^app\/\(tabs\)\/index\.tsx$/, /^app\/article\/\[id\]\.tsx$/, /^src\/data\/sampleArticles\.ts$/, /^src\/utils\/articleGrouping\.ts$/]
+      },
+      {
+        node_key: "feature.flashcard_fsrs_review",
+        title_ko: "플래시카드와 FSRS 복습",
+        title_en: "Flashcards and FSRS review",
+        summary_ko: "저장된 표현은 카드가 되고 Review 탭은 FSRS 큐, 답 확인, Again/Good 평가, 제외, 되돌리기, Instant QA를 제공한다.",
+        summary_en: "Saved expressions become cards; the Review tab provides the FSRS queue, reveal, Again/Good grading, exclusion, undo, and Instant QA.",
+        patterns: [/^app\/\(tabs\)\/review\.tsx$/, /^src\/services\/fsrs\.ts$/, /^src\/services\/queueManager\.ts$/, /^test\/fsrs/]
+      },
+      {
+        node_key: "feature.writing_listening_practice",
+        title_ko: "쓰기 교정과 듣기 연습",
+        title_en: "Writing correction and listening practice",
+        summary_ko: "아티클 기반 쓰기 화면은 AI 교정과 점수/CEFR/수정 제안을 제공하고, 듣기 화면은 문장 TTS, 속도, 반복, 문장 이동을 제공한다.",
+        summary_en: "Article-based writing provides AI correction, score, CEFR, and corrections; listening provides sentence TTS, speed, repeat, and navigation.",
+        patterns: [/^app\/write\/\[articleId\]\.tsx$/, /^app\/listen\/\[articleId\]\.tsx$/, /^src\/utils\/sentences\.ts$/]
+      },
+      {
+        node_key: "feature.ai_quota_runtime",
+        title_ko: "AI 프록시, 모델 런타임, 사용량 제한",
+        title_en: "AI proxy, model runtime, and quota",
+        summary_ko: "AI 요청은 Edge Function에서 인증, 액션 검증, Free/Pro/Admin 한도, 활성 모델/프롬프트 선택을 거친 뒤 AI 런타임으로 전달된다.",
+        summary_en: "AI requests pass through an Edge Function for auth, action validation, Free/Pro/Admin limits, and active model/prompt selection before runtime execution.",
+        patterns: [/^supabase\/functions\/ai-proxy\/index\.ts$/, /^supabase\/functions\/_shared\/ai-runtime\.ts$/, /^src\/services\/ai\.ts$/]
+      },
+      {
+        node_key: "feature.ocr_capture",
+        title_ko: "OCR 이미지/클립보드 캡처",
+        title_en: "OCR image and clipboard capture",
+        summary_ko: "이미지 선택 또는 클립보드 이미지에서 영어 텍스트를 추출해 읽기 자료로 만들며, 입력 제한과 권한 경계를 적용한다.",
+        summary_en: "Extracts English text from selected or clipboard images into reading material while enforcing input limits and entitlement boundaries.",
+        patterns: [/^src\/services\/ocr\.ts$/, /^supabase\/functions\/image-ocr\/index\.ts$/, /ocr.*\.spec\.ts$/]
+      },
+      {
+        node_key: "feature.browser_extension_capture",
+        title_ko: "브라우저 확장 캡처",
+        title_en: "Browser extension capture",
+        summary_ko: "브라우저 확장은 선택한 웹 텍스트를 Nado로 보내 커스텀 아티클, 하이라이트, 또는 분석된 카드 저장 흐름에 연결한다.",
+        summary_en: "The browser extension sends selected web text to Nado for custom article, highlight, or analyzed card save flows.",
+        patterns: [/^extensions\/nado-browser\//, /^supabase\/functions\/extension-capture\/index\.ts$/]
+      },
+      {
+        node_key: "feature.mcp_article_practice",
+        title_ko: "MCP 아티클 저장과 저장 카드 연습",
+        title_en: "MCP article save and saved-card practice",
+        summary_ko: "데스크톱 AI는 MCP로 아티클을 저장하고 기존 학습 카드를 조회/수정하며 저장 카드 기반 연습을 생성한다.",
+        summary_en: "Desktop AI can save articles through MCP, list/update existing study cards, and generate practice from saved cards.",
+        patterns: [/^mcp\/nado-language-server\.mjs$/, /^scripts\/nado-mcp/, /^test\/nado-mcp/]
+      },
+      {
+        node_key: "feature.connect_hub",
+        title_ko: "커넥트 허브",
+        title_en: "Connect Hub",
+        summary_ko: "Connect Hub는 브라우저 확장 다운로드, Remote MCP URL, 로컬 연결 명령, 로그인 상태, 저장 테스트를 제공한다.",
+        summary_en: "Connect Hub provides extension download, Remote MCP URL, local connection command, login state, and save tests.",
+        patterns: [/^app\/connect\.tsx$/, /^app\/mcp\/connect\.tsx$/, /^app\/extension\/connect\.tsx$/, /^src\/services\/remoteMcp\.ts$/]
+      },
+      {
+        node_key: "feature.admin_ai_lab_metrics",
+        title_ko: "관리자 지표와 AI Lab",
+        title_en: "Admin metrics and AI Lab",
+        summary_ko: "관리자는 서비스 지표를 보고 AI Lab에서 task별 모델과 프롬프트를 비교, 편집, 배포해 운영 런타임에 반영한다.",
+        summary_en: "Admins view service metrics and use AI Lab to compare, edit, and deploy task-specific model/prompt settings into runtime.",
+        patterns: [/^app\/admin\.tsx$/, /^app\/admin-ai\.tsx$/, /^src\/services\/adminMetrics\.ts$/, /^src\/services\/aiLab\.ts$/, /^supabase\/functions\/admin-metrics\/index\.ts$/, /^supabase\/functions\/ai-lab\/index\.ts$/]
+      }
+    );
+  }
+  return configs;
+}
+
+function specificUseCaseConfigs(packageName) {
+  const configs = [];
+  if (packageName === "work-q") {
+    configs.push(
+      {
+        node_key: "use_case.submit_report_with_screenshot",
+        title_ko: "사용자가 스크린샷과 함께 리포트를 제출한다",
+        title_en: "User submits a report with screenshots",
+        summary_ko: "사용자는 기대와 다른 동작을 URL, 설명, 재현 단계, 로그, 스크린샷으로 제출하고 중복 제출은 하나로 처리된다.",
+        summary_en: "A user submits unexpected behavior with URL, description, repro steps, logs, and screenshots; duplicate submissions collapse into one report.",
+        patterns: [/^src\/app\/page\.tsx$/, /^src\/app\/api\/\[\.\.\.path\]\/route\.ts$/, /^src\/lib\/artifacts\.ts$/],
+        feature_keys: ["feature.report_intake"]
+      },
+      {
+        node_key: "use_case.classify_report_against_spec",
+        title_ko: "AI가 리포트를 기능명세 지도에 매칭한다",
+        title_en: "AI matches a report against the product map",
+        summary_ko: "Work Q는 리포트의 기대 동작을 제품 지도 노드와 관계에 매칭해 버그인지 결정 필요 항목인지 분류한다.",
+        summary_en: "Work Q matches report expectations against product-map nodes and edges to classify bugs versus decision-needed work.",
+        patterns: [/^src\/lib\/store\.ts$/, /^src\/lib\/ai\.ts$/],
+        feature_keys: ["feature.report_classification", "feature.product_state_map"]
+      },
+      {
+        node_key: "use_case.owner_approves_non_bug_work",
+        title_ko: "소유자가 비버그 작업을 승인한다",
+        title_en: "Owner approves non-bug work",
+        summary_ko: "기획부재, 기능충돌, 개선 요청은 사람이 웹에서 근거를 보고 승인한 뒤에만 에이전트 작업으로 이동한다.",
+        summary_en: "Spec gaps, conflicts, and enhancements move to agent work only after the owner reviews evidence and approves them in the web app.",
+        patterns: [/^src\/app\/page\.tsx$/, /^src\/lib\/store\.ts$/],
+        feature_keys: ["feature.owner_decision_gate", "feature.report_classification"]
+      },
+      {
+        node_key: "use_case.connect_local_project",
+        title_ko: "사용자가 로컬 레포를 Work Q 프로젝트에 연결한다",
+        title_en: "User connects a local repo to a Work Q project",
+        summary_ko: "사용자는 로컬 레포에서 Work Q CLI를 실행해 git root, remote, branch를 운영 프로젝트 키와 바인딩한다.",
+        summary_en: "The user runs the Work Q CLI inside a local repo to bind git root, remote, and branch to the production project key.",
+        patterns: [/^packages\/workq-mcp\/bin\/workq\.mjs$/, /^src\/lib\/local-agent\.ts$/, /^docs\/desktop-agent-mcp\.md$/],
+        feature_keys: ["feature.local_project_binding", "feature.desktop_agent_mcp_queue"]
+      },
+      {
+        node_key: "use_case.desktop_agent_claims_and_finishes_task",
+        title_ko: "로컬 에이전트가 작업을 claim하고 완료 처리한다",
+        title_en: "Desktop agent claims and completes a task",
+        summary_ko: "로컬 에이전트는 MCP 작업 패킷을 받아 수정하고, 테스트 결과와 완료 상태를 Work Q에 돌려준다.",
+        summary_en: "A local agent receives an MCP work packet, applies a change, and posts test evidence plus completion status back to Work Q.",
+        patterns: [/^src\/lib\/local-agent\.ts$/, /^packages\/workq-mcp\/README\.md$/, /^tests\/e2e\/workflow\.spec\.ts$/],
+        feature_keys: ["feature.desktop_agent_mcp_queue"]
+      },
+      {
+        node_key: "use_case.bootstrap_repo_product_map",
+        title_ko: "MCP가 로컬 레포에서 기능명세 지도를 부트스트랩한다",
+        title_en: "MCP bootstraps a product map from a local repo",
+        summary_ko: "CLI가 문서, 라우트, API, 테스트, 배포 설정을 읽어 기능, 유즈케이스, 상태 노드와 관계를 생성한다.",
+        summary_en: "The CLI reads docs, routes, APIs, tests, and deploy config to generate feature, use-case, state nodes, and relationships.",
+        patterns: [/^packages\/workq-mcp\/lib\/analyze-repo\.mjs$/, /^packages\/workq-mcp\/bin\/workq\.mjs$/],
+        feature_keys: ["feature.product_state_map", "feature.local_project_binding"]
+      }
+    );
+  }
+
+  if (packageName === "english-learning" || packageName === "nado-language") {
+    configs.push(
+      {
+        node_key: "use_case.read_existing_article",
+        title_ko: "사용자가 기존 영어 기사를 읽는다",
+        title_en: "User reads an existing English article",
+        summary_ko: "사용자는 Read 탭에서 샘플, 커스텀, 책 챕터 자료를 열고 아티클 상세 화면에서 문장을 읽는다.",
+        summary_en: "A user opens sample, custom, or book-chapter material from the Read tab and reads sentences in the article detail screen.",
+        patterns: [/^app\/\(tabs\)\/index\.tsx$/, /^app\/article\/\[id\]\.tsx$/, /^src\/data\/sampleArticles\.ts$/],
+        feature_keys: ["feature.reading_articles"]
+      },
+      {
+        node_key: "use_case.create_article_from_text_or_image",
+        title_ko: "사용자가 텍스트나 이미지로 읽기 자료를 만든다",
+        title_en: "User creates reading material from text or image",
+        summary_ko: "사용자는 직접 입력한 텍스트나 OCR 이미지/클립보드 캡처를 읽기 자료로 저장해 학습 흐름에 넣는다.",
+        summary_en: "A user turns typed text or OCR image/clipboard capture into reading material and adds it to the learning flow.",
+        patterns: [/^app\/\(tabs\)\/index\.tsx$/, /^src\/services\/ocr\.ts$/, /^supabase\/functions\/image-ocr\/index\.ts$/],
+        feature_keys: ["feature.reading_articles", "feature.ocr_capture"]
+      },
+      {
+        node_key: "use_case.save_expression_and_review",
+        title_ko: "사용자가 표현을 저장하고 복습한다",
+        title_en: "User saves an expression and reviews it",
+        summary_ko: "사용자는 아티클에서 모르는 표현을 저장하고 Review 탭에서 FSRS 큐에 따라 답을 확인하고 평가한다.",
+        summary_en: "A user saves an unfamiliar expression from an article, then reviews it in the FSRS queue with reveal and grading actions.",
+        patterns: [/^app\/article\/\[id\]\.tsx$/, /^app\/\(tabs\)\/review\.tsx$/, /^src\/services\/fsrs\.ts$/, /^src\/services\/queueManager\.ts$/],
+        feature_keys: ["feature.reading_articles", "feature.flashcard_fsrs_review"]
+      },
+      {
+        node_key: "use_case.practice_writing_from_article",
+        title_ko: "사용자가 아티클 기반 쓰기 연습을 한다",
+        title_en: "User practices writing from an article",
+        summary_ko: "사용자는 아티클을 바탕으로 글을 쓰고 AI 교정, 점수, CEFR, 수정 제안을 받는다.",
+        summary_en: "A user writes from an article and receives AI correction, score, CEFR level, and revision suggestions.",
+        patterns: [/^app\/write\/\[articleId\]\.tsx$/, /^src\/services\/ai\.ts$/],
+        feature_keys: ["feature.writing_listening_practice"]
+      },
+      {
+        node_key: "use_case.listen_to_article_sentences",
+        title_ko: "사용자가 아티클 문장을 듣고 반복한다",
+        title_en: "User listens to and repeats article sentences",
+        summary_ko: "사용자는 듣기 화면에서 문장 TTS를 재생하고 속도, 반복, 문장 이동을 조절한다.",
+        summary_en: "A user plays article sentence TTS and controls speed, repeat, and sentence navigation in the listening screen.",
+        patterns: [/^app\/listen\/\[articleId\]\.tsx$/, /^src\/utils\/sentences\.ts$/],
+        feature_keys: ["feature.writing_listening_practice"]
+      },
+      {
+        node_key: "use_case.capture_web_text_with_extension",
+        title_ko: "사용자가 브라우저 확장으로 웹 텍스트를 캡처한다",
+        title_en: "User captures web text with the browser extension",
+        summary_ko: "사용자는 웹페이지에서 선택한 영어 텍스트를 브라우저 확장으로 Nado에 보내 커스텀 아티클이나 카드 저장 흐름으로 연결한다.",
+        summary_en: "A user sends selected English web text through the browser extension into Nado as a custom article or card-save flow.",
+        patterns: [/^extensions\/nado-browser\/manifest\.json$/, /^extensions\/nado-browser\/src\/background\.js$/, /^extensions\/nado-browser\/src\/sidepanel\.js$/],
+        feature_keys: ["feature.browser_extension_capture", "feature.reading_articles"]
+      },
+      {
+        node_key: "use_case.desktop_ai_saves_article",
+        title_ko: "데스크톱 AI가 MCP로 아티클과 연습을 저장한다",
+        title_en: "Desktop AI saves articles and practice through MCP",
+        summary_ko: "Codex나 Claude 같은 데스크톱 AI는 MCP로 아티클을 저장하고 기존 카드 조회/수정 및 저장 카드 기반 연습 생성을 수행한다.",
+        summary_en: "Desktop AI such as Codex or Claude saves articles through MCP, lists or updates cards, and generates practice from saved cards.",
+        patterns: [/^mcp\/nado-language-server\.mjs$/, /^scripts\/nado-mcp/, /^packages\/nado-mcp\/README\.md$/],
+        feature_keys: ["feature.mcp_article_practice", "feature.reading_articles", "feature.flashcard_fsrs_review"]
+      }
+    );
+  }
+
+  if (packageName === "type") {
+    configs.push(
+      {
+        node_key: "use_case.start_daily_typing_lesson",
+        title_ko: "사용자가 일일 타자 학습을 시작한다",
+        title_en: "User starts a daily typing lesson",
+        summary_ko: "사용자는 240일 커리큘럼에서 단계와 언어를 선택하고 해당 단계의 연습을 시작한다.",
+        summary_en: "A user selects a step and language from the 240-day curriculum and starts that lesson's practice.",
+        patterns: [/^src\/data\.js$/, /^src\/main\.js$/],
+        feature_keys: ["feature.learning_curriculum_word_pools", "feature.typing_engine"]
+      },
+      {
+        node_key: "use_case.practice_key_position_words",
+        title_ko: "사용자가 자리별 단어를 연습한다",
+        title_en: "User practices key-position words",
+        summary_ko: "사용자는 선택한 자리 조합에 맞는 한글/영문 단어 풀을 입력하며 정확도와 속도를 확인한다.",
+        summary_en: "A user types Korean or English word pools for selected key-position groups while tracking accuracy and speed.",
+        patterns: [/^src\/generated\/word-pools\.js$/, /^src\/content\/reviewed-word-seeds\.js$/, /^src\/typing\.js$/],
+        feature_keys: ["feature.learning_curriculum_word_pools", "feature.typing_engine"]
+      },
+      {
+        node_key: "use_case.type_short_sentence",
+        title_ko: "사용자가 짧은 문장을 입력한다",
+        title_en: "User types a short sentence",
+        summary_ko: "사용자는 검수된 격언이나 문장을 한 문장씩 입력하고 완료 후 Enter로 다음 문장에 이동한다.",
+        summary_en: "A user types reviewed aphorisms or short sentences one prompt at a time, then presses Enter to advance.",
+        patterns: [/reviewed-short-aphorisms\.js$/, /^src\/generated\/quotes\.js$/, /^src\/typing\.js$/],
+        feature_keys: ["feature.short_sentence_practice", "feature.typing_engine"]
+      },
+      {
+        node_key: "use_case.complete_long_classic_page",
+        title_ko: "사용자가 긴 고전 본문 페이지를 완주한다",
+        title_en: "User completes a long classic text page",
+        summary_ko: "사용자는 작품을 선택하고 긴 본문을 페이지 단위로 입력하며 완주 기록을 쌓는다.",
+        summary_en: "A user selects a classic work and types long-form text page by page, building completion records.",
+        patterns: [/^src\/classics\.js$/, /^src\/content\/classics\//, /^src\/generated\/classic-catalog\.js$/, /^src\/typing\.js$/],
+        feature_keys: ["feature.long_classics_practice", "feature.typing_engine"]
+      },
+      {
+        node_key: "use_case.play_falling_word_game",
+        title_ko: "사용자가 산성비 타자 게임을 한다",
+        title_en: "User plays the falling-word typing game",
+        summary_ko: "사용자는 떨어지는 단어를 입력해 점수를 얻고 단계 상승, 압박, 특수 단어 효과를 경험한다.",
+        summary_en: "A user types falling words to score points while levels, pressure, and special-word effects change game state.",
+        patterns: [/^src\/game\.js$/, /^src\/typing\.js$/],
+        feature_keys: ["feature.acid_rain_typing_game", "feature.typing_engine"]
+      },
+      {
+        node_key: "use_case.sign_in_and_track_records",
+        title_ko: "사용자가 로그인하고 연습 기록을 확인한다",
+        title_en: "User signs in and tracks practice records",
+        summary_ko: "사용자는 간단한 계정으로 로그인하고 연습 세션 저장, 최근 기록, 랭킹을 확인한다.",
+        summary_en: "A user signs in with a simple account and checks saved practice sessions, recent records, and rankings.",
+        patterns: [/^api\/src\/functions\/index\.js$/, /^src\/main\.js$/],
+        feature_keys: ["feature.account_records_ranking"]
+      }
+    );
+  }
+
+  return configs;
+}
+
+function docPriority(file) {
+  const base = path.basename(file);
+  if (/^README/i.test(base) && !file.includes("/")) return 0;
+  if (/product-plan/i.test(file) || /제품.*설계/i.test(file)) return 1;
+  if (/architecture|아키텍처/i.test(file)) return 2;
+  if (/서비스.*아키텍처|기능.*인벤토리|라인맵/i.test(file)) return 3;
+  if (base === "USE_CASES.md") return 4;
+  if (base === "FEATURES.md") return 5;
+  if (base === "CLAUDE.md") return 6;
+  if (/개요/i.test(file)) return 7;
+  if (/^README/i.test(base)) return 8;
+  if (base === "QA_CHECKLIST.md") return 9;
+  if (base === "CHANGELOG.md") return 10;
+  if (base === "TODOS.md") return 11;
+  return 20;
+}
+
+function genericFeatureConfigs() {
+  return [
+    {
+      node_key: "feature.web_entrypoints",
+      title_ko: "웹/앱 진입점과 화면 구조",
+      title_en: "Web/app entrypoints and screen structure",
+      summary_ko: "프로젝트의 HTML, 앱 라우트, 메인 스크립트, 화면 컴포넌트가 사용자가 실제로 보는 주요 화면 흐름을 구성한다.",
+      summary_en: "HTML, app routes, main scripts, and screen components define the primary user-visible product flow.",
+      patterns: [/^index\.html$/, /^app\//, /^pages\//, /^routes\//, /^src\/main\./, /^src\/App\./, /^src\/components\//],
+      confidence: 0.78
+    },
+    {
+      node_key: "feature.backend_api",
+      title_ko: "백엔드 API와 서버 함수",
+      title_en: "Backend APIs and server functions",
+      summary_ko: "API 라우트, 서버 함수, Edge Function은 클라이언트가 직접 처리하지 않는 인증, 저장, 외부 연동, 비즈니스 로직을 담당한다.",
+      summary_en: "API routes, server functions, and edge functions handle auth, persistence, integrations, and business logic outside the client.",
+      patterns: [/^api\//, /^server\//, /^src\/app\/api\//, /^supabase\/functions\//, /functions\/index\./],
+      confidence: 0.78
+    },
+    {
+      node_key: "feature.data_persistence",
+      title_ko: "데이터 저장과 동기화",
+      title_en: "Data persistence and sync",
+      summary_ko: "마이그레이션, 저장소 어댑터, 로컬 캐시, 동기화 서비스가 사용자 데이터와 운영 데이터를 보존한다.",
+      summary_en: "Migrations, storage adapters, local cache, and sync services preserve user and operational data.",
+      patterns: [/migration/i, /schema/i, /storage/i, /sync/i, /database/i, /localStorage/i],
+      confidence: 0.76
+    },
+    {
+      node_key: "feature.content_pipeline",
+      title_ko: "콘텐츠와 생성 파이프라인",
+      title_en: "Content and generation pipeline",
+      summary_ko: "정적 콘텐츠, 생성 스크립트, 공개 문서, 생성 산출물이 제품이 제공하는 읽기/학습/자료 경험의 원천이 된다.",
+      summary_en: "Static content, generation scripts, public docs, and generated artifacts feed the product's content experience.",
+      patterns: [/^content\//, /^src\/content\//, /^src\/generated\//, /^scripts\/generate/, /^public\//],
+      confidence: 0.76
+    },
+    {
+      node_key: "feature.testing_quality_gates",
+      title_ko: "테스트와 품질 게이트",
+      title_en: "Tests and quality gates",
+      summary_ko: "단위 테스트, E2E, 린트, 타입체크, smoke 스크립트가 수정 이후 기능 회귀를 확인하는 기준이 된다.",
+      summary_en: "Unit tests, E2E tests, lint, typecheck, and smoke scripts define regression checks after changes.",
+      patterns: [/^test\//, /^tests\//, /playwright\.config/, /vitest\.config/, /\.test\./, /\.spec\./],
+      confidence: 0.8
+    },
+    {
+      node_key: "feature.deployment_automation",
+      title_ko: "배포와 운영 자동화",
+      title_en: "Deployment and operations automation",
+      summary_ko: "배포 설정, 인프라 코드, 빌드 스크립트, CI 설정이 서비스 릴리즈와 운영 검증 흐름을 정의한다.",
+      summary_en: "Deploy config, infrastructure code, build scripts, and CI settings define service release and operational verification.",
+      patterns: [/staticwebapp\.config/, /vercel\.json/, /^infra\//, /^\.github\//, /^scripts\/.*deploy/i, /Dockerfile/, /bicep$/],
+      confidence: 0.78
+    }
+  ];
+}
+
+function addUseCases(nodes, edges, files, packageName, language) {
+  const ko = language === "ko";
+  for (const config of specificUseCaseConfigs(packageName)) {
+    const evidence = addConfiguredNodeIfEvidence(
+      nodes,
+      files,
+      {
+        ...config,
+        type: "use_case",
+        confidence: config.confidence ?? 0.84,
+        terms: {
+          user_scenario: "An actor-goal flow that exercises one or more product features.",
+          ...(config.terms ?? {})
+        },
+        rules: [
+          {
+            if: "a report expectation contradicts this user scenario while linked feature evidence says it should work",
+            then: "classify as a candidate bug for the linked feature"
+          },
+          ...(config.rules ?? [])
+        ]
+      },
+      language
+    );
+    if (!evidence) continue;
+    for (const featureKey of config.feature_keys ?? []) {
+      if (!hasNode(nodes, featureKey) || edgeExists(edges, config.node_key, featureKey, "exercises")) continue;
+      edges.push(
+        makeEdge(
+          config.node_key,
+          featureKey,
+          "exercises",
+          ko ? "사용자 시나리오가 이 기능을 실제 흐름에서 사용한다." : "The user scenario exercises this feature in a real product flow.",
+          evidence[0] ?? "local repository bootstrap"
+        )
+      );
+    }
+  }
+}
+
+function buildProjectContext({ projectKey, packageJson, packageName, repoName, localPath, remote, branch, docs, files, urls, language }) {
+  const description = compactText(packageJson?.description || firstParagraph(docs[0]?.text ?? "") || `${repoName} repository`, 220);
+  const docLines = docs.flatMap((doc) => extractDocLines(doc.text, 10)).slice(0, 18);
+  const evidenceSummary = compactText(docLines.slice(0, 5).join(" / ") || "package scripts and source tree", 360);
+  const productionUrl = inferProductionUrl(urls);
+  const buildCommand = scriptCommand(packageJson, ["build", "web:azure:build", "web:e2e:build"]);
+  const testCommand = scriptCommand(packageJson, ["test", "typecheck", "lint"]);
+  const smokeCommand = scriptCommand(packageJson, ["test:e2e:smoke", "smoke", "seo:health"]);
+  const installCommand = files.includes("package-lock.json") ? "npm ci" : packageJson ? "npm install" : "";
+  const ko = language === "ko";
+  const observedDocs = docs.map((doc) => doc.relative).join(", ") || "no product docs";
+
+  return {
+    project_key: projectKey,
+    project_name: packageName || repoName || titleCase(projectKey.toLowerCase()),
+    local_path_hint: localPath,
+    repository_owner: remote.owner,
+    repository_repo: remote.repo,
+    default_branch: branch || "main",
+    production_url: productionUrl,
+    project_notes: ko
+      ? `${description} 근거 문서: ${observedDocs}.`
+      : `${description} Evidence docs: ${observedDocs}.`,
+    spec_summary: ko
+      ? `${packageName || repoName}의 현재 레포 기준 기능 표면을 자동 분석했다. 주요 근거: ${evidenceSummary}.`
+      : `Automatic bootstrap analyzed the current repository feature surface for ${packageName || repoName}. Main evidence: ${evidenceSummary}.`,
+    planning_considerations: ko
+      ? "현재 코드, 테스트, 배포 스크립트, 최신 문서를 우선 근거로 삼는다. 코드에 보이지만 제품 의도가 불명확한 내용은 버그로 확정하지 않고 기획부재 또는 결정필요로 남긴다."
+      : "Prioritize current code, tests, deployment scripts, and recent docs. Behavior visible in code but unclear as product intent must remain spec_gap or decision_needed, not an automatic bug target.",
+    known_conflicts: ko
+      ? "자동 부트스트랩은 문서와 코드의 시간차를 완전히 판정할 수 없다. 충돌이 보이면 최신 코드/테스트와 owner 결정을 우선하고, 오래된 문서만 근거인 기대 동작은 stale/spec_gap으로 분류한다."
+      : "Automatic bootstrap cannot fully resolve doc/code drift. If conflict appears, prefer current code/tests and owner decisions; expectations found only in stale docs should classify as stale/spec_gap.",
+    install_command: installCommand,
+    build_command: buildCommand,
+    test_command: testCommand,
+    smoke_command: smokeCommand
+  };
+}
+
+function projectIntentSummary({ ko, packageName, repoName, hasIntentEvidence }) {
+  const productName = packageName || repoName;
+  if (hasIntentEvidence) {
+    return ko
+      ? `${productName}의 제품 의도는 문서와 소스 근거로 확인됐다. 근거 밖 기대 동작은 결정 필요로 분류한다.`
+      : `${productName} product intent is grounded in docs and source evidence; expectations outside that evidence require owner decision.`;
+  }
+  return ko
+    ? "제품 의도 근거가 아직 부족하다. 사용자가 목표, 대상 사용자, 핵심 흐름을 입력해야 다음 판단을 진행할 수 있다."
+    : "Product intent evidence is missing. The owner must provide goals, users, and core flows before downstream judgment.";
+}
+
+export function analyzeRepository({ localPath, projectKey, remote, branch = "main", commitSha = "", nodeDisplayLanguage = "" }) {
+  const root = path.resolve(localPath);
+  const files = walkRepo(root);
+  const packageJson = safeJson(path.join(root, "package.json"));
+  const packageName = packageJson?.name || "";
+  const repoName = remote?.repo || path.basename(root);
+  const docCandidates = files
+    .filter((file) => DOC_BASENAMES.has(path.basename(file)) || /^docs\/(product-plan|architecture|.*개요|.*설계|.*아키텍처).*\.md$/i.test(file))
+    .sort((a, b) => docPriority(a) - docPriority(b) || a.localeCompare(b))
+    .slice(0, 12);
+  const docs = docCandidates
+    .map((relative) => ({ relative, text: safeRead(path.join(root, relative), 220_000) }))
+    .filter((doc) => doc.text.trim());
+  const docText = docs.map((doc) => doc.text).join("\n");
+  const inferredLanguage = hasHangul(docText) || hasHangul(packageJson?.description ?? "") ? "ko" : "en";
+  const language = nodeDisplayLanguage === "ko" || nodeDisplayLanguage === "en" ? nodeDisplayLanguage : inferredLanguage;
+  const ko = language === "ko";
+  const urls = Array.from(new Set([...extractUrlsFromDocs(docs), ...extractUrlsFromFiles(root, files)]));
+  const nodes = [];
+  const edges = [];
+
+  const projectContext = buildProjectContext({
+    projectKey,
+    packageJson,
+    packageName,
+    repoName,
+    localPath: root,
+    remote,
+    branch,
+    docs,
+    files,
+    urls,
+    language
+  });
+  const hasIntentEvidence = Boolean(docs.length || packageJson?.description);
+  const repositorySummaryKo = `${remote.owner}/${remote.repo} 레포가 ${root} 경로와 ${branch || "unknown"} 브랜치로 검증되어 로컬 에이전트가 수정 대상을 식별할 수 있다.`;
+  const repositorySummaryEn = `${remote.owner}/${remote.repo} is verified on branch ${branch || "unknown"}, so local agents can identify the correct target repository.`;
+
+  addNode(
+    nodes,
+    makeNode({
+      node_key: "input_required.repository",
+      type: "state",
+      title: ko ? "코드 레포 연결 상태" : "Repository connection state",
+      summary: ko ? repositorySummaryKo : repositorySummaryEn,
+      product_state: "verified",
+      confidence: 0.94,
+      evidence: ["git rev-parse --show-toplevel", "git remote get-url origin", "git branch --show-current"],
+      display: {
+        ko: {
+          title: "코드 레포 연결 상태",
+          summary: repositorySummaryKo
+        },
+        en: {
+          title: "Repository connection state",
+          summary: repositorySummaryEn
+        }
+      },
+      terms: { repository_binding: "Verified identity tying a Work Q project to a local git repository." },
+      rules: [{ if: "observed repo/path does not match this binding", then: "do not claim or patch tasks for this project" }]
+    })
+  );
+
+  addNode(
+    nodes,
+    makeNode({
+      node_key: "input_required.project_intent",
+      type: "state",
+      title: ko ? "제품 의도 연결 상태" : "Product intent state",
+      summary: projectIntentSummary({ ko, packageName, repoName, hasIntentEvidence }),
+      product_state: hasIntentEvidence ? "verified" : "input_required",
+      status: hasIntentEvidence ? "approved" : "draft",
+      confidence: docs.length ? 0.88 : 0.64,
+      evidence: docs.map((doc) => doc.relative).concat(packageJson ? ["package.json"] : []),
+      display: {
+        ko: {
+          title: "제품 의도 연결 상태",
+          summary: projectIntentSummary({ ko: true, packageName, repoName, hasIntentEvidence })
+        },
+        en: {
+          title: "Product intent state",
+          summary: projectIntentSummary({ ko: false, packageName, repoName, hasIntentEvidence })
+        }
+      },
+      terms: { product_intent: "The product purpose used to classify reports against expected behavior." },
+      rules: [{ if: "owner intent is absent or ambiguous", then: "classify adjacent work as input_required or decision_needed" }],
+      rationale: [projectContext.spec_summary, projectContext.planning_considerations, projectContext.known_conflicts]
+    })
+  );
+
+  addNode(
+    nodes,
+    makeNode({
+      node_key: "input_required.deployment",
+      type: "state",
+      title: projectContext.production_url ? (ko ? "배포 대상 연결 상태" : "Deployment target state") : ko ? "배포 정보 입력 필요" : "Deployment information required",
+      summary: projectContext.production_url
+        ? ko
+          ? `운영 URL ${projectContext.production_url} 이 문서에서 확인되어 배포 후 smoke 기준으로 사용할 수 있다.`
+          : `Production URL ${projectContext.production_url} was found in docs and can be used for post-deploy smoke checks.`
+        : ko
+          ? "운영 URL이나 배포 확인 기준이 문서에서 확인되지 않았다. 배포 검증이 필요한 작업은 입력 필요 상태로 남긴다."
+          : "No production URL or deploy verification target was found in docs. Work requiring deployment verification remains input_required.",
+      product_state: projectContext.production_url ? "verified" : "input_required",
+      status: projectContext.production_url ? "approved" : "draft",
+      confidence: projectContext.production_url ? 0.86 : 0.62,
+      evidence: docs.map((doc) => doc.relative).concat(findFiles(files, [/staticwebapp\.config/, /vercel\.json/, /^infra\//], 4)),
+      display: {
+        ko: {
+          title: projectContext.production_url ? "배포 대상 연결 상태" : "배포 정보 입력 필요",
+          summary: projectContext.production_url
+            ? `운영 URL ${projectContext.production_url} 이 문서에서 확인되어 배포 후 smoke 기준으로 사용할 수 있다.`
+            : "운영 URL이나 배포 확인 기준이 문서에서 확인되지 않았다. 배포 검증이 필요한 작업은 입력 필요 상태로 남긴다."
+        },
+        en: {
+          title: projectContext.production_url ? "Deployment target state" : "Deployment information required",
+          summary: projectContext.production_url
+            ? `Production URL ${projectContext.production_url} was found in docs and can be used for post-deploy smoke checks.`
+            : "No production URL or deploy verification target was found in docs. Work requiring deployment verification remains input_required."
+        }
+      },
+      terms: { production_url: "URL used to verify deployed behavior." }
+    })
+  );
+
+  addNode(
+    nodes,
+    makeNode({
+      node_key: "feature.project_bootstrap_analysis",
+      title: ko ? "신규 프로젝트 분석과 지도 부트스트랩" : "New project analysis and map bootstrap",
+      summary: ko
+        ? "로컬 MCP/CLI가 README, 제품 문서, package scripts, 라우트, API, 테스트, 배포 설정을 읽어 초기 기능명세 지도를 만들고 불확실한 의도는 별도 상태 노드로 남긴다."
+        : "The local MCP/CLI reads README, product docs, package scripts, routes, APIs, tests, and deploy config to build the initial map while preserving uncertain intent as state nodes.",
+      confidence: 0.9,
+      evidence: docs.map((doc) => doc.relative).concat(["package.json"]).filter((item, index, arr) => item && arr.indexOf(item) === index),
+      display: {
+        ko: {
+          title: "신규 프로젝트 분석과 지도 부트스트랩",
+          summary:
+            "로컬 MCP/CLI가 README, 제품 문서, package scripts, 라우트, API, 테스트, 배포 설정을 읽어 초기 기능명세 지도를 만들고 불확실한 의도는 별도 상태 노드로 남긴다."
+        },
+        en: {
+          title: "New project analysis and map bootstrap",
+          summary:
+            "The local MCP/CLI reads README, product docs, package scripts, routes, APIs, tests, and deploy config to build the initial map while preserving uncertain intent as state nodes."
+        }
+      },
+      terms: { bootstrap_analysis: "Local repository analysis that creates the first Work Q product-state map." }
+    })
+  );
+
+  for (const config of specificFeatureConfigs(packageName)) addFeatureIfEvidence(nodes, files, config, language);
+  for (const config of genericFeatureConfigs()) addFeatureIfEvidence(nodes, files, config, language);
+
+  if (hasAny(files, [/^mcp\//, /^packages\/[^/]*mcp/i, /^scripts\/.*mcp/i, /^docs\/.*mcp/i])) {
+    addFeatureIfEvidence(
+      nodes,
+      files,
+      {
+        node_key: "feature.mcp_integration",
+        title_ko: "MCP/에이전트 연동",
+        title_en: "MCP and agent integration",
+        summary_ko: "MCP 서버, CLI, 인증 스크립트 또는 패키지가 외부 AI/데스크톱 도구와 제품 데이터를 연결한다.",
+        summary_en: "MCP servers, CLIs, auth scripts, or packages connect product data to external AI/desktop tools.",
+        patterns: [/^mcp\//, /^packages\/[^/]*mcp/i, /^scripts\/.*mcp/i, /^docs\/.*mcp/i],
+        confidence: 0.78
+      },
+      language
+    );
+  }
+
+  if (hasAny(files, [/extension/i, /^extensions\//])) {
+    addFeatureIfEvidence(
+      nodes,
+      files,
+      {
+        node_key: "feature.external_extension_integration",
+        title_ko: "브라우저/외부 확장 연동",
+        title_en: "Browser or external extension integration",
+        summary_ko: "확장 프로그램 또는 외부 연동 코드가 제품의 데이터를 브라우저나 다른 도구에서 캡처하거나 전달한다.",
+        summary_en: "Extension or external integration code captures or passes product data through browsers or other tools.",
+        patterns: [/extension/i, /^extensions\//],
+        confidence: 0.76
+      },
+      language
+    );
+  }
+
+  addUseCases(nodes, edges, files, packageName, language);
+
+  const featureKeys = nodes.filter((node) => node.type === "feature").map((node) => node.node_key);
+  const useCaseKeys = nodes.filter((node) => node.type === "use_case").map((node) => node.node_key);
+  for (const key of featureKeys) {
+    if (key !== "feature.project_bootstrap_analysis") {
+      edges.push(makeEdge("feature.project_bootstrap_analysis", key, "derived_from", ko ? "레포 부트스트랩 분석에서 발견된 기능이다." : "Feature found during repository bootstrap analysis.", "local repository bootstrap"));
+    }
+  }
+  for (const key of useCaseKeys) {
+    edges.push(makeEdge("feature.project_bootstrap_analysis", key, "derived_from", ko ? "레포 부트스트랩 분석에서 발견된 사용자 시나리오다." : "User scenario found during repository bootstrap analysis.", "local repository bootstrap"));
+  }
+  if (featureKeys.includes("feature.testing_quality_gates")) {
+    for (const key of featureKeys.filter((featureKey) => featureKey !== "feature.testing_quality_gates").slice(0, 8)) {
+      edges.push(makeEdge("feature.testing_quality_gates", key, "covered_by", ko ? "테스트/품질 게이트가 이 기능의 회귀 검증 후보가 된다." : "Tests and quality gates are candidate regression checks for this feature.", "package scripts and test files"));
+    }
+  }
+  if (featureKeys.includes("feature.deployment_automation") && featureKeys.includes("feature.testing_quality_gates")) {
+    edges.push(makeEdge("feature.deployment_automation", "feature.testing_quality_gates", "requires", ko ? "배포 전 품질 게이트 실행이 필요하다." : "Deployment should run quality gates first.", "package scripts"));
+  }
+
+  const summary = ko
+    ? `로컬 레포 자동 분석으로 ${nodes.length}개 노드와 ${edges.length}개 관계를 생성했다. 근거 파일 ${files.length}개 중 문서 ${docs.length}개와 주요 소스 경로를 사용했다.`
+    : `Local repository bootstrap generated ${nodes.length} nodes and ${edges.length} edges from ${files.length} files, using ${docs.length} docs plus source paths.`;
+
+  return {
+    projectContext,
+    productMap: {
+      summary,
+      nodes,
+      edges
+    },
+    analysis: {
+      language,
+      packageName,
+      file_count: files.length,
+      doc_files: docs.map((doc) => doc.relative),
+      production_url: projectContext.production_url,
+      commit_sha: commitSha
+    }
+  };
+}