universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/src/utils/workflow-gate.js

@@ -0,0 +1,292 @@
+/**
+ * WorkflowGate — Phase Transition Validator
+ *
+ * Connects WorkflowStateManager to the workflow definitions to validate
+ * that prerequisites are met before allowing phase transitions.
+ *
+ * @version 1.0.0
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import { execSync } from 'child_process';
+import { WORKFLOW_DEFINITIONS } from '../config/workflow-definitions.js';
+import { WorkflowStateManager, WorkflowStatus } from './workflow-state.js';
+
+/**
+ * Gate result status
+ */
+export const GateResult = {
+  ALLOWED: 'allowed',
+  BLOCKED: 'blocked',
+  WARNING: 'warning'
+};
+
+/**
+ * Enforcement modes
+ */
+export const EnforcementMode = {
+  ENFORCE: 'enforce',
+  SUGGEST: 'suggest',
+  OFF: 'off'
+};
+
+/**
+ * WorkflowGate — validates phase transitions for workflows
+ */
+export class WorkflowGate {
+  /**
+   * @param {string} projectPath - Project root path
+   */
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.enforcementMode = this._loadEnforcementMode();
+  }
+
+  /**
+   * Load enforcement mode from project config
+   * @returns {string} Enforcement mode
+   * @private
+   */
+  _loadEnforcementMode() {
+    const configPath = join(this.projectPath, '.uds', 'config.yaml');
+    if (!existsSync(configPath)) {
+      return EnforcementMode.ENFORCE; // default
+    }
+
+    try {
+      const content = readFileSync(configPath, 'utf-8');
+      const match = content.match(/enforcement_mode:\s*(\w+)/);
+      if (match && Object.values(EnforcementMode).includes(match[1])) {
+        return match[1];
+      }
+    } catch {
+      // Fall through to default
+    }
+
+    return EnforcementMode.ENFORCE;
+  }
+
+  /**
+   * Check if a phase transition is allowed
+   * @param {string} workflowName - Workflow type (sdd, tdd, bdd)
+   * @param {string} targetPhase - Target phase to transition to
+   * @param {Object} [options] - Additional options
+   * @param {string} [options.specFile] - Specific spec file to check
+   * @returns {Object} Gate result: { status, checks, message, guidance }
+   */
+  checkGate(workflowName, targetPhase, options = {}) {
+    // If enforcement is off, always allow
+    if (this.enforcementMode === EnforcementMode.OFF) {
+      return {
+        status: GateResult.ALLOWED,
+        checks: [],
+        message: 'Workflow enforcement is off',
+        guidance: null
+      };
+    }
+
+    const workflow = WORKFLOW_DEFINITIONS[workflowName];
+    if (!workflow) {
+      return {
+        status: GateResult.ALLOWED,
+        checks: [],
+        message: `Unknown workflow: ${workflowName}`,
+        guidance: null
+      };
+    }
+
+    // Get checks for the target phase
+    const phaseChecks = workflow.checks?.[targetPhase] || [];
+    const results = [];
+
+    for (const check of phaseChecks) {
+      const result = this._executeCheck(check, options);
+      results.push(result);
+    }
+
+    // Check for existing workflow state (offer resume)
+    const resumeInfo = this._checkForResumableState(workflowName);
+
+    // Determine overall result
+    const failedChecks = results.filter(r => !r.passed);
+
+    if (failedChecks.length === 0) {
+      return {
+        status: GateResult.ALLOWED,
+        checks: results,
+        message: `All prerequisites met for ${workflowName}:${targetPhase}`,
+        guidance: null,
+        resumeInfo
+      };
+    }
+
+    // In suggest mode, return warning instead of blocked
+    const status = this.enforcementMode === EnforcementMode.SUGGEST
+      ? GateResult.WARNING
+      : GateResult.BLOCKED;
+
+    const guidance = failedChecks
+      .map(c => `- ${c.checkId}: ${c.guidance}`)
+      .join('\n');
+
+    return {
+      status,
+      checks: results,
+      message: `Phase ${targetPhase} prerequisites not met`,
+      guidance,
+      resumeInfo
+    };
+  }
+
+  /**
+   * Execute a single prerequisite check
+   * @param {Object} check - Check definition
+   * @param {Object} options - Additional options
+   * @returns {Object} Check result
+   * @private
+   */
+  _executeCheck(check, options) {
+    // If check has a shell command, execute it
+    if (check.check) {
+      try {
+        let cmd = check.check;
+        // Replace SPEC-XXX with actual spec file if provided
+        if (options.specFile) {
+          cmd = cmd.replace('SPEC-XXX.md', basename(options.specFile));
+        }
+
+        const output = execSync(cmd, {
+          cwd: this.projectPath,
+          encoding: 'utf-8',
+          timeout: 5000,
+          stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+
+        const passed = check.expectedCondition === 'non_empty'
+          ? output.length > 0
+          : output === check.expectedCondition;
+
+        return {
+          checkId: check.id,
+          passed,
+          description: check.description,
+          guidance: check.guidance,
+          output
+        };
+      } catch {
+        // Command failed (e.g., no files found by glob)
+        return {
+          checkId: check.id,
+          passed: false,
+          description: check.description,
+          guidance: check.guidance,
+          output: ''
+        };
+      }
+    }
+
+    // For checks without commands (manual/contextual checks), return as needing manual verification
+    return {
+      checkId: check.id,
+      passed: true, // Cannot verify automatically, assume ok
+      description: check.description,
+      guidance: check.guidance,
+      output: 'manual_check'
+    };
+  }
+
+  /**
+   * Check for existing resumable workflow state
+   * @param {string} workflowName - Workflow type
+   * @returns {Object|null} Resume info or null
+   * @private
+   */
+  _checkForResumableState(workflowName) {
+    const stateManager = new WorkflowStateManager(workflowName, this.projectPath);
+    const state = stateManager.load();
+
+    if (!state) return null;
+
+    if (stateManager.canResume()) {
+      const summary = stateManager.getSummary();
+      return {
+        canResume: true,
+        workflowName: state.workflowName,
+        currentStep: state.currentStepId,
+        status: state.status,
+        progress: summary?.progress,
+        updatedAt: state.updatedAt
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * List all active workflows in the project
+   * @returns {Array} List of active workflow summaries
+   */
+  listActiveWorkflows() {
+    const stateDir = join(this.projectPath, '.standards', 'workflow-state');
+    if (!existsSync(stateDir)) return [];
+
+    const activeWorkflows = [];
+
+    try {
+      const files = readdirSync(stateDir).filter(f => f.endsWith('.json'));
+      for (const file of files) {
+        const workflowName = file.replace('.json', '');
+        const stateManager = new WorkflowStateManager(workflowName, this.projectPath);
+        const state = stateManager.load();
+
+        if (state && [WorkflowStatus.IN_PROGRESS, WorkflowStatus.PAUSED].includes(state.status)) {
+          const summary = stateManager.getSummary();
+          activeWorkflows.push({
+            workflowName: state.workflowName,
+            status: state.status,
+            currentStep: state.currentStepId,
+            progress: summary?.progress,
+            updatedAt: state.updatedAt,
+            startedAt: state.startedAt
+          });
+        }
+      }
+    } catch {
+      // Return empty if can't read
+    }
+
+    return activeWorkflows;
+  }
+
+  /**
+   * Get a formatted report of active workflows (for session start)
+   * @returns {string|null} Formatted report or null if no active workflows
+   */
+  getSessionStartReport() {
+    const activeWorkflows = this.listActiveWorkflows();
+
+    if (activeWorkflows.length === 0) return null;
+
+    const lines = ['## Active Workflows | 進行中的工作流程', ''];
+
+    for (const wf of activeWorkflows) {
+      const progress = wf.progress
+        ? `${wf.progress.completed}/${wf.progress.total} steps (${wf.progress.percentage}%)`
+        : 'unknown';
+
+      lines.push(`- **${wf.workflowName}** — ${wf.status}`);
+      lines.push(`  - Current step: ${wf.currentStep || 'N/A'}`);
+      lines.push(`  - Progress: ${progress}`);
+      lines.push(`  - Last updated: ${wf.updatedAt}`);
+      lines.push('');
+    }
+
+    lines.push('> Resume with the corresponding workflow command (e.g., `/sdd implement`)');
+    lines.push('> 使用對應的工作流程命令恢復（例如 `/sdd implement`）');
+
+    return lines.join('\n');
+  }
+}
+
+export default WorkflowGate;

package/standards-registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.0.0-rc.8",
-  "lastUpdated": "2026-03-16",
+  "version": "5.0.0",
+  "lastUpdated": "2026-03-23",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
     "ai": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "5.0.0-rc.8"
+      "version": "5.0.0"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "5.0.0-rc.8",
+      "version": "5.0.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -771,6 +771,30 @@
       "skillName": null,
       "description": "Safe deployment strategies, feature flags, rollback, environment parity, and DORA metrics"
     },
+    {
+      "id": "api-design-standards",
+      "name": "API Design Standards",
+      "nameZh": "API 設計標準",
+      "source": {
+        "human": "core/api-design-standards.md",
+        "ai": "ai/standards/api-design-standards.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "REST, GraphQL, and gRPC API design principles, versioning, pagination, authentication, and error handling"
+    },
+    {
+      "id": "database-standards",
+      "name": "Database Standards",
+      "nameZh": "資料庫標準",
+      "source": {
+        "human": "core/database-standards.md",
+        "ai": "ai/standards/database-standards.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Schema design, migration strategy, indexing, query optimization, and data integrity"
+    },
     {
       "id": "spec-driven-development",
       "name": "Spec-Driven Development",
@@ -947,6 +971,18 @@
       "skillName": null,
       "description": "Protocol for persisting and restoring workflow state across AI sessions"
     },
+    {
+      "id": "workflow-enforcement",
+      "name": "Workflow Enforcement",
+      "nameZh": "工作流程強制執行",
+      "source": {
+        "human": "core/workflow-enforcement.md",
+        "ai": "ai/standards/workflow-enforcement.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Machine-enforceable workflow gates that prevent phase skipping in SDD/TDD/BDD methodologies"
+    },
     {
       "id": "testing",
       "name": "Testing Standards",
@@ -1162,6 +1198,17 @@
       "category": "reference",
       "description": "Protocols for establishing service-level agreements and context contracts between AI agents"
     },
+    {
+      "id": "ai-command-behavior",
+      "name": "AI Command Behavior Standards",
+      "nameZh": "AI 命令行為標準",
+      "source": {
+        "human": "core/ai-command-behavior.md",
+        "ai": "ai/standards/ai-command-behavior.ai.yaml"
+      },
+      "category": "reference",
+      "description": "Standard structure for specifying AI Agent runtime behavior in command/skill definition files"
+    },
     {
       "id": "virtual-organization",
       "name": "Virtual Organization Standards",
@@ -1424,6 +1471,42 @@
       "skillName": "requirement-assistant",
       "description": "Template for writing comprehensive requirement documents"
     },
+    {
+      "id": "pipeline-integration",
+      "name": "Pipeline Integration Standards",
+      "nameZh": "Pipeline 整合標準",
+      "source": {
+        "human": "core/pipeline-integration-standards.md",
+        "ai": "ai/standards/pipeline-integration-standards.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Configuration contract, stage model, and context classification for automated development pipelines"
+    },
+    {
+      "id": "acceptance-criteria-traceability",
+      "name": "Acceptance Criteria Traceability Standards",
+      "nameZh": "驗收條件追蹤標準",
+      "source": {
+        "human": "core/acceptance-criteria-traceability.md",
+        "ai": "ai/standards/acceptance-criteria-traceability.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "AC-to-test traceability matrix, coverage calculation, and spec generation quality rules"
+    },
+    {
+      "id": "change-batching",
+      "name": "Change Batching Standards",
+      "nameZh": "變更批次合併標準",
+      "source": {
+        "human": "core/change-batching-standards.md",
+        "ai": "ai/standards/change-batching-standards.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Pending changes state machine, threshold strategies, and atomicity guarantees for batch commits"
+    },
     {
       "id": "migration-template",
       "name": "Migration Plan Template",
@@ -1433,6 +1516,78 @@
       "skillName": null,
       "description": "Template for planning technology migrations",
       "applicability": "Migration projects"
+    },
+    {
+      "id": "systematic-debugging",
+      "name": "Systematic Debugging Workflow",
+      "nameZh": "系統化除錯工作流",
+      "source": {
+        "human": "core/systematic-debugging.md",
+        "ai": "ai/standards/systematic-debugging.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": null,
+      "description": "Four-phase debugging workflow (Root Cause → Pattern Analysis → Hypothesis Testing → Fix) with 3-Strike Rule"
+    },
+    {
+      "id": "agent-dispatch",
+      "name": "Agent Dispatch & Parallel Coordination",
+      "nameZh": "子代理派遣與並行協調",
+      "source": {
+        "human": "core/agent-dispatch.md",
+        "ai": "ai/standards/agent-dispatch.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": null,
+      "description": "Sub-agent dispatch, parallel coordination, and status protocol (DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED)"
+    },
+    {
+      "id": "model-selection",
+      "name": "AI Model Selection Strategy",
+      "nameZh": "AI 模型分級選擇策略",
+      "source": {
+        "human": "core/model-selection.md",
+        "ai": "ai/standards/model-selection.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": null,
+      "description": "Three-tier model selection strategy (fast/standard/capable) with cost-effective escalation"
+    },
+    {
+      "id": "git-worktree",
+      "name": "Git Worktree Isolation",
+      "nameZh": "Git Worktree 隔離開發",
+      "source": {
+        "human": "core/git-worktree.md",
+        "ai": "ai/standards/git-worktree.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Git worktree lifecycle management: setup → baseline → execute → merge → cleanup"
+    },
+    {
+      "id": "branch-completion",
+      "name": "Branch Completion Workflow",
+      "nameZh": "分支完成工作流",
+      "source": {
+        "human": "core/branch-completion.md",
+        "ai": "ai/standards/branch-completion.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Branch completion workflow with 4 options (merge/PR/keep/discard) and prerequisite checks"
+    },
+    {
+      "id": "verification-evidence",
+      "name": "Verification Evidence Standard",
+      "nameZh": "驗證證據標準",
+      "source": {
+        "human": "core/verification-evidence.md",
+        "ai": "ai/standards/verification-evidence.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": null,
+      "description": "Iron Law: no verification evidence = no completion claim. RED-GREEN cycle for bug fixes"
     }
   ]
-}
+}