workq-mcp 0.1.7 → 0.1.9

package/lib/natural-git.mjs

@@ -183,20 +183,58 @@ function stripTags(value) {
   return value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
 }
 
+function isProbablyCodeText(value) {
+  const text = value.trim();
+  if (!text) return true;
+  if (/[{}<>]|=>|\$\{/.test(text)) return true;
+  if (/[;]\s*$/.test(text)) return true;
+  if (/\b(?:on[A-Z]\w*|className|aria-label|text\.\w+|event\.|set[A-Z]\w*|function|const|let|return|await|async|JSON\.|api\(|onAction\(|document\.|querySelector)/.test(text)) return true;
+  if (/\w+\([^)]*\)/.test(text) && !/[가-힣]/.test(text)) return true;
+  if (/^[\w.$-]+\s*[=:]\s*[\w.$-]+$/.test(text)) return true;
+  return false;
+}
+
+function normalizeVisibleTextCandidate(value) {
+  const text = compact(stripTags(value).replace(/&nbsp;/g, " "), 100);
+  if (!text || /^[{}()[\];,.]+$/.test(text)) return "";
+  if (isProbablyCodeText(text)) return "";
+  return text;
+}
+
+function pushVisibleText(texts, value) {
+  const text = normalizeVisibleTextCandidate(value);
+  if (text) texts.push(text);
+}
+
 function extractVisibleTexts(file) {
   const texts = [];
   const markupContent = file.content.replace(/<script\b[\s\S]*?<\/script>/gi, "").replace(/<style\b[\s\S]*?<\/style>/gi, "");
   if (file.extension === ".html") {
-    for (const match of file.content.matchAll(/<title[^>]*>([\s\S]*?)<\/title>/gi)) texts.push(stripTags(match[1]));
-    for (const match of markupContent.matchAll(/>([^<>{}][^<>{}]{1,80})</g)) texts.push(stripTags(match[1]));
+    for (const match of file.content.matchAll(/<title[^>]*>([\s\S]*?)<\/title>/gi)) pushVisibleText(texts, match[1]);
+  }
+  if ([".html", ".tsx", ".jsx"].includes(file.extension)) {
+    for (const match of markupContent.matchAll(/>([^<>{}][^<>{}]{1,100})</g)) {
+      pushVisibleText(texts, match[1]);
+    }
   }
   for (const match of file.content.matchAll(/\b(?:textContent|innerText|placeholder|aria-label|title)\s*=\s*["'`]([^"'`]{1,100})["'`]/g)) {
-    texts.push(stripTags(match[1]));
+    pushVisibleText(texts, match[1]);
   }
-  for (const match of file.content.matchAll(/<button[^>]*>([\s\S]{1,160}?)<\/button>/gi)) {
-    texts.push(stripTags(match[1]));
+  if (file.extension === ".html") {
+    for (const match of file.content.matchAll(/<button[^>]*>([\s\S]{1,160}?)<\/button>/gi)) {
+      pushVisibleText(texts, match[1]);
+    }
   }
-  return unique(texts.map((item) => compact(item, 100)).filter((item) => item && !/^[{}()[\];,.]+$/.test(item)), 18);
+  return unique(texts, 18);
+}
+
+function visibleTextInitialStatements(file) {
+  const texts = extractVisibleTexts(file).slice(0, 8);
+  if (texts.length) return texts.map((item) => `"${item}" 문구가 보인다.`);
+  return [
+    "초기 화면에는 이 URL의 기본 콘텐츠와 조작 영역이 표시된다.",
+    "동적 문구는 원본 코드 조각이 아니라 실제 렌더링 결과를 기준으로 확인한다."
+  ];
 }
 
 function primaryVisibleTitle(file) {
@@ -906,6 +944,76 @@ function workQV2Regions() {
   ];
 }
 
+function isWorkQDashboardPage(file) {
+  return (
+    file.path === "src/app/page.tsx" &&
+    /ProjectContextPanel/.test(file.content) &&
+    /ReportPanel/.test(file.content) &&
+    /TriagePanel/.test(file.content) &&
+    /AgentQueuePanel/.test(file.content) &&
+    /McpPanel/.test(file.content)
+  );
+}
+
+function workQDashboardRegions() {
+  return [
+    {
+      slug: "topbar-and-login",
+      title: "상단 상태 · 로그인 영역",
+      purpose: "사용자는 Work Q에 접속해 언어를 바꾸고, 소유자 세션으로 로그인한 뒤 현재 작업 상태를 확인한다.",
+      initial: ["상단에 Work Q 서비스 이름과 언어 전환, 새로고침 조작이 보인다.", "로그인 전에는 비밀번호 입력과 로그인 버튼이 보인다."],
+      actions: ["사용자는 표시 언어를 전환한다.", "사용자는 새로고침으로 최신 프로젝트와 작업 상태를 다시 불러온다.", "소유자는 비밀번호를 입력해 관리 화면에 들어간다."],
+      rules: ["로그인 전에는 프로젝트, 리포트, 큐 관리 영역을 보여주지 않는다.", "새로고침은 현재 선택된 프로젝트 컨텍스트를 유지해야 한다."],
+      verification: ["로그인 전에는 로그인 폼만 주요 조작으로 표시된다.", "언어 전환 후 화면 문구가 같은 의미로 바뀐다.", "새로고침 후 선택 프로젝트가 임의로 바뀌지 않는다."]
+    },
+    {
+      slug: "project-context",
+      title: "프로젝트 컨텍스트 영역",
+      purpose: "사용자는 여러 프로젝트와 레포 중 현재 Work Q가 판단하고 작업할 대상을 선택한다.",
+      initial: ["프로젝트 선택 목록과 새 프로젝트 입력 흐름이 보인다.", "프로젝트 키, 이름, 레포, 로컬 연결 상태를 확인할 수 있다."],
+      actions: ["사용자는 기존 프로젝트를 선택한다.", "사용자는 새 프로젝트 정보를 저장한다.", "사용자는 로컬 MCP가 연결한 레포 정보와 웹 프로젝트 정보가 맞는지 확인한다."],
+      rules: ["모든 리포트, 명세, 큐, 결정 필요 항목은 선택된 프로젝트 기준으로만 표시한다.", "프로젝트 키는 서로 다른 레포나 서비스를 섞지 않기 위한 안정적인 식별자다."],
+      verification: ["프로젝트를 바꾸면 리포트, 명세 지도, 큐 목록도 같은 프로젝트 기준으로 바뀐다.", "저장된 프로젝트 키와 MCP 연결 정보가 일치하지 않으면 사용자가 확인할 수 있어야 한다."]
+    },
+    {
+      slug: "report-intake",
+      title: "리포트 접수 영역",
+      purpose: "사용자는 버그, 개선, 기획문의, 개발문의를 올리고 필요한 맥락과 이미지를 첨부한다.",
+      initial: ["리포트 제목, 유형, URL, 실제 동작, 기대 동작, 재현 방법 입력 영역이 보인다.", "스크린샷 파일 선택 또는 붙여넣기 영역이 보인다."],
+      actions: ["사용자는 문제나 문의 내용을 작성한다.", "사용자는 스크린샷을 붙여넣거나 첨부한다.", "사용자는 리포트를 제출하고 분석 결과를 기다린다."],
+      rules: ["재현 방법은 비어 있으면 사용자가 어떤 행동을 했는지 판단하기 어렵기 때문에 입력 필요 상태로 남긴다.", "첨부 이미지는 리포트 판단 근거로 연결되지만 그 자체가 승인된 명세는 아니다."],
+      verification: ["리포트 제출 후 선택 프로젝트의 리포트 목록에 추가된다.", "스크린샷이 있는 리포트는 첨부 정보가 함께 남는다.", "필수 맥락이 부족하면 작업 큐로 바로 보내지 않고 입력 필요로 구분한다."]
+    },
+    {
+      slug: "triage-and-spec-map",
+      title: "판단 근거 · 기능명세 지도 영역",
+      purpose: "사용자는 리포트가 버그, 기획부재, 충돌, 개선 중 무엇인지와 그 판단 근거를 확인한다.",
+      initial: ["선택된 리포트의 분석 결과와 관련 기능 노드가 보인다.", "입력 필요, 결정 필요, 충돌 같은 상태가 카드나 칩으로 표시된다."],
+      actions: ["사용자는 판단 근거를 읽고 필요한 결정을 입력한다.", "사용자는 승인 가능한 항목을 Agent 큐로 보낸다.", "사용자는 부족한 정보를 보충해 다시 판단하게 한다."],
+      rules: ["승인된 기능명세와 다른 실제 동작이면 버그 후보로 본다.", "기대 동작은 있지만 승인된 명세가 없으면 기획부재 또는 결정 필요로 본다.", "서로 다른 승인 명세가 같은 조건에서 다른 결과를 요구하면 충돌로 본다."],
+      verification: ["각 판단 결과에는 어떤 명세 노드와 리포트 내용이 근거였는지 표시된다.", "결정 필요 항목은 사용자의 승인 또는 거절 전까지 자동 개발 큐로 넘어가지 않는다."]
+    },
+    {
+      slug: "project-memory-and-roadmap",
+      title: "프로젝트 기억 · 로드맵 영역",
+      purpose: "사용자는 현재 프로젝트의 기능명세, 알려진 충돌, 검증 상태, 가벼운 로드맵 메모를 확인한다.",
+      initial: ["기능명세 지도와 프로젝트 메모, 로드맵 항목이 선택 프로젝트 기준으로 보인다."],
+      actions: ["사용자는 로드맵 메모를 추가하거나 순서를 조정한다.", "사용자는 기능명세 카드의 상태를 확인한다."],
+      rules: ["로드맵은 참고 메모이며 승인된 기능명세가 아니다.", "기능명세 지도는 리포트 분류와 Agent 작업의 기준으로 사용한다."],
+      verification: ["로드맵 순서 변경이 같은 프로젝트 안에서 유지된다.", "명세 업데이트 후 기능명세 지도와 판단 근거가 같은 기준을 참조한다."]
+    },
+    {
+      slug: "agent-queue-and-mcp",
+      title: "Agent 큐 · MCP 연결 영역",
+      purpose: "사용자는 데스크톱 Codex 또는 Claude가 가져갈 작업 큐와 MCP 연결 준비 상태를 확인한다.",
+      initial: ["선택 프로젝트의 Agent 작업 목록과 상태가 보인다.", "MCP URL과 token 준비 상태가 보인다."],
+      actions: ["로컬 Agent는 MCP로 다음 작업을 가져간다.", "작업이 끝난 Agent는 완료 결과와 검증 내용을 Work Q에 남긴다.", "사용자는 완료, 진행, 결정 필요 상태를 확인한다."],
+      rules: ["큐 작업은 선택 프로젝트와 연결된 레포를 기준으로 처리해야 한다.", "Agent가 작업을 완료하면 완료 표시와 함께 명세 변경 또는 검증 근거를 남겨야 한다."],
+      verification: ["다른 프로젝트의 큐가 섞여 보이지 않는다.", "MCP token이 없으면 로컬 Agent 연결이 준비되지 않은 상태로 보인다.", "완료된 작업은 큐 상태가 완료로 바뀐다."]
+    }
+  ];
+}
+
 function genericHtmlRegions(file) {
   const title = primaryVisibleTitle(file) || "화면";
   const hasOneToNineLoop = /\bfor\s*\(\s*let\s+\w+\s*=\s*1\s*;\s*\w+\s*<=\s*9\s*;/.test(file.content);
@@ -936,7 +1044,7 @@ function genericHtmlRegions(file) {
       slug: "main-content",
       title: `${title} 주요 화면 영역`,
       purpose: "사용자는 이 화면에서 주요 콘텐츠와 조작 가능한 요소를 확인한다.",
-      initial: extractVisibleTexts(file).slice(0, 8).map((item) => `"${item}" 문구가 보인다.`),
+      initial: visibleTextInitialStatements(file),
       actions: ["사용자는 화면에 표시된 버튼, 링크, 입력 요소를 조작한다."],
       rules: ["화면에 보이는 문구와 조작 요소는 같은 URL 화면 명세 안에서 관리한다."],
       verification: ["초기 화면의 주요 문구와 조작 요소가 표시된다."]
@@ -945,13 +1053,12 @@ function genericHtmlRegions(file) {
 }
 
 function genericRouteRegions(file) {
-  const texts = extractVisibleTexts(file);
   return [
     {
       slug: "main-screen",
       title: "주요 화면 영역",
       purpose: "사용자는 이 URL에서 제공되는 핵심 화면을 본다.",
-      initial: texts.slice(0, 8).map((item) => `"${item}" 문구가 보인다.`),
+      initial: visibleTextInitialStatements(file),
       actions: ["사용자는 화면에 표시된 버튼, 입력칸, 선택값을 조작한다."],
       rules: ["같은 URL 패턴에 속한 상태 변화는 같은 화면 명세 안에서 관리한다."],
       verification: ["URL 접속 시 주요 화면 문구와 조작 요소가 표시된다."]
@@ -960,15 +1067,245 @@ function genericRouteRegions(file) {
 }
 
 function regionsForRoute(file, route) {
+  if (isWorkQDashboardPage(file)) return workQDashboardRegions();
   if (route.url_pattern === "/v2" && file.path === "src/app/v2/page.tsx") return workQV2Regions();
   if (file.path === "index.html") return genericHtmlRegions(file);
   return genericRouteRegions(file);
 }
 
-function screenReadmeDoc(file, route, regions) {
+const INTERNAL_FEATURE_DEFINITIONS = [
+  {
+    slug: "repository-natural-analysis",
+    title: "레포 코드 자연어 분석 내부 기능",
+    purpose: "사용자가 연결한 코드 레포를 읽고 URL 화면, 화면 영역, 검증 근거 중심의 natural-spec repo 초안을 만든다.",
+    match: [/repo-natural-spec/i, /generateNaturalSpecFromRepository/i, /generateNaturalGitDocs/i, /workq_import_natural_git_specs/i],
+    used_by_routes: ["/v2"],
+    related_regions: ["project-repo-registration", "natural-spec-repo"],
+    triggers: ["사용자가 레포 코드 자연어 분석을 요청한다.", "로컬 MCP CLI가 `workq natural-git` 업로드를 실행한다."],
+    outcomes: ["화면/영역 중심 Markdown 명세가 생성된다.", "코드 파일별 상세 구현은 `_evidence`로 분리된다."],
+    failure_impact: ["새 프로젝트의 초기 기능명세가 비어 있거나 코드 중심 문서로 잘못 보일 수 있다."],
+    verification: ["생성 결과에 `natural-git/screens/` 문서와 `_evidence` 문서가 함께 존재하는지 확인한다."]
+  },
+  {
+    slug: "natural-spec-repo-sync",
+    title: "자연어 git 저장소 동기화 내부 기능",
+    purpose: "웹에서 편집한 자연어 명세 draft, commit, merge 상태를 natural-spec repo 기준 상태와 맞춘다.",
+    match: [/spec-git/i, /natural-spec-repo/i, /stageNaturalSpecDocs/i, /commitNaturalSpec/i, /readNaturalSpecDocs/i],
+    used_by_routes: ["/v2"],
+    related_regions: ["natural-spec-repo", "natural-spec-editor", "commit-merge-agent-queue"],
+    triggers: ["사용자가 자연어 명세를 저장한다.", "사용자가 자연어 커밋, 머지, 롤백을 실행한다."],
+    outcomes: ["draft와 HEAD commit 상태가 구분된다.", "승인된 자연어 커밋만 Agent 큐 기준이 된다."],
+    failure_impact: ["화면에 보이는 명세와 Agent가 기준으로 읽는 명세가 달라질 수 있다."],
+    verification: ["draft 저장, commit, merge 이후 같은 프로젝트의 문서 상태와 commit id가 유지되는지 확인한다."]
+  },
+  {
+    slug: "report-triage-and-classification",
+    title: "리포트 판단 · 분류 내부 기능",
+    purpose: "사용자가 올린 버그, 개선, 기획문의, 개발문의를 승인된 자연어 명세와 비교해 bug, 기획부재, 충돌, 결정 필요로 구분한다.",
+    match: [/triage/i, /classification/i, /classify/i, /analyze-report/i, /mini.ai/i, /report/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["report-intake", "triage-and-spec-map", "decision-needed-mcp"],
+    triggers: ["사용자가 리포트를 제출한다.", "사용자가 기존 리포트를 다시 분석한다."],
+    outcomes: ["판단 결과와 근거 명세가 사용자에게 표시된다.", "승인이 필요한 항목은 자동 개발 큐로 넘어가지 않는다."],
+    failure_impact: ["버그가 아닌 기획부재를 버그로 고치거나, 실제 버그를 문의로 놓칠 수 있다."],
+    verification: ["명세가 있는 동작 차이는 bug 후보로, 명세가 없는 기대 동작은 기획부재/결정 필요로 표시되는지 확인한다."]
+  },
+  {
+    slug: "desktop-agent-mcp-queue",
+    title: "데스크톱 Agent MCP 큐 내부 기능",
+    purpose: "승인된 자연어 커밋이나 결정 사항을 로컬 Codex/Claude가 가져갈 작업 패킷으로 만들고 완료 결과를 다시 받는다.",
+    match: [/workq_list_tasks/i, /workq_get_work_packet/i, /workq_finish_task/i, /agent_task/i, /queued_for_agent/i, /MCP/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["agent-queue-and-mcp", "decision-needed-mcp", "existing-workq-queue", "commit-merge-agent-queue"],
+    triggers: ["사용자가 승인된 작업을 Agent 큐로 보낸다.", "로컬 Agent가 MCP로 다음 작업을 조회한다.", "로컬 Agent가 완료 결과를 제출한다."],
+    outcomes: ["작업 패킷에 프로젝트, 레포, 명세 근거, 완료 절차가 포함된다.", "완료 시 검증 결과와 명세 변경 근거가 Work Q에 남는다."],
+    failure_impact: ["로컬 Agent가 잘못된 프로젝트를 고치거나, 완료 작업이 큐에 남을 수 있다."],
+    verification: ["MCP 작업 조회, work packet 수신, finish task 호출 후 큐 상태가 완료로 바뀌는지 확인한다."]
+  },
+  {
+    slug: "project-context-binding",
+    title: "프로젝트 · 로컬 레포 바인딩 내부 기능",
+    purpose: "웹의 프로젝트 키와 로컬 데스크톱의 실제 git 레포 정보를 대조해 엉뚱한 레포를 고치지 않도록 한다.",
+    match: [/connect_local_project/i, /local.*project/i, /repository_owner/i, /local_path/i, /git remote/i, /project_key/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["project-context", "project-repo-registration", "project-status-summary"],
+    triggers: ["사용자가 프로젝트를 등록한다.", "로컬 MCP가 현재 git root, remote, branch를 Work Q에 연결한다."],
+    outcomes: ["프로젝트 키, repo owner/name, local path, branch가 같은 대상인지 확인된다."],
+    failure_impact: ["여러 프로젝트를 사용할 때 다른 레포의 리포트나 작업을 처리할 수 있다."],
+    verification: ["웹 프로젝트 정보와 MCP가 제출한 git root, remote, branch가 일치하지 않으면 연결 미검증 상태가 되는지 확인한다."]
+  }
+];
+
+function isUserFacingNavigationFile(file) {
+  if (isTestFile(file) || isApiOrServerFile(file) || isCliEntryFile(file)) return false;
+  return [".tsx", ".jsx", ".html", ".ts", ".js"].includes(file.extension);
+}
+
+function routeLiteralForSearch(route) {
+  return route.url_pattern.replace(/\[(.+?)\]/g, "");
+}
+
+function hasVisibleNavigationToRoute(route, routeFile, sourceFiles) {
+  if (route.url_pattern === "/" || route.url_pattern === "<product-overview>") return true;
+  const literal = routeLiteralForSearch(route);
+  if (!literal || literal === "/") return true;
+  const escaped = literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const navigationPatterns = [
+    new RegExp(`href\\s*=\\s*[{]?["'\`]${escaped}["'\`]`, "i"),
+    new RegExp(`router\\.push\\(\\s*["'\`]${escaped}`, "i"),
+    new RegExp(`navigate\\(\\s*["'\`]${escaped}`, "i"),
+    new RegExp(`location\\.href\\s*=\\s*["'\`]${escaped}`, "i")
+  ];
+  return sourceFiles.some((file) => {
+    if (file.path === routeFile.path || !isUserFacingNavigationFile(file)) return false;
+    return navigationPatterns.some((pattern) => pattern.test(file.content));
+  });
+}
+
+function routeEntriesForSourceFiles(sourceFiles) {
+  return sourceFiles.flatMap((file) => {
+    const route = routeInfoForFile(file);
+    if (!route) return [];
+    const regions = regionsForRoute(file, route);
+    return [
+      {
+        file,
+        route,
+        regions,
+        entryless: !hasVisibleNavigationToRoute(route, file, sourceFiles)
+      }
+    ];
+  });
+}
+
+function matchingInternalSourcePaths(sourceFiles, definition) {
+  return unique(
+    sourceFiles
+      .filter((file) => !isTestFile(file))
+      .filter((file) => {
+        const haystack = `${file.path}\n${file.content}`;
+        return definition.match.some((pattern) => pattern.test(haystack));
+      })
+      .map((file) => file.path),
+    10
+  );
+}
+
+function detectInternalFeatures(sourceFiles, entries) {
+  const availableRoutes = new Set(entries.map((entry) => entry.route.url_pattern));
+  const fallbackRoute = entries[0]?.route.url_pattern;
+  return INTERNAL_FEATURE_DEFINITIONS.flatMap((definition) => {
+    const sourcePaths = matchingInternalSourcePaths(sourceFiles, definition);
+    if (!sourcePaths.length) return [];
+    const usedByRoutes = definition.used_by_routes.filter((route) => availableRoutes.has(route));
+    const resolvedRoutes = usedByRoutes.length ? usedByRoutes : fallbackRoute ? [fallbackRoute] : [];
+    return [
+      {
+        slug: definition.slug,
+        title: definition.title,
+        purpose: definition.purpose,
+        used_by_routes: resolvedRoutes,
+        related_regions: definition.related_regions,
+        triggers: definition.triggers,
+        outcomes: definition.outcomes,
+        failure_impact: definition.failure_impact,
+        verification: definition.verification,
+        source_paths: sourcePaths,
+        shared: resolvedRoutes.length > 1
+      }
+    ];
+  });
+}
+
+function internalFeaturesForRoute(features, route) {
+  return features.filter((feature) => feature.used_by_routes.includes(route.url_pattern));
+}
+
+function internalFeaturesForRegion(features, region) {
+  return features.filter((feature) => feature.related_regions.includes(region.slug));
+}
+
+function internalFeatureDocPath(feature, entries) {
+  if (feature.shared || feature.used_by_routes.length !== 1) return `natural-git/shared-internals/${feature.slug}.md`;
+  const entry = entries.find((item) => item.route.url_pattern === feature.used_by_routes[0]);
+  return `${entry?.route.directory ?? "natural-git/shared-internals"}/internals/${feature.slug}.md`;
+}
+
+function internalFeatureDoc(feature, entries) {
+  return {
+    path: internalFeatureDocPath(feature, entries),
+    title: feature.title,
+    content: [
+      `# ${feature.title}`,
+      NATURAL_SPEC_FORMAT_COMMENT,
+      "",
+      "## 성격",
+      "이 문서는 화면에 직접 보이는 버튼이나 카드가 아니라, 화면 기능을 가능하게 하는 내부/백그라운드 기능 명세다.",
+      "",
+      "## 목적",
+      feature.purpose,
+      "",
+      "## 사용 화면",
+      ...feature.used_by_routes.map((route) => {
+        const entry = entries.find((item) => item.route.url_pattern === route);
+        return `- ${route}: ${entry ? `${entry.route.directory}/README.md` : "연결된 화면 명세"}`;
+      }),
+      "",
+      "## 연결된 화면 영역",
+      ...feature.related_regions.map((region) => `- ${region}`),
+      "",
+      "## 트리거",
+      ...feature.triggers.map((item) => `- ${item}`),
+      "",
+      "## 결과",
+      ...feature.outcomes.map((item) => `- ${item}`),
+      "",
+      "## 실패 시 사용자 영향",
+      ...feature.failure_impact.map((item) => `- ${item}`),
+      "",
+      "## 검증 방법",
+      ...feature.verification.map((item) => `- ${item}`),
+      "",
+      "## 구현 근거",
+      ...feature.source_paths.map((sourcePath) => `- ${sourceEvidencePath({ path: sourcePath })}`)
+    ].join("\n")
+  };
+}
+
+function entrylessScreenDoc(entry) {
+  const slug = slugSegment(entry.route.url_pattern.replace(/^\//, "") || "root");
+  return {
+    path: `natural-git/entryless-screens/${slug}.md`,
+    title: `진입점 없는 화면: ${entry.route.url_pattern}`,
+    content: [
+      `# 진입점 없는 화면: ${entry.route.url_pattern}`,
+      NATURAL_SPEC_FORMAT_COMMENT,
+      "",
+      "## 의미",
+      "이 URL은 화면 파일과 기능명세가 있지만, 다른 사용자 화면에서 명확한 버튼이나 링크 진입점을 발견하지 못했다.",
+      "",
+      "## 기준 화면 명세",
+      `- ${entry.route.directory}/README.md`,
+      "",
+      "## 운영 원칙",
+      "- 직접 URL, 관리자 전용, 실험용, MCP/Agent 전용 화면일 수 있다.",
+      "- 사용자가 일반 화면에서 접근해야 하는 기능이면 별도 메뉴, 버튼, 링크를 추가해야 한다.",
+      "- 진입점이 없는 상태 자체가 제품 의도인지 오너가 확인해야 한다.",
+      "",
+      "## 검증 방법",
+      "- 이 화면으로 이동하는 실제 사용자 진입점이 있는지 확인한다.",
+      "- 진입점이 의도적으로 없다면 이유를 이 문서 또는 화면 README에 기록한다."
+    ].join("\n")
+  };
+}
+
+function screenReadmeDoc(file, route, regions, internals, entries) {
+  const isWorkQDashboard = isWorkQDashboardPage(file);
   const isWorkQV2 = route.url_pattern === "/v2" && file.path === "src/app/v2/page.tsx";
-  const title = isWorkQV2 ? "Work Q v2 대시보드 화면 명세" : route.title;
-  const purpose = isWorkQV2
+  const title = isWorkQDashboard ? "Work Q 대시보드 화면 명세" : isWorkQV2 ? "Work Q v2 대시보드 화면 명세" : route.title;
+  const purpose = isWorkQDashboard
+    ? "사용자는 Work Q에서 프로젝트를 선택하고, 리포트를 등록하고, 기능명세 판단 근거와 Agent 큐 상태를 확인한다."
+    : isWorkQV2
     ? "사용자는 Work Q v2에서 프로젝트와 레포를 연결하고, natural-spec repo를 편집하며, 리포트와 자연어 커밋을 Agent 작업 큐로 연결한다."
     : `${route.url_pattern} URL에서 사용자가 보는 화면의 목적, 영역, 조작, 결과를 정의한다.`;
   return {
@@ -987,9 +1324,15 @@ function screenReadmeDoc(file, route, regions) {
       "## 화면 영역",
       ...regions.map((region) => `- ${region.title}: ${region.purpose}`),
       "",
+      "## 관련 내부 기능",
+      ...(internals.length
+        ? internals.map((feature) => `- ${feature.title}: ${feature.purpose} (${internalFeatureDocPath(feature, entries)})`)
+        : ["- 이 화면에 연결된 내부/백그라운드 기능이 아직 발견되지 않았다."]),
+      "",
       "## 핵심 원칙",
       "- URL 패턴을 최상위 화면 명세로 삼는다.",
       "- 화면 안의 사용자 인식 영역을 region 명세로 나눈다.",
+      "- 화면에 보이지 않지만 이 화면 기능을 가능하게 하는 백그라운드 동작은 관련 내부 기능으로 연결한다.",
       "- 코드 파일 경로는 사용자 기능명세 제목으로 쓰지 않고 evidence로 분리한다.",
       "- 페이지네이션, 게시물 번호, 상세 id처럼 값만 바뀌는 URL은 하나의 URL 패턴으로 추상화한다.",
       "",
@@ -999,7 +1342,7 @@ function screenReadmeDoc(file, route, regions) {
   };
 }
 
-function screenRulesDoc(route, regions) {
+function screenRulesDoc(route, regions, internals) {
   return {
     path: `${route.directory}/rules.md`,
     title: `${route.url_pattern} 화면 규칙`,
@@ -1014,12 +1357,23 @@ function screenRulesDoc(route, regions) {
       "- 코드에서 관찰된 구현만으로 제품 의도를 단정하지 않는다.",
       "",
       "## 영역별 핵심 규칙",
-      ...regions.flatMap((region) => [`### ${region.title}`, ...region.rules.map((rule) => `- ${rule}`), ""])
+      ...regions.flatMap((region) => [`### ${region.title}`, ...region.rules.map((rule) => `- ${rule}`), ""]),
+      ...(internals.length
+        ? [
+            "## 관련 내부 기능 판단 기준",
+            ...internals.flatMap((feature) => [
+              `### ${feature.title}`,
+              `- 이 내부 기능은 ${feature.used_by_routes.join(", ")} 화면의 기능을 지원한다.`,
+              ...feature.failure_impact.map((item) => `- 실패 영향: ${item}`),
+              ""
+            ])
+          ]
+        : [])
     ].join("\n")
   };
 }
 
-function screenVerificationDoc(route, regions) {
+function screenVerificationDoc(route, regions, internals) {
   return {
     path: `${route.directory}/verification.md`,
     title: `${route.url_pattern} 화면 검증`,
@@ -1033,12 +1387,19 @@ function screenVerificationDoc(route, regions) {
       "- Agent 완료 전에는 관련 영역의 verification 항목을 확인하고 Work Q 완료 기록에 남긴다.",
       "",
       "## 영역별 검증",
-      ...regions.flatMap((region) => [`### ${region.title}`, ...region.verification.map((item) => `- ${item}`), ""])
+      ...regions.flatMap((region) => [`### ${region.title}`, ...region.verification.map((item) => `- ${item}`), ""]),
+      ...(internals.length
+        ? [
+            "## 관련 내부 기능 검증",
+            ...internals.flatMap((feature) => [`### ${feature.title}`, ...feature.verification.map((item) => `- ${item}`), ""])
+          ]
+        : [])
     ].join("\n")
   };
 }
 
-function regionDoc(route, region) {
+function regionDoc(route, region, internals, entries) {
+  const relatedInternals = internalFeaturesForRegion(internals, region);
   return {
     path: `${route.directory}/regions/${region.slug}.md`,
     title: region.title,
@@ -1058,6 +1419,13 @@ function regionDoc(route, region) {
       "## 핵심 규칙",
       ...region.rules.map((item) => `- ${item}`),
       "",
+      ...(relatedInternals.length
+        ? [
+            "## 관련 내부 기능",
+            ...relatedInternals.map((feature) => `- ${feature.title}: ${internalFeatureDocPath(feature, entries)}`),
+            ""
+          ]
+        : []),
       "## 검증 방법",
       ...region.verification.map((item) => `- ${item}`)
     ].join("\n")
@@ -1119,25 +1487,32 @@ function fallbackRegions(sourceFiles) {
 }
 
 function routeScreenDocs(sourceFiles) {
-  const docs = sourceFiles.flatMap((file) => {
-    const route = routeInfoForFile(file);
-    if (!route) return [];
-    const regions = regionsForRoute(file, route);
+  const entries = routeEntriesForSourceFiles(sourceFiles);
+  const detectedInternals = detectInternalFeatures(sourceFiles, entries);
+  const docs = entries.flatMap((entry) => {
+    const internals = internalFeaturesForRoute(detectedInternals, entry.route);
     return [
-      screenReadmeDoc(file, route, regions),
-      screenRulesDoc(route, regions),
-      screenVerificationDoc(route, regions),
-      ...regions.map((region) => regionDoc(route, region))
+      screenReadmeDoc(entry.file, entry.route, entry.regions, internals, entries),
+      screenRulesDoc(entry.route, entry.regions, internals),
+      screenVerificationDoc(entry.route, entry.regions, internals),
+      ...entry.regions.map((region) => regionDoc(entry.route, region, internals, entries))
     ];
   });
-  if (docs.length || !sourceFiles.length) return docs;
+  if (docs.length || !sourceFiles.length) {
+    return [...docs, ...detectedInternals.map((feature) => internalFeatureDoc(feature, entries)), ...entries.filter((entry) => entry.entryless).map((entry) => entrylessScreenDoc(entry))];
+  }
   const route = fallbackRouteInfo();
   const regions = fallbackRegions(sourceFiles);
+  const fallbackEntry = { file: sourceFiles[0], route, regions, entryless: false };
+  const entriesWithFallback = [fallbackEntry];
+  const internals = detectInternalFeatures(sourceFiles, entriesWithFallback);
+  const routeInternals = internalFeaturesForRoute(internals, route);
   return [
-    screenReadmeDoc(sourceFiles[0], route, regions),
-    screenRulesDoc(route, regions),
-    screenVerificationDoc(route, regions),
-    ...regions.map((region) => regionDoc(route, region))
+    screenReadmeDoc(sourceFiles[0], route, regions, routeInternals, entriesWithFallback),
+    screenRulesDoc(route, regions, routeInternals),
+    screenVerificationDoc(route, regions, routeInternals),
+    ...regions.map((region) => regionDoc(route, region, routeInternals, entriesWithFallback)),
+    ...internals.map((feature) => internalFeatureDoc(feature, entriesWithFallback))
   ];
 }
 
@@ -1164,13 +1539,18 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     "## 디렉토리 구조",
     "- `natural-git/screens/`: URL 패턴별 최상위 화면 명세",
     "- `natural-git/screens/<url>/regions/`: 화면 안의 사용자 인식 영역 명세",
+    "- `natural-git/screens/<url>/internals/`: 특정 화면 기능을 가능하게 하는 내부/백그라운드 기능 명세",
     "- `natural-git/screens/<url>/components/`: 여러 화면에서 재사용되는 컴포넌트 명세",
     "- `natural-git/screens/<url>/dialogs/`: 모달, 팝업, 드로어 상태 명세",
+    "- `natural-git/shared-internals/`: 여러 화면에서 같이 쓰는 내부/백그라운드 기능 명세",
+    "- `natural-git/entryless-screens/`: 화면은 있지만 메뉴나 버튼 진입점이 명확하지 않은 URL 명세",
     "- `natural-git/verification/`: 기능이 실제로 동작하는지 확인하는 검증 시나리오 명세",
     "- `natural-git/_evidence/`: 코드 파일, 설정, 테스트의 구현 근거. 기본 사용자 명세가 아니라 traceability 근거다.",
     "",
     "## 운영 규칙",
     "- 자연어 문서는 URL 화면과 사용자 인식 영역 중심으로 작성한다.",
+    "- 화면에 보이지 않는 동기화, 분류, 큐, 임베딩, 백그라운드 작업은 그 기능을 사용하는 화면에 관련 내부 기능으로 연결한다.",
+    "- 여러 화면에서 쓰는 내부 기능은 `shared-internals`에 두고, 어느 화면에서도 진입점이 없는 화면은 `entryless-screens`에 기록한다.",
     "- 코드 파일 문서는 사용자 기능명세가 아니라 `_evidence` 아래 구현 근거로 보존한다.",
     "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
     "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workq-mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Work Q MCP stdio bridge and local repository connection CLI.",
   "type": "module",
   "bin": {