workq-mcp 0.1.10 → 0.1.12

package/lib/natural-git.mjs

@@ -955,6 +955,139 @@ function isWorkQDashboardPage(file) {
   );
 }
 
+function isWorkQV3Page(file, route) {
+  return (
+    /WorkQV3App/.test(file.content) ||
+    file.path === "src/app/v3/WorkQV3App.tsx" ||
+    route?.url_pattern === "/v3"
+  );
+}
+
+function workQV3Regions() {
+  return [
+    {
+      slug: "login-screen",
+      title: "로그인 화면",
+      purpose: "사용자는 소유자 비밀번호로 Work Q v3 관리 화면에 접근한다.",
+      initial: [
+        "로그인하지 않은 사용자는 Owner password 입력칸과 Sign in 버튼을 본다.",
+        "프로젝트, 명세, 요청, Agent 큐 관리 영역은 로그인 전에는 보이지 않는다."
+      ],
+      actions: ["사용자는 Owner password를 입력한다.", "Enter 키나 Sign in 버튼으로 인증을 시도한다."],
+      rules: ["인증 전에는 프로젝트 데이터와 큐 상태를 노출하지 않는다.", "인증 실패 시 사용자가 다시 시도할 수 있는 오류 메시지를 보여준다."],
+      verification: ["비밀번호 없이 접근하면 로그인 화면만 보인다.", "올바른 비밀번호로 로그인하면 v3 메인 화면과 Active project 선택 영역이 보인다."]
+    },
+    {
+      slug: "topbar-and-principles",
+      title: "상단 상태 · 원칙 영역",
+      purpose: "사용자는 v3가 승인된 자연어 의도 명세를 기준으로 동작한다는 제품 원칙과 현재 상태를 확인한다.",
+      initial: [
+        "`Work Q v3 · Intent Spec MVP` 표시가 보인다.",
+        "`사람이 승인한 자연어 의도 명세가 기준입니다.` 제목이 보인다.",
+        "신규 레포 초안 생성, 오너 승인 후 기준 명세, 요청 시 필요한 코드만 검증이라는 세 원칙이 보인다.",
+        "Refresh 버튼과 Agent 큐 준비 또는 의도 명세 검토 상태 칩이 보인다."
+      ],
+      actions: ["사용자는 Refresh 버튼으로 현재 프로젝트의 명세, 요청, 큐 상태를 다시 불러온다."],
+      rules: ["새로고침 후에도 사용자가 선택한 Active project를 유지한다.", "코드 기반 생성은 신규 레포 초안 부트스트랩 용도이며 승인된 기준 명세와 구분한다."],
+      verification: ["`/`와 `/v3` 모두 같은 v3 상단 원칙을 보여준다.", "Refresh 후 Active project가 임의로 바뀌지 않는다."]
+    },
+    {
+      slug: "project-repo-bootstrap",
+      title: "프로젝트 · 레포 부트스트랩 영역",
+      purpose: "사용자는 신규 레포를 Work Q에 연결하고, natural-git이 없을 때 코드 기반 의도 명세 초안을 생성한다.",
+      initial: [
+        "Active project 선택값이 보인다.",
+        "프로젝트 키, 프로젝트 이름, GitHub owner, repo, default branch, branch prefix, local repo path, test command, smoke command 입력칸이 보인다.",
+        "코드 기반 초안 생성은 신규 레포 부트스트랩 용도라는 안내가 보인다."
+      ],
+      actions: [
+        "사용자는 프로젝트와 레포 정보를 입력한다.",
+        "`프로젝트 저장` 버튼을 눌러 Work Q가 관리할 대상을 저장한다.",
+        "`신규 레포 코드로 초안 생성` 버튼을 눌러 아직 natural-git이 없는 레포의 의도 명세 초안을 만든다."
+      ],
+      rules: [
+        "코드 기반 생성 결과는 오너 승인 전까지 기준 명세가 아니다.",
+        "생성 결과는 파일/함수/라인 설명이 아니라 사용자 기능, 입력, 출력, 상태 변화, 규칙, 검증 방법 중심이어야 한다.",
+        "프로젝트 키는 여러 레포와 요청을 섞지 않기 위한 안정적인 식별자다."
+      ],
+      verification: [
+        "프로젝트 저장 후 Active project가 저장한 프로젝트로 유지된다.",
+        "초안 생성 안내가 코드 설명 뷰어가 아니라 신규 레포 부트스트랩임을 명확히 설명한다.",
+        "잘못된 로컬 경로나 미연결 상태에서는 사용자가 다음 행동을 알 수 있어야 한다."
+      ]
+    },
+    {
+      slug: "intent-spec-status",
+      title: "의도 명세 상태 요약 영역",
+      purpose: "사용자는 현재 프로젝트의 승인된 의도 명세, 초안, 입력 필요, 충돌, MCP 준비 상태를 빠르게 확인한다.",
+      initial: [
+        "기준 프로젝트, 의도 명세 문서 수, 검토 필요 수, MCP Agent 상태가 카드로 보인다.",
+        "승인/동기화된 문서 수와 초안/수정 문서 수가 구분된다."
+      ],
+      actions: ["이 영역은 직접 입력 영역이 아니라 현재 프로젝트 상태를 읽는 요약 영역이다."],
+      rules: ["상태 숫자는 현재 Active project 기준으로만 계산한다.", "초안과 승인된 명세를 같은 지위로 보여주면 안 된다."],
+      verification: ["프로젝트 전환 후 다른 프로젝트의 명세 상태가 섞이지 않는다.", "초안, 수정, 승인 상태가 서로 구분되어 표시된다."]
+    },
+    {
+      slug: "intent-spec-list",
+      title: "자연어 의도 명세 목록 영역",
+      purpose: "사용자는 natural-git에 들어 있는 의도 명세 문서를 선택한다.",
+      initial: ["의도 명세 목록 제목이 보인다.", "문서가 있으면 제목, 짧은 경로, 상태가 보인다.", "문서가 없으면 natural-git 의도 명세가 없다는 안내가 보인다."],
+      actions: ["사용자는 문서를 클릭해 편집할 의도 명세를 선택한다."],
+      rules: ["사용자용 목록에는 코드 evidence 문서를 기본 명세처럼 섞지 않는다.", "문서 상태는 초안, 수정됨, 동기화, 승인됨을 구분해야 한다."],
+      verification: ["문서를 클릭하면 편집 영역에 같은 문서가 열린다.", "evidence 문서가 의도 명세 목록의 주 문서처럼 보이지 않는다."]
+    },
+    {
+      slug: "intent-spec-editor",
+      title: "자연어 의도 명세 편집 영역",
+      purpose: "사용자는 선택한 자연어 의도 명세를 읽고, 오너가 판단할 수 있는 형태로 수정한다.",
+      initial: [
+        "선택한 문서의 제목과 경로가 보인다.",
+        "목적, 초기 상태, 사용자 입력, 상태 변화, 결과, 핵심 규칙, 예외 상태, 검증 방법을 쓰라는 작성 기준이 보인다.",
+        "Markdown 편집창이 충분한 높이로 보인다."
+      ],
+      actions: ["사용자는 Markdown 명세를 수정한다.", "`Draft 저장` 버튼으로 저장한다."],
+      rules: [
+        "파일명, 함수명, 변수명, 라인별 코드 설명은 의도 명세가 아니다.",
+        "draft 저장은 승인된 기준 명세가 아니다.",
+        "오너가 승인한 자연어 의도만 이후 요청 판단의 기준이 된다."
+      ],
+      verification: ["긴 문서가 좁은 고정 높이에 갇히지 않는다.", "수정 전에는 저장 버튼이 비활성화되고, 수정 후에는 활성화된다.", "저장한 draft가 자연어 커밋 후보로 남는다."]
+    },
+    {
+      slug: "approval-flow",
+      title: "의도 명세 승인 플로우 영역",
+      purpose: "사용자는 초안 또는 수정된 의도 명세를 자연어 커밋, 머지 검증, 오너 승인, Agent 큐 단계로 진행한다.",
+      initial: ["Commit message 입력칸과 자연어 커밋, 명세 머지 검증, 승인 후 Agent 큐, 롤백 버튼이 보인다.", "HEAD, 검증, Agent 큐 상태가 단계별로 보인다."],
+      actions: ["사용자는 자연어 커밋을 만든다.", "사용자는 명세 머지 검증으로 입력 필요와 충돌을 확인한다.", "사용자는 승인 후 Agent 큐 버튼으로 로컬 Agent 작업 큐를 만든다.", "잘못된 커밋은 롤백한다."],
+      rules: ["수정된 문서가 없으면 자연어 커밋을 할 수 없다.", "HEAD commit이 없으면 머지, 승인, 롤백을 할 수 없다.", "입력 필요나 충돌이 있으면 Agent 큐로 바로 넘어가면 안 된다."],
+      verification: ["자연어 커밋 후 HEAD 상태가 표시된다.", "머지 검증 후 충돌과 입력 필요 수가 표시된다.", "승인 후 MCP가 읽을 수 있는 Agent 큐가 생성된다."]
+    },
+    {
+      slug: "request-analysis",
+      title: "사용자 요청 분석 영역",
+      purpose: "사용자는 버그, 개선, 개발문의, 기획문의를 자연어로 입력하고 승인된 의도 명세 기준으로 분석한다.",
+      initial: ["유형, 제목, 현재 URL, 실제 동작, 기대 동작, 재현 방법 입력칸이 보인다.", "의도 명세 기준으로 분석 버튼이 보인다."],
+      actions: ["사용자는 요청 내용을 입력한다.", "사용자는 분석 버튼을 눌러 승인된 명세와 요청을 비교한다."],
+      rules: [
+        "승인된 의도 명세와 실제 동작이 다르면 버그 후보로 본다.",
+        "기대 동작이 타당하지만 승인된 명세가 없으면 기획부재 또는 결정 필요로 본다.",
+        "승인된 명세끼리 충돌하면 기능충돌로 본다."
+      ],
+      verification: ["요청 제출 후 최근 요청 목록에 추가된다.", "제목이 없으면 분석 버튼을 사용할 수 없다.", "분석 결과는 현재 프로젝트 기준으로만 생성된다."]
+    },
+    {
+      slug: "request-and-agent-queue",
+      title: "요청과 Agent 큐 영역",
+      purpose: "사용자는 최근 요청과 로컬 Agent 작업 큐 상태를 함께 확인한다.",
+      initial: ["최근 요청 목록과 Agent 작업 목록이 나뉘어 보인다.", "작업이 없으면 빈 상태 안내가 보인다."],
+      actions: ["사용자는 요청과 Agent 작업의 상태, 제목, 요약을 확인한다."],
+      rules: ["다른 프로젝트의 요청과 큐가 섞이면 안 된다.", "문의는 자동으로 코드 작업 큐가 아니라 답변 완료 흐름으로 처리할 수 있어야 한다."],
+      verification: ["프로젝트를 바꾸면 요청과 큐 목록도 해당 프로젝트 기준으로 바뀐다.", "Agent 작업이 완료되면 상태와 결과 요약이 갱신된다."]
+    }
+  ];
+}
+
 function workQDashboardRegions() {
   return [
     {
@@ -1067,6 +1200,7 @@ function genericRouteRegions(file) {
 }
 
 function regionsForRoute(file, route) {
+  if (isWorkQV3Page(file, route)) return workQV3Regions();
   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);
@@ -1077,13 +1211,13 @@ const INTERNAL_FEATURE_DEFINITIONS = [
   {
     slug: "repository-natural-analysis",
     title: "레포 코드 자연어 분석 백엔드",
-    purpose: "사용자가 연결한 코드 레포를 읽고 URL 화면, 화면 영역, 검증 근거 중심의 natural-spec repo 초안을 만든다.",
+    purpose: "신규 프로젝트에 아직 natural-git 기준 명세가 없을 때 코드 레포를 읽고 사용자 기능, 입력, 출력, 상태 변화, 규칙 중심의 의도 명세 초안을 만든다.",
     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: ["새 프로젝트의 초기 기능명세가 비어 있거나 코드 중심 문서로 잘못 보일 수 있다."],
+    used_by_routes: ["/", "/v2", "/v3"],
+    related_regions: ["project-repo-bootstrap", "intent-spec-list", "project-repo-registration", "natural-spec-repo"],
+    triggers: ["사용자가 신규 레포 코드로 초안 생성을 요청한다.", "로컬 MCP CLI가 `workq natural-git` 업로드를 실행한다."],
+    outcomes: ["화면/영역 중심 Markdown 의도 명세 초안이 생성된다.", "코드 파일별 상세 구현은 `_evidence`로 분리된다.", "오너 승인 전까지 초안은 판단 기준 HEAD가 아니다."],
+    failure_impact: ["새 프로젝트의 초기 의도 명세가 비어 있거나 코드 변수/라인 설명 중심 문서로 잘못 보일 수 있다."],
     verification: ["생성 결과에 `natural-git/screens/` 문서와 `_evidence` 문서가 함께 존재하는지 확인한다."]
   },
   {
@@ -1091,8 +1225,8 @@ const INTERNAL_FEATURE_DEFINITIONS = [
     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"],
+    used_by_routes: ["/", "/v2", "/v3"],
+    related_regions: ["intent-spec-list", "intent-spec-editor", "approval-flow", "natural-spec-repo", "natural-spec-editor", "commit-merge-agent-queue"],
     triggers: ["사용자가 자연어 명세를 저장한다.", "사용자가 자연어 커밋, 머지, 롤백을 실행한다."],
     outcomes: ["draft와 HEAD commit 상태가 구분된다.", "승인된 자연어 커밋만 Agent 큐 기준이 된다."],
     failure_impact: ["화면에 보이는 명세와 Agent가 기준으로 읽는 명세가 달라질 수 있다."],
@@ -1103,8 +1237,8 @@ const INTERNAL_FEATURE_DEFINITIONS = [
     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"],
+    used_by_routes: ["/", "/v2", "/v3"],
+    related_regions: ["request-analysis", "request-and-agent-queue", "report-intake", "triage-and-spec-map", "decision-needed-mcp"],
     triggers: ["사용자가 리포트를 제출한다.", "사용자가 기존 리포트를 다시 분석한다."],
     outcomes: ["판단 결과와 근거 명세가 사용자에게 표시된다.", "승인이 필요한 항목은 자동 개발 큐로 넘어가지 않는다."],
     failure_impact: ["버그가 아닌 기획부재를 버그로 고치거나, 실제 버그를 문의로 놓칠 수 있다."],
@@ -1115,8 +1249,8 @@ const INTERNAL_FEATURE_DEFINITIONS = [
     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"],
+    used_by_routes: ["/", "/v2", "/v3"],
+    related_regions: ["approval-flow", "request-and-agent-queue", "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가 잘못된 프로젝트를 고치거나, 완료 작업이 큐에 남을 수 있다."],
@@ -1127,8 +1261,8 @@ const INTERNAL_FEATURE_DEFINITIONS = [
     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"],
+    used_by_routes: ["/", "/v2", "/v3"],
+    related_regions: ["project-repo-bootstrap", "intent-spec-status", "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: ["여러 프로젝트를 사용할 때 다른 레포의 리포트나 작업을 처리할 수 있다."],
@@ -1305,9 +1439,18 @@ function entrylessScreenDoc(entry) {
 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 = isWorkQDashboard ? "Work Q 대시보드 화면 명세" : isWorkQV2 ? "Work Q v2 대시보드 화면 명세" : route.title;
+  const isWorkQV3 = isWorkQV3Page(file, route);
+  const title = isWorkQV3
+    ? "Work Q v3 의도 명세 MVP 화면 명세"
+    : isWorkQDashboard
+    ? "Work Q 대시보드 화면 명세"
+    : isWorkQV2
+    ? "Work Q v2 대시보드 화면 명세"
+    : route.title;
   const purpose = isWorkQDashboard
     ? "사용자는 Work Q에서 프로젝트를 선택하고, 리포트를 등록하고, 기능명세 판단 근거와 Agent 큐 상태를 확인한다."
+    : isWorkQV3
+    ? "사용자는 Work Q v3에서 신규 레포를 의도 명세 초안으로 부트스트랩하고, 오너가 승인한 자연어 git을 기준으로 요청을 분석하고 로컬 Agent 큐로 보낸다."
     : isWorkQV2
     ? "사용자는 Work Q v2에서 프로젝트와 레포를 연결하고, natural-spec repo를 편집하며, 리포트와 자연어 커밋을 Agent 작업 큐로 연결한다."
     : `${route.url_pattern} URL에서 사용자가 보는 화면의 목적, 영역, 조작, 결과를 정의한다.`;

package/package.json

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