@mycodemap/mycodemap 0.4.2 → 0.5.0

package/docs/ai-guide/OUTPUT.md

@@ -405,6 +405,421 @@ interface StructuredResult {
 
 ---
 
+## design validate 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignContractSectionId =
+  | "goal"
+  | "constraints"
+  | "acceptanceCriteria"
+  | "nonGoals"
+  | "context"
+  | "openQuestions"
+  | "notes";
+
+type DesignContractDiagnosticCode =
+  | "file-not-found"
+  | "missing-section"
+  | "duplicate-section"
+  | "empty-section"
+  | "unknown-section"
+  | "ambiguous-heading";
+
+interface DesignValidateOutput {
+  ok: boolean;
+  exists: boolean;
+  filePath: string;
+  title?: string;
+  missingRequiredSections: Array<"goal" | "constraints" | "acceptanceCriteria" | "nonGoals">;
+  diagnostics: DesignContractDiagnostic[];
+  sections: Array<{
+    id: DesignContractSectionId;
+    title: string;
+    line: number;
+    itemCount: number;
+  }>;
+}
+
+interface DesignContractDiagnostic {
+  code: DesignContractDiagnosticCode;
+  severity: "error" | "warning" | "info";
+  message: string;
+  section?: DesignContractSectionId;
+  heading?: string;
+  line?: number;
+  suggestion?: string;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": false,
+  "exists": true,
+  "filePath": "/repo/mycodemap.design.md",
+  "title": "Design Contract: Missing acceptance example",
+  "missingRequiredSections": [
+    "acceptanceCriteria"
+  ],
+  "diagnostics": [
+    {
+      "code": "missing-section",
+      "severity": "error",
+      "message": "缺少必填 section: Acceptance Criteria",
+      "section": "acceptanceCriteria"
+    }
+  ],
+  "sections": [
+    {
+      "id": "goal",
+      "title": "Goal",
+      "line": 3,
+      "itemCount": 1
+    }
+  ]
+}
+```
+
+> `design validate --json` 必须保持纯 JSON；不要在前后拼接说明性 prose。
+
+---
+
+## design map 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignMappingCandidateKind = "file" | "module" | "symbol";
+
+type DesignMappingDiagnosticCode =
+  | "no-candidates"
+  | "over-broad-scope"
+  | "high-risk-scope"
+  | string;
+
+interface DesignMappingReason {
+  section: DesignContractSectionId;
+  matchedText: string;
+  evidenceType: string;
+}
+
+interface DesignMappingCandidate {
+  kind: DesignMappingCandidateKind;
+  path: string;
+  moduleName?: string;
+  symbolName?: string;
+  reasons: DesignMappingReason[];
+  dependencies: string[];
+  testImpact: string[];
+  risk: "high" | "medium" | "low";
+  confidence: {
+    score: number;
+    level: "high" | "medium" | "low";
+  };
+  unknowns: string[];
+}
+
+interface DesignMappingDiagnostic {
+  code: DesignMappingDiagnosticCode;
+  severity: "error" | "warning" | "info";
+  blocker: boolean;
+  message: string;
+  candidatePaths?: string[];
+}
+
+interface DesignMapOutput {
+  ok: boolean;
+  filePath: string;
+  summary: {
+    candidateCount: number;
+    blocked: boolean;
+    unknownCount: number;
+    diagnosticCount: number;
+  };
+  candidates: DesignMappingCandidate[];
+  diagnostics: DesignMappingDiagnostic[];
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": false,
+  "filePath": "/repo/mycodemap.design.md",
+  "summary": {
+    "candidateCount": 1,
+    "blocked": true,
+    "unknownCount": 0,
+    "diagnosticCount": 1
+  },
+  "candidates": [
+    {
+      "kind": "file",
+      "path": "src/cli/commands/analyze.ts",
+      "reasons": [
+        {
+          "section": "goal",
+          "matchedText": "src/cli/commands/analyze.ts",
+          "evidenceType": "path-anchor"
+        }
+      ],
+      "dependencies": [],
+      "testImpact": [],
+      "risk": "high",
+      "confidence": {
+        "score": 0.92,
+        "level": "high"
+      },
+      "unknowns": []
+    }
+  ],
+  "diagnostics": [
+    {
+      "code": "high-risk-scope",
+      "severity": "error",
+      "blocker": true,
+      "message": "候选范围命中了高 blast-radius 文件；请先补充更具体的 design scope，再继续执行。"
+    }
+  ]
+}
+```
+
+> `design map --json` 必须保持纯 JSON；不要在前后拼接说明性 prose。`unknowns` 与 `diagnostics` 都属于正式契约，不是可选注释。
+
+---
+
+## design handoff 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignHandoffApprovalStatus = "approved" | "needs-review";
+
+interface DesignHandoffTraceItem {
+  id: string;
+  text: string;
+  sourceRefs: string[];
+}
+
+interface DesignHandoffOutput {
+  ok: boolean;
+  filePath: string;
+  outputDir: string;
+  readyForExecution: boolean;
+  artifacts: {
+    markdownPath: string;
+    jsonPath: string;
+  };
+  summary: {
+    approvalCount: number;
+    assumptionCount: number;
+    openQuestionCount: number;
+    requiresReview: boolean;
+  };
+  handoff: {
+    touchedFiles: string[];
+    constraints: string[];
+    tests: string[];
+    approvals: Array<DesignHandoffTraceItem & {
+      status: DesignHandoffApprovalStatus;
+    }>;
+    assumptions: DesignHandoffTraceItem[];
+    openQuestions: DesignHandoffTraceItem[];
+  };
+  diagnostics: Array<{
+    code: "blocked-mapping" | "review-required" | string;
+    blocker: boolean;
+    message: string;
+  }>;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": true,
+  "filePath": "/repo/mycodemap.design.md",
+  "outputDir": "/repo/.mycodemap/handoffs",
+  "readyForExecution": false,
+  "artifacts": {
+    "markdownPath": "/repo/.mycodemap/handoffs/mycodemap.handoff.md",
+    "jsonPath": "/repo/.mycodemap/handoffs/mycodemap.handoff.json"
+  },
+  "summary": {
+    "approvalCount": 4,
+    "assumptionCount": 1,
+    "openQuestionCount": 1,
+    "requiresReview": true
+  },
+  "handoff": {
+    "touchedFiles": [
+      "src/cli/design-handoff-builder.ts"
+    ],
+    "constraints": [
+      "默认 artifact path 必须复用 src/cli/paths.ts"
+    ],
+    "tests": [
+      "src/cli/__tests__/design-handoff-builder.test.ts"
+    ],
+    "approvals": [
+      {
+        "id": "approved-goal",
+        "status": "approved",
+        "text": "Goal 已被纳入 handoff 事实输入",
+        "sourceRefs": ["design:goal"]
+      }
+    ],
+    "assumptions": [
+      {
+        "id": "assumption-1-1",
+        "text": "需要补充 reviewer 对未知范围的确认",
+        "sourceRefs": ["candidate:src/cli/design-handoff-builder.ts"]
+      }
+    ],
+    "openQuestions": [
+      {
+        "id": "open-question-1",
+        "text": "低风险 assumptions 是否也必须显式批准？",
+        "sourceRefs": ["design:openQuestions"]
+      }
+    ]
+  },
+  "diagnostics": [
+    {
+      "code": "review-required",
+      "blocker": false,
+      "message": "Handoff generated successfully but still requires human review before execution."
+    }
+  ]
+}
+```
+
+> `design handoff --json` 必须保持纯 JSON；`readyForExecution`、`approvals`、`assumptions`、`openQuestions` 都属于正式契约。human mode 默认写出 `.mycodemap/handoffs/{stem}.handoff.md|json`。
+
+---
+
+## design verify 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignVerificationStatus =
+  | "satisfied"
+  | "needs-review"
+  | "violated"
+  | "blocked";
+
+type DesignDriftKind =
+  | "scope-extra"
+  | "acceptance-unverified"
+  | "handoff-missing"
+  | "blocked-input";
+
+interface DesignVerificationOutput {
+  ok: boolean;
+  filePath: string;
+  readyForExecution: boolean;
+  summary: {
+    checklistCount: number;
+    satisfiedCount: number;
+    needsReviewCount: number;
+    violatedCount: number;
+    blockedCount: number;
+    driftCount: number;
+    diagnosticCount: number;
+    reviewRequired: boolean;
+    blocked: boolean;
+  };
+  checklist: Array<{
+    id: string;
+    text: string;
+    status: DesignVerificationStatus;
+    evidenceRefs: string[];
+  }>;
+  drift: Array<{
+    kind: DesignDriftKind;
+    severity: "error" | "warning" | "info";
+    message: string;
+    sourceRefs: string[];
+  }>;
+  diagnostics: Array<{
+    code: "handoff-missing" | "handoff-invalid" | "blocked-input" | string;
+    blocker: boolean;
+    message: string;
+    sourceRefs: string[];
+  }>;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": true,
+  "filePath": "/repo/tests/fixtures/design-contracts/verify-ready.design.md",
+  "readyForExecution": false,
+  "summary": {
+    "checklistCount": 3,
+    "satisfiedCount": 1,
+    "needsReviewCount": 2,
+    "violatedCount": 0,
+    "blockedCount": 0,
+    "driftCount": 3,
+    "diagnosticCount": 1,
+    "reviewRequired": true,
+    "blocked": false
+  },
+  "checklist": [
+    {
+      "id": "acceptance-1",
+      "text": "src/cli/design-verification-builder.ts 会产出 conservative verification result",
+      "status": "satisfied",
+      "evidenceRefs": [
+        "candidate:src/cli/design-verification-builder.ts",
+        "diagnostic:handoff-missing"
+      ]
+    },
+    {
+      "id": "acceptance-2",
+      "text": "src/interface/types/design-verification.ts 会定义正式 verification schema",
+      "status": "needs-review",
+      "evidenceRefs": [
+        "design:acceptanceCriteria"
+      ]
+    }
+  ],
+  "drift": [
+    {
+      "kind": "handoff-missing",
+      "severity": "warning",
+      "message": "Canonical handoff artifact is missing, so verification remains review-needed even though a live handoff was rebuilt.",
+      "sourceRefs": [
+        "diagnostic:handoff-missing"
+      ]
+    }
+  ],
+  "diagnostics": [
+    {
+      "code": "handoff-missing",
+      "blocker": false,
+      "message": "Canonical handoff artifact is missing, so verification remains review-needed even though a live handoff was rebuilt.",
+      "sourceRefs": [
+        "diagnostic:handoff-missing"
+      ]
+    }
+  ]
+}
+```
+
+> `design verify --json` 必须保持纯 JSON；`checklist` 与 `drift` 都属于正式契约。`readyForExecution=false` 不等于 blocker，只有 `ok=false` 或 blocker diagnostics 才应返回非零 exit code。
+
+---
+
 ## impact 命令输出结构
 
 ### JSON 输出 (-j)

package/docs/ai-guide/PATTERNS.md

@@ -189,13 +189,25 @@ npm test
 **执行步骤**:
 
 ```bash
+# Step 0: 如果任务来自人类设计，先校验 design contract
+node dist/cli/index.js design validate mycodemap.design.md --json
+
+# Step 0.5: 把 design contract 映射成 candidate code scope
+node dist/cli/index.js design map mycodemap.design.md --json
+
+# Step 0.75: 生成 reviewer / agent 共用的 handoff package
+node dist/cli/index.js design handoff mycodemap.design.md --json
+
+# Step 0.9: 基于 reviewed handoff truth 做 verification / drift 检查
+node dist/cli/index.js design verify mycodemap.design.md --json
+
 # Step 1: 启动工作流
 node dist/cli/index.js workflow start "实现用户认证模块"
 
 # Step 2: 查看当前阶段建议
 node dist/cli/index.js workflow status
 
-# Step 3: 执行当前阶段的分析和实现
+# Step 3: 执行当前阶段的分析（实现/提交/CI 不在 workflow phase 内）
 
 # Step 4: 完成阶段后推进
 node dist/cli/index.js workflow proceed
@@ -214,10 +226,8 @@ node dist/cli/index.js workflow checkpoint
 2. `read` - 阅读影响范围、复杂度与上下文
 3. `link` - 汇总依赖、引用与关联关系
 4. `show` - 生成概览、摘要与展示型结果
-5. `commit` - 提交验证
-6. `ci` - CI 验证
 
-> 说明：以上是当前公开实现，不代表最终收敛模型；如果只需要代码地图能力，优先使用前面几个核心分析模式。
+> 说明：`workflow` 仍只保留 `find` / `read` / `link` / `show` 四阶段；如果任务由人类设计驱动，先走 `design validate → design map → design handoff → design verify` 固定输入、候选范围、review gate 与 drift 检查，再进入 workflow。
 
 ---
 

package/docs/ai-guide/PROMPTS.md

@@ -340,32 +340,38 @@
 
 请执行以下步骤：
 
-1. **相关代码搜索**
+1. **先把设计写成可验证输入**
+   ```bash
+   cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md
+   node dist/cli/index.js design validate mycodemap.design.md --json
+   ```
+
+2. **相关代码搜索**
    ```bash
    node dist/cli/index.js analyze -i find -k "{{RELATED_KEYWORD}}" --topK 10 --json
    ```
 
-2. **参考现有实现**
+3. **参考现有实现**
    分析类似功能的实现方式
 
-3. **确定实现位置**
+4. **确定实现位置**
    ```bash
    node dist/cli/index.js analyze -i read -t "候选目录" --json
    ```
    选择复杂度最低的模块
 
-4. **影响分析**（如果需要修改现有代码）
+5. **影响分析**（如果需要修改现有代码）
    ```bash
    node dist/cli/index.js analyze -i read -t "目标文件" --json
    ```
 
-5. **实现步骤**
+6. **实现步骤**
    - [ ] 创建新文件（添加 [META] [WHY] 头）
    - [ ] 实现核心功能
    - [ ] 添加单元测试
    - [ ] 运行测试验证
 
-6. **验证**
+7. **验证**
    ```bash
    node dist/cli/index.js ci check-headers -f "新文件.ts"
    npm test