openmatrix 0.2.15 → 0.2.16

package/dist/agents/agent-runner.d.ts

@@ -67,6 +67,10 @@ export declare class AgentRunner {
      * 构建完整的执行提示词
      */
     buildExecutionPrompt(task: Task): Promise<string>;
+    /**
+     * 构建歧义检测指令
+     */
+    private buildAmbiguityDetectionInstruction;
     /**
      * 构建累积上下文 - 从全局 context.md 读取前序 Agent 的决策和知识
      */

package/dist/agents/agent-runner.js

@@ -136,8 +136,11 @@ class AgentRunner {
         const agentPrompt = this.buildAgentPrompt(task);
         const phaseContext = this.buildPhaseContext(task);
         const accumulatedContext = await this.buildAccumulatedContext(task);
+        const ambiguityInstruction = this.buildAmbiguityDetectionInstruction(task);
         return `# 任务执行
 
+${ambiguityInstruction}
+
 ## 任务信息
 - ID: ${task.id}
 - 标题: ${task.title}
@@ -172,6 +175,89 @@ ${agentPrompt.instructions}
 注意: 任务完成后，由 Skill 调用 \`openmatrix complete\` 并传入 --summary 参数，
 该摘要会自动追加到全局 \`.openmatrix/context.md\` 供后续 Agent 参考。
 `;
+    }
+    /**
+     * 构建歧义检测指令
+     */
+    buildAmbiguityDetectionInstruction(task) {
+        return `## 🚨 歧义检测指令（必须在执行前完成）
+
+在开始执行任务之前，你必须完成歧义检测。检测以下 5 种歧义类型：
+
+### 检测清单
+
+1. **需求歧义** (requirement)
+   - 任务描述是否清晰可理解？
+   - 是否有缺少的关键信息？
+   - 验收标准是否明确？
+
+2. **技术歧义** (technical)
+   - 技术选型是否明确？
+   - 实现方案是否有多种选择？
+   - 是否需要特定的技术决策？
+
+3. **依赖歧义** (dependency)
+   - 依赖任务是否已完成？
+   - 依赖代码是否可找到？
+   - 是否有缺失的依赖项？
+
+4. **验收歧义** (acceptance)
+   - 验收标准是否明确？
+   - 成功定义是否清晰？
+   - 是否有模糊的边界条件？
+
+5. **测试结果歧义** (test_result)
+   - 测试失败原因是否明确？
+   - 测试通过是否可信？
+   - 是否需要额外的验证？
+
+### 严重程度定义
+
+| 级别 | 说明 | 处理方式 |
+|-----|------|---------|
+| **Critical** | 无法继续执行，必须澄清 | 立即报告，等待澄清 |
+| **High** | 可能导致错误结果 | 报告并建议处理方案 |
+| **Medium** | 影响执行效率 | 记录并尝试解决 |
+| **Low** | 轻微不确定性 | 继续执行，备注说明 |
+
+### 输出格式
+
+如果检测到歧义，在任务执行前输出：
+\`\`\`xml
+<ambiguity_report>
+{
+  "hasAmbiguity": true,
+  "taskId": "${task.id}",
+  "detectionPhase": "pre_execution",
+  "ambiguities": [
+    {
+      "type": "requirement|technical|dependency|acceptance|test_result",
+      "severity": "Critical|High|Medium|Low",
+      "description": "歧义描述",
+      "suggestedResolution": "建议的处理方案"
+    }
+  ],
+  "maxSeverity": "Critical|High|Medium|Low",
+  "suggestedStrategy": "ask_immediate|write_meeting|continue",
+  "detectedAt": "<ISO timestamp>"
+}
+</ambiguity_report>
+\`\`\`
+
+如果没有歧义，输出：
+\`\`\`xml
+<ambiguity_report>
+{ "hasAmbiguity": false }
+</ambiguity_report>
+\`\`\`
+
+### 处理策略
+
+- **Critical/High**: 输出报告后暂停，等待用户决策
+- **Medium**: 输出报告后继续执行，采用合理假设
+- **Low**: 记录并继续执行
+
+**重要**: 如果无法解析歧义检测结果，视为无歧义继续执行。`;
     }
     /**
      * 构建累积上下文 - 从全局 context.md 读取前序 Agent 的决策和知识

package/dist/orchestrator/executor.d.ts

@@ -4,6 +4,7 @@ import type { SubagentTask } from '../types/index.js';
 import { StateManager } from '../storage/state-manager.js';
 import { ApprovalManager } from './approval-manager.js';
 import { PhaseExecutor } from './phase-executor.js';
+import type { AmbiguityReport } from '../types/index.js';
 export interface ExecutorConfig {
     maxConcurrent: number;
     taskTimeout: number;
@@ -16,7 +17,7 @@ export interface ExecutorStatus {
     waitingApprovals: number;
 }
 export interface ExecutionResult {
-    status: 'continue' | 'waiting_approval' | 'completed' | 'failed';
+    status: 'continue' | 'waiting_approval' | 'completed' | 'failed' | 'ambiguity_ask_user';
     subagentTasks: SubagentTask[];
     message: string;
     statistics: {
@@ -26,6 +27,8 @@ export interface ExecutionResult {
         pending: number;
         failed: number;
     };
+    /** 歧义报告 (仅 status 为 'ambiguity_ask_user' 时存在) */
+    ambiguityReport?: AmbiguityReport;
 }
 /**
  * OrchestratorExecutor - 执行循环核心
@@ -41,6 +44,7 @@ export declare class OrchestratorExecutor {
     private phaseExecutor;
     private retryManager;
     private aiReviewer;
+    private meetingManager;
     private config;
     private taskTimers;
     constructor(stateManager: StateManager, approvalManager: ApprovalManager, config?: Partial<ExecutorConfig>);
@@ -94,7 +98,9 @@ export declare class OrchestratorExecutor {
     /**
      * 标记任务完成
      *
-     * 增强：对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 增强：
+     * 1. 对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 2. 解析歧义报告并根据执行模式处理
      */
     completeTask(taskId: string, result: {
         success: boolean;
@@ -102,6 +108,10 @@ export declare class OrchestratorExecutor {
         error?: string;
     }): Promise<{
         createdFixTasks?: string[];
+        ambiguityResult?: {
+            status: 'ambiguity_ask_user' | 'ambiguity_handled';
+            report: AmbiguityReport;
+        };
     }>;
     /**
      * 处理 Review 结果：解析报告，如有 critical/major 问题则自动创建修复任务
@@ -111,6 +121,26 @@ export declare class OrchestratorExecutor {
      * 获取当前阶段
      */
     private getCurrentPhase;
+    /**
+     * 解析歧义报告
+     *
+     * 从 Agent 输出中提取歧义报告 JSON
+     * 支持多种标记格式：
+     * - <ambiguity_report>...</ambiguity_report>
+     * - AMBIGUITY_REPORT: {...}
+     * - 直接 JSON 块
+     */
+    private parseAmbiguityReport;
+    /**
+     * 处理歧义
+     *
+     * 根据执行模式和严重程度选择处理策略：
+     * - auto 模式：所有歧义写入 Meeting，继续执行
+     * - 其他模式：
+     *   - Critical/High：返回 ambiguity_ask_user 状态，让 Skill 层用 AskUserQuestion 处理
+     *   - Medium/Low：写入 Meeting，继续执行
+     */
+    private handleAmbiguity;
     /**
      * 获取执行器状态
      */

package/dist/orchestrator/executor.js

@@ -8,6 +8,7 @@ const state_machine_js_1 = require("./state-machine.js");
 const phase_executor_js_1 = require("./phase-executor.js");
 const retry_manager_js_1 = require("./retry-manager.js");
 const ai_reviewer_js_1 = require("./ai-reviewer.js");
+const meeting_manager_js_1 = require("./meeting-manager.js");
 const logger_js_1 = require("../utils/logger.js");
 /**
  * OrchestratorExecutor - 执行循环核心
@@ -23,11 +24,13 @@ class OrchestratorExecutor {
     phaseExecutor;
     retryManager;
     aiReviewer;
+    meetingManager;
     config;
     taskTimers = new Map();
     constructor(stateManager, approvalManager, config) {
         this.stateManager = stateManager;
         this.approvalManager = approvalManager;
+        this.meetingManager = new meeting_manager_js_1.MeetingManager(stateManager, approvalManager);
         // 从 state.config 读取 taskTimeout，如果未定义则使用默认值
         const stateConfig = stateManager.getState().then(s => s.config).catch(() => null);
         const defaultTaskTimeout = 600000; // 10 分钟（毫秒）
@@ -265,13 +268,25 @@ class OrchestratorExecutor {
     /**
      * 标记任务完成
      *
-     * 增强：对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 增强：
+     * 1. 对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 2. 解析歧义报告并根据执行模式处理
      */
     async completeTask(taskId, result) {
         const task = await this.stateManager.getTask(taskId);
         if (!task) {
             throw new Error(`Task ${taskId} not found`);
         }
+        // 检查输出中是否包含歧义报告（仅匹配 XML 标签作为唯一触发标记）
+        if (result.output?.includes('<ambiguity_report>')) {
+            const ambiguityReport = this.parseAmbiguityReport(taskId, result.output);
+            if (ambiguityReport?.hasAmbiguity) {
+                const ambiguityResult = await this.handleAmbiguity(task, ambiguityReport);
+                if (ambiguityResult) {
+                    return { ambiguityResult };
+                }
+            }
+        }
         if (result.success) {
             // 清除超时计时器
             this.clearTaskTimeout(taskId);
@@ -370,6 +385,109 @@ class OrchestratorExecutor {
             return 'verify';
         return 'accept';
     }
+    // ============ Ambiguity Management ============
+    /**
+     * 解析歧义报告
+     *
+     * 从 Agent 输出中提取歧义报告 JSON
+     * 支持多种标记格式：
+     * - <ambiguity_report>...</ambiguity_report>
+     * - AMBIGUITY_REPORT: {...}
+     * - 直接 JSON 块
+     */
+    parseAmbiguityReport(taskId, output) {
+        try {
+            // 尝试提取 XML 标记格式
+            const xmlMatch = output.match(/<ambiguity_report>([\s\S]*?)<\/ambiguity_report>/);
+            if (xmlMatch) {
+                const jsonStr = xmlMatch[1].trim();
+                const report = JSON.parse(jsonStr);
+                return { ...report, taskId };
+            }
+            // 尝试提取 AMBIGUITY_REPORT: 格式
+            const prefixMatch = output.match(/AMBIGUITY_REPORT:\s*([\s\S]*?)(?:\n\n|\n---|$)/);
+            if (prefixMatch) {
+                const jsonStr = prefixMatch[1].trim();
+                const report = JSON.parse(jsonStr);
+                return { ...report, taskId };
+            }
+            // 尝试查找包含 hasAmbiguity 的 JSON 块（平衡括号匹配，作为最后兜底）
+            const hasAmbiguityIdx = output.indexOf('"hasAmbiguity"');
+            if (hasAmbiguityIdx !== -1) {
+                // 向前扫描找到深度为 1 的最外层 {
+                let start = -1;
+                let depth = 0;
+                for (let i = hasAmbiguityIdx; i >= 0; i--) {
+                    if (output[i] === '}')
+                        depth++;
+                    else if (output[i] === '{') {
+                        depth--;
+                        if (depth < 0) {
+                            start = i;
+                            break;
+                        }
+                    }
+                }
+                if (start !== -1) {
+                    let d = 0;
+                    let end = -1;
+                    for (let i = start; i < output.length; i++) {
+                        if (output[i] === '{')
+                            d++;
+                        else if (output[i] === '}') {
+                            d--;
+                            if (d === 0) {
+                                end = i;
+                                break;
+                            }
+                        }
+                    }
+                    if (end !== -1) {
+                        const report = JSON.parse(output.slice(start, end + 1));
+                        return { ...report, taskId };
+                    }
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            console.warn(`⚠️ 解析歧义报告失败: ${taskId}`, error);
+            return null;
+        }
+    }
+    /**
+     * 处理歧义
+     *
+     * 根据执行模式和严重程度选择处理策略：
+     * - auto 模式：所有歧义写入 Meeting，继续执行
+     * - 其他模式：
+     *   - Critical/High：返回 ambiguity_ask_user 状态，让 Skill 层用 AskUserQuestion 处理
+     *   - Medium/Low：写入 Meeting，继续执行
+     */
+    async handleAmbiguity(task, report) {
+        const state = await this.stateManager.getState();
+        const mode = state.config.approvalPoints.length === 0 ? 'auto' : 'interactive';
+        console.log(`🔍 检测到歧义: ${task.id} - 最高严重程度: ${report.maxSeverity || 'unknown'}`);
+        // auto 模式：所有歧义写入 Meeting，继续执行
+        if (mode === 'auto') {
+            await this.meetingManager.createAmbiguityMeeting(task.id, report);
+            console.log(`📝 [auto模式] 歧义已写入 Meeting，继续执行`);
+            return { status: 'ambiguity_handled', report };
+        }
+        // 其他模式：根据严重程度处理
+        const severity = report.maxSeverity;
+        if (severity === 'critical' || severity === 'high') {
+            // Critical/High: 返回特殊状态让 Skill 层用 AskUserQuestion 处理
+            console.log(`⚠️ [interactive模式] Critical/High 歧义，需用户确认`);
+            return { status: 'ambiguity_ask_user', report };
+        }
+        else {
+            // Medium/Low: 写入 Meeting，继续执行
+            await this.meetingManager.createAmbiguityMeeting(task.id, report);
+            console.log(`📝 [interactive模式] Medium/Low 歧义已写入 Meeting，继续执行`);
+            return { status: 'ambiguity_handled', report };
+        }
+    }
     /**
      * 获取执行器状态
      */

package/dist/orchestrator/meeting-manager.d.ts

@@ -1,6 +1,6 @@
 import { StateManager } from '../storage/state-manager.js';
 import { ApprovalManager } from './approval-manager.js';
-import type { Approval, Meeting } from '../types/index.js';
+import type { Approval, Meeting, AmbiguityReport } from '../types/index.js';
 /**
  * MeetingManager - Meeting 管理器
  *
@@ -28,6 +28,21 @@ export declare class MeetingManager {
         meeting: Meeting;
         approval: Approval;
     }>;
+    /**
+     * 获取严重程度对应的图标和标题前缀
+     */
+    private getSeverityPrefix;
+    /**
+     * 格式化歧义报告为 Markdown 描述
+     */
+    private formatAmbiguityReport;
+    /**
+     * 创建歧义 Meeting
+     */
+    createAmbiguityMeeting(taskId: string, ambiguityReport: AmbiguityReport): Promise<{
+        meeting: Meeting;
+        approval: Approval;
+    }>;
     /**
      * 开始 Meeting
      */

package/dist/orchestrator/meeting-manager.js

@@ -104,6 +104,119 @@ ${options.map((opt, i) => `${i + 1}. ${opt}`).join('\n')}
         });
         return { meeting, approval };
     }
+    /**
+     * 获取严重程度对应的图标和标题前缀
+     */
+    getSeverityPrefix(severity) {
+        const prefixes = {
+            critical: '🔴 Critical',
+            high: '🟠 High',
+            medium: '🟡 Medium',
+            low: '🟢 Low'
+        };
+        return prefixes[severity];
+    }
+    /**
+     * 格式化歧义报告为 Markdown 描述
+     */
+    formatAmbiguityReport(report) {
+        const lines = [];
+        lines.push('## 歧义检测结果');
+        lines.push('');
+        lines.push(`**检测阶段**: ${report.detectionPhase === 'pre_execution' ? '执行前' : '执行中'}`);
+        lines.push(`**检测时间**: ${report.detectedAt}`);
+        lines.push(`**歧义数量**: ${report.ambiguities.length}`);
+        if (report.maxSeverity) {
+            lines.push(`**最高严重程度**: ${this.getSeverityPrefix(report.maxSeverity)}`);
+        }
+        lines.push('');
+        lines.push('## 歧义详情');
+        lines.push('');
+        for (const ambiguity of report.ambiguities) {
+            const severityIcon = this.getSeverityPrefix(ambiguity.severity);
+            lines.push(`### ${severityIcon} ${ambiguity.type}`);
+            lines.push('');
+            lines.push(`**描述**: ${ambiguity.description}`);
+            lines.push('');
+            if (ambiguity.impactScope.length > 0) {
+                lines.push('**影响范围**:');
+                for (const scope of ambiguity.impactScope) {
+                    lines.push(`- ${scope}`);
+                }
+                lines.push('');
+            }
+            if (ambiguity.possibleSolutions && ambiguity.possibleSolutions.length > 0) {
+                lines.push('**可能的解决方案**:');
+                for (let i = 0; i < ambiguity.possibleSolutions.length; i++) {
+                    lines.push(`${i + 1}. ${ambiguity.possibleSolutions[i]}`);
+                }
+                lines.push('');
+            }
+            if (ambiguity.relatedFiles && ambiguity.relatedFiles.length > 0) {
+                lines.push(`**相关文件**: ${ambiguity.relatedFiles.join(', ')}`);
+                lines.push('');
+            }
+            if (ambiguity.relatedTaskIds && ambiguity.relatedTaskIds.length > 0) {
+                lines.push(`**相关任务**: ${ambiguity.relatedTaskIds.join(', ')}`);
+                lines.push('');
+            }
+        }
+        if (report.suggestedStrategy) {
+            lines.push('## 建议处理策略');
+            lines.push('');
+            const strategyMap = {
+                ask_immediate: '立即提问 (ask_immediate)',
+                write_meeting: '写入 Meeting (write_meeting)',
+                continue: '继续执行 (continue)'
+            };
+            lines.push(strategyMap[report.suggestedStrategy] || report.suggestedStrategy);
+            lines.push('');
+        }
+        if (report.suggestedQuestions && report.suggestedQuestions.length > 0) {
+            lines.push('## 建议的问题');
+            lines.push('');
+            for (let i = 0; i < report.suggestedQuestions.length; i++) {
+                lines.push(`${i + 1}. ${report.suggestedQuestions[i]}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * 创建歧义 Meeting
+     */
+    async createAmbiguityMeeting(taskId, ambiguityReport) {
+        const meetingId = `meeting-${Date.now().toString(36)}`;
+        const now = new Date().toISOString();
+        // 根据最高严重程度生成标题
+        const severity = ambiguityReport.maxSeverity || 'medium';
+        const severityPrefix = this.getSeverityPrefix(severity);
+        const titleSummary = ambiguityReport.ambiguities[0]?.description.slice(0, 50) || '歧义检测';
+        const meeting = {
+            id: meetingId,
+            type: 'ambiguity',
+            status: 'pending',
+            taskId,
+            title: `${severityPrefix}: ${titleSummary}...`,
+            description: `任务 ${taskId} 检测到歧义，需要用户确认处理方式`,
+            impactScope: ambiguityReport.ambiguities.flatMap(a => a.impactScope),
+            participants: ['user'],
+            createdAt: now,
+            ambiguityReport,
+            suggestedQuestions: ambiguityReport.suggestedQuestions
+        };
+        // 保存 Meeting
+        await this.stateManager.saveMeeting(meeting);
+        // 创建审批
+        const approval = await this.approvalManager.createApproval({
+            type: 'meeting',
+            taskId,
+            title: meeting.title,
+            description: this.formatAmbiguityReport(ambiguityReport),
+            content: JSON.stringify({ meetingId, ambiguityReport })
+        });
+        return { meeting, approval };
+    }
     /**
      * 开始 Meeting
      */

package/dist/types/index.d.ts

@@ -204,7 +204,7 @@ export interface ApprovalOption {
     label: string;
 }
 export type MeetingStatus = 'pending' | 'in_progress' | 'resolved' | 'cancelled';
-export type MeetingType = 'blocking' | 'decision' | 'review' | 'planning';
+export type MeetingType = 'blocking' | 'decision' | 'review' | 'planning' | 'ambiguity';
 export interface Meeting {
     id: string;
     type: MeetingType;
@@ -219,6 +219,10 @@ export interface Meeting {
     createdAt: string;
     startedAt?: string;
     resolvedAt?: string;
+    /** 歧义报告 (仅 type 为 'ambiguity' 时使用) */
+    ambiguityReport?: AmbiguityReport;
+    /** 建议的问题列表 (用于歧义处理) */
+    suggestedQuestions?: string[];
 }
 export interface ParsedTask {
     title: string;
@@ -311,3 +315,64 @@ export interface DebugSession {
     updatedAt: string;
     completedAt?: string;
 }
+/**
+ * 歧义类型
+ * - requirement: 需求歧义 (需求描述不清晰、存在多种解读)
+ * - technical: 技术歧义 (技术方案选择、实现方式不明确)
+ * - dependency: 依赖歧义 (依赖项版本、接口契约不明确)
+ * - acceptance: 验收歧义 (验收标准不清晰、无法验证)
+ * - test_result: 测试结果歧义 (测试结果不一致、无法判断)
+ */
+export type AmbiguityType = 'requirement' | 'technical' | 'dependency' | 'acceptance' | 'test_result';
+/**
+ * 歧义严重程度
+ * - critical: 严重歧义，必须立即解决，否则任务无法继续
+ * - high: 高优先级歧义，影响核心功能，应尽快解决
+ * - medium: 中等优先级歧义，影响非核心功能，可稍后解决
+ * - low: 低优先级歧义，影响较小，可在后续处理
+ */
+export type AmbiguitySeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * 歧义项 - 描述单个歧义点
+ */
+export interface AmbiguityItem {
+    /** 歧义唯一标识 */
+    id: string;
+    /** 歧义类型 */
+    type: AmbiguityType;
+    /** 严重程度 */
+    severity: AmbiguitySeverity;
+    /** 歧义描述 */
+    description: string;
+    /** 影响范围 */
+    impactScope: string[];
+    /** 可能的解决方案 */
+    possibleSolutions?: string[];
+    /** 相关文件 */
+    relatedFiles?: string[];
+    /** 相关任务 ID */
+    relatedTaskIds?: string[];
+}
+/**
+ * 歧义报告 - Agent 输出的歧义检测结果
+ */
+export interface AmbiguityReport {
+    /** 报告唯一标识 */
+    id: string;
+    /** 关联的任务 ID */
+    taskId: string;
+    /** 检测阶段: 'pre_execution' 执行前 | 'during_execution' 执行中 */
+    detectionPhase: 'pre_execution' | 'during_execution';
+    /** 检测到的歧义列表 */
+    ambiguities: AmbiguityItem[];
+    /** 是否存在歧义 */
+    hasAmbiguity: boolean;
+    /** 最高严重程度 (用于快速判断) */
+    maxSeverity?: AmbiguitySeverity;
+    /** 检测时间 */
+    detectedAt: string;
+    /** 建议的处理策略 */
+    suggestedStrategy?: 'ask_immediate' | 'write_meeting' | 'continue';
+    /** 建议的问题列表 (用于 AskUserQuestion) */
+    suggestedQuestions?: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmatrix",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "AI Agent task orchestration system with Claude Code Skills integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.58.1",
     "@typescript-eslint/parser": "^8.58.1",
+    "@vitest/coverage-v8": "^1.6.1",
     "eslint": "^10.2.0",
     "vitest": "^1.6.0"
   },

package/skills/auto.md

@@ -154,7 +154,7 @@ openmatrix complete TASK-XXX --success       # 标记完成 + 更新统计（含
 # 提交验证（防止 commit 静默失败）:
 git status --porcelain                        # 检查是否有未提交的文件
 # 如果有未提交文件 → 必须手动提交:
-git add -A && git commit -m "feat(TASK-XXX): 任务标题"
+git add . && git commit -m "feat(TASK-XXX): 任务标题"
 
 openmatrix step --json                       # 获取下一个任务 + 检查是否全部完成
 ```
@@ -167,7 +167,68 @@ openmatrix step --json                       # 获取下一个任务 + 检查是
 4. 如果返回 `status: "blocked"` → 有阻塞任务需要处理
 </LOOP-ENFORCEMENT>
 
-对 `subagentTasks` 列表中的每个任务，**必须使用 Agent 工具**（禁止用 gsd-executor 或其他技能替代）:
+#### 6.1 歧义检测机制（全自动模式）
+
+**Agent 输出中可能包含歧义报告（JSON 格式）:**
+
+当 Agent 输出包含以下标记时，表示检测到歧义：
+```
+<AMBIGUITY_REPORT>
+{
+  "ambiguities": [
+    {
+      "type": "missing_info" | "conflicting_req" | "unclear_scope" | "tech_choice" | "edge_case",
+      "severity": "critical" | "high" | "medium" | "low",
+      "description": "歧义描述",
+      "suggestions": ["建议1", "建议2"]
+    }
+  ],
+  "overallSeverity": "critical" | "high" | "medium" | "low"
+}
+</AMBIGUITY_REPORT>
+```
+
+**5 种歧义类型说明：**
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `missing_info` | 缺失关键信息 | "未指定数据库类型" |
+| `conflicting_req` | 需求冲突 | "既要高性能又要低成本" |
+| `unclear_scope` | 范围不清晰 | "是否包含历史数据处理？" |
+| `tech_choice` | 技术选型歧义 | "用 REST 还是 GraphQL？" |
+| `edge_case` | 边界情况未定义 | "超过限制时如何处理？" |
+
+#### 6.2 歧义处理策略（全自动模式）
+
+**在 `/om:auto` 全自动模式下，所有歧义都写入 Meeting 继续执行，不中断流程：**
+
+| 严重程度 | 处理方式 |
+|---------|---------|
+| **Critical** | Meeting + 继续执行其他任务 |
+| **High** | Meeting + 继续执行其他任务 |
+| **Medium** | Meeting + 继续执行其他任务 |
+| **Low** | Meeting + 继续执行其他任务 |
+
+**全自动模式特点：**
+- ❌ **不使用 AskUserQuestion** — 全自动执行，零人工干预
+- ✅ **所有歧义写入 Meeting** — 执行完成后统一展示
+- ✅ **继续执行其他任务** — 最大化并行度，无阻塞等待
+
+**Meeting 处理流程：**
+```bash
+# 检测到歧义时，写入 Meeting 记录并继续执行
+openmatrix meeting --create --task TASK-XXX --reason "歧义: ${description}" --severity ${overallSeverity}
+
+# 继续执行下一个任务
+openmatrix step --json
+```
+
+**执行完成后提示用户：**
+```
+⚠️ 检测到 N 个歧义记录，请使用 `/om:meeting` 统一处理
+```
+
+#### 6.3 执行 Agent 任务
 
 ```typescript
 Agent({
@@ -246,7 +307,7 @@ openmatrix step --json
 Agent-1 完成 → 写入 context.md → Agent-2 读取 Agent-1 的上下文 → 写入 context.md → ...
 ```
 ```bash
-git add -A && git commit -m "$(cat <<'EOF'
+git add . && git commit -m "$(cat <<'EOF'
 feat: 任务标题
 
 改动点1

package/skills/debug.md

@@ -440,7 +440,7 @@ ${lessons}
 ```bash
 git status --porcelain
 # 如果有未提交文件：
-git add -A && git commit -m "$(cat <<'EOF'
+git add . && git commit -m "$(cat <<'EOF'
 fix: 修复 bug - 问题描述
 
 根因: ...

package/skills/feature.md

@@ -20,6 +20,7 @@ priority: high
 ## 执行顺序 - 必须严格按此顺序，不得跳过
 
 ```
+Step 0:  Git 前置检查与持久化初始化（必须执行）
 Step 1:  接收任务输入（参数、文件、或询问用户）
 Step 2:  AI 自动判断任务边界（不符合条件才询问切换）
 Step 3:  收集项目上下文（技术栈、目录结构、CLAUDE.md）
@@ -45,6 +46,39 @@ Step 11: 输出执行摘要并清理
 
 <process>
 
+## Step 0: Git 前置检查与持久化初始化（必须执行）
+
+**检查 Git 仓库:**
+
+```bash
+ls -la .git 2>/dev/null || echo "NOT_INITIALIZED"
+git status --porcelain
+```
+
+| 检查结果 | 处理 |
+|---------|------|
+| `NOT_INITIALIZED` | AskUserQuestion 是否初始化 git |
+| 有未提交文件 | AskUserQuestion 处理方式（暂存/忽略/取消） |
+| 干净 | 继续执行 |
+
+**初始化持久化状态:**
+
+```bash
+mkdir -p .openmatrix
+cat > .openmatrix/feature-session.json << 'EOF'
+{
+  "sessionId": "FEATURE-$(date +%Y%m%d%H%M%S)",
+  "status": "running",
+  "tasks": [],
+  "currentTaskIndex": 0,
+  "quality": null,
+  "failureCount": {}
+}
+EOF
+echo '' > .openmatrix/feature-context.md
+echo '' > .openmatrix/feature-progress.md
+```
+
 ## Step 1: 接收任务输入
 
 **检查 `$ARGUMENTS`:**
@@ -96,35 +130,33 @@ AskUserQuestion: `header: "任务复杂度"`, `multiSelect: false`
 | 切换到 /om:start | 使用完整流程 |
 | 继续用 /om:feature | 强制使用轻量流程（可能无法完整追踪） |
 
-## Step 3: 收集项目上下文
+## Step 3: 收集项目上下文并写入文件
 
-**在拆分任务前，收集必要的项目上下文信息，存入 `${projectContext}` 变量供后续步骤使用。**
+**收集并写入上下文文件:**
 
 ```bash
-# 收集技术栈（从 package.json 提取关键依赖）
-cat package.json | grep -E '"(react|vue|angular|next|express|fastify|koa|typeorm|prisma|sequelize|mongoose|jest|vitest|playwright|cypress)"' || echo "未检测到常见框架"
+mkdir -p .openmatrix
 
-# 收集项目目录结构（仅顶层，避免输出过长）
-find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.openmatrix/*' | head -30
+# 写入上下文文件头
+echo "# 项目上下文" > .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
-# 读取 CLAUDE.md 项目规范（如果存在）
-cat CLAUDE.md 2>/dev/null | head -50 || echo "无 CLAUDE.md"
-```
+# 收集技术栈并写入文件
+echo "## 技术栈" >> .openmatrix/feature-context.md
+cat package.json 2>/dev/null | grep -E '"(react|vue|angular|next|express|fastify|koa|typeorm|prisma|sequelize|mongoose|jest|vitest|playwright|cypress)"' >> .openmatrix/feature-context.md || echo "未检测到常见框架" >> .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
-**将收集结果存入 `${projectContext}`：**
+# 收集目录结构并写入文件
+echo "## 目录结构" >> .openmatrix/feature-context.md
+find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.openmatrix/*' 2>/dev/null | head -30 >> .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
+# 读取 CLAUDE.md 并写入文件
+echo "## 项目规范（来自 CLAUDE.md）" >> .openmatrix/feature-context.md
+cat CLAUDE.md 2>/dev/null | head -50 >> .openmatrix/feature-context.md || echo "无 CLAUDE.md" >> .openmatrix/feature-context.md
 ```
-## 项目上下文
 
-### 技术栈
-${从 package.json 提取的关键依赖}
-
-### 目录结构
-${顶层目录结构}
-
-### 项目规范（来自 CLAUDE.md）
-${CLAUDE.md 前 50 行，包含构建/测试命令、架构概述、开发约定}
-```
+上下文已写入 `.openmatrix/feature-context.md`，后续 Agent 会读取此文件。
 
 ## Step 4: AI 拆分为 2-5 个小任务块
 
@@ -191,7 +223,7 @@ TodoWrite({
 })
 ```
 
-状态仅在当前会话有效，不产生持久化文件。
+状态同时在会话和 `.openmatrix/feature-session.json` 中管理。
 
 ## Step 6: 问答确认
 
@@ -241,7 +273,56 @@ AskUserQuestion: `header: "确认计划"`, `multiSelect: false`
 TodoWrite({ todos: [...] }) // 当前任务标记 in_progress
 ```
 
-**7.2 调用 Agent 执行**
+**7.2 歧义检测与处理**
+
+Agent 输出中可能包含歧义报告：
+
+当 Agent 输出包含以下标记时，表示检测到歧义：
+```
+<AMBIGUITY_REPORT>
+{
+  "ambiguities": [
+    {
+      "type": "missing_info" | "conflicting_req" | "unclear_scope" | "tech_choice" | "edge_case",
+      "severity": "critical" | "high" | "medium" | "low",
+      "description": "歧义描述",
+      "suggestions": ["建议1", "建议2"]
+    }
+  ],
+  "overallSeverity": "critical" | "high" | "medium" | "low"
+}
+</AMBIGUITY_REPORT>
+```
+
+**5 种歧义类型说明：**
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `missing_info` | 缺失关键信息 | "未指定数据库类型" |
+| `conflicting_req` | 需求冲突 | "既要高性能又要低成本" |
+| `unclear_scope` | 范围不清晰 | "是否包含历史数据处理？" |
+| `tech_choice` | 技术选型歧义 | "用 REST 还是 GraphQL？" |
+| `edge_case` | 边界情况未定义 | "超过限制时如何处理？" |
+
+**歧义处理策略（轻量模式）：**
+
+| 严重程度 | 处理方式 |
+|---------|---------|
+| **Critical/High** | AskUserQuestion 立即确认 |
+| **Medium/Low** | 写入进度文件，继续执行 |
+
+**AskUserQuestion 处理（仅 Critical/High）：**
+
+AskUserQuestion: `header: "歧义确认"`, `multiSelect: false`
+**question:** 检测到 ${severity} 级歧义：${description}。请确认处理方式
+
+| label | description |
+|-------|-------------|
+| 提供信息 | 回答歧义相关问题，继续执行 |
+| 跳过任务块 | 标记当前任务块为可选，继续执行下一个 |
+| 修改方案 | 根据歧义调整方案后继续 |
+
+**7.3 调用 Agent 执行**
 
 ```typescript
 Agent({
@@ -249,6 +330,12 @@ Agent({
   description: task.content,
   prompt: `你是实现专家。执行以下任务块。
 
+## 项目上下文（请读取文件）
+请先读取 .openmatrix/feature-context.md 了解项目上下文。
+
+## 前序任务结果（请读取文件）
+请读取 .openmatrix/feature-progress.md 了解前序 Agent 的决策和发现。
+
 ## 整体任务
 ${taskDescription}
 
@@ -258,11 +345,6 @@ ${taskDescription}
 - 质量等级：${quality}
 - 前置任务完成状态：${previousTasksStatus}
 
-${projectContext}
-
-${agentMemory ? `## 前序任务结果（跨 Agent 上下文）
-${agentMemory}` : ''}
-
 ## 质量要求
 ${quality === 'strict' ? `
 - 必须使用 TDD：先写测试，再写实现
@@ -307,17 +389,19 @@ ${quality === 'strict' ? `
 })
 ```
 
-**7.3 等待 Agent 完成，收集上下文**
+**7.3 等待 Agent 完成，写入进度文件**
 
-Agent 完成后，将输出中的关键决策和建议追加到 `${agentMemory}` 变量中：
-```
-${agentMemory}
----
-## 任务 N: ${task.content}
-${agentOutput}
+Agent 完成后，将输出中的关键决策和建议写入 `.openmatrix/feature-progress.md` 文件：
+
+```bash
+# Agent 完成后，追加写入进度文件
+echo "" >> .openmatrix/feature-progress.md
+echo "## 任务 N: ${task.content}" >> .openmatrix/feature-progress.md
+echo "${agentOutput}" >> .openmatrix/feature-progress.md
+echo "" >> .openmatrix/feature-progress.md
 ```
 
-这样后续 Agent 能获取前序 Agent 的决策和发现。
+这样后续 Agent 能通过读取文件获取前序 Agent 的决策和发现。
 
 ## Step 8: 验证（按质量等级）
 
@@ -329,10 +413,14 @@ ${agentOutput}
 
 | 质量等级 | 验证命令 |
 |---------|---------|
-| `strict` | `npm test -- --run && npm run lint && npm run test:coverage` |
-| `balanced` | `npm test -- --run && npm run lint` |
+| `strict` | `npm test -- --run && npm run lint && npm run test:coverage && npm audit --audit-level=moderate` |
+| `balanced` | `npm test -- --run && npm run lint && npm audit --audit-level=moderate` |
 | `fast` | 跳过验证 |
 
+**覆盖率阈值检查说明：**
+- strict 模式要求 >80% 覆盖率，`npm run test:coverage` 命令应输出覆盖率报告
+- balanced 模式要求 >60% 覆盖率，建议定期检查覆盖率报告
+
 **8.2 E2E 验证（如果用户选择）**
 - 功能测试：`npm run test:e2e`
 - 视觉验证：启动 Playwright 截图对比
@@ -357,7 +445,7 @@ fi
 **验证失败处理：**
 - 自动展示验证失败详情（最后 30 行输出）
 - 停止执行流程
-- 提示用户修复后使用 `/om:resume` 继续
+- 提示用户修复后使用 `/om:resume-feature` 继续
 
 **验证成功处理：**
 - 继续执行 Step 9 Git 提交
@@ -366,8 +454,14 @@ fi
 
 **⛔ 验证通过后必须立即提交，不得积累多个任务块**
 
+**只提交本次任务修改的文件（而非 `git add -A`）：**
+
 ```bash
-git add -A
+# 获取本次任务修改的文件列表（从 Agent 输出中提取）
+git status --porcelain
+
+# 只提交任务涉及的文件
+git add ${modifiedFiles}
 git commit -m "$(cat <<'EOF'
 feat(feature): ${originalTask} - ${currentChunk}
 
@@ -420,8 +514,8 @@ ${decisions}
 
 **清理操作：**
 - TodoWrite 所有任务保持 completed 状态
-- 不产生任何 `.openmatrix/` 持久化文件
-- 会话结束后状态自动消失
+- 持久化文件可选择保留或手动清理
+- 任务完成后状态标记为 `completed`
 
 </process>
 
@@ -474,12 +568,12 @@ $ARGUMENTS
 
 ## 与其他指令的区别
 
-| 指令 | 适用场景 | 任务文件 | 问答 | 验证 |
-|-----|---------|:-------:|:----:|:----:|
-| `/om:feature` | 小需求（≤100字，单一功能） | ❌ | 质量+E2E | 按等级 |
-| `/om:start` | 标准任务 | ✅ | 质量+E2E+模式 | 按等级 |
-| `/om:brainstorm` | 复杂任务 | ✅ | 设计问答 | 按等级 |
-| `/om:auto` | 全自动执行 | ✅ | 无 | 按等级 |
+| 指令 | 适用场景 | 任务文件 | 问答 | 验证 | 持久化 |
+|-----|---------|:-------:|:----:|:----:|:-----:|
+| `/om:feature` | 小需求（≤100字，单一功能） | ❌ | 质量+E2E | 按等级 | 必须 |
+| `/om:start` | 标准任务 | ✅ | 质量+E2E+模式 | 按等级 | 必须 |
+| `/om:brainstorm` | 复杂任务 | ✅ | 设计问答 | 按等级 | 必须 |
+| `/om:auto` | 全自动执行 | ✅ | 无 | 按等级 | 必须 |
 
 ## 路由触发条件
 
@@ -492,13 +586,14 @@ $ARGUMENTS
 ## 错误处理流程
 
 ```
-验证失败 → 停止执行 → 展示错误详情 → 提示用户修复 → 建议使用 /om:resume 继续
+验证失败 → 停止执行 → 展示错误详情 → 提示用户修复 → 使用 /om:resume-feature 恢复
 ```
 
 | 错误 | 处理 |
 |-----|-----|
 | 测试失败 | 停止，提示用户修复 |
 | Lint 错误 | 停止，提示用户修复 |
+| 安全扫描失败 | 停止，提示用户修复 |
 | Agent 超时 | 询问重试或跳过 |
 | Git 失败 | 提示手动处理 |
 
@@ -534,8 +629,14 @@ type: feat/fix/test/refactor/docs
 
 ## 恢复执行
 
-如果验证失败需要修复，使用 `/om:resume` 继续执行：
-```bash
-/om:resume
-```
+如果验证失败需要修复：
+
+使用 `/om:resume-feature` 继续执行（读取 `.openmatrix/feature-session.json`）
+
+## 挡久化文件说明
+
+执行过程中产生以下文件：
+- `.openmatrix/feature-session.json` - 会话状态（任务列表、当前索引、质量等级）
+- `.openmatrix/feature-context.md` - 项目上下文
+- `.openmatrix/feature-progress.md` - Agent 执行进度
 </notes>

package/skills/resume-feature.md

@@ -0,0 +1,227 @@
+---
+name: om:resume-feature
+description: "恢复中断的 /om:feature 流程。读取 .openmatrix/feature-session.json 状态文件，继续执行剩余任务。"
+priority: high
+---
+
+<NO-OTHER-SKILLS>
+**绝对禁止**调用以下技能：
+- ❌ superpowers:brainstorming → 用 /om:brainstorm 代替
+- ❌ superpowers:* → 全部被 OpenMatrix 替代
+- ❌ gsd:* → 全部被 OpenMatrix 替代
+- ❌ /om:start / /om:auto → 本 skill 是轻量恢复，不调用完整流程
+</NO-OTHER-SKILLS>
+
+<objective>
+恢复中断的轻量级小需求开发流程：读取持久化状态，继续执行剩余任务块。
+</objective>
+
+<process>
+
+## Step 1: 检查持久化文件是否存在
+
+```bash
+ls -la .openmatrix/feature-session.json 2>/dev/null || echo "NOT_FOUND"
+```
+
+| 检查结果 | 处理 |
+|---------|------|
+| `NOT_FOUND` | 提示"未找到持久化文件，请使用 /om:feature 重新开始"并退出 |
+| 存在 | 继续执行 |
+
+## Step 2: 读取会话状态
+
+```bash
+cat .openmatrix/feature-session.json
+```
+
+读取并解析以下信息：
+- `sessionId` - 会话 ID
+- `status` - 当前状态（running/paused/failed）
+- `tasks` - 任务列表
+- `currentTaskIndex` - 当前任务索引
+- `quality` - 质量等级
+- `failureCount` - 各任务失败次数统计
+
+同时读取：
+- `.openmatrix/feature-context.md` - 项目上下文
+- `.openmatrix/feature-progress.md` - Agent 执行进度
+
+## Step 3: 恢复 TodoWrite 状态
+
+根据读取的任务列表，恢复 TodoWrite 状态：
+
+```typescript
+TodoWrite({
+  todos: tasks.map((task, index) => ({
+    activeForm: `正在执行 ${task.content}`,
+    content: task.content,
+    status: index < currentTaskIndex ? "completed" : 
+            index === currentTaskIndex ? "in_progress" : "pending"
+  }))
+})
+```
+
+## Step 4: 展示恢复状态
+
+```
+🔄 恢复会话：${sessionId}
+
+📊 当前状态：
+- 质量等级：${quality}
+- 已完成任务：${completedCount}/${totalCount}
+- 当前任务：${currentTask.content}
+- 失败次数：${failureCount[currentTaskIndex] || 0}
+
+📝 已完成的决策（来自 feature-progress.md）：
+${显示前序任务的关键决策}
+```
+
+## Step 5: 继续执行当前任务
+
+从 `currentTaskIndex` 位置继续执行：
+
+**5.1 如果当前任务是 in_progress 状态（之前失败）：**
+
+询问用户：
+AskUserQuestion: `header: "继续方式"`, `multiSelect: false`
+**question:** 当前任务之前验证失败，如何继续？
+
+| label | description |
+|-------|-------------|
+| `重试当前任务` | 重新执行当前任务块 |
+| `跳过当前任务` | 标记为完成，继续下一任务（风险较高） |
+| `重新拆分` | 返回 /om:feature 重新规划 |
+
+**5.2 如果当前任务是 pending 状态（正常恢复）：**
+
+直接调用 Agent 执行：
+
+```typescript
+Agent({
+  subagent_type: "general-purpose",
+  description: currentTask.content,
+  prompt: `你是实现专家。执行以下任务块。
+
+## 项目上下文（请读取文件）
+请先读取 .openmatrix/feature-context.md 了解项目上下文。
+
+## 前序任务结果（请读取文件）
+请读取 .openmatrix/feature-progress.md 了解前序 Agent 的决策和发现。
+
+## 当前任务
+- 任务名称：${currentTask.content}
+- 预估文件：${currentTask.files}
+- 质量等级：${quality}
+
+## 质量要求
+${quality === 'strict' ? `
+- 必须使用 TDD：先写测试，再写实现
+- 测试覆盖率要求：>80%
+- 必须通过严格 Lint
+- 必须通过安全扫描
+` : quality === 'balanced' ? `
+- 测试覆盖率要求：>60%
+- 必须通过 Lint
+- 必须通过安全扫描
+` : `
+- 无质量门禁要求
+`}
+
+## 实施原则
+1. 先阅读预估文件中的现有代码，理解上下文后再动手
+2. 只修改当前任务相关的文件
+3. 不做"顺便"的重构或优化
+
+## 禁止行为
+❌ 执行 git commit（由主流程处理）
+❌ 执行 git checkout/merge/pull/push/rebase/branch
+❌ 修改与当前任务无关的文件
+
+✅ 允许：git status, git diff, git log`,
+  run_in_background: true
+})
+```
+
+## Step 6: 验证（按质量等级）
+
+| 质量等级 | 验证命令 |
+|---------|---------|
+| `strict` | `npm test -- --run && npm run lint && npm run test:coverage && npm audit --audit-level=moderate` |
+| `balanced` | `npm test -- --run && npm run lint && npm audit --audit-level=moderate` |
+| `fast` | 跳过验证 |
+
+验证失败处理：
+- 更新 `.openmatrix/feature-session.json` 的 `failureCount`
+- 如果同一任务失败 3 次，提示用户质疑拆分方案
+- 停止执行，提示再次使用 `/om:resume-feature`
+
+## Step 7: Git 提交
+
+验证通过后：
+
+```bash
+git status --porcelain
+git add ${modifiedFiles}
+git commit -m "feat(feature): ${sessionId} - ${currentTask.content}"
+```
+
+## Step 8: 更新持久化状态
+
+```bash
+# 更新 currentTaskIndex
+cat > .openmatrix/feature-session.json << EOF
+{
+  "sessionId": "${sessionId}",
+  "status": "running",
+  "tasks": ${tasks},
+  "currentTaskIndex": ${currentTaskIndex + 1},
+  "quality": "${quality}",
+  "failureCount": ${failureCount}
+}
+EOF
+
+# 更新进度文件
+echo "## 任务 ${currentTaskIndex}: ${currentTask.content}" >> .openmatrix/feature-progress.md
+echo "${agentOutput}" >> .openmatrix/feature-progress.md
+```
+
+## Step 9: 继续下一任务或完成
+
+- 如果还有 pending 任务：回到 Step 5
+- 如果所有任务完成：执行 Step 10
+
+## Step 10: 全部任务完成
+
+```bash
+# 最终整体验证
+npm test -- --run
+
+# 清理持久化文件（可选）
+# 用户可选择保留或删除
+```
+
+输出执行摘要并更新状态为 `completed`。
+
+</process>
+
+<notes>
+## 恢复条件
+
+- 必须存在 `.openmatrix/feature-session.json`
+- 必须由 `/om:feature` 启用持久化后产生
+
+## 失败次数限制
+
+同一任务失败 3 次以上：
+- 建议用户质疑拆分方案
+- 提示可能需要切换到 `/om:start`
+
+## 持久化文件说明
+
+| 文件 | 内容 |
+|-----|------|
+| `feature-session.json` | 会话状态、任务列表、当前索引、质量等级、失败次数 |
+| `feature-context.md` | 项目上下文（技术栈、目录结构、CLAUDE.md） |
+| `feature-progress.md` | 各 Agent 的执行决策和发现 |
+</notes>

package/skills/start.md

@@ -382,14 +382,77 @@ openmatrix complete TASK-XXX --success --summary "决策: xxx; 文件: xxx"
 # 提交验证（防止 commit 静默失败）:
 git status --porcelain                        # 检查是否有未提交的文件
 # 如果有未提交文件 → 必须手动提交:
-git add -A && git commit -m "feat(TASK-XXX): 任务标题"
+git add . && git commit -m "feat(TASK-XXX): 任务标题"
 
 openmatrix step --json                       # 获取下一个任务 + 检查是否全部完成
 ```
 `openmatrix step` 会从磁盘读取真实状态，不依赖上下文记忆。
 </LOOP-ENFORCEMENT>
 
-对每个任务**必须使用 Agent 工具**（禁止用 gsd-executor 或其他技能替代）:
+#### 11.1 歧义检测机制
+
+**Agent 输出中可能包含歧义报告（JSON 格式）:**
+
+当 Agent 输出包含以下标记时，表示检测到歧义：
+```
+<AMBIGUITY_REPORT>
+{
+  "ambiguities": [
+    {
+      "type": "missing_info" | "conflicting_req" | "unclear_scope" | "tech_choice" | "edge_case",
+      "severity": "critical" | "high" | "medium" | "low",
+      "description": "歧义描述",
+      "suggestions": ["建议1", "建议2"]
+    }
+  ],
+  "overallSeverity": "critical" | "high" | "medium" | "low"
+}
+</AMBIGUITY_REPORT>
+```
+
+**5 种歧义类型说明：**
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `missing_info` | 缺失关键信息 | "未指定数据库类型" |
+| `conflicting_req` | 需求冲突 | "既要高性能又要低成本" |
+| `unclear_scope` | 范围不清晰 | "是否包含历史数据处理？" |
+| `tech_choice` | 技术选型歧义 | "用 REST 还是 GraphQL？" |
+| `edge_case` | 边界情况未定义 | "超过限制时如何处理？" |
+
+#### 11.2 歧义处理策略
+
+根据 `overallSeverity` 和执行模式选择处理方式：
+
+| 执行模式 | Critical/High | Medium/Low |
+|---------|--------------|------------|
+| **全自动执行** | Meeting + 继续执行 | Meeting + 继续执行 |
+| **关键节点确认** | AskUserQuestion | Meeting + 继续执行 |
+| **每阶段确认** | AskUserQuestion | Meeting + 继续执行 |
+
+**Meeting 处理（写入阻塞记录）:**
+```bash
+# 将歧义信息写入 Meeting 记录，继续执行其他任务
+openmatrix meeting --create --task TASK-XXX --reason "歧义: ${description}" --severity ${severity}
+```
+
+**AskUserQuestion 处理（交互确认）:**
+
+AskUserQuestion: `header: "歧义确认"`, `multiSelect: false`
+**question:** 检测到 ${severity} 级歧义：${description}。请确认处理方式
+
+| label | description |
+|-------|-------------|
+| 提供信息 | 回答歧义相关问题，继续执行 |
+| 跳过任务 | 标记当前任务为可选，继续执行其他任务 |
+| 修改方案 | 根据歧义调整任务方案后继续 |
+
+用户选择后：
+- **提供信息** → 将用户输入作为上下文注入，继续执行当前任务
+- **跳过任务** → `openmatrix complete TASK-XXX --skip --reason "用户选择跳过"`
+- **修改方案** → 更新任务方案，重新执行当前任务
+
+#### 11.3 执行 Agent 任务
 
 ```typescript
 Agent({
@@ -538,7 +601,7 @@ openmatrix meeting --list
 
 所有任务完成后，执行最终 Git 提交（**必须使用 HEREDOC 格式**）:
 ```bash
-git add -A && git commit -m "$(cat <<'EOF'
+git add . && git commit -m "$(cat <<'EOF'
 feat: 完成所有任务 - 任务总标题
 
 改动点1