@zhuan-ai/zhuanspec 2.11.3 → 2.11.6

package/dist/core/templates/tasks-template.js

@@ -74,6 +74,12 @@ Answer: <!-- user answer -->
 
 ## 任务格式说明
 
+⚠️ **所有任务项必须使用 GitHub Flavored Markdown 复选框格式**：
+- 待完成：\`- [ ] N.M 描述\` 
+- 已完成：\`- [x] N.M 描述\`
+- **严禁使用** \`#### Task N.M:\` 或 \`#### T1:\` 标题格式
+- **严禁使用** ✅ emoji 标记完成，必须用 \`[x]\`
+
 每个任务按类型使用对应的固定模板，必须填满所有字段：
 
 ### 类型 A：新增文件
@@ -169,6 +175,7 @@ Wave assignment logic:
 - Wave 2: @depends:1.x → depends on Wave 1
 - Wave 3: @depends:2.x → depends on Wave 2
 
+
 ## File Conflict Analysis
 
 <!-- 当多个任务修改同一文件时，在此声明冲突并指定隔离策略 -->
@@ -214,51 +221,7 @@ flowchart TD
 \`\`\`
 `;
 }
-/**
- * Get the minimal tasks.md template (for quick scaffolding)
- * Note: This minimal template will NOT pass strict validation by default
- * User must fill in the Pre-Clarification Log and Skill Mapping sections
- */
-export function getMinimalTasksTemplate() {
-    return `## Pre-Clarification Log
-
-<!-- Replace with actual Q&A or "Status: COMPLETED - No clarification needed" -->
-
-Status: COMPLETED - No clarification needed
-
-Reason: <!-- fill in reason -->
-
-## Skill Mapping
-
-| 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
-|---------|---------|-----------|---------|
-| <!-- fill in --> | <!-- fill in --> | <!-- fill in --> | <!-- fill in --> |
-
-### Wave 1
-
-- [ ] 1.1 <!-- Task description --> @skill:none <!-- 纯配置变更 -->
-
-### Wave 2
-
-- [ ] 2.1 <!-- Task description --> @depends:1.1 @skill:none <!-- 无需特定 skill -->
-
-## Dependency Analysis
-
-Status: COMPLETED
-
-Wave assignment logic:
-- Wave 1: No dependencies
-- Wave 2: Depends on Wave 1
-
-## File Conflict Analysis
-
-| 文件 | 涉及任务 | 各任务修改区域 | 隔离策略 |
-|------|---------|-------------|---------|
-| <!-- 相对路径 --> | <!-- T1.x, T2.y --> | <!-- T1.x: 函数名/行范围; T2.y: 函数名/行范围 --> | <!-- parallel / serial --> |
-`;
-}
 export default {
-    getTasksTemplate,
-    getMinimalTasksTemplate
+    getTasksTemplate
 };
 //# sourceMappingURL=tasks-template.js.map

package/dist/core/templates/tdd-tasks-template.d.ts

@@ -14,14 +14,8 @@ export interface TddTasksTemplateOptions {
  * Uses valid completion markers to pass strict validation by default
  */
 export declare function getTddTasksTemplate(options?: TddTasksTemplateOptions): string;
-/**
- * Get the minimal TDD tasks.md template (for quick scaffolding)
- * Note: User must fill in Pre-Clarification Log and Skill Mapping sections
- */
-export declare function getMinimalTddTasksTemplate(): string;
 declare const _default: {
     getTddTasksTemplate: typeof getTddTasksTemplate;
-    getMinimalTddTasksTemplate: typeof getMinimalTddTasksTemplate;
 };
 export default _default;
 //# sourceMappingURL=tdd-tasks-template.d.ts.map

package/dist/core/templates/tdd-tasks-template.js

@@ -24,61 +24,164 @@ Status: COMPLETED - No clarification needed
 
 Reason: TDD workflow requirements are clear - specification first, then failing tests, then implementation.
 
-<!-- If clarification was needed:
+<!-- If clarification was needed, replace above with Q&A record:
 Question 1: <!-- clarification question -->
 Answer: <!-- user answer -->
+
+Question 2: <!-- clarification question -->
+Answer: <!-- user answer -->
 -->
 
 ## Skill Mapping
 
-<!-- ⚠️ CHECKPOINT [SKILL-TAGGING]: Run \`zhuanspec skills list\` first -->
+<!-- ⚠️ CHECKPOINT [SKILL-TAGGING]: Run \`zhuanspec skills list\` first and record discovered skills -->
 <!-- Every task MUST have either @skill:real-skill-name or @skill:none -->
+<!-- If @skill:none, MUST provide justification in description -->
+<!-- @skill names MUST match exactly the names returned by \`zhuanspec skills list\` -->
 
 | 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
-|---------|---------|-----------|---------|
+|---------|---------|-----------|--------|
 | 测试层 | 单元测试生成 | generate-${testFramework}-unit-test-skill | TDD Red phase 需要生成测试框架特定测试 |
+| <!-- module/file --> | <!-- actual function --> | <!-- skill name --> | <!-- why it matches --> |
 
 <!--
-  TDD Skill Mapping Guidelines:
-  - Wave 2 (Red): Unit test generation requires test skill
-  - Wave 3-4 (Green/Refactor): Implementation may need domain-specific skills
-  - Wave 5 (Docs): Documentation tasks typically @skill:none
+  @skill 标注指南：
+  1. 首先运行 \`zhuanspec skills list --json\` 获取可用 skill 列表
+  2. 基于任务的实际功能内容与 skill description 进行语义匹配
+  3. 匹配原则：
+     - 精确匹配：任务功能应与 skill description 明确对应
+     - 避免过度匹配：简单的代码修改只需通用编码规范 skill
+     - 避免关键词匹配：不要仅因文件名或路径关键词就匹配
+
+  @depends 标注指南：
+  1. 使用 @depends:taskId 标注依赖，支持多依赖 @depends:taskId1,taskId2
+  2. 无 @depends 的任务默认无依赖，可与其他无依赖任务并行执行
+  3. 不允许循环依赖
+  4. 仅标注直接依赖（如 A→B→C，C 只需标注 @depends:B）
+
+  @test-case 标注指南（TDD 模式下强烈推荐）：
+  1. TDD 模式下每个实现任务（Wave 3-4）应关联对应的测试 case
+  2. 格式：@test-case:TC-001 或 @test-case:TC-001,TC-002（多个用逗号分隔）
+  3. 确保引用的 TC-XXX 在 test-cases.md 中存在
+  4. 任务应覆盖对应测试 case 的所有验收点
+
+  @ref 标注指南：
+  1. 指向技术方案文档的具体章节（路径为实际定位到的技术方案文件相对路径）
+  2. 格式：@ref:<tech-spec路径>#章节编号-章节名称
+  3. 示例：@ref:techDesign/tech-spec.md#3.1-新建客户接口
+  4. 确保引用的章节在技术方案文档中存在
 -->
 
+## 任务格式说明
+
+⚠️ **所有任务项必须使用 GitHub Flavored Markdown 复选框格式**：
+- 待完成：\`- [ ] N.M 描述\` 
+- 已完成：\`- [x] N.M 描述\`
+- **严禁使用** \`#### Task N.M:\` 或 \`#### T1:\` 标题格式
+- **严禁使用** ✅ emoji 标记完成，必须用 \`[x]\`
+
+每个任务按类型使用对应的固定模板，必须填满所有字段：
+
+### 类型 A：新增文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: \`完整相对路径\`（新增）
+  - **内容**:
+    - 类定义: [类名、继承/实现关系]
+    - 依赖注入: [注入的 Bean/Service 列表]
+    - 核心方法: [方法签名 → 返回类型]（列出全部 public 方法）
+    - 关键逻辑: [核心业务流程，如：校验 → 加锁 → 写库 → 同步ES]
+    - 字段/配置: [若为 Entity/DTO/配置类，列出全部字段及类型]
+  - **验证**: [具体的输入输出断言，含正常和异常场景]
+
+示例：
+- [ ] 3.1 创建 OrderDomainService @skill:java-scf-rpc-usage-skill
+  @ref:techDesign/tech-spec.md#3.1-创建订单
+  - **文件**: \`order_server/src/main/java/com/zz/order/domain/OrderDomainService.java\`（新增）
+  - **内容**:
+    - 类定义: \`@Service public class OrderDomainService\`
+    - 依赖注入: OrderMapper, InventoryService, RedissonClient
+    - 核心方法: createOrder(CreateOrderRequest, Long userId) → Long
+    - 关键逻辑: 参数校验 → 库存预扣 → 分布式锁 order:create:{userId} → insert t_order → 发送MQ
+    - 异常处理: 库存不足抛 BizException(ErrorCode.STOCK_INSUFFICIENT)
+  - **验证**: 库存不足返回 STOCK_INSUFFICIENT；正常创建返回 orderId > 0；并发创建幂等
+
+### 类型 B：修改文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: \`完整相对路径\`（总行数）
+  - **修改位置**: L行号范围 \`函数名/类名\` 之后/之内
+  - **内容**: [具体改什么：新增代码逻辑/修改现有逻辑/删除代码，描述修改方式]
+  - **验证**: [修改后的预期行为，含回归验证]
+
+示例：
+- [ ] 3.2 在 PaymentService 中增加退款超时重试 @skill:none
+  @ref:techDesign/tech-spec.md#4.2-退款重试机制
+  - **文件**: \`payment_server/src/main/java/com/zz/payment/service/PaymentService.java\`（215行）
+  - **修改位置**: L89-102 \`refund()\` 函数内，现有退款调用之后
+  - **内容**: 新增重试逻辑 — 退款接口超时时最多重试3次，间隔2s指数退避，3次失败后记录失败日志并发告警MQ
+  - **验证**: 超时重试3次后成功；3次均失败触发告警；正常退款不触发重试
+
+## 任务粒度原则
+- 每个任务对应一个类或一个接口方法的实现
+- 单个任务 AI 执行时间不超过 30 分钟
+- 超过则需拆分为多个子任务
+- **禁止模糊描述**：不允许"创建XXX类"不带文件路径、"实现YYY方法"不带方法签名和关键逻辑
+
+## Coverage Checklist
+
+<!-- 当存在技术方案（techDesign/tech-spec.md/ 通过--tech-spec创建的提案）时，必须填写此表 -->
+<!-- 列出技术方案中所有维度与任务的映射关系，确保覆盖率 >= 95% -->
+
+| 维度 | 技术方案数量 | 提案任务覆盖 | 覆盖率 |
+|------|-------------|-------------|-------|
+| DB 表 | <!-- N张 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| ES 索引 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| Entity 类 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| Mapper | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| SCF接口方法 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| DTO 类 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| 配置项 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| 前端组件 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+
 ### Wave 1
 
 <!-- Wave 1: Specification - Define what to build before writing any code -->
+<!-- 此阶段定义功能规格，无代码产出 -->
 
-- [ ] 1.1 Write feature specification @skill:none <!-- justification: spec definition, no code -->
+- [ ] 1.1 <!-- 编写功能规格说明 --> @skill:none <!-- justification: spec definition, no code -->
 
 ### Wave 2
 
 <!-- Wave 2: Red Phase - Write failing tests that define expected behavior -->
-<!-- Tests should fail initially - this proves they test something meaningful -->
+<!-- 先写测试，测试应当初始失败 — 证明测试确实在验证有意义的行为 -->
+<!-- 每个测试任务必须使用类型A/B模板，明确测试文件路径、测试方法签名、断言内容 -->
 
-- [ ] 2.1 Write unit tests for core functionality @depends:1.1 @skill:generate-${testFramework}-unit-test-skill
-- [ ] 2.2 Write integration tests @depends:1.1 @skill:none <!-- justification: integration tests, framework-specific -->
+- [ ] 2.1 <!-- 编写核心功能单元测试 --> @depends:1.1 @skill:generate-${testFramework}-unit-test-skill
+- [ ] 2.2 <!-- 编写集成测试 --> @depends:1.1 @skill:none <!-- justification: integration tests -->
 
 ### Wave 3
 
 <!-- Wave 3: Green Phase - Write minimal code to make tests pass -->
+<!-- 编写最少代码使测试通过，每个任务必须使用类型A（新增）或类型B（修改）模板 -->
 
-- [ ] 3.1 Implement core logic @depends:2.1 @skill:none <!-- fill in actual skill if needed -->
-- [ ] 3.2 Implement edge case handling @depends:3.1 @skill:none
+- [ ] 3.1 <!-- 实现核心逻辑 --> @depends:2.1 @skill:none <!-- fill in actual skill if needed -->
+- [ ] 3.2 <!-- 实现边界场景处理 --> @depends:3.1 @skill:none
 
 ### Wave 4
 
 <!-- Wave 4: Refactor Phase - Clean up code while keeping tests green -->
+<!-- 在保持测试通过的前提下重构，每个任务使用类型B模板标明修改位置 -->
 
-- [ ] 4.1 Refactor for clarity @depends:3.2 @skill:none <!-- justification: code cleanup -->
-- [ ] 4.2 Optimize performance @depends:4.1 @skill:none
+- [ ] 4.1 <!-- 重构提升可读性 --> @depends:3.2 @skill:none <!-- justification: code cleanup -->
+- [ ] 4.2 <!-- 性能优化 --> @depends:4.1 @skill:none
 
 ### Wave 5
 
 <!-- Wave 5: Documentation - Document the implemented feature -->
 
-- [ ] 5.1 Update API documentation @depends:4.2 @skill:none <!-- justification: documentation task -->
-- [ ] 5.2 Add usage examples @depends:5.1 @skill:none
+- [ ] 5.1 <!-- 更新 API 文档 --> @depends:4.2 @skill:none <!-- justification: documentation task -->
+- [ ] 5.2 <!-- 补充使用示例 --> @depends:5.1 @skill:none
 
 ## Dependency Analysis
 
@@ -90,11 +193,44 @@ Status: COMPLETED
 
 TDD Wave assignment logic:
 - Wave 1: Specification (no dependencies)
-- Wave 2: Tests (depends on spec)
-- Wave 3: Implementation (depends on tests)
-- Wave 4: Refactor (depends on implementation)
+- Wave 2: Tests (depends on spec) — Red phase
+- Wave 3: Implementation (depends on tests) — Green phase
+- Wave 4: Refactor (depends on implementation) — Refactor phase
 - Wave 5: Documentation (depends on refactor)
 
+## File Conflict Analysis
+
+<!-- 当多个任务修改同一文件时，在此声明冲突并指定隔离策略 -->
+<!-- 隔离策略：parallel（不同区域可并行）/ serial（同区域必须串行）-->
+<!-- 此表帮助编排 Agent 做更精确的并行化决策，补充自动检测无法覆盖的"同文件不同区域可并行"场景 -->
+<!-- 无文件冲突时章节可省略，或将表格行填写 N/A -->
+
+| 文件 | 涉及任务 | 各任务修改区域 | 隔离策略 |
+|------|---------|-------------|--------|
+| <!-- 相对路径 --> | <!-- T1.x, T2.y --> | <!-- T1.x: 函数名/行范围; T2.y: 函数名/行范围 --> | <!-- parallel / serial --> |
+
+## Test Case Coverage
+
+<!-- ⚠️ CHECKPOINT [TEST-CASE-COVERAGE]: TDD 模式下此表为必填项 -->
+<!-- Wave 2 的测试任务必须与 Wave 3-4 的实现任务形成完整映射 -->
+<!-- Use @test-case:TC-XXX to link tasks to test cases -->
+<!-- 表格必须包含四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景 -->
+
+| Task | 测试 Case ID | 测试 Case 文件路径 | 覆盖场景 |
+|------|-------------|-------------------|----------|
+| <!-- T2.1 --> | <!-- TC-001 --> | <!-- BIC 路径层级 --> | <!-- 描述覆盖的场景 --> |
+
+<!--
+  TDD 测试 case 设计指南：
+  1. Wave 2 每个测试任务至少覆盖一个正向场景和一个异常场景
+  2. Wave 3-4 实现任务应通过 @test-case 反向关联 Wave 2 的测试
+  3. 测试 case ID 格式：TC-XXX（三位数字）
+  4. 测试 case 详情记录在 test-cases.md 文件中
+  5. "测试 Case 文件路径" 列填写 BIC 路径层级格式：
+     - 格式：功能模块 > 子模块 > 页面 > 操作 > 结果
+     - 示例：退货退款 > 创建售后 > 三选一页面 > 组装机 > 退货退款 > 点击后,显示组装机弹窗
+-->
+
 ## Quality Gates
 
 - [ ] Apply 全部任务完成后自动执行一次 \`zhuanspec review <change-id>\`（如失败则手动补执行）
@@ -106,64 +242,14 @@ TDD Wave assignment logic:
 
 \`\`\`mermaid
 flowchart TD
-    W1[Wave 1: Spec] --> W2[Wave 2: Tests]
-    W2 --> W3[Wave 3: Impl]
+    W1[Wave 1: Spec] --> W2[Wave 2: Red - Tests]
+    W2 --> W3[Wave 3: Green - Impl]
     W3 --> W4[Wave 4: Refactor]
     W4 --> W5[Wave 5: Docs]
 \`\`\`
 `;
 }
-/**
- * Get the minimal TDD tasks.md template (for quick scaffolding)
- * Note: User must fill in Pre-Clarification Log and Skill Mapping sections
- */
-export function getMinimalTddTasksTemplate() {
-    return `## Pre-Clarification Log
-
-Status: COMPLETED - No clarification needed
-
-Reason: <!-- fill in reason -->
-
-## Skill Mapping
-
-| 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
-|---------|---------|-----------|---------|
-| <!-- fill in --> | <!-- fill in --> | <!-- fill in --> | <!-- fill in --> |
-
-### Wave 1
-
-- [ ] 1.1 Write specification @skill:none
-
-### Wave 2
-
-- [ ] 2.1 Write tests @depends:1.1 @skill:none
-
-### Wave 3
-
-- [ ] 3.1 Implement @depends:2.1 @skill:none
-
-### Wave 4
-
-- [ ] 4.1 Refactor @depends:3.1 @skill:none
-
-### Wave 5
-
-- [ ] 5.1 Document @depends:4.1 @skill:none
-
-## Dependency Analysis
-
-Status: COMPLETED
-
-Wave assignment: TDD strict order
-
-## Quality Gates
-
-- [ ] Apply 全部任务完成后自动执行一次 \`zhuanspec review <change-id>\`（如失败则手动补执行）
-- [ ] 单元测试命令已执行且测试通过（如 \`npm test\` / \`mvn test\`）
-`;
-}
 export default {
-    getTddTasksTemplate,
-    getMinimalTddTasksTemplate
+    getTddTasksTemplate
 };
 //# sourceMappingURL=tdd-tasks-template.js.map

package/dist/core/validation/strict-rules.d.ts

@@ -137,19 +137,28 @@ export declare function checkTestCaseCoverage(tasksContent: string, hasTestCase?
  *
  * When a tech-spec document exists, validates that the technical spec
  * adequately covers the proposal's requirements.
- * This is a basic framework - full logic will be implemented in Task 7's Skill.
  *
- * Tech spec document lookup order:
- *   1. techDesign/tech-spec.md (standard path)
- *   2. tech-spec.md in the proposal root directory
- *   3. 用户提供本地技术方案路径
+ * Tech spec document lookup order (priority):
+ *   1. 用户通过 --tech-spec 指定的外部路径 (externalTechSpecPath)
+ *   2. techDesign/ 目录下的任意 .md 文件（文件名不限定为 tech-spec.md）
+ *   3. 提案根目录下的任意技术方案相关 .md 文件
  *
  * Checks:
- *   - tech-spec.md file exists and is non-empty
- *   - tech-spec.md contains substantive content (not just placeholder)
+ *   - tech-spec file exists and is non-empty
+ *   - tech-spec contains substantive content (not just placeholder)
+ *   - structural elements (DB tables, APIs, classes, etc.) are covered in proposal files
  */
-export declare function checkTechSpecCoverage(changeDir: string): StrictCheckResult;
+export declare function checkTechSpecCoverage(changeDir: string, externalTechSpecPath?: string): StrictCheckResult;
 export declare function checkTaskIdFormat(tasksContent: string): StrictCheckResult;
+/**
+ * Rule: task-checkbox-format
+ *
+ * Validates that all tasks under Wave headers use standard GitHub Flavored Markdown
+ * checkbox format: `- [ ] N.M description` or `- [x] N.M description`.
+ * Rejects legacy formats like `#### Task N.M:` headers or `✅` emoji as completion marker.
+ * This ensures automated progress tracking (parseTasks, record-progress, review gate) works correctly.
+ */
+export declare function checkTaskCheckboxFormat(tasksContent: string): StrictCheckResult;
 /**
  * Main entry: Run all strict validation rules
  */
@@ -159,6 +168,7 @@ export declare function runStrictValidation(tasksContent: string, parsedTasks: P
     repoRoot?: string;
     changeDir?: string;
     hasTestCase?: boolean;
+    techSpecPath?: string;
 }): Promise<StrictValidationResult>;
 export {};
 //# sourceMappingURL=strict-rules.d.ts.map