@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/commands/artifact-workflow.js

@@ -475,25 +475,17 @@ async function generateApplyInstructions(projectRoot, changeName, schemaName) {
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';
-        instruction = `All tasks are complete! This change is ready for code review or archiving.
+        instruction = `All tasks are complete. Review should auto-run once after apply completion.
 
-**Next Step: Code Review (Optional)**
+**Required Next Steps**
 
-When all tasks are complete, you should:
-1. Use the **AskUserQuestion tool** to ask the user: "所有任务已完成。是否进行代码审查？" (or "All tasks are complete. Would you like to perform a code review?")
-2. Provide options:
-   - "是，进行代码审查" / "Yes, perform code review"
-   - "跳过，直接归档" / "Skip, proceed to archive"
-3. Wait for user selection before proceeding.
+1. Verify auto review report exists (\`metrics/review.json\`, \`metrics/tests.json\`)
+2. Ensure unit tests pass in the review report
+3. Ensure critical issues = 0
+4. If auto review failed/missing, run \`zhuanspec review ${changeName}\` manually
+5. Then continue to \`zhuanspec archive ${changeName}\`
 
-If the user selects code review, review the implemented code for:
-- Code standards and conventions compliance
-- Logic correctness
-- Performance issues
-- Security concerns
-- Best practices adherence
-
-See the apply command template for detailed code review workflow instructions.`;
+Archive may be blocked if review/tests are missing or failed.`;
     }
     else if (!tracksFile) {
         // No tracking file (e.g., TDD schema) - ready to apply
@@ -596,27 +588,16 @@ function printApplyInstructionsText(instructions) {
     // Code review prompt for all_done state
     if (state === 'all_done') {
         console.log();
-        console.log('### 📋 Code Review (Optional)');
+        console.log('### 📋 Code Review (Auto + Required)');
         console.log();
         console.log('All tasks are complete. You should now:');
         console.log();
-        console.log('1. **Prompt for code review** using the **AskUserQuestion tool**:');
-        console.log('   - Ask: "所有任务已完成。是否进行代码审查？" (or "All tasks are complete. Would you like to perform a code review?")');
-        console.log('   - Provide options:');
-        console.log('     • "是，进行代码审查" / "Yes, perform code review"');
-        console.log('     • "跳过，直接归档" / "Skip, proceed to archive"');
-        console.log('   - Wait for user selection before proceeding');
-        console.log();
-        console.log('2. **If user selects code review**, review the implemented code for:');
-        console.log('   - Code standards and conventions compliance');
-        console.log('   - Logic correctness');
-        console.log('   - Performance issues');
-        console.log('   - Security concerns');
-        console.log('   - Best practices adherence');
-        console.log();
-        console.log('3. **After code review** (or if skipped), proceed to archive workflow.');
-        console.log();
-        console.log('See the apply command template for detailed code review workflow instructions.');
+        console.log('1. Auto review is triggered once when all apply tasks complete');
+        console.log('2. Confirm `metrics/review.json` and `metrics/tests.json` exist');
+        console.log('3. Ensure review report is PASS with no critical issues');
+        console.log('4. Ensure unit tests pass');
+        console.log('5. If auto review failed/missing, run `zhuanspec review <change-id>` manually');
+        console.log('6. Then proceed to archive workflow');
     }
 }
 async function templatesCommand(options) {

package/dist/commands/design.d.ts

@@ -0,0 +1,42 @@
+export declare class DesignCommand {
+    execute(changeName?: string, options?: {
+        force?: boolean;
+        initTemplate?: boolean;
+        change?: string;
+        desc?: string;
+        dashenPageId?: string;
+        dashenUrl?: string;
+        output?: string;
+        validate?: boolean;
+        autoFix?: boolean;
+        createChange?: boolean;
+    }): Promise<void>;
+    private writeTemplateToChange;
+    private resolveDesignContext;
+    private resolveOutputPath;
+    private buildSkillRequestDoc;
+    private bindDesignSourceToChange;
+    private selectChangeInteractively;
+    /**
+     * Validate design.md for required sections and optionally auto-fix
+     */
+    private validateDesign;
+    /**
+     * Auto-fix design content by adding missing section skeletons
+     */
+    private autoFixDesign;
+    /**
+     * Generate a kebab-case change name from design context
+     */
+    private generateChangeName;
+    /**
+     * Create a new change directory for techDesign phase
+     * - Creates change directory using createChange()
+     * - Creates .tech-design marker file
+     * - Initializes progress.json with phase=techDesign
+     * - Creates design.md skeleton
+     * - Creates doc/ request file
+     */
+    private createTechDesignChange;
+}
+//# sourceMappingURL=design.d.ts.map

package/dist/commands/design.js

@@ -0,0 +1,337 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { createChange } from '../utils/change-utils.js';
+import { initializeProgress } from '../core/hooks/record-progress.js';
+const DEFAULT_DESIGN_TEMPLATE = `## 背景
+[背景、约束、利益相关者]
+
+## 目标 / 非目标
+- Goals: [...]
+- Non-Goals: [...]
+
+## 决策
+- Decision: [内容和原因]
+- Alternatives considered: [选项 + 理由]
+
+## 风险 / 权衡
+- [风险] -> 缓解措施
+
+## 迁移计划
+[步骤、回滚]
+
+## 待解决问题
+- [...]
+`;
+export class DesignCommand {
+    async execute(changeName, options) {
+        const boundChange = options?.change?.trim() || changeName?.trim() || undefined;
+        // Create new change directory mode (techDesign phase)
+        if (options?.createChange && !boundChange) {
+            const designContext = await this.resolveDesignContext({
+                desc: options?.desc,
+                dashenPageId: options?.dashenPageId,
+                dashenUrl: options?.dashenUrl,
+            });
+            const newChangeName = await this.generateChangeName(designContext);
+            await this.createTechDesignChange(newChangeName, designContext);
+            return;
+        }
+        // Backward-compatible mode: generate empty design template in change directory.
+        if (options?.initTemplate) {
+            const targetChange = boundChange || (process.stdin.isTTY ? await this.selectChangeInteractively() : undefined);
+            if (!targetChange) {
+                throw new Error('No change selected. Usage: zhuanspec techDesign <change-id> --init-template');
+            }
+            await this.writeTemplateToChange(targetChange, !!options?.force);
+            return;
+        }
+        // Validation mode: validate existing design.md
+        if (options?.validate) {
+            const targetChange = boundChange || (process.stdin.isTTY ? await this.selectChangeInteractively() : undefined);
+            if (!targetChange) {
+                throw new Error('No change selected. Usage: zhuanspec techDesign <change-id> --validate');
+            }
+            await this.validateDesign(targetChange, !!options?.autoFix);
+            return;
+        }
+        const designContext = await this.resolveDesignContext({
+            desc: options?.desc,
+            dashenPageId: options?.dashenPageId,
+            dashenUrl: options?.dashenUrl,
+        });
+        if (!designContext.desc && !designContext.dashenPageId && !designContext.dashenUrl) {
+            throw new Error('Missing design source. Provide --desc / --dashen-page-id / --dashen-url to generate technical design.');
+        }
+        const outputPath = await this.resolveOutputPath(options?.output, boundChange);
+        const exists = await FileSystemUtils.fileExists(outputPath);
+        if (exists && !options?.force) {
+            throw new Error(`Output file already exists: ${outputPath}. Use --force to overwrite.`);
+        }
+        const content = this.buildSkillRequestDoc(designContext, outputPath, boundChange);
+        await FileSystemUtils.writeFile(outputPath, content);
+        console.log(`Design generation request created: ${outputPath}`);
+        console.log('Next step: run generate-tech-spec-md-skill in agent mode with this request.');
+        if (boundChange) {
+            await this.bindDesignSourceToChange(boundChange, outputPath, !!options?.force);
+        }
+    }
+    async writeTemplateToChange(changeName, force) {
+        const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeName);
+        if (!(await FileSystemUtils.directoryExists(changeDir))) {
+            throw new Error(`Change '${changeName}' not found in zhuanspec/changes`);
+        }
+        const designPath = path.join(changeDir, 'design.md');
+        const exists = await FileSystemUtils.fileExists(designPath);
+        if (exists && !force) {
+            console.log(`design.md already exists: ${designPath}`);
+            return;
+        }
+        await FileSystemUtils.writeFile(designPath, DEFAULT_DESIGN_TEMPLATE);
+        console.log(`Design template generated: ${designPath}`);
+    }
+    async resolveDesignContext(input) {
+        const result = {
+            desc: input.desc?.trim() ?? '',
+            dashenPageId: input.dashenPageId?.trim() ?? '',
+            dashenUrl: input.dashenUrl?.trim() ?? '',
+        };
+        if (result.desc || result.dashenPageId || result.dashenUrl || !process.stdin.isTTY) {
+            return result;
+        }
+        const { input: askInput } = await import('@inquirer/prompts');
+        const source = await askInput({
+            message: '请输入需求描述（或留空后继续输入 Dashen 信息）',
+            default: '',
+        });
+        result.desc = source.trim();
+        return result;
+    }
+    async resolveOutputPath(output, boundChange) {
+        if (output?.trim()) {
+            return path.isAbsolute(output) ? output : path.join(process.cwd(), output);
+        }
+        const docDir = path.join(process.cwd(), 'doc');
+        await FileSystemUtils.createDirectory(docDir);
+        const stamp = new Date().toISOString().slice(0, 10);
+        const fileName = boundChange
+            ? `${stamp}-${boundChange}-技术方案生成请求.md`
+            : `${stamp}-技术方案生成请求.md`;
+        return path.join(docDir, fileName);
+    }
+    buildSkillRequestDoc(context, outputPath, boundChange) {
+        return [
+            '# 技术方案生成请求',
+            '',
+            '## 目标',
+            '使用 `generate-tech-spec-md-skill` 基于以下输入生成完整技术方案文档。',
+            '',
+            '## 输入',
+            `- 需求描述: ${context.desc || '(未提供)'}`,
+            `- Dashen Page ID: ${context.dashenPageId || '(未提供)'}`,
+            `- Dashen URL: ${context.dashenUrl || '(未提供)'}`,
+            `- 绑定变更: ${boundChange || '(无，独立于提案阶段)'}`,
+            '',
+            '## 生成要求',
+            '- 使用 Dashen 模板优先，本地模板兜底',
+            '- 输出完整技术方案（含 Mermaid）',
+            '- 覆盖需求功能点并附带校验结果与修复记录',
+            '',
+            '## 输出建议',
+            `- 当前请求文件: ${outputPath}`,
+            '- 技术方案目标文件: doc/[项目名称]技术方案.md',
+            '',
+        ].join('\n');
+    }
+    async bindDesignSourceToChange(changeName, outputPath, force) {
+        const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeName);
+        if (!(await FileSystemUtils.directoryExists(changeDir))) {
+            throw new Error(`Change '${changeName}' not found in zhuanspec/changes`);
+        }
+        const designPath = path.join(changeDir, 'design.md');
+        const exists = await FileSystemUtils.fileExists(designPath);
+        if (exists && !force) {
+            console.log(`Skip binding to ${designPath} because it already exists. Use --force to overwrite binding.`);
+            return;
+        }
+        const relative = path.relative(changeDir, outputPath).replaceAll('\\', '/');
+        const binding = `# Design Source\n\n- source: \`${relative}\`\n- mode: generated-before-proposal\n`;
+        await FileSystemUtils.writeFile(designPath, binding);
+        console.log(`Bound design source to change: ${designPath}`);
+    }
+    async selectChangeInteractively() {
+        const changesDir = path.join(process.cwd(), 'zhuanspec', 'changes');
+        let entries = [];
+        try {
+            entries = await fs.readdir(changesDir, { withFileTypes: true });
+        }
+        catch {
+            throw new Error("No zhuanspec changes directory found. Run 'zhuanspec init' first.");
+        }
+        const changes = entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+        if (changes.length === 0) {
+            throw new Error('No active changes found. Create one first with zhuanspec new change <name>.');
+        }
+        if (!process.stdin.isTTY) {
+            throw new Error(`Missing change name. Available changes: ${changes.join(', ')}`);
+        }
+        const { select } = await import('@inquirer/prompts');
+        try {
+            return await select({
+                message: '选择要生成 design 的变更',
+                choices: changes.map((id) => ({ name: id, value: id })),
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Validate design.md for required sections and optionally auto-fix
+     */
+    async validateDesign(changeName, autoFix) {
+        const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeName);
+        const designPath = path.join(changeDir, 'design.md');
+        if (!await FileSystemUtils.fileExists(designPath)) {
+            throw new Error(`design.md not found in change '${changeName}'`);
+        }
+        const content = await FileSystemUtils.readFile(designPath);
+        const issues = [];
+        // Check required sections: 背景/目标/决策/风险
+        const requiredSections = [
+            { pattern: /^##\s+(背景|Background)/im, name: '背景/Background', skeleton: '## 背景\n\n[请补充背景、约束、利益相关者]\n' },
+            { pattern: /^##\s+(目标|Goals|非目标|Non-Goals)/im, name: '目标/Goals', skeleton: '## 目标 / 非目标\n\n- Goals: [...]\n- Non-Goals: [...]\n' },
+            { pattern: /^##\s+(决策|Decision)/im, name: '决策/Decision', skeleton: '## 决策\n\n- Decision: [内容和原因]\n- Alternatives considered: [选项 + 理由]\n' },
+            { pattern: /^##\s+(风险|权衡|Risks)/im, name: '风险/Risks', skeleton: '## 风险 / 权衡\n\n- [风险] -> 缓解措施\n' },
+        ];
+        for (const section of requiredSections) {
+            if (!section.pattern.test(content)) {
+                issues.push({
+                    type: 'missing-section',
+                    section: section.name,
+                    skeleton: section.skeleton,
+                });
+            }
+        }
+        // Check if content has placeholder markers (needs completion)
+        const placeholderPatterns = [
+            /\[请补充[^\]]*\]/g,
+            /\[\.\.\.\]/g,
+            /\[待[^\]]*\]/g,
+        ];
+        const placeholderCount = placeholderPatterns.reduce((count, pattern) => {
+            const matches = content.match(pattern) || [];
+            return count + matches.length;
+        }, 0);
+        if (placeholderCount > 5) {
+            issues.push({
+                type: 'placeholders-excessive',
+                count: placeholderCount,
+            });
+        }
+        // Report validation results
+        if (issues.length === 0) {
+            console.log(`✓ Design validation passed for ${changeName}`);
+            return;
+        }
+        console.log(`✗ Design validation failed for ${changeName}:`);
+        for (const issue of issues) {
+            if (issue.type === 'missing-section') {
+                console.log(`  - Missing section: ${issue.section}`);
+            }
+            else if (issue.type === 'placeholders-excessive') {
+                console.log(`  - Excessive placeholders: ${issue.count} placeholders detected`);
+            }
+        }
+        // Auto-fix missing sections
+        if (autoFix) {
+            const fixedContent = this.autoFixDesign(content, issues);
+            await FileSystemUtils.writeFile(designPath, fixedContent);
+            console.log(`✓ Auto-fixed ${issues.filter(i => i.type === 'missing-section').length} missing sections`);
+        }
+        else {
+            console.log('Tip: Use --auto-fix to add missing section skeletons');
+            throw new Error('Design validation failed');
+        }
+    }
+    /**
+     * Auto-fix design content by adding missing section skeletons
+     */
+    autoFixDesign(content, issues) {
+        let result = content;
+        for (const issue of issues) {
+            if (issue.type === 'missing-section' && issue.skeleton) {
+                // Add skeleton at end of document
+                result = result.trimEnd() + '\n\n' + issue.skeleton;
+            }
+        }
+        return result;
+    }
+    /**
+     * Generate a kebab-case change name from design context
+     */
+    async generateChangeName(context) {
+        let base;
+        if (context.desc) {
+            base = context.desc;
+        }
+        else if (context.dashenPageId) {
+            base = `tech-design-${context.dashenPageId}`;
+        }
+        else if (context.dashenUrl) {
+            // Extract page ID from URL if possible
+            const match = context.dashenUrl.match(/pages\/(\d+)/);
+            base = match ? `tech-design-${match[1]}` : `tech-design-${Date.now()}`;
+        }
+        else {
+            base = `tech-design-${Date.now()}`;
+        }
+        // Convert to kebab-case
+        const kebabName = base
+            .toLowerCase()
+            .replace(/[^\w\s-]/g, '') // Remove non-word chars except spaces and hyphens
+            .replace(/\s+/g, '-') // Replace spaces with hyphens
+            .replace(/-+/g, '-') // Replace multiple hyphens with single
+            .slice(0, 40) // Limit length
+            .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+        // Ensure unique name
+        const changesDir = path.join(process.cwd(), 'zhuanspec', 'changes');
+        if (await FileSystemUtils.directoryExists(path.join(changesDir, kebabName))) {
+            return `${kebabName}-${Date.now()}`;
+        }
+        return kebabName;
+    }
+    /**
+     * Create a new change directory for techDesign phase
+     * - Creates change directory using createChange()
+     * - Creates .tech-design marker file
+     * - Initializes progress.json with phase=techDesign
+     * - Creates design.md skeleton
+     * - Creates doc/ request file
+     */
+    async createTechDesignChange(changeName, context) {
+        const projectRoot = process.cwd();
+        // 1. Create change directory
+        await createChange(projectRoot, changeName, { schema: 'spec-driven' });
+        const changeDir = path.join(projectRoot, 'zhuanspec', 'changes', changeName);
+        // 2. Initialize progress.json with phase=techDesign
+        await initializeProgress(changeName, 'techDesign');
+        // 3. Create .tech-design marker file
+        await FileSystemUtils.writeFile(path.join(changeDir, '.tech-design'), `created: ${new Date().toISOString()}\nsource: ${context.desc || context.dashenPageId || 'manual'}\n`);
+        // 4. Create design.md skeleton
+        await FileSystemUtils.writeFile(path.join(changeDir, 'design.md'), DEFAULT_DESIGN_TEMPLATE);
+        // 5. Create doc/ request file (keep compatibility)
+        const docDir = path.join(projectRoot, 'doc');
+        await FileSystemUtils.createDirectory(docDir);
+        const requestPath = path.join(docDir, `${changeName}-技术方案生成请求.md`);
+        await FileSystemUtils.writeFile(requestPath, this.buildSkillRequestDoc(context, requestPath, changeName));
+        console.log(`\n✓ TechDesign change created: zhuanspec/changes/${changeName}/`);
+        console.log(`✓ Phase: techDesign (run /zhuanspec:proposal to continue)`);
+        console.log(`✓ Design skeleton: ${changeDir}/design.md`);
+        console.log(`✓ Request file: ${requestPath}\n`);
+    }
+}
+//# sourceMappingURL=design.js.map

package/dist/commands/progress.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Progress Command - Display current execution status
+ *
+ * This command reads progress.json and tasks.md to show:
+ * - Current phase and wave status
+ * - Task completion percentage with visual progress bar
+ * - Estimated remaining time
+ */
+export declare class ProgressCommand {
+    /**
+     * Show progress for a specific change
+     * Usage: zhuanspec progress show <change-id>
+     */
+    show(changeId: string, options?: {
+        json?: boolean;
+    }): Promise<void>;
+    execute(options?: {
+        json?: boolean;
+    }): Promise<void>;
+    private findMostRecentChange;
+    private parseTasks;
+    private computeWaves;
+    private outputJson;
+    private outputFormatted;
+    private generateProgressBar;
+    /**
+     * Set phase for a change
+     * Usage: zhuanspec progress set-phase <change-id> <phase>
+     */
+    setPhase(changeId: string, phase: string): Promise<void>;
+}
+//# sourceMappingURL=progress.d.ts.map