workq-mcp 0.1.9 → 0.1.10

package/lib/natural-git.mjs

@@ -1076,7 +1076,7 @@ function regionsForRoute(file, route) {
 const INTERNAL_FEATURE_DEFINITIONS = [
   {
     slug: "repository-natural-analysis",
-    title: "레포 코드 자연어 분석 내부 기능",
+    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"],
@@ -1088,7 +1088,7 @@ const INTERNAL_FEATURE_DEFINITIONS = [
   },
   {
     slug: "natural-spec-repo-sync",
-    title: "자연어 git 저장소 동기화 내부 기능",
+    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"],
@@ -1100,7 +1100,7 @@ const INTERNAL_FEATURE_DEFINITIONS = [
   },
   {
     slug: "report-triage-and-classification",
-    title: "리포트 판단 · 분류 내부 기능",
+    title: "리포트 판단 · 분류 백엔드",
     purpose: "사용자가 올린 버그, 개선, 기획문의, 개발문의를 승인된 자연어 명세와 비교해 bug, 기획부재, 충돌, 결정 필요로 구분한다.",
     match: [/triage/i, /classification/i, /classify/i, /analyze-report/i, /mini.ai/i, /report/i],
     used_by_routes: ["/", "/v2"],
@@ -1112,7 +1112,7 @@ const INTERNAL_FEATURE_DEFINITIONS = [
   },
   {
     slug: "desktop-agent-mcp-queue",
-    title: "데스크톱 Agent MCP 큐 내부 기능",
+    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"],
@@ -1124,7 +1124,7 @@ const INTERNAL_FEATURE_DEFINITIONS = [
   },
   {
     slug: "project-context-binding",
-    title: "프로젝트 · 로컬 레포 바인딩 내부 기능",
+    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"],
@@ -1226,9 +1226,7 @@ function internalFeaturesForRegion(features, region) {
 }
 
 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`;
+  return `natural-git/backend/${feature.slug}/README.md`;
 }
 
 function internalFeatureDoc(feature, entries) {
@@ -1240,7 +1238,7 @@ function internalFeatureDoc(feature, entries) {
       NATURAL_SPEC_FORMAT_COMMENT,
       "",
       "## 성격",
-      "이 문서는 화면에 직접 보이는 버튼이나 카드가 아니라, 화면 기능을 가능하게 하는 내부/백그라운드 기능 명세다.",
+      "이 문서는 화면에 직접 보이는 버튼이나 카드가 아니라, 화면 기능의 결과를 만드는 백엔드 기능의 원본 명세다.",
       "",
       "## 목적",
       feature.purpose,
@@ -1266,6 +1264,11 @@ function internalFeatureDoc(feature, entries) {
       "## 검증 방법",
       ...feature.verification.map((item) => `- ${item}`),
       "",
+      "## 화면 표시 원칙",
+      "- 화면/영역 명세에는 이 문서의 전체 내용을 복사하지 않고 참조 링크만 둔다.",
+      "- Work Q UI에서는 관련 백엔드 기능 칩을 눌렀을 때 현재 문서 아래에 이 명세를 인라인으로 펼쳐 보여준다.",
+      "- 사용자가 보는 결과와 무관한 일반 라이브러리 이름은 기능명세가 아니라 구현 근거로만 취급한다.",
+      "",
       "## 구현 근거",
       ...feature.source_paths.map((sourcePath) => `- ${sourceEvidencePath({ path: sourcePath })}`)
     ].join("\n")
@@ -1324,15 +1327,15 @@ function screenReadmeDoc(file, route, regions, internals, entries) {
       "## 화면 영역",
       ...regions.map((region) => `- ${region.title}: ${region.purpose}`),
       "",
-      "## 관련 내부 기능",
+      "## 관련 백엔드 기능",
       ...(internals.length
         ? internals.map((feature) => `- ${feature.title}: ${feature.purpose} (${internalFeatureDocPath(feature, entries)})`)
-        : ["- 이 화면에 연결된 내부/백그라운드 기능이 아직 발견되지 않았다."]),
+        : ["- 이 화면에 연결된 백엔드 기능이 아직 발견되지 않았다."]),
       "",
       "## 핵심 원칙",
       "- URL 패턴을 최상위 화면 명세로 삼는다.",
       "- 화면 안의 사용자 인식 영역을 region 명세로 나눈다.",
-      "- 화면에 보이지 않지만 이 화면 기능을 가능하게 하는 백그라운드 동작은 관련 내부 기능으로 연결한다.",
+      "- 화면에 보이지 않지만 이 화면 기능의 결과를 만드는 백엔드 동작은 `natural-git/backend/` 원본 명세로 연결한다.",
       "- 코드 파일 경로는 사용자 기능명세 제목으로 쓰지 않고 evidence로 분리한다.",
       "- 페이지네이션, 게시물 번호, 상세 id처럼 값만 바뀌는 URL은 하나의 URL 패턴으로 추상화한다.",
       "",
@@ -1360,10 +1363,10 @@ function screenRulesDoc(route, regions, internals) {
       ...regions.flatMap((region) => [`### ${region.title}`, ...region.rules.map((rule) => `- ${rule}`), ""]),
       ...(internals.length
         ? [
-            "## 관련 내부 기능 판단 기준",
+            "## 관련 백엔드 기능 판단 기준",
             ...internals.flatMap((feature) => [
               `### ${feature.title}`,
-              `- 이 내부 기능은 ${feature.used_by_routes.join(", ")} 화면의 기능을 지원한다.`,
+              `- 이 백엔드 기능은 ${feature.used_by_routes.join(", ")} 화면의 기능을 지원한다.`,
               ...feature.failure_impact.map((item) => `- 실패 영향: ${item}`),
               ""
             ])
@@ -1390,7 +1393,7 @@ function screenVerificationDoc(route, regions, internals) {
       ...regions.flatMap((region) => [`### ${region.title}`, ...region.verification.map((item) => `- ${item}`), ""]),
       ...(internals.length
         ? [
-            "## 관련 내부 기능 검증",
+            "## 관련 백엔드 기능 검증",
             ...internals.flatMap((feature) => [`### ${feature.title}`, ...feature.verification.map((item) => `- ${item}`), ""])
           ]
         : [])
@@ -1421,7 +1424,7 @@ function regionDoc(route, region, internals, entries) {
       "",
       ...(relatedInternals.length
         ? [
-            "## 관련 내부 기능",
+            "## 관련 백엔드 기능",
             ...relatedInternals.map((feature) => `- ${feature.title}: ${internalFeatureDocPath(feature, entries)}`),
             ""
           ]
@@ -1539,18 +1542,19 @@ 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/backend/`: 화면 기능의 결과를 만드는 백엔드 기능 원본 명세",
     "- `natural-git/entryless-screens/`: 화면은 있지만 메뉴나 버튼 진입점이 명확하지 않은 URL 명세",
     "- `natural-git/verification/`: 기능이 실제로 동작하는지 확인하는 검증 시나리오 명세",
     "- `natural-git/_evidence/`: 코드 파일, 설정, 테스트의 구현 근거. 기본 사용자 명세가 아니라 traceability 근거다.",
     "",
     "## 운영 규칙",
     "- 자연어 문서는 URL 화면과 사용자 인식 영역 중심으로 작성한다.",
-    "- 화면에 보이지 않는 동기화, 분류, 큐, 임베딩, 백그라운드 작업은 그 기능을 사용하는 화면에 관련 내부 기능으로 연결한다.",
-    "- 여러 화면에서 쓰는 내부 기능은 `shared-internals`에 두고, 어느 화면에서도 진입점이 없는 화면은 `entryless-screens`에 기록한다.",
+    "- 모든 백엔드 기능은 `natural-git/backend/`에 원본 명세를 둔다.",
+    "- 화면에 보이지 않는 동기화, 분류, 큐, 임베딩, 백그라운드 작업은 화면 문서에 길게 복사하지 않고 관련 백엔드 기능 참조로 연결한다.",
+    "- 여러 화면에서 쓰는 백엔드 기능도 `natural-git/backend/` 원본 하나만 두고 각 화면에서 참조한다.",
+    "- 어느 화면에서도 진입점이 없는 화면은 `entryless-screens`에 기록한다.",
     "- 코드 파일 문서는 사용자 기능명세가 아니라 `_evidence` 아래 구현 근거로 보존한다.",
     "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
     "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",

package/package.json

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