@zhuan-ai/zhuanspec 2.9.5 → 2.11.2

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

@@ -64,8 +64,80 @@ Answer: <!-- user answer -->
   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-新建客户接口 或 @ref:/path/to/external-tech-spec.md#3.1-新建客户接口
+  4. 确保引用的章节在技术方案文档中存在
 -->
 
+## 任务格式说明
+
+每个任务按类型使用对应的固定模板，必须填满所有字段：
+
+### 类型 A：新增文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: \`完整相对路径\`（新增）
+  - **内容**:
+    - 类定义: [类名、继承/实现关系]
+    - 依赖注入: [注入的 Bean/Service 列表]
+    - 核心方法: [方法签名 → 返回类型]（列出全部 public 方法）
+    - 关键逻辑: [核心业务流程，如：校验 → 加锁 → 写库 → 同步ES]
+    - 字段/配置: [若为 Entity/DTO/配置类，列出全部字段及类型]
+  - **验证**: [具体的输入输出断言，含正常和异常场景]
+
+示例：
+- [ ] 5.1 创建 CustomerDomainService @skill:java-scf-rpc-usage-skill
+  @ref:techDesign/tech-spec.md#3.1-新建客户
+  - **文件**: \`domain_hub_server/src/main/java/com/zz/domain/hub/domain/CustomerDomainService.java\`（新增）
+  - **内容**:
+    - 类定义: \`@Service public class CustomerDomainService\`
+    - 依赖注入: CustomerMapper, CustomerEmployeeMapper, EsSyncService, RedissonClient
+    - 核心方法: createCustomer(CreateCustomerRequest, Long tenantId) → Long
+    - 关键逻辑: customerName 必填校验 → selectByPhoneAndTenant 手机号唯一检查 → 分布式锁 dh:customer:merge:{phone} → insert t_customer → 异步 ES 同步
+    - 异常处理: 手机号重复抛 BizException(ErrorCode.PHONE_DUPLICATE)
+  - **验证**: 手机号重复返回 PHONE_DUPLICATE 错误码；正常创建返回 customerId > 0；无锁时并发创建只成功一个
+
+### 类型 B：修改文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: \`完整相对路径\`（总行数）
+  - **修改位置**: L行号范围 \`函数名/类名\` 之后/之内
+  - **内容**: [具体改什么：新增代码逻辑/修改现有逻辑/删除代码，描述修改方式]
+  - **验证**: [修改后的预期行为，含回归验证]
+
+示例：
+- [ ] 1.1 在 review 命令中增加任务完成度硬门禁 @skill:none
+  @ref:techDesign/tech-spec.md#7.1-任务完成度检查
+  - **文件**: \`src/commands/review.ts\`（138行）
+  - **修改位置**: L32-38 \`runReview()\` 函数内，现有校验逻辑之后
+  - **内容**: 新增任务完成度检查 — 读取 tasks.md 匹配 \`- [ ]\` 统计未完成任务数，>0 时输出未完成列表并阻断 review 流程，支持 \`--force\` 参数跳过检查
+  - **验证**: 有未完成任务时阻断并输出列表；--force 跳过；全部完成时正常通过
+
+## 任务粒度原则
+- 每个任务对应一个类或一个接口方法的实现
+- 单个任务 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: Tasks with no dependencies -->
@@ -97,6 +169,17 @@ Wave assignment logic:
 - Wave 2: @depends:1.x → depends on Wave 1
 - Wave 3: @depends:2.x → depends on Wave 2
 
+## 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]: Each task should reference related test cases (recommended) -->
@@ -166,6 +249,12 @@ 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 {

package/dist/core/update.d.ts

@@ -1,4 +1,7 @@
 export declare class UpdateCommand {
     execute(projectPath: string): Promise<void>;
+    private syncDotClaudeFromRemote;
+    private cloneRemoteToTemp;
+    private syncDirectory;
 }
 //# sourceMappingURL=update.d.ts.map

package/dist/core/update.js

@@ -1,9 +1,14 @@
 import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { mkdtempSync, rmSync, readdirSync, readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { ZHUANSPEC_DIR_NAME } from './config.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 import { agentsTemplate } from './templates/agents-template.js';
+const ARCH_REPO_URL = 'http://gitlab.zhuanspirit.com/zz-kf/spec_repo.git';
+const ARCH_REPO_BRANCH = 'spec_repo-feature-6612-2';
 export class UpdateCommand {
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
@@ -59,6 +64,8 @@ export class UpdateCommand {
                 console.error(`更新 ${slashConfigurator.toolId} 的斜杠命令失败：${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        // 4. Sync .claude/ from remote (rules, skills, agents)
+        const claudeSyncResult = this.syncDotClaudeFromRemote(resolvedProjectPath);
         const summaryParts = [];
         const instructionFiles = ['zhuanspec/AGENTS.md'];
         if (updatedFiles.includes('AGENTS.md')) {
@@ -70,10 +77,24 @@ export class UpdateCommand {
             summaryParts.push(`已更新 AI 工具文件：${aiToolFiles.join(', ')}`);
         }
         if (updatedSlashFiles.length > 0) {
-            // Normalize to forward slashes for cross-platform log consistency
             const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
             summaryParts.push(`已更新斜杠命令：${normalized.join(', ')}`);
         }
+        if (claudeSyncResult.synced) {
+            const { added, overwritten, skipped } = claudeSyncResult;
+            const total = added + overwritten + skipped;
+            const parts = [];
+            if (added > 0)
+                parts.push(`新增 ${added} 个`);
+            if (overwritten > 0)
+                parts.push(`更新 ${overwritten} 个`);
+            if (skipped > 0)
+                parts.push(`跳过 ${skipped} 个`);
+            summaryParts.push(`已同步 .claude/ 远端内容（${total} 个文件，${parts.join('，')}）`);
+        }
+        else if (claudeSyncResult.attempted) {
+            summaryParts.push('同步 .claude/ 远端内容失败（网络不可用或权限不足）');
+        }
         const failedItems = [
             ...failedFiles,
             ...failedSlashTools.map((toolId) => `斜杠命令刷新（${toolId}）`),
@@ -82,7 +103,69 @@ export class UpdateCommand {
             summaryParts.push(`更新失败：${failedItems.join(', ')}`);
         }
         console.log(summaryParts.join(' | '));
-        // No additional notes
+    }
+    syncDotClaudeFromRemote(projectPath) {
+        const tempDir = this.cloneRemoteToTemp();
+        if (!tempDir) {
+            return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+        }
+        try {
+            const commonDotClaude = path.join(tempDir, 'specs', 'common', 'claude', '.claude');
+            if (!existsSync(commonDotClaude)) {
+                return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+            }
+            const targetDotClaude = path.join(projectPath, '.claude');
+            const result = this.syncDirectory(commonDotClaude, targetDotClaude);
+            return { attempted: true, synced: true, ...result };
+        }
+        catch {
+            return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+    cloneRemoteToTemp() {
+        const tempDir = mkdtempSync(path.join(os.tmpdir(), 'zhuanspec-update-'));
+        try {
+            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            return tempDir;
+        }
+        catch {
+            rmSync(tempDir, { recursive: true, force: true });
+            return null;
+        }
+    }
+    syncDirectory(srcDir, dstDir) {
+        const result = { added: 0, overwritten: 0, skipped: 0 };
+        const sync = (src, dst) => {
+            mkdirSync(dst, { recursive: true });
+            for (const entry of readdirSync(src, { withFileTypes: true })) {
+                const srcPath = path.join(src, entry.name);
+                const dstPath = path.join(dst, entry.name);
+                if (entry.isDirectory()) {
+                    sync(srcPath, dstPath);
+                }
+                else {
+                    const srcContent = readFileSync(srcPath);
+                    if (existsSync(dstPath)) {
+                        if (Buffer.compare(srcContent, readFileSync(dstPath)) === 0) {
+                            result.skipped++;
+                        }
+                        else {
+                            writeFileSync(dstPath, srcContent);
+                            result.overwritten++;
+                        }
+                    }
+                    else {
+                        writeFileSync(dstPath, srcContent);
+                        result.added++;
+                    }
+                }
+            }
+        };
+        sync(srcDir, dstDir);
+        return result;
     }
 }
 //# sourceMappingURL=update.js.map

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

@@ -15,6 +15,15 @@ export interface StrictValidationResult {
     checks: StrictCheckResult[];
     allPassed: boolean;
 }
+/**
+ * Rule 0: test-case-inquiry-logged
+ *
+ * Validates that tasks.md has a "## Test Case Source Log" section with non-empty content.
+ * This rule fires UNCONDITIONALLY — whether or not TDD mode is used.
+ * The AI must always ask the user about test cases and record the outcome before writing
+ * any spec/task content. Absence of this section means the inquiry was skipped.
+ */
+export declare function checkTestCaseInquiryLogged(tasksContent: string): StrictCheckResult;
 /**
  * Rule 1: pre-clarification-completed
  *
@@ -85,6 +94,25 @@ export declare function checkProposalFormatValid(proposalContent: string): Stric
  * 3. If progress.json exists without phase field -> Apply phase (default)
  */
 export declare function detectPhase(changeDir: string): 'propose' | 'apply' | 'review';
+/** Result of a single code search check */
+interface CodeSearchResult {
+    dimension: string;
+    keyword: string;
+    fileType: string;
+    found: boolean;
+    matchedFile?: string;
+}
+/** Result for a single scenario's coverage check */
+interface ScenarioResult {
+    scenario: string;
+    covered: boolean;
+    checks: CodeSearchResult[];
+}
+/** Overall consistency result across all scenarios */
+export interface ConsistencyResult {
+    scenarios: ScenarioResult[];
+    coverageRate: number;
+}
 /**
  * Rule: file-conflict-detection
  *
@@ -104,6 +132,24 @@ export declare function checkFileConflicts(parsedTasks: ParsedTask[]): StrictChe
  * - Column headers must match expected format
  */
 export declare function checkTestCaseCoverage(tasksContent: string, hasTestCase?: boolean): StrictCheckResult;
+/**
+ * Rule: tech-spec-coverage
+ *
+ * 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. 用户提供本地技术方案路径
+ *
+ * Checks:
+ *   - tech-spec.md file exists and is non-empty
+ *   - tech-spec.md contains substantive content (not just placeholder)
+ */
+export declare function checkTechSpecCoverage(changeDir: string): StrictCheckResult;
+export declare function checkTaskIdFormat(tasksContent: string): StrictCheckResult;
 /**
  * Main entry: Run all strict validation rules
  */
@@ -114,4 +160,5 @@ export declare function runStrictValidation(tasksContent: string, parsedTasks: P
     changeDir?: string;
     hasTestCase?: boolean;
 }): Promise<StrictValidationResult>;
+export {};
 //# sourceMappingURL=strict-rules.d.ts.map