speccore 6.77.6 → 6.80.0

package/dist/commands/analyze.js

@@ -63,6 +63,8 @@ const unified_retrieval_1 = require("../core/unified-retrieval");
 const pipeline_engine_1 = require("../core/pipeline-engine");
 const change_detection_1 = require("../core/change-detection");
 const streaming_analyzer_1 = require("../core/streaming-analyzer");
+// v6.80.0+: 需求澄清模块
+const requirement_clarifier_1 = require("../core/requirement-clarifier");
 async function analyzeCommand(options) {
     // ── --full / --phase 模式: 委托给 synthesizeCommand（原 synthesize 命令） ──
     if (options.full || options.phase) {
@@ -538,15 +540,17 @@ async function analyzeCommand(options) {
             initStep = 'init';
         }
         else {
-            // 迭代层：使用 createAnalyzePipeline（支持契约先行 + 逐端推进 + 变更感知 + 关键路径优先）
+            // 迭代层：使用 createAnalyzePipeline（支持契约先行 + 逐端推进 + 变更感知 + 关键路径优先 + 需求澄清）
             const result = await (0, pipeline_engine_1.createAnalyzePipeline)(iter, process.cwd(), {
                 affectedPlatforms: affectedPlatforms && affectedPlatforms.length > 0 ? affectedPlatforms : undefined,
                 platformOrder: platformOrder && platformOrder.length > 0 ? platformOrder : undefined,
+                skipClarify: options.skipClarify,
             });
             engine = result.engine;
             steps = result.steps;
             pipelineKey = iter;
-            initStep = 'phase1-prompt';
+            // v6.80.0+: 默认从 clarify 开始，skipClarify 时从 phase1 开始
+            initStep = options.skipClarify ? 'phase1-prompt' : 'clarify-prompt';
         }
         // 检查是否有活跃的 Pipeline（恢复模式）
         const hasActive = await pipeline_engine_1.PipelineEngine.hasActivePipeline(process.cwd(), pipelineKey);
@@ -591,6 +595,14 @@ async function analyzeCommand(options) {
                 }, options);
             }
         }
+        else if (currentStep === 'clarify-prompt') {
+            // v6.80.0+: Phase 0 需求澄清
+            prompt = await buildClarifyPhasePrompt(iter);
+        }
+        else if (currentStep === 'confirm-check') {
+            // v6.80.0+: 需求确认阶段 — 输出质量报告提示
+            prompt = await buildConfirmCheckPrompt(iter);
+        }
         else if (currentStep === 'phase1-prompt') {
             prompt = await buildMultiDocPrompt('analyze', {
                 iteration: iter, task: options.task, type: options.type,
@@ -628,13 +640,17 @@ async function analyzeCommand(options) {
                                 : '全局 Pipeline';
         }
         else {
-            progressLabel = currentStep === 'phase1-prompt'
-                ? 'Phase 1/3: 迭代综合文档'
-                : currentStep === 'contract-prompt'
-                    ? 'Phase 2/3: 契约定义'
-                    : platformMatch
-                        ? `Phase 2/3: ${platformMatch[1]} 端专属文档`
-                        : 'Pipeline';
+            progressLabel = currentStep === 'clarify-prompt'
+                ? 'Phase 0/3: 需求澄清'
+                : currentStep === 'confirm-check'
+                    ? 'Phase 0/3: 需求确认'
+                    : currentStep === 'phase1-prompt'
+                        ? 'Phase 1/3: 迭代综合文档'
+                        : currentStep === 'contract-prompt'
+                            ? 'Phase 2/3: 契约定义'
+                            : platformMatch
+                                ? `Phase 2/3: ${platformMatch[1]} 端专属文档`
+                                : 'Pipeline';
         }
         const finalPrompt = prompt + `\n\n## ⚠️ Pipeline 模式：自动继续 (${progressLabel})\n\n` +
             `当前是 Pipeline 模式（步骤 ${currentStepIndex + 1}/${totalSteps}）。` +
@@ -647,6 +663,18 @@ async function analyzeCommand(options) {
     // ── Prompt 模式 ──
     if (options.prompt) {
         const iter = options.scope === 'global' ? 'GLOBAL' : (options.iteration || await (0, context_1.getDefaultIteration)());
+        // v6.80.0+: 非 Pipeline 模式下也默认检测需求质量
+        if (iter !== 'GLOBAL' && !options.skipClarify && !options.pipeline) {
+            const iterDir = await (0, context_1.getIterationDir)(iter);
+            const hasClarified = await (0, requirement_clarifier_1.hasValidClarifiedDocs)(iterDir);
+            if (!hasClarified) {
+                // 未澄清过，先执行 clarify
+                const clarifyPrompt = await buildClarifyPhasePrompt(iter);
+                process.stdout.write(`[SPECCORE_PROMPT]\n${clarifyPrompt}`);
+                process.exitCode = 10;
+                return;
+            }
+        }
         const prompt = await buildMultiDocPrompt('analyze', { iteration: iter, task: options.task, type: options.type, scope: options.scope, withCode: options.withCode, platform: options.platform, phase: options.phase, autoMode: options.auto }, options);
         process.stdout.write(`[SPECCORE_PROMPT]\n${prompt}`);
         process.exitCode = 10;
@@ -780,6 +808,22 @@ async function analyzeCommand(options) {
                     const validPlatforms = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_1.parsePlatformList)())]);
                     let skippedCount = 0;
                     for (const [filename, content] of Object.entries(docs)) {
+                        // v6.80.0+: 010-requirements/ 路径处理（clarify 结果写入）
+                        if (filename.startsWith('010-requirements/')) {
+                            const reqFilePath = filename.slice('010-requirements/'.length);
+                            const reqDir = (0, path_1.join)(iterDir, '010-requirements');
+                            const fp = (0, path_1.join)(reqDir, reqFilePath);
+                            await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
+                            // 为 clarified 文件添加头部元信息
+                            let finalContent = content;
+                            if (reqFilePath.startsWith('converted/clarified-') && !content.startsWith('---')) {
+                                finalContent = (0, requirement_clarifier_1.buildClarifiedHeader)(reqFilePath) + content;
+                            }
+                            await (0, fs_extra_1.writeFile)(fp, finalContent);
+                            logger_1.logger.info(`   📝 需求文档已写入: ${reqFilePath}`);
+                            count++;
+                            continue;
+                        }
                         // v6.72.0+: PATTERNS/ 文件特殊处理 → 写入 .speccore/PATTERNS/
                         if (filename.startsWith('PATTERNS/')) {
                             const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
@@ -872,7 +916,7 @@ async function analyzeCommand(options) {
                         }
                     }
                     // v6.72.0+: FUNCTION_MAP.md 自检
-                    const fmContent = docs['FUNCTION_MAP.md'] || docs['global/FUNCTION_MAP.md'];
+                    const fmContent = docs['FUNCTION_MAP.md'] || docs['overview/FUNCTION_MAP.md'] || docs['global/FUNCTION_MAP.md'];
                     if (fmContent) {
                         const platforms = Array.from(validPlatforms);
                         const fmResult = validateFunctionMap(fmContent, platforms);
@@ -941,7 +985,7 @@ async function analyzeCommand(options) {
             }
         }
         else {
-            // 迭代级：写 020-specs/global/（综合文档，v6.41.0+）
+            // 迭代级：写 020-specs/overview/（迭代综合文档，v6.78.0+）
             const specDir = (0, path_1.join)(iterDir, '020-specs');
             const globalDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
             await (0, fs_extra_1.ensureDir)(globalDir);
@@ -953,7 +997,7 @@ async function analyzeCommand(options) {
                     logger_1.logger.info(`   📦 旧版已备份: ${iterBackup.split('/').pop()}`);
                 }
                 await (0, fs_extra_1.writeFile)(iterAnalysisPath, options.apply);
-                logger_1.logger.success(`✅ ANALYSIS.md 已写入 020-specs/global/`);
+                logger_1.logger.success(`✅ ANALYSIS.md 已写入 020-specs/overview/`);
             }
             else {
                 logger_1.logger.info(`   ⏭️  用户取消覆盖`);
@@ -1050,6 +1094,13 @@ async function analyzeCommand(options) {
                                 iteration: options.iteration || 'GLOBAL', scope: 'global', withCode: options.withCode,
                             });
                         }
+                        // v6.80.0+: clarify 阶段推进
+                    }
+                    else if (state.currentStep === 'clarify-prompt') {
+                        nextPrompt = await buildClarifyPhasePrompt(options.iteration);
+                    }
+                    else if (state.currentStep === 'confirm-check') {
+                        nextPrompt = await buildConfirmCheckPrompt(options.iteration);
                     }
                     else if (state.currentStep === 'contract-prompt') {
                         nextPrompt = await buildContractFirstPrompt(options.iteration);
@@ -1085,11 +1136,11 @@ async function analyzeCommand(options) {
             // 检查是否有多个端
             const platforms = await (0, spec_paths_1.parsePlatformList)();
             // 只有多端项目(≥2 个端)才需要分两阶段:
-            // - Phase 1: 生成综合文档(global/REQUIREMENT.md、ANALYSIS.md、DEPS.md)
+            // - Phase 1: 生成综合文档(overview/REQUIREMENT.md、ANALYSIS.md、DEPS.md)
             // - Phase 2: 生成各端专属文档({端}/TECH.md、TEST.md、UI_SPEC.md)
             // 
             // 单端项目(=1 个端)不需要分阶段:
-            // - Phase 1 生成的 global/TECH.md 本身就是该端的专属文档
+            // - Phase 1 生成的 overview/TECH.md 本身就是该端的专属文档
             // - 不需要再生成 {端}/TECH.md(会重复)
             if (platforms.length >= 2) {
                 logger_1.logger.info('');
@@ -1788,7 +1839,7 @@ async function buildMultiDocPrompt(command, ctx, options) {
 - 缓存策略/并发与事务/消息队列（如涉及）
 - 安全：SQL注入防护/接口鉴权/数据脱敏
 - 性能：QPS预估/慢查询优化/连接池配置
-- **不要写**用户旅程、业务场景、页面清单（这些在 global/REQUIREMENT.md 中）
+- **不要写**用户旅程、业务场景、页面清单（这些在 overview/REQUIREMENT.md 中）
 
 ### 前端端（h5 / admin-web / miniapp）— 产品+技术双视角
 - **产品视角（主要）**：
@@ -1976,7 +2027,7 @@ sequenceDiagram
 
 ## 写作要求
 
-### 全局级 DEV_GUIDE.md（020-specs/global/）
+### 迭代级 DEV_GUIDE.md（020-specs/overview/）
 - **技术栈与选型决策**：每个技术点的选型理由、替代方案对比
 - **代码分层规范**：目录结构、各层职责、代码组织方式
 - **通用设计模式**：Repository 模式、Service 模式、策略模式等具体实现
@@ -2011,7 +2062,7 @@ sequenceDiagram
     ];
     // 任务类型 × 文档矩阵: 每种类型生成哪些文档
     const DOC_MATRIX = {
-        feature: ['REQUIREMENT.md', 'ANALYSIS.md', 'TECH.md', 'TEST.md', 'REVIEW.md', 'RISK.md', 'DEPS.md', 'MONITOR.md', 'UI_SPEC.md', 'FUNCTION_MAP.md', 'INTERACTION_MAP.md'],
+        feature: ['REQUIREMENT.md', 'ANALYSIS.md', 'TECH.md', 'TEST.md', 'REVIEW.md', 'RISK.md', 'DEPS.md', 'MONITOR.md', 'UI_SPEC.md', 'FUNCTION_MAP.md', 'INTERACTION_MAP.md', 'DEV_GUIDE.md'],
         refactor: ['ANALYSIS.md', 'TECH.md', 'TEST.md', 'REVIEW.md', 'RISK.md'],
         bugfix: ['ANALYSIS.md', 'TECH.md', 'TEST.md'],
         research: ['ANALYSIS.md'],
@@ -2023,12 +2074,12 @@ sequenceDiagram
         performance: ['ANALYSIS.md', 'TECH.md', 'TEST.md', 'MONITOR.md'],
     };
     let includeDocs = isTask ? (DOC_MATRIX[taskType] || DOC_MATRIX['feature']) : DOC_MATRIX['feature'];
-    // v6.76.0+: --dev-guide 模式下增加 DEV_GUIDE.md
-    if (options?.devGuide) {
-        includeDocs = [...includeDocs, 'DEV_GUIDE.md'];
+    // v6.78.0+: DEV_GUIDE.md 默认生成（--dev-guide 向后兼容，--no-dev-guide 可禁用）
+    if (options?.devGuide === false) {
+        includeDocs = includeDocs.filter(d => d !== 'DEV_GUIDE.md');
     }
     // ── v6.61.0+: 恢复 Phase 1/Phase 2 分步逻辑，但 CLI 自动触发 Phase 2 ──
-    // Phase 1: 生成综合文档(global/REQUIREMENT.md、ANALYSIS.md、DEPS.md 等)
+    // Phase 1: 生成综合文档(overview/REQUIREMENT.md、ANALYSIS.md、DEPS.md 等)
     // Phase 2: 生成各端专属文档({端}/TECH.md、TEST.md、UI_SPEC.md 等)
     const GLOBAL_DOCS = ['REQUIREMENT.md', 'ANALYSIS.md', 'TECH.md', 'RISK.md', 'DEPS.md', 'REVIEW.md', 'MONITOR.md', 'FUNCTION_MAP.md', 'INTERACTION_MAP.md'];
     const PLATFORM_DOCS = ['TECH.md', 'TEST.md', 'UI_SPEC.md'];
@@ -2067,7 +2118,7 @@ sequenceDiagram
                 doc[1] = `# \u672c\u4efb\u52a1\u9700\u6c42\u89c4\u683c\n\n> ${iter} | ${ctx.task} | ${now}\n\n## \u5199\u4f5c\u8981\u6c42\n\u6839\u636e split \u4ea7\u51fa\u7684\u9700\u6c42\u5207\u7247\uff0c\u7ed3\u5408\u5168\u5c40\u4e0a\u4e0b\u6587\uff0c\u91cd\u65b0\u7ec4\u7ec7\u672c\u4efb\u52a1\u7684\u9700\u6c42\u89c4\u683c\uff1a\n- \u660e\u786e\u672c\u4efb\u52a1\u7684\u9a8c\u6536\u6807\u51c6\uff08\u53ef\u6d4b\u8bd5\u7684\u3001\u5177\u4f53\u7684\uff09\n- \u7ec6\u5316\u4e1a\u52a1\u89c4\u5219\u548c\u8fb9\u754c\u6761\u4ef6\n- \u5217\u51fa\u5f02\u5e38\u573a\u666f\u548c\u5904\u7406\u65b9\u5f0f\n- \u6807\u6ce8\u4e0e\u5176\u4ed6 Task \u7684\u4f9d\u8d56\u5173\u7cfb\n`;
             }
             else if (doc[0] === 'TECH.md') {
-                doc[1] = `# \u672c\u4efb\u52a1\u6280\u672f\u65b9\u6848\n\n> ${iter} | ${ctx.task} | ${now}\n\n## \u5199\u4f5c\u8981\u6c42\n\u57fa\u4e8e global/TECH.md \u7684\u6574\u4f53\u67b6\u6784\uff0c\u7ec6\u5316\u5230\u51fd\u6570/\u63a5\u53e3\u7ea7\u522b\uff1a\n- \u5177\u4f53\u7684\u63a5\u53e3\u5b9a\u4e49\uff08\u8def\u5f84/\u53c2\u6570/\u54cd\u5e94\uff09\n- \u6570\u636e\u6a21\u578b\u8bbe\u8ba1\uff08Entity/DTO/VO \u5b57\u6bb5\u6620\u5c04\uff09\n- \u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u7684\u4f2a\u4ee3\u7801\u6216\u6d41\u7a0b\u63cf\u8ff0\n- \u524d\u7aef\u7ec4\u4ef6\u62c6\u5206\u548c\u72b6\u6001\u8bbe\u8ba1\n- \u5fc5\u987b\u4e0e global/TECH.md \u7684\u6574\u4f53\u67b6\u6784\u4fdd\u6301\u4e00\u81f4\n`;
+                doc[1] = `# \u672c\u4efb\u52a1\u6280\u672f\u65b9\u6848\n\n> ${iter} | ${ctx.task} | ${now}\n\n## \u5199\u4f5c\u8981\u6c42\n\u57fa\u4e8e overview/TECH.md \u7684\u6574\u4f53\u67b6\u6784\uff0c\u7ec6\u5316\u5230\u51fd\u6570/\u63a5\u53e3\u7ea7\u522b\uff1a\n- \u5177\u4f53\u7684\u63a5\u53e3\u5b9a\u4e49\uff08\u8def\u5f84/\u53c2\u6570/\u54cd\u5e94\uff09\n- \u6570\u636e\u6a21\u578b\u8bbe\u8ba1\uff08Entity/DTO/VO \u5b57\u6bb5\u6620\u5c04\uff09\n- \u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u7684\u4f2a\u4ee3\u7801\u6216\u6d41\u7a0b\u63cf\u8ff0\n- \u524d\u7aef\u7ec4\u4ef6\u62c6\u5206\u548c\u72b6\u6001\u8bbe\u8ba1\n- \u5fc5\u987b\u4e0e overview/TECH.md \u7684\u6574\u4f53\u67b6\u6784\u4fdd\u6301\u4e00\u81f4\n`;
             }
             else if (doc[0] === 'TASK.md') {
                 doc[1] = `# \u5b9e\u65bd\u8ba1\u5212\n\n> ${iter} | ${ctx.task} | ${now}\n\n## \u5199\u4f5c\u8981\u6c42\n\u6839\u636e\u672c\u4efb\u52a1\u7684\u9700\u6c42\u548c\u6280\u672f\u65b9\u6848\uff0c\u5236\u5b9a\u5177\u4f53\u5b9e\u65bd\u6b65\u9aa4\uff1a\n- \u6309\u5f00\u53d1\u987a\u5e8f\u5217\u51fa\u5177\u4f53\u6b65\u9aa4\n- \u6bcf\u4e2a\u6b65\u9aa4\u6709\u660e\u786e\u7684\u5b8c\u6210\u6807\u51c6\n- \u6807\u6ce8\u6b65\u9aa4\u95f4\u7684\u4f9d\u8d56\u5173\u7cfb\n- \u4f30\u7b97\u6bcf\u6b65\u7684\u5de5\u4f5c\u91cf\n`;
@@ -2098,17 +2149,44 @@ sequenceDiagram
     // ── v6.60.0+: TECH.md 模板：global/ 侧重整体架构，{端}/ 侧重端专属方案 ──
     const techDoc = taskDocs.find(([n]) => n === 'TECH.md');
     if (techDoc) {
-        // global/TECH.md: 整体架构
+        // overview/TECH.md: 整体架构
         techDoc[1] = `# 技术架构（跨端全局）\n\n> ${iter}\n\n## 写作要求\n撰写整体技术架构，覆盖所有端的交互关系：\n- 系统整体分层设计（各端在架构中的位置）\n- 跨端交互协议（前端↔后端通信方式、数据流向）\n- 中间件选型（缓存、消息队列、网关等）\n- 数据库整体设计（核心表结构、ER 关系）\n- 技术栈选型及理由\n`;
     }
     let prompt = `\n# 任务: ${command}${task} (${taskDocs.length}个文档 · ${isTask ? `类型:${taskType}` : '迭代全量'}${ctx.phase ? ` · Phase ${ctx.phase}` : ''})\n\n`;
+    // v6.80.0+: 注入需求质量上下文（迭代级分析时）
+    if (!isGlobal && !isTask && ctx.iteration && ctx.iteration !== 'GLOBAL') {
+        try {
+            const iterDir = await (0, context_1.getIterationDir)(ctx.iteration);
+            const reportPath = (0, path_1.join)(iterDir, '010-requirements', 'CLARIFY_REPORT.md');
+            if (await (0, fs_extra_1.pathExists)(reportPath)) {
+                const report = await (0, fs_extra_2.readFile)(reportPath, 'utf-8');
+                // 提取汇总表和关键信息
+                const summaryMatch = report.match(/## 质量评分汇总[\s\S]*?(?=## |$)/);
+                if (summaryMatch) {
+                    prompt += `## 📋 需求文档质量声明\n\n`;
+                    prompt += `> 以下评价基于 Phase 0 需求澄清结果\n\n`;
+                    prompt += summaryMatch[0].split('\n').slice(0, 12).join('\n'); // 取汇总表前12行
+                    prompt += `\n\n`;
+                    // 检测是否有遗留问题
+                    const hasIssues = report.includes('待澄清') || report.includes('❌');
+                    if (hasIssues) {
+                        prompt += `⚠️ **遗留问题**: 部分需求文档仍有未解决问题，分析时请标注不确定性。\n\n`;
+                    }
+                    else {
+                        prompt += `✅ **质量确认**: 所有需求文档已通过澄清，可直接深入技术分析。\n\n`;
+                    }
+                }
+            }
+        }
+        catch { /* 忽略质量上下文注入失败 */ }
+    }
     // ── v6.67.0+: 在 prompt 开头就明确完整工作流程 ──
     if (!ctx.phase && !isTask) {
         const platforms = await (0, spec_paths_1.parsePlatformList)();
         if (platforms.length >= 2) {
             prompt += `## 📋 完整工作流程（两阶段分析）\n\n`;
             prompt += `本项目检测到有 ${platforms.length} 个端(${platforms.join('、')})，需要分两阶段执行：\n\n`;
-            prompt += `**Phase 1（当前阶段）**: 生成综合文档(global/REQUIREMENT.md、ANALYSIS.md、DEPS.md 等)\n`;
+            prompt += `**Phase 1（当前阶段）**: 生成综合文档(overview/REQUIREMENT.md、ANALYSIS.md、DEPS.md 等)\n`;
             prompt += `**Phase 2（下一阶段）**: 生成各端专属文档({端}/TECH.md、TEST.md、UI_SPEC.md 等)\n\n`;
             prompt += `## ⚠️ 强制要求：Phase 1 完成后立即执行 Phase 2\n\n`;
             prompt += `当你通过 --apply 写入所有综合文档后，**必须立即执行**以下命令进入 Phase 2：\n\n`;
@@ -2126,8 +2204,8 @@ sequenceDiagram
     prompt += `- ✅ **正确行为**：只使用 CLI 预创建的 global/ 和 {端名}/ 目录，不要手动 mkdir 或 Write 到不存在的目录\n`;
     prompt += `- ⚠️ **后果**：如果创建额外目录，会导致后续 split/execute 命令找不到文件，整个工作流失败\n\n`;
     prompt += `###  绝对禁止直接用 Write 工具写文件\n`;
-    prompt += `- ❌ **错误行为**：Write("020-specs/global/ANALYSIS.md", content) 或直接 Write 到任何路径\n`;
-    prompt += `- ✅ **正确行为**：必须通过 \`speccore analyze --apply '{"global/ANALYSIS.md":"...","admin-web/TECH.md":"..."}' -I ${iter}\` 写入\n`;
+    prompt += `- ❌ **错误行为**：Write("020-specs/overview/ANALYSIS.md", content) 或直接 Write 到任何路径\n`;
+    prompt += `- ✅ **正确行为**：必须通过 \`speccore analyze --apply '{"overview/ANALYSIS.md":"...","admin-web/TECH.md":"..."}' -I ${iter}\` 写入\n`;
     prompt += `- 💡 **Windows 兼容**：如果 JSON 在命令行中转义困难，先将 JSON 写入文件（如 result.json），然后执行 \`speccore analyze --apply @result.json -I ${iter}\`\n`;
     prompt += `- ⚠️ **原因**：--apply 会让 CLI 自动路由文件到正确的子目录，直接 Write 会绕过这个机制，导致所有文件扁平在根目录\n\n`;
     prompt += `### ✅ 正确的目录结构\n`;
@@ -2166,12 +2244,12 @@ sequenceDiagram
         prompt += `### Step 2: 读取全局上下文（作为参考）\n`;
         prompt += `- Read .speccore/CONSTITUTION.md → 项目配置\n`;
         prompt += `- Read 020-specs/PLATFORMS.md → 端列表\n`;
-        prompt += `- Read 020-specs/global/REQUIREMENT.md → 全局需求规格\n`;
-        prompt += `- Read 020-specs/global/TECH.md → 整体技术架构\n`;
-        prompt += `- Read 020-specs/global/ANALYSIS.md → 全局分析报告\n`;
+        prompt += `- Read 020-specs/overview/REQUIREMENT.md → 迭代综合需求规格\n`;
+        prompt += `- Read 020-specs/overview/TECH.md → 迭代综合技术架构\n`;
+        prompt += `- Read 020-specs/overview/ANALYSIS.md → 迭代综合分析报告\n`;
         prompt += `- Read 020-specs/{本任务端名}/TECH.md → 该端专属技术方案\n\n`;
         prompt += `### Step 3: 撰写任务级深度分析文档\n\n`;
-        prompt += `**REQ.md** — 本任务的需求规格（不是 global/REQUIREMENT.md 的复制）：\n`;
+        prompt += `**REQ.md** — 本任务的需求规格（不是 overview/REQUIREMENT.md 的复制）：\n`;
         prompt += `- 明确本任务的验收标准（可测试的、具体的）\n`;
         prompt += `- 细化业务规则和边界条件\n`;
         prompt += `- 列出本任务涉及的异常场景\n\n`;
@@ -2180,7 +2258,7 @@ sequenceDiagram
         prompt += `- 数据模型设计（Entity/DTO/VO 字段映射）\n`;
         prompt += `- 核心业务逻辑的伪代码或流程描述\n`;
         prompt += `- 前端组件拆分和状态设计\n`;
-        prompt += `- 必须与 global/TECH.md 的整体架构保持一致\n\n`;
+        prompt += `- 必须与 overview/TECH.md 的整体架构保持一致\n\n`;
         prompt += `**TASK.md** — 本任务的实施步骤：\n`;
         prompt += `- 按开发顺序列出具体步骤\n`;
         prompt += `- 每个步骤有明确的完成标准\n`;
@@ -2197,7 +2275,7 @@ sequenceDiagram
         if (ctx.platform) {
             prompt += `- **只分析 ${ctx.platform} 端**：从 CONSTITUTION.md 读取端列表，但只生成 ${ctx.platform} 端的专属文档\n`;
             prompt += `- 在 020-specs/${ctx.platform}/ 下写入该端专属文档（ANALYSIS.md、TECH.md、TEST.md 等）\n`;
-            prompt += `- 全局跨端文档写入 020-specs/global/（REQUIREMENT.md、DEPS.md、RISK.md 等）\n`;
+            prompt += `- 迭代综合文档写入 020-specs/overview/（REQUIREMENT.md、DEPS.md、RISK.md 等）\n`;
             prompt += `- **不要生成**其他端的子目录和文档\n`;
         }
         // ── v6.61.0+: 阶段专属指令（Phase 2）──
@@ -2207,13 +2285,13 @@ sequenceDiagram
             prompt += `依次 Read 以下文件，建立全局技术架构认知：\n`;
             prompt += `- Read .speccore/CONSTITUTION.md\n`;
             prompt += `- Read 020-specs/PLATFORMS.md → 获取端列表\n`;
-            prompt += `- Read 020-specs/global/REQUIREMENT.md → 需求规格\n`;
-            prompt += `- Read 020-specs/global/ANALYSIS.md → 分析报告\n`;
-            prompt += `- Read 020-specs/global/TECH.md → 整体技术架构\n`;
-            prompt += `- Read 020-specs/global/RISK.md、DEPS.md、REVIEW.md、MONITOR.md（如存在）\n\n`;
+            prompt += `- Read 020-specs/overview/REQUIREMENT.md → 需求规格\n`;
+            prompt += `- Read 020-specs/overview/ANALYSIS.md → 分析报告\n`;
+            prompt += `- Read 020-specs/overview/TECH.md → 整体技术架构\n`;
+            prompt += `- Read 020-specs/overview/RISK.md、DEPS.md、REVIEW.md、MONITOR.md（如存在）\n\n`;
             prompt += `### Step 2: 为每个端撰写专属文档\n`;
             prompt += `根据全局上下文，为 PLATFORMS.md 中的**每个端**分别撰写：\n`;
-            prompt += `- **{端}/TECH.md**：该端专属技术方案（必须对齐 global/TECH.md 架构）\n`;
+            prompt += `- **{端}/TECH.md**：该端专属技术方案（必须对齐 overview/TECH.md 架构）\n`;
             prompt += `  - ⚠️ **必须包含「业务-代码映射」章节**：在 TECH.md 末尾添加表格，列出本端涉及的业务模块及其对应的代码实体（文件/表/API/组件等），关系类型由你根据技术栈自主决定（如 api_controller、uses_table、page、component、route、middleware、interceptor、gateway 等）\n`;
             prompt += `  - 表格格式：| 业务模块 | 代码实体 | 关系类型 | 说明 |\n`;
             prompt += `  - 示例：| 会议室档案 | backend/RoomController.java | api_controller | REST 控制器 |\n`;
@@ -2221,7 +2299,7 @@ sequenceDiagram
             prompt += `- **{端}/TEST.md**：该端专属测试计划\n`;
             prompt += `- **{端}/UI_SPEC.md**：该端专属 UI 规格（仅前端端需要）\n\n`;
             prompt += `### Step 3: 一致性检查\n`;
-            prompt += `- 各端 TECH.md 的技术选型必须与 global/TECH.md 一致\n`;
+            prompt += `- 各端 TECH.md 的技术选型必须与 overview/TECH.md 一致\n`;
             prompt += `- UI_SPEC.md 的字段映射必须与后端 API 响应字段一一对应\n`;
             prompt += `- TEST.md 必须覆盖 REQUIREMENT.md 中该端的验收标准\n\n`;
             prompt += `### 写入方式\n`;
@@ -2285,7 +2363,7 @@ sequenceDiagram
             prompt += `   - 端的信息只在「功能模块清单」表格中标注，正文不区分端\n`;
             // v6.49.14+: 功能模块清单必须含涉及端列 + 来源链接
             // v6.71.3+: 增加「与全局层对比」列
-            prompt += `9. **功能模块清单（重要）**：写入 global/REQUIREMENT.md 时，功能模块清单表格必须包含以下列\n`;
+            prompt += `9. **功能模块清单（重要）**：写入 overview/REQUIREMENT.md 时，功能模块清单表格必须包含以下列\n`;
             prompt += `   - 表格格式：| # | 功能模块 | 涉及端 | 全局对比 | 来源 | 说明 |\n`;
             prompt += `   - 「涉及端」：每个模块标注需要**新开发工作**的端（标准端名，逗号分隔）\n`;
             prompt += `     - 「涉及」= 该端需要写新接口/新页面/新逻辑\n`;
@@ -2311,7 +2389,7 @@ sequenceDiagram
             prompt += `   - 标注每个功能模块的「全局对比」类型（新增/扩展/重构/复用）\n`;
             prompt += `   - 识别冲突：如迭代需求修改了全局层已有接口的字段/路径 → 在 RISK.md 中标注\n`;
             prompt += `   - 识别依赖：如迭代的新功能依赖全局层的某个功能 → 在 FUNCTION_MAP.md「依赖任务」中标注\n\n`;
-            prompt += `7b. **跨端功能映射表（重要）**：在 REQUIREMENT.md 完成后，必须生成 global/FUNCTION_MAP.md\n`;
+            prompt += `7b. **跨端功能映射表（重要）**：在 REQUIREMENT.md 完成后，必须生成 overview/FUNCTION_MAP.md\n`;
             prompt += `   - 这是 split 阶段的核心输入，决定任务如何按功能单元拆分\n`;
             prompt += `   - 表格格式：| # | 功能单元 | 涉及端 | 全局对比 | 共享能力 | 依赖任务 | 说明 |\n`;
             prompt += `   - 「功能单元」必须与 REQUIREMENT.md 功能模块清单一一对应，不允许合并\n`;
@@ -2324,7 +2402,7 @@ sequenceDiagram
             prompt += `   - **错误示例**（禁止）：将"审批流程"和"定时任务"合并为一行\n`;
             prompt += `   - FUNCTION_MAP.md 生成后，split 将**严格按此表**创建任务目录，不再由 AI 推断\n`;
             // v6.70.0+: 跨端交互图谱（INTERACTION_MAP.md）
-            prompt += `7c. **跨端交互图谱（重要）**：在 FUNCTION_MAP.md 完成后，必须生成 global/INTERACTION_MAP.md\n`;
+            prompt += `7c. **跨端交互图谱（重要）**：在 FUNCTION_MAP.md 完成后，必须生成 overview/INTERACTION_MAP.md\n`;
             prompt += `   - 按功能单元组织，每个功能单元一个 Mermaid sequenceDiagram\n`;
             prompt += `   - 展示完整的业务交互时序：用户操作 → 前端处理 → 后端调用 → 数据返回\n`;
             prompt += `   - 明确标出后端服务之间的内部调用（产品文档写"系统处理"的地方）\n`;
@@ -2356,7 +2434,7 @@ sequenceDiagram
             }
             const dirStepNum = platformTypes.size > 0 ? 9 : 8;
             prompt += `${dirStepNum}. **目录结构（严格遵循，禁止自创目录）**：\n`;
-            prompt += `   - **综合文档**（跨端通用）→ 通过 --apply 写入，CLI 自动路由到 \`020-specs/global/{文件名}\`\n`;
+            prompt += `   - **综合文档**（跨端通用）→ 通过 --apply 写入，CLI 自动路由到 \`020-specs/overview/{文件名}\`\n`;
             prompt += `     - REQUIREMENT.md（需求文档，含功能模块清单+涉及端列）\n`;
             prompt += `     - ANALYSIS.md（需求分析）\n`;
             prompt += `     - DEPS.md（依赖清单）\n`;
@@ -2383,7 +2461,7 @@ sequenceDiagram
                 prompt += `- 缓存策略/并发与事务/消息队列（如涉及）\n`;
                 prompt += `- 安全：SQL 注入防护/接口鉴权/数据脱敏\n`;
                 prompt += `- 性能：QPS 预估/慢查询优化/连接池配置\n`;
-                prompt += `- **不需要**产品视角的需求描述（用户故事、业务场景已在 global/REQUIREMENT.md 中）\n\n`;
+                prompt += `- **不需要**产品视角的需求描述（用户故事、业务场景已在 overview/REQUIREMENT.md 中）\n\n`;
                 prompt += `### 前端端（h5 / admin-web / miniapp）必含内容 — 产品+技术双视角\n`;
                 prompt += `- **产品视角（主要）**：\n`;
                 prompt += `  - 用户旅程：该端用户如何完成核心任务（步骤流程图）\n`;
@@ -2401,11 +2479,11 @@ sequenceDiagram
         // v6.60.0+: 文档与端的对应关系（不再分 Phase）
         // v6.71.0+: 前后端文档差异化
         prompt += `### 文档与端的对应关系\n`;
-        prompt += `- **global/REQUIREMENT.md**：整体需求（产品视角，按业务场景组织）\n`;
-        prompt += `- **global/ANALYSIS.md**：整体需求分析\n`;
-        prompt += `- **global/DEPS.md**：整体依赖清单\n`;
-        prompt += `- **global/FUNCTION_MAP.md**：功能单元 × 端映射表\n`;
-        prompt += `- **global/INTERACTION_MAP.md**：跨端交互时序图\n`;
+        prompt += `- **overview/REQUIREMENT.md**：整体需求（产品视角，按业务场景组织）\n`;
+        prompt += `- **overview/ANALYSIS.md**：整体需求分析\n`;
+        prompt += `- **overview/DEPS.md**：整体依赖清单\n`;
+        prompt += `- **overview/FUNCTION_MAP.md**：功能单元 × 端映射表\n`;
+        prompt += `- **overview/INTERACTION_MAP.md**：跨端交互时序图\n`;
         prompt += `- **后端端（*service）/{端}/TECH.md**：纯技术视角 — 接口设计+数据模型+架构+性能\n`;
         prompt += `- **前端端（h5/admin/miniapp）/{端}/TECH.md**：产品+技术双视角 — 用户旅程+页面清单+交互流程+API调用链\n`;
         prompt += `- **前端端/{端}/UI_SPEC.md**：UI 规格（字段映射、组件设计、交互细节）\n`;
@@ -2526,11 +2604,11 @@ sequenceDiagram
     prompt += `### 4. 跨文档引用一致性\n`;
     prompt += `- [ ] 检查 UI_SPEC.md 中的字段映射是否与后端 API 响应字段一一对应\n`;
     prompt += `- [ ] 检查 TEST.md 中的测试场景是否覆盖了 REQUIREMENT.md 中的所有验收标准\n`;
-    prompt += `- [ ] 检查各端 TECH.md 的技术选型是否与 global/TECH.md 的整体架构一致\n\n`;
+    prompt += `- [ ] 检查各端 TECH.md 的技术选型是否与 overview/TECH.md 的整体架构一致\n\n`;
     prompt += `### 5. 目录结构合法性\n`;
     prompt += `- [ ] 确认 --apply 的 JSON 键名只包含合法文件名或「合法端名/文件名」格式\n`;
     prompt += `- [ ] **禁止**包含数字编号目录（如 1001/、1002/）、中文目录（如 错误码/）、特殊符号目录（如 .../）\n`;
-    prompt += `- [ ] 合法格式示例：\`global/ANALYSIS.md\`、\`admin-web/TECH.md\`、\`REQUIREMENT.md\`\n\n`;
+    prompt += `- [ ] 合法格式示例：\`overview/ANALYSIS.md\`、\`admin-web/TECH.md\`、\`REQUIREMENT.md\`\n\n`;
     prompt += `### 自检通过标准\n`;
     prompt += `以上 5 项全部勾选通过后，方可执行 --apply 写入。如果任何一项未通过，先修正问题，重新自检，直到全部通过。\n`;
     return prompt;
@@ -2560,11 +2638,11 @@ async function buildStreamingGlobalPrompt(command, ctx, options) {
     prompt += `| :--- | :--- | :--- | :--- |\n`;
     prompt += `| Phase 0 | 快速全局扫描 | 所有端并行索引 | platforms/{端}/_INDEX.md |\n`;
     prompt += `| Phase 1 | 后端深度分析 | 拓扑排序，从依赖源头开始 | platforms/{后端端}/API_INVENTORY.md, DATA_MODEL.md, ... |\n`;
-    prompt += `| Phase 2 | 全局实时更新 | 后端完成后更新全局文档 | global/API_CONTRACT.yaml, ARCHITECTURE.md, ... |\n`;
+    prompt += `| Phase 2 | 迭代综合实时更新 | 后端完成后更新迭代综合文档 | overview/API_CONTRACT.yaml, ARCHITECTURE.md, ... |\n`;
     prompt += `| Phase 3 | 前端深度分析 | 对齐后端契约 | platforms/{前端端}/FEATURES.md, UI_SPEC.md, ... |\n`;
-    prompt += `| Phase 4 | 横向关联检查 | 前后端字段/接口一致性 | global/CROSS_CHECK.md |\n`;
-    prompt += `| Phase 5 | 纵向关联检查 | 功能模块跨端完整性 | global/VERTICAL_CHECK.md |\n`;
-    prompt += `| Phase 6 | 最终核对检查 | 完整性+一致性+遗漏检测 | global/FINAL_AUDIT.md |\n\n`;
+    prompt += `| Phase 4 | 横向关联检查 | 前后端字段/接口一致性 | overview/CROSS_CHECK.md |\n`;
+    prompt += `| Phase 5 | 纵向关联检查 | 功能模块跨端完整性 | overview/VERTICAL_CHECK.md |\n`;
+    prompt += `| Phase 6 | 最终核对检查 | 完整性+一致性+遗漏检测 | overview/FINAL_AUDIT.md |\n\n`;
     prompt += `## ⚠️ 实时关联调整机制\n\n`;
     prompt += `分析过程中，如果当前阶段发现与前期文档冲突或不一致：\n`;
     prompt += `1. **在当前阶段文档中标注冲突点**\n`;
@@ -2648,10 +2726,10 @@ async function buildContractFirstPrompt(iteration) {
     prompt += `Phase 1 迭代分析已完成。现在需要在各端开始专属技术方案分析之前，**先定义跨端 API 契约**。\n\n`;
     prompt += `## 读取内容\n\n`;
     prompt += `1. Read .speccore/CONSTITUTION.md → 获取端列表和项目配置\n`;
-    prompt += `2. Read 020-specs/global/REQUIREMENT.md → 全局需求规格\n`;
-    prompt += `3. Read 020-specs/global/ANALYSIS.md → 全局分析报告\n`;
-    prompt += `4. Read 020-specs/global/TECH.md → 整体技术架构\n`;
-    prompt += `5. Read 020-specs/global/DEPS.md → 依赖关系（如存在）\n\n`;
+    prompt += `2. Read 020-specs/overview/REQUIREMENT.md → 迭代综合需求规格\n`;
+    prompt += `3. Read 020-specs/overview/ANALYSIS.md → 迭代综合分析报告\n`;
+    prompt += `4. Read 020-specs/overview/TECH.md → 迭代综合技术架构\n`;
+    prompt += `5. Read 020-specs/overview/DEPS.md → 依赖关系（如存在）\n\n`;
     prompt += `## 输出要求\n\n`;
     prompt += `基于上述文档，生成一份 **API_CONTRACT.yaml**，使用标准 YAML 格式：\n\n`;
     prompt += `### 格式要求\n`;
@@ -2714,7 +2792,7 @@ async function buildContractFirstPrompt(iteration) {
     prompt += `## 写入方式\n\n`;
     prompt += `speccore analyze --apply '{"API_CONTRACT.yaml":"..."}' -I ${iteration}\n\n`;
     prompt += `⚠️ **注意**：\n`;
-    prompt += `- 契约文件写入 020-specs/global/API_CONTRACT.yaml（全局共享）\n`;
+    prompt += `- 契约文件写入 020-specs/overview/API_CONTRACT.yaml（迭代综合共享）\n`;
     prompt += `- 这是各端技术方案分析的**前置输入**，后续各端分析必须遵循此契约\n`;
     prompt += `- 契约应**精确且完整**，避免后续各端分析时出现接口不一致\n\n`;
     return prompt;
@@ -2759,4 +2837,118 @@ async function getSubtaskDirs(taskDir) {
     }
     return result;
 }
+// ═══════════════════════════════════════════════════════════
+// v6.80.0+: 需求澄清 Phase Prompt 构建
+// ═══════════════════════════════════════════════════════════
+async function buildClarifyPhasePrompt(iteration) {
+    const iterDir = await (0, context_1.getIterationDir)(iteration);
+    const reqDir = (0, path_1.join)(iterDir, '010-requirements');
+    // 收集所有需求文档
+    const docPaths = [];
+    for (const sub of ['sources', 'converted', 'features']) {
+        const subDir = (0, path_1.join)(reqDir, sub);
+        if (await (0, fs_extra_1.pathExists)(subDir)) {
+            try {
+                const entries = await (0, fs_extra_2.readdir)(subDir, { withFileTypes: true });
+                for (const e of entries) {
+                    if (e.isFile() && e.name.endsWith('.md') && !e.name.startsWith('.')) {
+                        docPaths.push((0, path_1.join)(subDir, e.name));
+                    }
+                    else if (e.isDirectory()) {
+                        const files = await (0, fs_extra_2.readdir)((0, path_1.join)(subDir, e.name));
+                        for (const f of files) {
+                            if (f.endsWith('.md') && !f.startsWith('.'))
+                                docPaths.push((0, path_1.join)(subDir, e.name, f));
+                        }
+                    }
+                }
+            }
+            catch { /* ignore */ }
+        }
+    }
+    // 读取并评估每个文档
+    const qualityReports = [];
+    for (const p of docPaths) {
+        try {
+            const content = await (0, fs_extra_2.readFile)(p, 'utf-8');
+            const report = (0, requirement_clarifier_1.assessRequirementQuality)(content, p);
+            qualityReports.push(report);
+        }
+        catch { /* ignore */ }
+    }
+    // 生成质量报告文件
+    if (qualityReports.length > 0) {
+        await (0, requirement_clarifier_1.writeClarifyReport)(iterDir, qualityReports);
+    }
+    // 构建 Clarify Prompt
+    let prompt = `\n# 任务: 需求专业化（Phase 0: 需求澄清）\n\n`;
+    prompt += `## 你的角色\n`;
+    prompt += `你是资深产品经理 + 领域专家。请将迭代 "${iteration}" 的需求文档整理为专业的 PRD 级需求规格说明书。\n\n`;
+    prompt += `## 质量评价摘要\n\n`;
+    for (const r of qualityReports) {
+        const name = r.filePath.split('/').pop() || '-';
+        prompt += `- **${name}**: 评分 ${r.overallScore}/100 (${r.level.toUpperCase()})\n`;
+        for (const dim of r.dimensions) {
+            if (dim.issues.length > 0) {
+                prompt += `  - ${dim.name}: ${dim.score}分 — ${dim.issues.join('、')}\n`;
+            }
+        }
+    }
+    prompt += `\n## 读取需求文档\n\n`;
+    prompt += `依次读取以下文档（按优先级）：\n`;
+    prompt += `1. \`010-requirements/INDEX.md\` — 需求全貌\n`;
+    prompt += `2. \`010-requirements/sources/*.md\` — 原始需求（主要依据）\n`;
+    prompt += `3. \`010-requirements/converted/*.md\` — 已转换文档\n`;
+    prompt += `4. \`010-requirements/features/*/README.md\` — 功能级补充\n`;
+    prompt += `5. \`010-requirements/prototypes/\` — 原型文件\n\n`;
+    prompt += `## 整理要求\n\n`;
+    prompt += `### 必须包含的章节\n`;
+    prompt += `1. **背景与目标**：为什么要做这个功能，解决什么问题\n`;
+    prompt += `2. **用户故事**：作为 [角色]，我希望 [目标]，以便 [价值]\n`;
+    prompt += `3. **功能规格**：功能清单、详细描述、业务规则、异常场景\n`;
+    prompt += `4. **验收标准（AC）**：可测试的、具体的验收条件，每条用 \`[ ]\` 标记\n`;
+    prompt += `5. **非功能需求**：性能、安全、兼容性等（如适用）\n`;
+    prompt += `6. **依赖与约束**：依赖的其他系统/模块\n`;
+    prompt += `7. **功能边界**：明确「做什么」和「不做什么」\n\n`;
+    prompt += `### 质量要求\n`;
+    prompt += `- 为每个功能点分配唯一需求编号（如 R-01, R-02）\n`;
+    prompt += `- 统一术语表述，不要同一概念用不同词汇\n`;
+    prompt += `- 验收标准必须量化（如响应时间<200ms，成功率>99%）\n`;
+    prompt += `- 如果原始描述不完整，标注「待补充」而不是编造\n`;
+    prompt += `- 不要添加文档中未提及的功能\n\n`;
+    prompt += `## 输出格式\n\n`;
+    prompt += `直接输出整理后的 Markdown PRD 文档。\n`;
+    prompt += `文档末尾附加「原始输入」章节。\n\n`;
+    prompt += `## 写入方式\n\n`;
+    prompt += `\`\`\`bash\n`;
+    prompt += `speccore analyze --apply '{"010-requirements/converted/clarified-xxx.md":"..."}' -I ${iteration}\n`;
+    prompt += `\`\`\`\n\n`;
+    prompt += `> 注意：写入 clarified-*.md 后，CLI 会自动推进到需求确认阶段。\n`;
+    return prompt;
+}
+async function buildConfirmCheckPrompt(iteration) {
+    const iterDir = await (0, context_1.getIterationDir)(iteration);
+    const reportPath = (0, path_1.join)(iterDir, '010-requirements', 'CLARIFY_REPORT.md');
+    let prompt = `\n# 任务: 需求确认（Phase 0: 确认检查）\n\n`;
+    if (await (0, fs_extra_1.pathExists)(reportPath)) {
+        const report = await (0, fs_extra_2.readFile)(reportPath, 'utf-8');
+        prompt += `## 需求澄清报告\n\n`;
+        prompt += report.slice(0, 3000); // 截取前 3000 字符
+        if (report.length > 3000) {
+            prompt += `\n\n... (报告共 ${report.length} 字符，已截断)\n`;
+        }
+    }
+    prompt += `\n## 确认要求\n\n`;
+    prompt += `1. 检查 clarified-*.md 是否已写入 \`010-requirements/converted/\`\n`;
+    prompt += `2. 确认验收标准是否可测试、可量化\n`;
+    prompt += `3. 确认功能边界是否明确（不做什么）\n`;
+    prompt += `4. 如有「待补充」项，确认是否已解决\n\n`;
+    prompt += `## 操作\n\n`;
+    prompt += `如果确认无误，直接执行以下命令进入技术方案生成阶段：\n\n`;
+    prompt += `\`\`\`bash\n`;
+    prompt += `speccore analyze --prompt -I ${iteration} --pipeline\n`;
+    prompt += `\`\`\`\n\n`;
+    prompt += `> 当前是 Pipeline 模式，确认后 CLI 会自动推进到 Phase 1。\n`;
+    return prompt;
+}
 //# sourceMappingURL=analyze.js.map