workq-mcp 0.1.1 → 0.1.3

package/lib/natural-git.mjs

@@ -152,48 +152,172 @@ function compact(value, maxLength = 220) {
   return `${normalized.slice(0, maxLength - 3).trim()}...`;
 }
 
-function lineKind(line) {
-  if (/^(\/\/|#|\/\*|\*|<!--)/.test(line)) return "comment";
-  if (/^(import\s|from\s+|const\s+\w+\s*=\s*require\(|require\(|#include|using\s+|use\s+)/.test(line)) return "import";
-  if (/^(export\s|module\.exports|exports\.)/.test(line)) return "export";
-  if (/^(?:async\s+)?function\s+|^(?:export\s+)?(?:const|let|var)\s+\w+\s*=.*=>|^def\s+|^function\s+/.test(line)) return "function";
-  if (/^class\s+|^(?:export\s+)?class\s+|^(?:public\s+)?(?:final\s+)?class\s+/.test(line)) return "class";
-  if (/\bif\s*\(|^if\s+|^elif\s+|\belse\s+if\s*\(/.test(line)) return "if";
-  if (/\bfor\s*\(|^for\s+|\bwhile\s*\(|^while\s+/.test(line)) return "loop";
-  if (/\bswitch\s*\(|^match\s+/.test(line)) return "switch";
-  if (/\bcatch\s*\(|^except\s+/.test(line)) return "catch";
-  if (/^return\b/.test(line)) return "return";
-  if (/^throw\b|^raise\b/.test(line)) return "throw";
-  if (/^(const|let|var)\s+\w+\s*=|^[A-Za-z_$][\w$]*\s*=/.test(line)) return "assignment";
-  if (/\b(app|router)\.(get|post|put|patch|delete|use)\s*\(/i.test(line)) return "route";
-  if (/\.addEventListener\(/.test(line)) return "event";
-  if (/^SELECT\b|^INSERT\b|^UPDATE\b|^DELETE\b|^CREATE\b|^ALTER\b/i.test(line)) return "sql";
-  if (/^\{|\}|\]|\[|,$/.test(line)) return "structure";
-  return "statement";
+function unique(values, limit = 40) {
+  return Array.from(new Set(values.filter(Boolean))).slice(0, limit);
 }
 
-function naturalSentenceForLine(line, lineNumber) {
-  const cleaned = cleanLine(line);
-  if (!cleaned) return "";
-  const text = compact(cleaned);
-  const kind = lineKind(cleaned);
-  if (kind === "comment") return `- ${lineNumber}행: 주석 \`${text}\`은 코드 작성자가 남긴 설명 또는 메모이다.`;
-  if (kind === "import") return `- ${lineNumber}행: \`${text}\` 구문으로 외부 모듈, 표준 라이브러리, 또는 다른 파일의 기능을 가져온다.`;
-  if (kind === "export") return `- ${lineNumber}행: \`${text}\` 구문으로 이 파일의 값을 다른 파일에서 사용할 수 있게 공개한다.`;
-  if (kind === "function") return `- ${lineNumber}행: \`${text}\` 형태의 함수 또는 콜백을 정의한다.`;
-  if (kind === "class") return `- ${lineNumber}행: \`${text}\` 형태의 클래스를 정의해 관련 상태와 동작을 객체 단위로 묶는다.`;
-  if (kind === "if") return `- ${lineNumber}행: 만약 \`${compact(cleaned.replace(/^else\s+/, ""))}\` 조건이 참이면 이어지는 블록의 동작을 실행한다.`;
-  if (kind === "loop") return `- ${lineNumber}행: \`${text}\` 반복 조건에 따라 여러 값 또는 여러 시도에 같은 처리를 반복한다.`;
-  if (kind === "switch") return `- ${lineNumber}행: \`${text}\` 값에 따라 여러 분기 중 하나의 흐름을 선택한다.`;
-  if (kind === "catch") return `- ${lineNumber}행: \`${text}\` 예외 흐름을 받아 실패 처리, 로깅, 복구 중 하나를 수행한다.`;
-  if (kind === "return") return `- ${lineNumber}행: \`${text}\` 값을 호출자에게 반환하고 현재 함수의 결과로 삼는다.`;
-  if (kind === "throw") return `- ${lineNumber}행: \`${text}\` 오류를 발생시켜 정상 흐름을 중단하고 실패 흐름으로 이동한다.`;
-  if (kind === "assignment") return `- ${lineNumber}행: \`${text}\` 값을 변수, 상수, 객체 속성, 또는 상태에 대입한다.`;
-  if (kind === "route") return `- ${lineNumber}행: \`${text}\` HTTP 라우트 또는 미들웨어를 등록해 요청이 들어왔을 때 실행될 처리를 연결한다.`;
-  if (kind === "event") return `- ${lineNumber}행: \`${text}\` 사용자 또는 브라우저 이벤트가 발생했을 때 실행될 동작을 연결한다.`;
-  if (kind === "sql") return `- ${lineNumber}행: \`${text}\` SQL 명령으로 데이터 조회, 생성, 수정, 삭제, 또는 스키마 변경을 수행한다.`;
-  if (kind === "structure") return `- ${lineNumber}행: \`${text}\` 문법 구조를 열거나 닫아 객체, 배열, 블록, 또는 설정 항목의 범위를 정한다.`;
-  return `- ${lineNumber}행: \`${text}\` 문장을 실행해 현재 파일의 동작, 설정, 화면, 데이터 처리 중 일부를 구성한다.`;
+const NATURAL_SPEC_FORMAT_COMMENT = "<!-- workq-natural-spec-format: feature-v2 -->";
+
+function stripTags(value) {
+  return value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+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(/\b(?:textContent|innerText|placeholder|aria-label|title)\s*=\s*["'`]([^"'`]{1,100})["'`]/g)) {
+    texts.push(stripTags(match[1]));
+  }
+  for (const match of file.content.matchAll(/<button[^>]*>([\s\S]{1,160}?)<\/button>/gi)) {
+    texts.push(stripTags(match[1]));
+  }
+  return unique(texts.map((item) => compact(item, 100)).filter((item) => item && !/^[{}()[\];,.]+$/.test(item)), 18);
+}
+
+function extractDesignFacts(file) {
+  if (![".css", ".html", ".tsx", ".jsx"].includes(file.extension)) return [];
+  const facts = [];
+  const colors = unique(Array.from(file.content.matchAll(/#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)/g)).map((match) => match[0]), 10);
+  const gradients = unique(Array.from(file.content.matchAll(/linear-gradient\([^)]+\)/g)).map((match) => match[0]), 6);
+  const radii = unique(Array.from(file.content.matchAll(/border-radius\s*:\s*([^;]+);/g)).map((match) => match[1].trim()), 6);
+  const shadows = unique(Array.from(file.content.matchAll(/box-shadow\s*:\s*([^;]+);/g)).map((match) => match[1].trim()), 6);
+  const layout = [];
+  if (/display\s*:\s*grid/.test(file.content)) layout.push("grid");
+  if (/display\s*:\s*flex/.test(file.content)) layout.push("flex");
+  if (/min-height\s*:\s*100vh/.test(file.content)) layout.push("full viewport height");
+  if (/justify-content\s*:\s*center|align-items\s*:\s*center/.test(file.content)) layout.push("centered alignment");
+  if (colors.length) facts.push(`색상 팔레트는 ${colors.join(", ")} 값을 포함한다.`);
+  if (gradients.length) facts.push(`그라데이션 배경/강조는 ${gradients.join(", ")} 형태를 사용한다.`);
+  if (layout.length) facts.push(`레이아웃은 ${unique(layout).join(", ")} 배치를 사용한다.`);
+  if (radii.length) facts.push(`둥근 모서리 값은 ${radii.join(", ")} 등이 관찰된다.`);
+  if (shadows.length) facts.push(`그림자 표현은 ${shadows.slice(0, 3).join(", ")} 값을 사용한다.`);
+  if (/@keyframes\s+([A-Za-z0-9_-]+)/.test(file.content)) {
+    facts.push(`애니메이션은 ${unique(Array.from(file.content.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)/g)).map((match) => match[1])).join(", ")} keyframes를 사용한다.`);
+  }
+  return facts;
+}
+
+function extractDataModelFacts(file) {
+  const facts = [];
+  const schemaMatch = file.content.match(/new\s+mongoose\.Schema\s*\(\s*\{([\s\S]*?)\}\s*\)/m);
+  if (schemaMatch) {
+    facts.push("서비스가 저장하고 조회하는 데이터 구조와 값의 종류를 정의한다.");
+  }
+  if (file.path === "package.json") {
+    const packageDoc = packageJsonDoc(file.content).split(/\r?\n/).filter((line) => line.startsWith("- `") || line.startsWith("- 패키지 이름"));
+    facts.push(...packageDoc.slice(0, 12));
+  }
+  return facts;
+}
+
+function isEnvironmentConfigFile(file) {
+  const normalized = file.path.toLowerCase();
+  const basename = path.basename(normalized);
+  return (
+    /(^|\/)(env|environment)\.[cm]?[jt]sx?$/.test(normalized) ||
+    /(^|\/)(env|environment)\.(mjs|cjs|js|ts)$/.test(normalized) ||
+    /(^|\/)(lib|config)\/env\.[cm]?[jt]sx?$/.test(normalized) ||
+    /(^|\/)(lib|config)\/environment\.[cm]?[jt]sx?$/.test(normalized) ||
+    /^(env|environment)\./.test(basename)
+  );
+}
+
+function isCliEntryFile(file) {
+  return (
+    /^#!\/usr\/bin\/env\s+node/m.test(file.content) ||
+    /\bprocess\.argv\b/.test(file.content) ||
+    /\bUsage:\s*[\r\n]/.test(file.content) ||
+    /\bworkq\s+(connect|bootstrap|natural-git|reset|mcp)\b/.test(file.content)
+  );
+}
+
+function extractCliFacts(file) {
+  if (!isCliEntryFile(file)) return [];
+  const facts = [];
+  if (/\bworkq\s+connect\b/.test(file.content)) facts.push("사용자는 터미널에서 현재 로컬 git 저장소를 Work Q 프로젝트에 연결한다.");
+  if (/\bworkq\s+bootstrap\b/.test(file.content)) facts.push("사용자는 현재 저장소를 분석해 프로젝트 컨텍스트와 기능 지도를 Work Q에 초기 등록한다.");
+  if (/\bworkq\s+natural-git\b/.test(file.content)) facts.push("사용자는 현재 저장소의 구현을 기능 중심 자연어 명세로 변환해 Work Q natural-spec repo에 업로드한다.");
+  if (/\bworkq\s+reset\b/.test(file.content)) facts.push("사용자는 프로젝트 키를 다시 확인한 뒤 Work Q에 저장된 프로젝트 데이터를 초기화한다.");
+  if (/\bworkq\s+mcp\b/.test(file.content)) facts.push("사용자는 데스크톱 AI 클라이언트가 연결할 수 있는 Work Q MCP bridge를 실행한다.");
+  if (/git\s*\(\s*\[\s*["']rev-parse["']|git\s+rev-parse/.test(file.content)) facts.push("명령 실행 시 현재 저장소의 로컬 경로, 현재 브랜치, 현재 커밋을 읽어 Work Q에 전달한다.");
+  if (/remote["']?,\s*["']get-url|git\s+remote\s+get-url/.test(file.content)) facts.push("명령 실행 시 원격 GitHub 저장소 주소를 읽어 프로젝트의 owner와 repo를 구분한다.");
+  if (/WORKQ_MCP_TOKEN|WORKQ_MCP_TOKEN_FILE/.test(file.content)) facts.push("MCP 인증 토큰은 환경 변수 또는 토큰 파일에서 읽어 Work Q API 호출에 사용한다.");
+  if (/WORKQ_MCP_URL/.test(file.content)) facts.push("Work Q MCP API 주소는 환경 변수로 바꿀 수 있고, 없으면 기본 운영 endpoint를 사용한다.");
+  return unique(facts, 14);
+}
+
+function extractCliRules(file) {
+  if (!isCliEntryFile(file)) return [];
+  const rules = [];
+  if (/--project-key/.test(file.content)) rules.push("프로젝트를 식별하는 key는 연결, 초기 분석, 자연어 명세 업로드, 초기화 명령에서 필수 입력이다.");
+  if (/--confirm-project-key/.test(file.content)) rules.push("프로젝트 초기화는 실수를 막기 위해 같은 프로젝트 key를 확인값으로 한 번 더 요구한다.");
+  if (/Only github\.com remotes are supported|github\.com/.test(file.content)) rules.push("원격 저장소는 GitHub 주소만 지원한다.");
+  if (/WORKQ_MCP_TOKEN_FILE|\.workq\/mcp-token/.test(file.content)) rules.push("직접 토큰이 없으면 지정된 토큰 파일을 읽고, 기본 토큰 파일 경로를 사용한다.");
+  if (/throw new Error/.test(file.content)) rules.push("필수 입력이나 연결 정보가 없으면 조용히 진행하지 않고 사용자에게 오류를 알린다.");
+  return unique(rules, 10);
+}
+
+function extractEnvironmentFacts(file) {
+  if (!isEnvironmentConfigFile(file)) return [];
+  const envVars = unique(
+    Array.from(file.content.matchAll(/process\.env(?:\.([A-Za-z_][A-Za-z0-9_]*)|\[["'`]([^"'`]+)["'`]\])/g)).map((match) => match[1] || match[2]),
+    18
+  );
+  const facts = [];
+  if (!envVars.length && !/get(DataDir|DbDir|WorkDir|AppUrl)|isMcpConfigured|getMiniAiConfig|isGithubCrudConfigured|requireEnv/.test(file.content)) return facts;
+  if (envVars.length) facts.push("데이터 저장 위치, 외부 접속 주소, 에이전트 연결, AI 분류, GitHub 자동화, 테스트 모드 같은 런타임 설정을 외부 설정값으로 결정한다.");
+  if (/getDataDir|getDbDir|getWorkDir/.test(file.content)) facts.push("서비스 데이터, 내부 데이터베이스, 작업 파일이 저장될 위치를 외부 설정과 기본값으로 분리한다.");
+  if (/getAppUrl/.test(file.content)) facts.push("앱 외부 접속 주소는 배포 환경에서 지정하고, 없으면 로컬 개발 주소를 기본값으로 사용한다.");
+  if (/isMcpConfigured|WORKQ_MCP_TOKEN/.test(file.content)) facts.push("MCP 인증 정보가 설정되어 있는지 확인해 로컬 에이전트 연결 가능 상태를 구분한다.");
+  if (/getMiniAiConfig|isMiniAiConfigured|WORKQ_MINI_AI/.test(file.content)) facts.push("AI 분류 서버 주소, 사용할 모델, 인증 정보를 하나의 설정으로 묶어 자동 분류 가능 여부를 판단한다.");
+  if (/isGithubCrudConfigured|WORKQ_GITHUB_TOKEN/.test(file.content)) facts.push("GitHub 자동화 인증 정보가 있으면 코드 변경 자동화 기능을 사용할 수 있는 상태로 판단한다.");
+  if (/requireEnv/.test(file.content)) facts.push("필수 환경 변수가 없으면 조용히 진행하지 않고 명시적인 설정 오류를 발생시킨다.");
+  return unique(facts, 10);
+}
+
+function extractFunctionalFacts(file, structure) {
+  const facts = [];
+  facts.push(...extractCliFacts(file));
+  const environmentFacts = extractEnvironmentFacts(file);
+  const visibleTexts = extractVisibleTexts(file);
+  facts.push(...environmentFacts);
+  if (visibleTexts.length) facts.push(`사용자에게 보이는 주요 문구는 ${visibleTexts.map((item) => `"${item}"`).join(", ")} 이다.`);
+  if (structure.events.length) facts.push("사용자 조작에 반응해 화면 상태나 결과 표시를 갱신한다.");
+  if (structure.routes.length) facts.push("HTTP 요청을 받아 서비스 상태 조회, 저장, 갱신 같은 서버 기능을 처리한다.");
+  if (/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/.test(file.content)) {
+    const loop = file.content.match(/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/);
+    facts.push(`반복문은 ${loop[2]}부터 ${loop[3]}까지의 선택지 또는 결과 행을 자동 생성한다.`);
+  }
+  if (/document\.createElement\(["']button["']\)/.test(file.content)) facts.push("버튼 요소를 코드에서 자동 생성한다.");
+  if (/classList\.add\(["']active["']\)|classList\.remove\(["']active["']\)/.test(file.content)) facts.push("선택 상태는 active 클래스로 표시하고 이전 선택은 해제한다.");
+  if (/innerHTML\s*=/.test(file.content)) facts.push("사용자 선택 이후 결과 영역의 HTML을 새 내용으로 교체한다.");
+  return facts;
+}
+
+function buildVerificationFacts(file, structure) {
+  const facts = [];
+  if (isCliEntryFile(file)) {
+    facts.push("각 CLI 명령이 필수 입력을 요구하고 누락 시 명확한 오류를 보여주는지 확인한다.");
+    facts.push("로컬 git 저장소 정보와 Work Q 프로젝트 정보가 의도한 프로젝트에만 연결되는지 확인한다.");
+    facts.push("자연어 명세 업로드 명령이 기능 중심 문서를 만들고 Work Q에 정상 반영하는지 확인한다.");
+    return facts;
+  }
+  if (isEnvironmentConfigFile(file)) {
+    facts.push("외부 설정값이 있을 때 해당 값이 우선 적용되는지 확인한다.");
+    facts.push("외부 설정값이 없을 때 기본값이나 명확한 설정 오류가 의도대로 동작하는지 확인한다.");
+    facts.push("에이전트 연결, AI 분류, GitHub 자동화 가능 상태가 설정 유무에 따라 올바르게 구분되는지 확인한다.");
+    return facts;
+  }
+  if (extractVisibleTexts(file).length) facts.push("화면에 노출되는 문구와 버튼이 의도한 사용자 흐름을 설명하는지 확인한다.");
+  if (structure.events.length) facts.push("사용자 이벤트 실행 후 화면 상태와 데이터가 기대값으로 바뀌는지 확인한다.");
+  if (structure.conditions.length) facts.push("반복/조건의 경계값과 예외 흐름을 테스트한다.");
+  if (extractDataModelFacts(file).length) facts.push("저장되는 필드 이름, 타입, 필수 여부가 실제 데이터와 맞는지 확인한다.");
+  if (!facts.length) facts.push("이 파일이 제공하는 설정 또는 보조 로직이 연결된 기능에서 실제로 사용되는지 확인한다.");
+  return facts;
 }
 
 function extractStructure(lines) {
@@ -237,11 +361,22 @@ function packageJsonDoc(content) {
 }
 
 function sourceFileToDoc(file) {
-  const structure = extractStructure(file.lines);
-  const lineSpec = file.lines.map((line, index) => naturalSentenceForLine(line, index + 1)).filter(Boolean);
+  const structure = {
+    imports: [],
+    exports: [],
+    classes: [],
+    routes: [],
+    events: [],
+    selectors: [],
+    ...extractStructure(file.lines)
+  };
   const purpose =
     file.path === "package.json"
       ? "패키지 이름, 실행 스크립트, 의존성, Node 런타임 조건을 정의한다."
+      : isCliEntryFile(file)
+        ? "터미널 명령으로 Work Q 프로젝트 연결, 초기 분석, 자연어 명세 업로드, 프로젝트 초기화, MCP bridge 실행을 수행한다."
+      : extractEnvironmentFacts(file).length
+        ? "런타임 환경 변수와 기본값을 해석해 저장소, URL, MCP, Mini AI, GitHub 연결 상태를 결정한다."
       : file.extension === ".css"
         ? "화면 요소의 레이아웃, 색상, 반응형 배치, 상호작용 상태를 정의한다."
         : file.extension === ".html"
@@ -249,39 +384,56 @@ function sourceFileToDoc(file) {
           : structure.functions.length
             ? "함수 단위로 데이터를 계산하거나 화면/파일/네트워크 동작을 수행한다."
             : "레포 동작을 구성하는 설정, 데이터, 또는 보조 텍스트를 제공한다.";
+  const dataModelFacts = extractDataModelFacts(file);
+  const functionalFacts = extractFunctionalFacts(file, structure);
+  const designFacts = extractDesignFacts(file);
+  const verificationFacts = buildVerificationFacts(file, structure);
+  const coreRules = unique(
+    [
+      ...dataModelFacts,
+      ...extractCliRules(file),
+      ...extractEnvironmentFacts(file),
+      ...functionalFacts.filter((item) => /반복문|선택 상태|자동 생성|결과 영역|HTTP 요청|필수|초기화|GitHub|토큰/.test(item))
+    ],
+    12
+  );
+  const titleText = extractVisibleTexts(file)[0];
+  const title = isCliEntryFile(file)
+    ? "Work Q CLI 기능명세"
+    : file.path === "package.json"
+      ? "프로젝트 실행 환경 기능명세"
+      : titleText && file.extension === ".html"
+        ? `${titleText} 기능명세`
+        : extractEnvironmentFacts(file).length
+          ? "런타임 환경 설정 기능명세"
+          : dataModelFacts.length
+            ? "데이터 모델 기능명세"
+            : file.extension === ".css"
+              ? "화면 디자인 기능명세"
+              : `${file.path} 기능명세`;
   return [
-    `# ${file.path}`,
-    "",
-    "## 자연어 명세",
-    `이 파일은 ${file.language} 파일이다. ${purpose}`,
-    "",
-    "## 파일 정보",
-    `- 원본 경로: \`${file.path}\``,
-    `- 언어/형식: ${file.language}`,
-    `- 총 라인 수: ${file.lines.length}`,
-    `- 감지된 함수/메서드: ${structure.functions.length}개`,
-    `- 감지된 조건/반복/예외 흐름: ${structure.conditions.length}개`,
+    `# ${title}`,
+    NATURAL_SPEC_FORMAT_COMMENT,
     "",
-    structure.functions.length ? "## 함수와 메서드" : "",
-    ...structure.functions.map((item) => `- ${item.line}행: \`${item.name}\` 함수는 \`${item.signature}\` 형태로 정의된다.`),
+    "## 기능 중심 자연어 명세",
+    `제품 관점에서 이 기능은 ${purpose}`,
     "",
-    structure.variables.length ? "## 주요 변수와 상수" : "",
-    ...structure.variables.map((item) => `- ${item.line}행: \`${item.name}\` 값은 \`${item.signature}\` 구문으로 정의된다.`),
+    functionalFacts.length ? "## 사용자 기능과 동작" : "",
+    ...functionalFacts.map((item) => `- ${item}`),
     "",
-    structure.conditions.length ? "## 조건, 반복, 예외 흐름" : "",
-    ...structure.conditions.map((item) => `- ${item.line}행: 만약 또는 반복 조건 \`${item.signature}\`에 따라 실행 흐름이 달라진다.`),
+    coreRules.length ? "## 핵심 규칙" : "",
+    ...coreRules.map((item) => `- ${item}`),
     "",
-    file.path === "package.json" ? packageJsonDoc(file.content) : "",
+    designFacts.length ? "## 화면과 디자인 명세" : "",
+    ...designFacts.map((item) => `- ${item}`),
     "",
-    "## 라인별 자연어 실행 흐름",
-    "이 섹션은 코드의 각 의미 있는 라인을 자연어 명세로 해석한다.",
-    ...lineSpec,
+    dataModelFacts.length && file.path !== "package.json" ? "## 데이터와 상태" : "",
+    ...(file.path !== "package.json" ? dataModelFacts.map((item) => `- ${item}`) : []),
     "",
     "## 검증 관점",
-    "- 이 파일의 자연어 명세는 코드의 현재 구조를 해석한 것이다.",
-    "- 라인별 자연어 실행 흐름은 원본 코드의 의미 있는 모든 라인을 대상으로 한다.",
-    "- 제품 의도와 코드가 다를 수 있으므로, 코드에서 관찰된 동작은 승인된 제품 의도가 아니라 검증 근거로 취급한다.",
-    "- 리포트 분류 시 이 문서의 함수, 조건, 라우트, 이벤트 설명을 근거로 실제 구현 여부를 판단한다."
+    ...verificationFacts.map((item) => `- ${item}`),
+    "- 이 문서는 현재 구현에서 관찰한 기능 초안이며, 오너가 승인한 뒤 기준 명세가 된다.",
+    "- 리포트 분류 시 이 문서는 기능 존재, 화면 동작, 입력/출력, 핵심 규칙의 근거로 사용한다."
   ].filter((line, index, array) => line || array[index - 1]).join("\n");
 }
 
@@ -290,9 +442,10 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
   for (const file of sourceFiles) byLanguage.set(file.language, (byLanguage.get(file.language) ?? 0) + 1);
   return [
     `# ${projectKey} 자연어 git 명세`,
+    NATURAL_SPEC_FORMAT_COMMENT,
     "",
     "## 의미",
-    "이 명세는 레포에 존재하는 코드 파일을 사람이 읽을 수 있는 자연어로 해석한 것이다. 함수, 변수, 조건, 반복, 라우트, 이벤트, 설정 파일, 의미 있는 코드 라인을 Markdown 문서로 풀어 쓰며, Work Q v2에서는 이 자연어 문서를 기준으로 리포트와 코드 변경을 판단한다.",
+    "이 명세는 레포에 존재하는 코드 파일을 제품 기능, 사용자 동작, 입력/출력, 화면/디자인, 데이터 규칙 중심의 자연어 Markdown 문서로 해석한 것이다. Work Q v2에서는 이 자연어 문서를 기준으로 리포트와 코드 변경을 판단한다.",
     "",
     "## 프로젝트",
     `- 프로젝트 키: ${projectKey}`,
@@ -305,8 +458,8 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     ...Array.from(byLanguage.entries()).map(([language, count]) => `- ${language}: ${count}개`),
     "",
     "## 운영 규칙",
-    "- 자연어 문서는 코드에서 관찰한 구조를 설명한다.",
-    "- 각 코드 파일 문서는 `라인별 자연어 실행 흐름` 섹션을 포함해야 한다.",
+    "- 자연어 문서는 코드에서 관찰한 제품 기능과 검증 가능한 동작을 설명한다.",
+    "- 각 코드 파일 문서는 라인별 번역이 아니라 기능, 규칙, 화면, 데이터, 검증 관점 중심으로 작성한다.",
     "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
     "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",
     "- 코드가 바뀌면 이 자연어 git 명세도 다시 분석하거나 수정해야 한다."

package/package.json

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