@zhuan-ai/zhuanspec 2.0.0 → 2.1.0

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

@@ -43,6 +43,14 @@ export const agentsTemplate = `# ZhuanSpec 使用说明
 **工作流**
 0. 审查 \`zhuanspec/project.md\`、\`zhuanspec list\` 和 \`zhuanspec list --specs\` 以了解当前上下文。
 1. **强制澄清检查（必须首先执行）**：分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、实现细节、数据获取来源、服务分层、依赖关系、优先级、验收标准等......）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测或创建提案，严禁要求用户手动输入大段文字。
+
+   ⚠️ **CHECKPOINT [PRE-CLARIFICATION]**:
+   You MUST record the pre-clarification result in tasks.md under "## Pre-Clarification Log":
+   - If questions were asked: Record each question and the user's answer
+   - If no clarification needed: Write "Status: COMPLETED - No clarification needed" with brief justification
+   - This section MUST NOT be empty or contain only HTML comments
+   - NEVER proceed to proposal writing without completing this checkpoint
+
 2. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\`、可选的 \`design.md\` 和规范增量。
 3. 使用 \`## ADDED|MODIFIED|REMOVED Requirements\` 起草规范增量，每个要求至少包含一个 \`#### Scenario:\`。
 4. 运行 \`zhuanspec validate <id> --strict\` 并在分享提案之前解决所有问题。
@@ -452,6 +460,21 @@ The system SHALL provide...
 > - 使用真实 skill 名称标注，支持多个 skill（\`@skill:name1,name2\`）
 > - Apply 阶段 AI 根据标签直接调用对应 skill。无可用 skill 时可省略。
 
+⚠️ **CHECKPOINT [SKILL-TAGGING]**:
+1. You MUST run \`zhuanspec skills list\` first and record discovered skills in the Skill Mapping table
+2. Every task MUST have either @skill:real-skill-name or @skill:none
+3. If @skill:none, you MUST provide a justification (e.g., "pure config change, no skill applies")
+4. @skill names MUST match exactly the names returned by \`zhuanspec skills list\` — do NOT invent skill names
+5. The Skill Mapping table in tasks.md MUST NOT be empty
+6. validate --strict will verify all @skill names exist in the known skill list
+
+⚠️ **CHECKPOINT [TASK-ORDERING]**:
+1. Tasks in tasks.md MUST be organized under Wave headers (### Wave 1, ### Wave 2, etc.)
+2. Wave assignment must be computed from @depends relationships (Wave 1 = no deps, Wave N = depends on Wave N-1)
+3. No task may appear before a task it depends on
+4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
+5. validate --strict will verify task ordering matches computed waves
+
 5. **在需要时创建 design.md：**
 如果以下任何情况适用，则创建 \`design.md\`；否则省略：
 - 横切变更（多个服务/模块）或新的架构模式

package/dist/core/templates/skill-templates.js

@@ -738,6 +738,13 @@ export function getProposeChangeSkillTemplate() {
 
    d. 只有所有模糊点都明确后，才继续后续步骤。
 
+   ⚠️ **CHECKPOINT [PRE-CLARIFICATION]**:
+   You MUST record the pre-clarification result in tasks.md under "## Pre-Clarification Log":
+   - If questions were asked: Record each question and the user's answer
+   - If no clarification needed: Write "Status: COMPLETED - No clarification needed" with brief justification
+   - This section MUST NOT be empty or contain only HTML comments
+   - NEVER proceed to proposal writing without completing this checkpoint
+
 2. **Derive change name**
 
    From the user's description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -762,6 +769,14 @@ export function getProposeChangeSkillTemplate() {
       - Read any completed dependency files for context
       - **For proposal artifact**: When filling Skill Mapping section, analyze each skill's description and match based on actual functionality (not just module names). Simple changes like enum modifications should map to general coding standards, not architecture-level skills.
       - **For tasks artifact only**: Before creating tasks.md, run \`zhuanspec skills list --json\` to discover available skills with their descriptions. For each task, read skill descriptions carefully and annotate with \`@skill:<real-skill-name>\` tags only when there's a clear semantic match between the task's functionality and the skill's purpose. Supports multiple: \`@skill:name1,name2\`.
+
+      ⚠️ **CHECKPOINT [SKILL-TAGGING]**:
+      1. You MUST run \`zhuanspec skills list\` first and record discovered skills in the Skill Mapping table
+      2. Every task MUST have either @skill:real-skill-name or @skill:none
+      3. If @skill:none, you MUST provide a justification (e.g., "pure config change, no skill applies")
+      4. @skill names MUST match exactly the names returned by \`zhuanspec skills list\` — do NOT invent skill names
+      5. The Skill Mapping table in tasks.md MUST NOT be empty
+      6. validate --strict will verify all @skill names exist in the known skill list
       - Create the artifact following the schema's instruction
       - Show brief progress: "✓ Created <artifact-id>"
 
@@ -771,6 +786,13 @@ export function getProposeChangeSkillTemplate() {
       - **design.md**: Only if needed (cross-cutting changes, new dependencies, security/performance)
       - **tasks.md**: Break into small, verifiable tasks with checkboxes. Annotate with @skill tags based on semantic matching of skill descriptions to task functionality.
 
+      ⚠️ **CHECKPOINT [TASK-ORDERING]**:
+      1. Tasks in tasks.md MUST be organized under Wave headers (### Wave 1, ### Wave 2, etc.)
+      2. Wave assignment must be computed from @depends relationships (Wave 1 = no deps, Wave N = depends on Wave N-1)
+      3. No task may appear before a task it depends on
+      4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
+      5. validate --strict will verify task ordering matches computed waves
+
 5. **Validate the change**
    \`\`\`bash
    zhuanspec validate <name> --strict
@@ -1019,6 +1041,13 @@ export function getOpsxProposeCommandTemplate() {
    - If any unclear aspects found, use **AskUserQuestion tool** with preset options to clarify
    - Do NOT proceed until all ambiguities are resolved
 
+   ⚠️ **CHECKPOINT [PRE-CLARIFICATION]**:
+   You MUST record the pre-clarification result in tasks.md under "## Pre-Clarification Log":
+   - If questions were asked: Record each question and the user's answer
+   - If no clarification needed: Write "Status: COMPLETED - No clarification needed" with brief justification
+   - This section MUST NOT be empty or contain only HTML comments
+   - NEVER proceed to proposal writing without completing this checkpoint
+
 2. **Derive change name** from input (kebab-case, verb-first, unique)
 
 3. **Create change**: \`zhuanspec new change "<name>"\`
@@ -1028,6 +1057,19 @@ export function getOpsxProposeCommandTemplate() {
    - Read dependencies, create artifact, show progress
    - Artifacts: proposal.md → specs/ → design.md (if needed) → tasks.md
 
+   ⚠️ **CHECKPOINT [SKILL-TAGGING]**:
+   1. You MUST run \`zhuanspec skills list\` first and record discovered skills in the Skill Mapping table
+   2. Every task MUST have either @skill:real-skill-name or @skill:none
+   3. If @skill:none, you MUST provide a justification (e.g., "pure config change, no skill applies")
+   4. @skill names MUST match exactly the names returned by \`zhuanspec skills list\` — do NOT invent skill names
+   5. The Skill Mapping table in tasks.md MUST NOT be empty
+
+   ⚠️ **CHECKPOINT [TASK-ORDERING]**:
+   1. Tasks in tasks.md MUST be organized under Wave headers (### Wave 1, ### Wave 2, etc.)
+   2. Wave assignment must be computed from @depends relationships (Wave 1 = no deps, Wave N = depends on Wave N-1)
+   3. No task may appear before a task it depends on
+   4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
+
 5. **Validate**: \`zhuanspec validate <name> --strict\`
 
 6. **Present** the complete proposal for review

package/dist/core/templates/slash-command-templates.js

@@ -21,13 +21,20 @@ const proposalSteps = `**步骤**
      * 其他不明确？（其他不明确的情况）
    - 如果发现任何模糊之处，必须停止并使用**选项式交互**提问：
      * 使用编辑器的结构化问答工具（如 \`AskQuestion\`），将每个问题转化为带 2-5 个预设选项的选择题
-     * 每个问题末尾包含"其他"选项作为兜底
+     * 每个问题末尾包含“其他”选项作为兖底
      * 尽量将多个问题合并到一次交互中一次性展示
      * 必须等待用户选择答案，不能继续
      * **严禁**要求用户手动输入大段文字来回答
-   - 如果用户选择"其他"，再针对该问题追问（仍优先使用选项式）
+   - 如果用户选择“其他”，再针对该问题追问（仍优先使用选项式）
    - **严禁**在不确定的情况下自行推测、假设或创建提案文件
    - 只有在所有模糊点都明确后，才能继续后续步骤
+
+   ⚠️ **CHECKPOINT [PRE-CLARIFICATION]**:
+   You MUST record the pre-clarification result in tasks.md under "## Pre-Clarification Log":
+   - If questions were asked: Record each question and the user's answer
+   - If no clarification needed: Write "Status: COMPLETED - No clarification needed" with brief justification
+   - This section MUST NOT be empty or contain only HTML comments
+   - NEVER proceed to proposal writing without completing this checkpoint
 2. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\` 和 \`design.md\`（需要时）。
 3. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
 4. 当解决方案跨越多个系统、引入新模式或在提交规范之前需要权衡讨论时，在 \`design.md\` 中捕获架构推理。
@@ -43,6 +50,22 @@ const proposalSteps = `**步骤**
    - 将 \`tasks.md\` 起草为有序的小型、可验证工作项列表
    - 使用 \`@skill:<real-skill-name>\` 标注与 skill 匹配的任务（支持多个：\`@skill:name1,name2\`）
    - 仅当 skill 明确匹配任务时才标注，没有匹配的 skill 可省略标签
+
+   ⚠️ **CHECKPOINT [SKILL-TAGGING]**:
+   1. You MUST run \`zhuanspec skills list\` first and record discovered skills in the Skill Mapping table
+   2. Every task MUST have either @skill:real-skill-name or @skill:none
+   3. If @skill:none, you MUST provide a justification (e.g., "pure config change, no skill applies")
+   4. @skill names MUST match exactly the names returned by \`zhuanspec skills list\` — do NOT invent skill names
+   5. The Skill Mapping table in tasks.md MUST NOT be empty
+   6. validate --strict will verify all @skill names exist in the known skill list
+
+   ⚠️ **CHECKPOINT [TASK-ORDERING]**:
+   1. Tasks in tasks.md MUST be organized under Wave headers (### Wave 1, ### Wave 2, etc.)
+   2. Wave assignment must be computed from @depends relationships (Wave 1 = no deps, Wave N = depends on Wave N-1)
+   3. No task may appear before a task it depends on
+   4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
+   5. validate --strict will verify task ordering matches computed waves
+
 7. 使用 \`zhuanspec validate <id> --strict\` 进行验证，并在分享提案之前解决所有问题。`;
 const proposalReferences = `**参考**
 - 当验证失败时，使用 \`zhuanspec show <id> --json --deltas-only\` 或 \`zhuanspec show <spec> --type spec\` 检查详细信息。

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

@@ -0,0 +1,23 @@
+/**
+ * Tasks Template
+ *
+ * Template for generating tasks.md with required checkpoint sections.
+ */
+export interface TasksTemplateOptions {
+    changeId: string;
+    capabilities?: string[];
+}
+/**
+ * Get the tasks.md template structure with required checkpoint sections
+ */
+export declare function getTasksTemplate(options?: TasksTemplateOptions): string;
+/**
+ * Get the minimal tasks.md template (for quick scaffolding)
+ */
+export declare function getMinimalTasksTemplate(): string;
+declare const _default: {
+    getTasksTemplate: typeof getTasksTemplate;
+    getMinimalTasksTemplate: typeof getMinimalTasksTemplate;
+};
+export default _default;
+//# sourceMappingURL=tasks-template.d.ts.map

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

@@ -0,0 +1,79 @@
+/**
+ * Tasks Template
+ *
+ * Template for generating tasks.md with required checkpoint sections.
+ */
+/**
+ * Get the tasks.md template structure with required checkpoint sections
+ */
+export function getTasksTemplate(options) {
+    const changeId = options?.changeId || '[change-id]';
+    return `# Tasks: ${changeId}
+
+## Pre-Clarification Log
+
+<!-- REQUIRED: Record clarification Q&A or write "Status: COMPLETED - No clarification needed" -->
+<!-- This section MUST NOT be empty or contain only HTML comments -->
+
+Status: PENDING
+
+## Skill Mapping
+
+| Skill Name | Actual Function | Match Reason |
+|---|---|---|
+
+<!-- REQUIRED: Run \`zhuanspec skills list\` and record skill matching decisions -->
+<!-- Every task MUST have either @skill:real-skill-name or @skill:none -->
+
+## Task List
+
+### Wave 1 (No Dependencies)
+
+<!-- Tasks organized by execution wave -->
+<!-- Wave assignment computed from @depends relationships -->
+
+- [ ] 1.1 [Task description] @skill:none <!-- justification: pure config change -->
+
+### Wave 2 (Depends on Wave 1)
+
+<!-- Tasks that depend on Wave 1 completion -->
+
+- [ ] 2.1 [Task description] @depends:1.1 @skill:none
+
+## Dependency Analysis
+
+<!-- REQUIRED: Status must be COMPLETED after wave analysis -->
+<!-- No task may appear before a task it depends on -->
+
+Status: PENDING
+`;
+}
+/**
+ * Get the minimal tasks.md template (for quick scaffolding)
+ */
+export function getMinimalTasksTemplate() {
+    return `## Pre-Clarification Log
+
+Status: PENDING
+
+## Skill Mapping
+
+| Skill Name | Actual Function | Match Reason |
+|---|---|---|
+
+## Task List
+
+### Wave 1 (No Dependencies)
+
+- [ ] 1.1 [Task description] @skill:none
+
+## Dependency Analysis
+
+Status: PENDING
+`;
+}
+export default {
+    getTasksTemplate,
+    getMinimalTasksTemplate
+};
+//# sourceMappingURL=tasks-template.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * TDD Tasks Template
+ *
+ * Template for generating tasks.md in TDD workflow with required checkpoint sections.
+ * This follows the TDD schema: spec → tests → implementation → docs
+ */
+export interface TddTasksTemplateOptions {
+    changeId: string;
+    testFramework?: string;
+}
+/**
+ * Get the TDD tasks.md template structure with required checkpoint sections
+ */
+export declare function getTddTasksTemplate(options?: TddTasksTemplateOptions): string;
+/**
+ * Get the minimal TDD tasks.md template (for quick scaffolding)
+ */
+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

@@ -0,0 +1,116 @@
+/**
+ * TDD Tasks Template
+ *
+ * Template for generating tasks.md in TDD workflow with required checkpoint sections.
+ * This follows the TDD schema: spec → tests → implementation → docs
+ */
+/**
+ * Get the TDD tasks.md template structure with required checkpoint sections
+ */
+export function getTddTasksTemplate(options) {
+    const changeId = options?.changeId || '[change-id]';
+    const testFramework = options?.testFramework || 'jest';
+    return `# TDD Tasks: ${changeId}
+
+## Pre-Clarification Log
+
+<!-- REQUIRED: Record clarification Q&A or write "Status: COMPLETED - No clarification needed" -->
+<!-- This section MUST NOT be empty or contain only HTML comments -->
+
+Status: PENDING
+
+## Skill Mapping
+
+| Skill Name | Actual Function | Match Reason |
+|---|---|---|
+
+<!-- REQUIRED: Run \`zhuanspec skills list\` and record skill matching decisions -->
+<!-- Every task MUST have either @skill:real-skill-name or @skill:none -->
+
+## Task List
+
+### Wave 1: Specification (No Dependencies)
+
+<!-- Define what to build before writing any code -->
+
+- [ ] 1.1 Write feature specification @skill:none <!-- spec definition -->
+
+### Wave 2: Red Phase - Write Failing Tests
+
+<!-- TDD Red: Write tests that define expected behavior -->
+<!-- Tests should fail initially - this proves they test something meaningful -->
+
+- [ ] 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
+
+### Wave 3: Green Phase - Implementation
+
+<!-- TDD Green: Write minimal code to make tests pass -->
+
+- [ ] 3.1 Implement core logic @depends:2.1 @skill:none
+- [ ] 3.2 Implement edge case handling @depends:3.1 @skill:none
+
+### Wave 4: Refactor Phase
+
+<!-- TDD Refactor: Clean up code while keeping tests green -->
+
+- [ ] 4.1 Refactor for clarity @depends:3.2 @skill:none
+- [ ] 4.2 Optimize performance @depends:4.1 @skill:none
+
+### Wave 5: Documentation
+
+<!-- Document the implemented feature -->
+
+- [ ] 5.1 Update API documentation @depends:4.2 @skill:none
+- [ ] 5.2 Add usage examples @depends:5.1 @skill:none
+
+## Dependency Analysis
+
+<!-- REQUIRED: Status must be COMPLETED after wave analysis -->
+<!-- TDD waves follow strict order: spec → tests → impl → refactor → docs -->
+<!-- No task may appear before a task it depends on -->
+
+Status: PENDING
+`;
+}
+/**
+ * Get the minimal TDD tasks.md template (for quick scaffolding)
+ */
+export function getMinimalTddTasksTemplate() {
+    return `## Pre-Clarification Log
+
+Status: PENDING
+
+## Skill Mapping
+
+| Skill Name | Actual Function | Match Reason |
+|---|---|---|
+
+## Task List
+
+### Wave 1: Specification
+
+- [ ] 1.1 Write feature specification @skill:none
+
+### Wave 2: Red Phase - Tests
+
+- [ ] 2.1 Write failing tests @depends:1.1 @skill:none
+
+### Wave 3: Green Phase - Implementation
+
+- [ ] 3.1 Implement to pass tests @depends:2.1 @skill:none
+
+### Wave 4: Documentation
+
+- [ ] 4.1 Document the feature @depends:3.1 @skill:none
+
+## Dependency Analysis
+
+Status: PENDING
+`;
+}
+export default {
+    getTddTasksTemplate,
+    getMinimalTddTasksTemplate
+};
+//# sourceMappingURL=tdd-tasks-template.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * Strict Validation Rules
+ *
+ * Implementation of three strict validation rules for `zhuanspec validate --strict`:
+ * 1. pre-clarification-completed: Check Pre-Clarification Log section
+ * 2. skill-tags-valid: Validate @skill tags against known skills
+ * 3. task-ordering-by-wave: Verify task ordering follows wave structure
+ */
+import type { ParsedTask } from '../task-graph/types.js';
+export interface StrictCheckResult {
+    ruleId: string;
+    ruleName: string;
+    passed: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface StrictValidationResult {
+    checks: StrictCheckResult[];
+    allPassed: boolean;
+}
+/**
+ * Rule 1: pre-clarification-completed
+ *
+ * Checks that tasks.md has a valid "## Pre-Clarification Log" section.
+ * Valid content includes:
+ *   - Actual Q&A record text
+ *   - "No clarification needed"
+ *   - "Status: COMPLETED"
+ * Invalid:
+ *   - Section missing
+ *   - Section empty (whitespace only)
+ *   - Only HTML comments
+ *   - Contains "TODO", "TBD", "PENDING", "?" unresolved markers
+ */
+export declare function checkPreClarification(tasksContent: string): StrictCheckResult;
+/**
+ * Rule 2: skill-tags-valid
+ *
+ * Validates:
+ *   a. Skill Mapping table exists with at least one data row
+ *   b. Each task has @skill:xxx tag or @skill:none
+ *   c. @skill:none tasks should have a reason in description
+ *   d. All @skill:xxx names must exist in knownSkillNames
+ *   e. Comma-separated multi-skills are validated individually
+ */
+export declare function checkSkillTagsValid(tasksContent: string, parsedTasks: ParsedTask[], knownSkillNames: string[]): StrictCheckResult;
+/**
+ * Rule 3: task-ordering-by-wave
+ *
+ * Validates:
+ *   - Tasks are ordered by wave (wave 1 tasks before wave 2, etc.)
+ *   - Wave headers "### Wave N" match actual computed wave numbers
+ *   - Tasks.md must have Wave headers
+ */
+export declare function checkTaskOrderingByWave(tasksContent: string, parsedTasks: ParsedTask[]): StrictCheckResult;
+/**
+ * Main entry: Run all strict validation rules
+ */
+export declare function runStrictValidation(tasksContent: string, parsedTasks: ParsedTask[], knownSkillNames: string[]): Promise<StrictValidationResult>;
+//# sourceMappingURL=strict-rules.d.ts.map