@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/utils/phase-utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Phase Utilities - Phase state management for ZhuanSpec
+ *
+ * Provides:
+ * - Phase type definition
+ * - setPhase: Write phase to progress.json
+ * - getPhaseFromProgress: Read phase from progress.json
+ * - getCurrentPhase: Comprehensive phase detection
+ */
+export type Phase = 'idle' | 'techDesign' | 'propose' | 'apply' | 'review' | 'archive';
+export declare const PHASE_ORDER: Phase[];
+export declare const PHASE_MARKERS: Partial<Record<Phase, string>>;
+/**
+ * Set phase in progress.json
+ * Creates or updates progress.json with the new phase value
+ */
+export declare function setPhase(changeDir: string, phase: Phase): Promise<void>;
+/**
+ * Get phase from progress.json
+ * Returns null if progress.json doesn't exist or phase field is missing
+ */
+export declare function getPhaseFromProgress(changeDir: string): Promise<Phase | null>;
+/**
+ * Get current phase using comprehensive detection
+ * Priority: progress.json phase > marker files > directory existence
+ */
+export declare function getCurrentPhase(changeDir: string): Promise<Phase>;
+/**
+ * Check if a directory is a techDesign change (can be reused by proposal)
+ */
+export declare function isTechDesignChange(changeDir: string): Promise<boolean>;
+/**
+ * Clear techDesign markers when transitioning to propose
+ */
+export declare function clearTechDesignMarkers(changeDir: string): Promise<void>;
+//# sourceMappingURL=phase-utils.d.ts.map

package/dist/utils/phase-utils.js

@@ -0,0 +1,117 @@
+/**
+ * Phase Utilities - Phase state management for ZhuanSpec
+ *
+ * Provides:
+ * - Phase type definition
+ * - setPhase: Write phase to progress.json
+ * - getPhaseFromProgress: Read phase from progress.json
+ * - getCurrentPhase: Comprehensive phase detection
+ */
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+export const PHASE_ORDER = ['idle', 'techDesign', 'propose', 'apply', 'review', 'archive'];
+export const PHASE_MARKERS = {
+    techDesign: '.tech-design',
+    apply: '.approved',
+    review: 'review-report.md',
+};
+/**
+ * Set phase in progress.json
+ * Creates or updates progress.json with the new phase value
+ */
+export async function setPhase(changeDir, phase) {
+    const metricsDir = path.join(changeDir, 'metrics');
+    await FileSystemUtils.createDirectory(metricsDir);
+    const progressPath = path.join(metricsDir, 'progress.json');
+    let progress;
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        try {
+            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        }
+        catch {
+            progress = { phase };
+        }
+    }
+    else {
+        progress = { phase };
+    }
+    progress.phase = phase;
+    progress.lastUpdatedAt = new Date().toISOString();
+    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+}
+/**
+ * Get phase from progress.json
+ * Returns null if progress.json doesn't exist or phase field is missing
+ */
+export async function getPhaseFromProgress(changeDir) {
+    const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+    if (!await FileSystemUtils.fileExists(progressPath)) {
+        return null;
+    }
+    try {
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const phase = progress.phase;
+        // Validate phase value
+        if (PHASE_ORDER.includes(phase)) {
+            return phase;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get current phase using comprehensive detection
+ * Priority: progress.json phase > marker files > directory existence
+ */
+export async function getCurrentPhase(changeDir) {
+    // 1. Priority: progress.json phase field
+    const progressPhase = await getPhaseFromProgress(changeDir);
+    if (progressPhase) {
+        return progressPhase;
+    }
+    // 2. Fallback: marker files
+    for (const [phase, marker] of Object.entries(PHASE_MARKERS)) {
+        if (marker) {
+            const markerPath = path.join(changeDir, marker);
+            if (await FileSystemUtils.fileExists(markerPath)) {
+                return phase;
+            }
+        }
+    }
+    // 3. Fallback: check for proposal.md (propose phase)
+    const proposalPath = path.join(changeDir, 'proposal.md');
+    if (await FileSystemUtils.fileExists(proposalPath)) {
+        return 'propose';
+    }
+    // 4. Check for design.md without .tech-design (could be techDesign or propose)
+    const designPath = path.join(changeDir, 'design.md');
+    if (await FileSystemUtils.fileExists(designPath)) {
+        // If design.md exists but no proposal.md, likely techDesign
+        return 'techDesign';
+    }
+    // 5. Default: idle (directory exists but no meaningful files)
+    return 'idle';
+}
+/**
+ * Check if a directory is a techDesign change (can be reused by proposal)
+ */
+export async function isTechDesignChange(changeDir) {
+    const techDesignMarker = path.join(changeDir, '.tech-design');
+    if (await FileSystemUtils.fileExists(techDesignMarker)) {
+        return true;
+    }
+    const phase = await getPhaseFromProgress(changeDir);
+    return phase === 'techDesign';
+}
+/**
+ * Clear techDesign markers when transitioning to propose
+ */
+export async function clearTechDesignMarkers(changeDir) {
+    const techDesignMarker = path.join(changeDir, '.tech-design');
+    if (await FileSystemUtils.fileExists(techDesignMarker)) {
+        await FileSystemUtils.deleteFile(techDesignMarker);
+    }
+}
+//# sourceMappingURL=phase-utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.2.4",
+  "version": "2.4.8",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -27,7 +27,8 @@
     }
   },
   "bin": {
-    "zhuanspec": "./bin/zhuanspec.js"
+    "zhuanspec": "./bin/zhuanspec.js",
+    "zhuanspec-hook": "./bin/zhuanspec-hook.js"
   },
   "files": [
     "dist",
@@ -38,26 +39,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -79,5 +60,23 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
   }
-}
+}

package/schemas/spec-driven/schema.yaml

@@ -1,10 +1,35 @@
 name: spec-driven
 version: 1
-description: 默认 OpenSpec 工作流 - proposal → specs → design → tasks
+description: 默认 zhuanspec 工作流 - techDesign(design) → proposal → specs → tasks
 artifacts:
+  - id: design
+    generates: design.md
+    description: 包含实现细节的技术设计文档（提案前置）
+    template: design.md
+    instruction: |
+      创建解释如何实现变更的设计文档。
+
+      何时包含 design.md（仅在以下任何情况适用时创建）：
+      - 横切变更（多个服务/模块）或新的架构模式
+      - 新的外部依赖或重要的数据模型更改
+      - 安全性、性能或迁移复杂性
+      - 在编码之前从技术决策中受益的模糊性
+
+      章节：
+      - **背景**：背景、当前状态、约束、利益相关者
+      - **目标 / 非目标**：此设计实现的内容和明确排除的内容
+      - **决策**：关键的技术选择及其理由（为什么选择 X 而不是 Y？）。包括为每个决策考虑的替代方案。
+      - **风险 / 权衡**：已知的限制，可能出错的事情。格式：[风险] → 缓解措施
+      - **迁移计划**：部署步骤、回滚策略（如果适用）
+      - **待解决问题**：待解决的决定或未知数
+
+      专注于架构和方法，而不是逐行实现。
+      好的设计文档解释了技术决策背后的"原因"。
+    requires: []
+
   - id: proposal
     generates: proposal.md
-    description: 概述变更的初始提案文档
+    description: 概述变更的初始提案文档（必须引用 design.md）
     template: proposal.md
     instruction: |
       **强制澄清检查点（必须首先执行）**：
@@ -41,6 +66,22 @@ artifacts:
       
       只有在所有必要的模糊点都明确后，才能继续创建 proposal.md。
 
+      **自动验证与修复流程**：
+      创建提案后，必须执行自动验证：
+      1. 运行 `zhuanspec validate <id> --strict --auto-fix`
+      2. 如果验证失败，CLI 会自动分析错误并尝试修复（最多 3 次循环）
+      3. 验证通过后，输出提案摘要
+      4. 使用 AskUserQuestion 工具弹出选项式交互确认：
+         - 批准，进入实施阶段 → 创建 `.approved` 文件
+         - 需要修改提案内容 → 返回修改提案
+         - 暂不批准，稍后处理 → 保持提案状态
+         - 其他 → 等待用户补充说明
+
+      **三铁律约束**：
+      - **No Spec, No Code**：未批准前禁止任何代码修改
+      - **Spec is Truth**：归档时强制校验 Spec-Code 一致性
+      - **Reverse Sync**：Apply 阶段偏离时必须先更新提案
+
       创建建立此变更原因的提案文档。
 
       章节：
@@ -65,7 +106,8 @@ artifacts:
       实现细节属于 design.md。
 
       这是基础 - 规范、设计和任务都建立在此基础上。
-    requires: []
+    requires:
+      - design
 
   - id: specs
     generates: "specs/**/*.md"
@@ -120,34 +162,6 @@ artifacts:
     requires:
       - proposal
 
-  - id: design
-    generates: design.md
-    description: 包含实现细节的技术设计文档
-    template: design.md
-    instruction: |
-      创建解释如何实现变更的设计文档。
-
-      何时包含 design.md（仅在以下任何情况适用时创建）：
-      - 横切变更（多个服务/模块）或新的架构模式
-      - 新的外部依赖或重要的数据模型更改
-      - 安全性、性能或迁移复杂性
-      - 在编码之前从技术决策中受益的模糊性
-
-      章节：
-      - **背景**：背景、当前状态、约束、利益相关者
-      - **目标 / 非目标**：此设计实现的内容和明确排除的内容
-      - **决策**：关键的技术选择及其理由（为什么选择 X 而不是 Y？）。包括为每个决策考虑的替代方案。
-      - **风险 / 权衡**：已知的限制，可能出错的事情。格式：[风险] → 缓解措施
-      - **迁移计划**：部署步骤、回滚策略（如果适用）
-      - **待解决问题**：待解决的决定或未知数
-
-      专注于架构和方法，而不是逐行实现。
-      参考提案了解动机，参考规范了解要求。
-
-      好的设计文档解释了技术决策背后的"原因"。
-    requires:
-      - proposal
-
   - id: tasks
     generates: tasks.md
     description: 从规范和设计派生的实施任务

package/schemas/spec-driven/templates/spec.md

@@ -1,8 +1,145 @@
+## Impact Assessment
+
+### 影响范围
+- **模块**: <!-- example: order-service -->
+- **数据库**: <!-- example: order_table (add column xxx) -->
+- **API**: <!-- example: /api/v1/orders -->
+- **消息**: <!-- example: OrderCreatedEvent -->
+
+### 风险等级
+- **等级**: <!-- HIGH | MEDIUM | LOW -->
+- **理由**: <!-- why this risk level -->
+
+### Breaking Change
+- **是否破坏性变更**: <!-- 是 | 否 -->
+
+## Estimated Changes
+
+### 文件列表
+| 文件路径 | 变更类型 | 关联要求 | 预估行数 |
+|---------|---------|---------|---------|
+| `<!-- path -->` | <!-- 新增/修改/删除 --> | <!-- Requirement name --> | <!-- estimated lines --> |
+
+### 核心类/方法
+- `<!-- Class.method -->` - <!-- what changes -->
+
+### 测试影响
+- **新增测试类**: <!-- list new test classes needed -->
+- **修改测试类**: <!-- list existing tests to modify -->
+
+## Validation Checklist
+
+- [ ] 功能验证清单已覆盖主要场景
+- [ ] 兼容性验证清单已完成
+- [ ] 回归测试清单已完成
+- [ ] 数据迁移方案已设计（如涉及数据库变更）
+- [ ] API 兼容性已评估（如涉及 API 变更）
+
 ## ADDED Requirements
 
-### 需求：<!-- 要求名称 -->
-<!-- 要求文本 -->
+### Requirement: <!-- Requirement name -->
+
+<!-- Requirement text MUST contain SHALL or MUST keyword -->
+<!-- Use SHALL for normative requirements, MUST for mandatory constraints -->
+
+**Location**: `<!-- file path, e.g. src/service/order.ts -->`
+
+系统 SHALL <!-- requirement description - what the system must do -->
+
+#### Scenario: <!-- Scenario name - describe the success case -->
+
+<!-- Scenario format: WHEN condition THEN expected result -->
+<!-- Use WHEN/THEN/AND for consistency across all specs -->
+
+**Location**: `<!-- specific method/class, e.g. OrderService.createOrder() -->`
+
+- **WHEN** <!-- condition: what triggers this scenario -->
+- **THEN** <!-- expected result: what should happen -->
+- **AND** <!-- optional additional result or constraint -->
+
+#### Scenario: <!-- Error/edge case scenario name -->
+
+**Location**: `<!-- specific method/class for error handling -->`
+
+- **WHEN** <!-- condition including error/edge case -->
+- **THEN** <!-- expected error handling or fallback behavior -->
+
+<!-- 
+  Requirements writing guidelines:
+  
+  1. Use SHALL/MUST keywords:
+     - SHALL: normative, standard behavior expectations
+     - MUST: mandatory, non-negotiable constraints
+  
+  2. Each requirement MUST have at least one scenario
+     - Success scenario: normal operation path
+     - Error scenario: failure handling (optional but recommended)
+  
+  3. Scenario naming:
+     - Use descriptive names that identify the specific test case
+     - Examples: "成功导出数据", "无效参数返回错误", "并发请求处理"
+  
+  4. Scenario format:
+     - MUST use exactly 4 hashes (####) for scenario headers
+     - Use WHEN/THEN/AND keywords for clarity
+     - Each scenario is a potential test case
+  
+  5. Cross-references:
+     - Reference related requirements: "See also: Requirement: 数据验证"
+     - Reference related specs: "Spec: user-auth"
+-->
+
+<!-- 
+  MODIFIED Requirements template (when changing existing behavior):
+  
+  ## MODIFIED Requirements
+  
+  ### Requirement: <!-- existing requirement name - must match original exactly -->
+
+  **Location**: `<!-- file path - where the modification happens -->`
+  
+  <!-- Copy original requirement text and modify it -->
+  <!-- MUST include full updated content, not just the change -->
+  
+  系统 SHALL <!-- updated requirement description -->
+  
+  #### Scenario: <!-- existing scenario name or new scenario -->
+
+  **Location**: `<!-- specific method/class being modified -->`
+  
+  - **WHEN** <!-- updated condition -->
+  - **THEN** <!-- updated expected result -->
+  
+  <!-- 
+    Important: For MODIFIED requirements:
+    1. Copy the entire requirement block from zhuanspec/specs/<capability>/spec.md
+    2. Edit it to reflect the new behavior
+    3. Ensure title matches exactly (ignore whitespace)
+    4. Keep all scenarios, even if unchanged
+    5. Partial MODIFIED entries will lose detail on archive
+  -->
+-->
+
+<!-- 
+  REMOVED Requirements template:
+  
+  ## REMOVED Requirements
+  
+  ### Requirement: <!-- requirement name being removed -->
+
+  **Location**: `<!-- file path where code was removed -->`
+  
+  **Reason**: <!-- why this requirement is being removed -->
+  **Migration**: <!-- how to handle existing usage/code -->
+-->
 
-#### 场景：<!-- 场景名称 -->
-- **当** <!-- 条件 -->
-- **则** <!-- 预期结果 -->
+<!-- 
+  RENAMED Requirements template (only for name changes):
+  
+  ## RENAMED Requirements
+  
+  - FROM: `### Requirement: OldName`
+  - TO: `### Requirement: NewName`
+  
+  <!-- If behavior also changes, use RENAMED (name) + MODIFIED (content) -->
+-->

package/schemas/spec-driven/templates/tasks.md

@@ -1,4 +1,31 @@
-## 1. <!-- 任务组名称 -->
+## Pre-Clarification Log
+
+<!-- ⚠️ CHECKPOINT [PRE-CLARIFICATION]: This section MUST be completed before writing proposal -->
+<!-- Record clarification Q&A or write "Status: COMPLETED - No clarification needed" -->
+<!-- This section MUST NOT be empty, contain only HTML comments, or have TODO/TBD/PENDING markers -->
+
+Status: COMPLETED - No clarification needed
+
+Reason: All scope, technical choices, priorities, and dependencies are clear from existing specs and project conventions.
+
+<!-- If clarification was needed, record Q&A like this:
+Question 1: 数据获取来源？
+Answer: 从 OrderService 获取
+
+Question 2: 是否需要分页？
+Answer: 是，每页20条
+-->
+
+## Skill Mapping
+
+<!-- ⚠️ 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 -->
+<!-- @skill names MUST match exactly the names returned by `zhuanspec skills list` -->
+
+| 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
+|---------|---------|-----------|---------|
+| <!-- example: DAO层 --> | <!-- example: 数据库表结构 --> | <!-- example: java-db-schema-standards --> | <!-- example: 需要创建新表，符合数据库规范 --> |
 
 <!-- 
   @skill 标注指南：
@@ -22,16 +49,53 @@
      - 独立任务：无数据或逻辑依赖的任务不要添加 @depends，以最大化并行度
 
   示例：
-  - [ ] 1.1 新增 AssBusinessDataEnum 枚举值 ASSEMBLY_MACHINE_FLAG @skill:kf-backend-coding-standards
-  - [ ] 1.2 创建数据库表 ass_order @skill:java-db-schema-standards
+  - [ ] 1.1 新增枚举值 @skill:kf-backend-coding-standards
+  - [ ] 1.2 创建数据库表 @skill:java-db-schema-standards
   - [ ] 1.3 编写 DAO 层代码 @skill:java-dao-standards @depends:1.2
-  - [ ] 1.4 定义 SCF 接口 IAssQueryService @skill:java-scf-rpc-usage-skill @depends:1.3
 -->
 
-- [ ] 1.1 <!-- 任务描述 --> <!-- @skill:real-skill-name -->
-- [ ] 1.2 <!-- 任务描述 --> <!-- @skill:real-skill-name @depends:1.1 -->
+### Wave 1
+
+<!-- Wave 1: Tasks with no dependencies -->
+
+- [ ] 1.1 <!-- Task description --> @skill:none <!-- 纯配置变更或手动操作 -->
+
+### Wave 2
+
+<!-- Wave 2: Tasks depending on Wave 1 -->
+
+- [ ] 2.1 <!-- Task description --> @depends:1.1 @skill:none <!-- 无需特定 skill，通用实现 -->
+
+### Wave 3
+
+<!-- Wave 3: Tasks depending on Wave 2 -->
+
+- [ ] 3.1 <!-- Task description --> @depends:2.1 @skill:none <!-- 无需特定 skill，通用实现 -->
+
+## Dependency Analysis
+
+<!-- ⚠️ CHECKPOINT [TASK-ORDERING]: Status must be COMPLETED after wave analysis -->
+<!-- No task may appear before a task it depends on -->
+<!-- validate --strict will verify task ordering matches computed waves -->
+
+Status: COMPLETED
+
+Wave assignment logic:
+- Wave 1: No @depends annotations → no dependencies
+- Wave 2: @depends:1.x → depends on Wave 1
+- Wave 3: @depends:2.x → depends on Wave 2
+
+## Quality Gates
+
+- [ ] Apply 全部任务完成后自动执行一次 `zhuanspec review <change-id>`（如失败则手动补执行）
+
+## Workflow Diagram
 
-## 2. <!-- 任务组名称 -->
+<!-- Auto-generated by zhuanspec validate --strict -->
+<!-- DO NOT EDIT - this section will be regenerated on each validation -->
 
-- [ ] 2.1 <!-- 任务描述 -->
-- [ ] 2.2 <!-- 任务描述 --> <!-- @depends:1.2,2.1 -->
+```mermaid
+flowchart TD
+    W1[Wave 1] --> W2[Wave 2]
+    W2 --> W3[Wave 3]
+```