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

package/src/utils/integration-generator.js

@@ -47,7 +47,8 @@ const STANDARD_TASK_MAPPING = {
   'test-completeness-dimensions.md': { task: 'Test coverage', when: 'When evaluating tests', priority: 'SHOULD' },
   'git-workflow.ai.yaml': { task: 'Git workflow', when: 'Branch/merge decisions', priority: 'SHOULD' },
   'developer-memory.ai.yaml': { task: 'Developer memory', when: 'Always (protocol)', priority: 'SHOULD' },
-  'project-context-memory.ai.yaml': { task: 'Project context', when: 'Planning & Coding', priority: 'MUST' }
+  'project-context-memory.ai.yaml': { task: 'Project context', when: 'Planning & Coding', priority: 'MUST' },
+  'workflow-enforcement.ai.yaml': { task: 'Workflow gates', when: 'Before any workflow phase', priority: 'MUST' }
 };
 
 /**
@@ -68,7 +69,8 @@ const STANDARD_DESCRIPTIONS = {
   'git-workflow.ai.yaml': 'Git 工作流程',
   'developer-memory.ai.yaml': '開發者持久記憶',
   'project-context-memory.ai.yaml': '專案情境記憶',
-  'zh-tw.md': '繁體中文本地化'
+  'zh-tw.md': '繁體中文本地化',
+  'workflow-enforcement.ai.yaml': '工作流程強制執行'
 };
 
 /**
@@ -236,7 +238,7 @@ function generateCommitStandardsContent(commitLanguage, detailLevel = 'standard'
 
     if (commitLanguage === 'traditional-chinese') {
       return `## 提交訊息標準
-參考: .standards/commit-message-guide.md, .standards/options/traditional-chinese.ai.yaml
+參考: .standards/commit-message.ai.yaml, .standards/options/traditional-chinese.ai.yaml
 
 ### 格式
 \`\`\`
@@ -256,7 +258,7 @@ ${typesTable}
 - 本文: 說明做了什麼及為什麼，而非如何做`;
     } else if (commitLanguage === 'bilingual') {
       return `## Commit Message Standards | 提交訊息標準
-Reference: .standards/commit-message-guide.md, .standards/options/bilingual.ai.yaml
+Reference: .standards/commit-message.ai.yaml, .standards/options/bilingual.ai.yaml
 
 ### Format | 格式
 \`\`\`
@@ -279,7 +281,7 @@ ${typesTable}
 - NEVER mix languages in one paragraph | 禁止同段落混合語言`;
     } else if (commitLanguage === 'bilingual-zhcn') {
       return `## Commit Message Standards | 提交消息标准
-Reference: .standards/commit-message-guide.md, .standards/options/bilingual.ai.yaml
+Reference: .standards/commit-message.ai.yaml, .standards/options/bilingual.ai.yaml
 
 ### Format | 格式
 \`\`\`
@@ -302,7 +304,7 @@ ${typesTable}
 - NEVER mix languages in one paragraph | 禁止同段落混合语言`;
     } else {
       return `## Commit Message Standards
-Reference: .standards/commit-message-guide.md
+Reference: .standards/commit-message.ai.yaml
 
 ### Format
 \`\`\`
@@ -328,7 +330,7 @@ ${typesTable}
 
   if (commitLanguage === 'traditional-chinese') {
     return `## 提交訊息標準
-參考: .standards/commit-message-guide.md, .standards/options/traditional-chinese.ai.yaml
+參考: .standards/commit-message.ai.yaml, .standards/options/traditional-chinese.ai.yaml
 
 ### 格式結構
 \`\`\`
@@ -361,7 +363,7 @@ ${typesTable}
 - 共同作者: \`Co-authored-by: Name <email>\``;
   } else if (commitLanguage === 'bilingual') {
     return `## Commit Message Standards | 提交訊息標準
-Reference: .standards/commit-message-guide.md, .standards/options/bilingual.ai.yaml
+Reference: .standards/commit-message.ai.yaml, .standards/options/bilingual.ai.yaml
 
 ### Format Structure | 格式結構
 \`\`\`
@@ -415,7 +417,7 @@ Closes #123
 - Co-authors: \`Co-authored-by: Name <email>\``;
   } else if (commitLanguage === 'bilingual-zhcn') {
     return `## Commit Message Standards | 提交消息标准
-Reference: .standards/commit-message-guide.md, .standards/options/bilingual.ai.yaml
+Reference: .standards/commit-message.ai.yaml, .standards/options/bilingual.ai.yaml
 
 ### Format Structure | 格式结构
 \`\`\`
@@ -469,7 +471,7 @@ Closes #123
 - Co-authors: \`Co-authored-by: Name <email>\``;
   } else {
     return `## Commit Message Standards
-Reference: .standards/commit-message-guide.md
+Reference: .standards/commit-message.ai.yaml
 
 ### Format Structure
 \`\`\`
@@ -772,7 +774,7 @@ If you realize you made an incorrect statement:
     },
     standard: {
       en: `## Commit Message Standards
-Reference: .standards/commit-message-guide.md
+Reference: .standards/commit-message.ai.yaml
 
 ### Format
 \`\`\`
@@ -797,7 +799,7 @@ Reference: .standards/commit-message-guide.md
 - Use imperative mood: "add" not "added"
 - Body: explain what and why, not how`,
       'zh-tw': `## 提交訊息標準
-參考: .standards/commit-message-guide.md
+參考: .standards/commit-message.ai.yaml
 
 ### 格式
 \`\`\`
@@ -824,7 +826,7 @@ Reference: .standards/commit-message-guide.md
     },
     comprehensive: {
       en: `## Commit Message Standards
-Reference: .standards/commit-message-guide.md
+Reference: .standards/commit-message.ai.yaml
 
 ### Format Structure
 \`\`\`
@@ -864,7 +866,7 @@ Reference: .standards/commit-message-guide.md
 - Issue references: \`Fixes #123\`, \`Closes #456\`
 - Co-authors: \`Co-authored-by: Name <email>\``,
       'zh-tw': `## 提交訊息標準
-參考: .standards/commit-message-guide.md
+參考: .standards/commit-message.ai.yaml
 
 ### 格式結構
 \`\`\`
@@ -2486,6 +2488,89 @@ function generateCommitLanguageDirective(commitLanguage, language) {
   return null;
 }
 
+/**
+ * Generate workflow enforcement gate content for integration files
+ * @param {string} language - Language: 'en', 'zh-tw', 'zh-cn', or 'bilingual'
+ * @returns {string} Generated workflow gate instructions
+ */
+function generateWorkflowGateContent(language) {
+  const sections = [];
+
+  if (language === 'zh-tw' || language === 'bilingual') {
+    sections.push('## Workflow Enforcement Gates / 工作流程強制閘門');
+    sections.push('');
+    sections.push('**CRITICAL**: Before executing any workflow phase command, you MUST check prerequisites.');
+    sections.push('**關鍵規則**：在執行任何工作流程階段命令前，你必須檢查前置條件。');
+    sections.push('');
+    sections.push('### Session Start Protocol / Session 啟動協議');
+    sections.push('At session start, check for active workflows:');
+    sections.push('```bash');
+    sections.push('ls .workflow-state/*.yaml 2>/dev/null');
+    sections.push('```');
+    sections.push('If active workflows found → inform user and offer to resume.');
+    sections.push('');
+    sections.push('### Phase Gates / 階段閘門');
+    sections.push('| Workflow | Phase | Prerequisite | On Failure |');
+    sections.push('|---------|-------|-------------|------------|');
+    sections.push('| SDD | implement | Spec status = Approved | → `/sdd approve` |');
+    sections.push('| SDD | verify | All ACs have code + tests | → `/sdd implement` |');
+    sections.push('| TDD | GREEN | Failing test exists | → Stay in RED |');
+    sections.push('| TDD | REFACTOR | All tests passing | → Stay in GREEN |');
+    sections.push('| BDD | AUTOMATION | `.feature` file exists | → FORMULATION |');
+    sections.push('| Commit | feat/fix | Check active specs | → Suggest `Refs: SPEC-XXX` |');
+    sections.push('');
+    sections.push('Reference: `.standards/workflow-enforcement.ai.yaml`');
+  } else if (language === 'zh-cn') {
+    sections.push('## 工作流程强制闸门');
+    sections.push('');
+    sections.push('**关键规则**：在执行任何工作流程阶段命令前，你必须检查前置条件。');
+    sections.push('');
+    sections.push('### Session 启动协议');
+    sections.push('每次 Session 开始时，检查活跃的工作流：');
+    sections.push('```bash');
+    sections.push('ls .workflow-state/*.yaml 2>/dev/null');
+    sections.push('```');
+    sections.push('如发现活跃工作流 → 通知用户并建议恢复。');
+    sections.push('');
+    sections.push('### 阶段闸门');
+    sections.push('| 工作流 | 阶段 | 前置条件 | 失败时 |');
+    sections.push('|--------|------|---------|--------|');
+    sections.push('| SDD | implement | Spec 状态 = Approved | → `/sdd approve` |');
+    sections.push('| SDD | verify | 所有 AC 有代码和测试 | → `/sdd implement` |');
+    sections.push('| TDD | GREEN | 存在失败的测试 | → 留在 RED |');
+    sections.push('| TDD | REFACTOR | 所有测试通过 | → 留在 GREEN |');
+    sections.push('| BDD | AUTOMATION | `.feature` 文件存在 | → FORMULATION |');
+    sections.push('| Commit | feat/fix | 检查活跃 spec | → 建议 `Refs: SPEC-XXX` |');
+    sections.push('');
+    sections.push('参考: `.standards/workflow-enforcement.ai.yaml`');
+  } else {
+    sections.push('## Workflow Enforcement Gates');
+    sections.push('');
+    sections.push('**CRITICAL**: Before executing any workflow phase command, you MUST check prerequisites.');
+    sections.push('');
+    sections.push('### Session Start Protocol');
+    sections.push('At session start, check for active workflows:');
+    sections.push('```bash');
+    sections.push('ls .workflow-state/*.yaml 2>/dev/null');
+    sections.push('```');
+    sections.push('If active workflows found → inform user and offer to resume.');
+    sections.push('');
+    sections.push('### Phase Gates');
+    sections.push('| Workflow | Phase | Prerequisite | On Failure |');
+    sections.push('|---------|-------|-------------|------------|');
+    sections.push('| SDD | implement | Spec status = Approved | → `/sdd approve` |');
+    sections.push('| SDD | verify | All ACs have code + tests | → `/sdd implement` |');
+    sections.push('| TDD | GREEN | Failing test exists | → Stay in RED |');
+    sections.push('| TDD | REFACTOR | All tests passing | → Stay in GREEN |');
+    sections.push('| BDD | AUTOMATION | `.feature` file exists | → FORMULATION |');
+    sections.push('| Commit | feat/fix | Check active specs | → Suggest `Refs: SPEC-XXX` |');
+    sections.push('');
+    sections.push('Reference: `.standards/workflow-enforcement.ai.yaml`');
+  }
+
+  return sections.join('\n');
+}
+
 /**
  * Generate integration file content
  * @param {Object} config - Integration configuration
@@ -2590,6 +2675,13 @@ export function generateIntegrationContent(config) {
     sections.push('\n---\n');
   }
 
+  // Add workflow enforcement gates if workflow-enforcement standard is installed
+  if (installedStandards.some(s => basename(s) === 'workflow-enforcement.ai.yaml')) {
+    const workflowGateContent = generateWorkflowGateContent(language);
+    sections.push(workflowGateContent);
+    sections.push('\n---\n');
+  }
+
   // Add language-specific rules
   const langRules = getLanguageRules();
   for (const lang of languages) {
@@ -2968,6 +3060,227 @@ export function getToolFilePath(tool) {
 
 
 
+/**
+ * Detect build/test commands based on project files
+ * @param {string} [projectPath] - Project root path
+ * @returns {string[]} Array of command lines
+ */
+function detectBuildCommands(projectPath) {
+  if (!projectPath) {
+    return [
+      '# Check project configuration for build commands',
+      'npm install      # Install dependencies (Node.js)',
+      'npm test         # Run tests',
+      'npm run lint     # Check code style'
+    ];
+  }
+
+  const commands = [];
+
+  const hasFile = (name) => existsSync(join(projectPath, name));
+
+  if (hasFile('package.json')) {
+    // Read package.json scripts for accurate commands
+    try {
+      const pkg = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf-8'));
+      const scripts = pkg.scripts || {};
+      commands.push('npm install      # Install dependencies');
+      if (scripts.build) {
+        commands.push('npm run build    # Build project');
+      }
+      if (scripts.test) {
+        commands.push('npm test         # Run tests');
+      }
+      if (scripts.lint) {
+        commands.push('npm run lint     # Check code style');
+      }
+      // Fallback if no test/lint scripts found
+      if (!scripts.test && !scripts.lint && !scripts.build) {
+        commands.push('# See package.json "scripts" for available commands');
+      }
+    } catch {
+      commands.push('npm install      # Install dependencies');
+      commands.push('npm test         # Run tests');
+      commands.push('npm run lint     # Check code style');
+    }
+  } else if (hasFile('pyproject.toml') || hasFile('setup.py')) {
+    commands.push('pip install -e .   # Install in development mode');
+    commands.push('pytest             # Run tests');
+    commands.push('ruff check .       # Check code style');
+  } else if (hasFile('Cargo.toml')) {
+    commands.push('cargo build        # Build project');
+    commands.push('cargo test         # Run tests');
+    commands.push('cargo clippy       # Check code style');
+  } else if (hasFile('go.mod')) {
+    commands.push('go build ./...     # Build project');
+    commands.push('go test ./...      # Run tests');
+    commands.push('go vet ./...       # Check code');
+  } else if (hasFile('Makefile')) {
+    commands.push('make               # Build project');
+    commands.push('make test          # Run tests');
+    commands.push('make lint          # Check code style');
+  } else {
+    commands.push('# Check project configuration for build commands');
+  }
+
+  return commands;
+}
+
+/**
+ * Generate a concise AGENTS.md summary file (≤ 150 lines)
+ * Follows AAIF best practices: commands, testing, structure, style, git, boundaries
+ *
+ * @param {Object} config - Generation configuration
+ * @param {string[]} config.installedStandards - List of installed standard file names
+ * @param {string} [config.language='en'] - Display language
+ * @param {string} [config.commitLanguage='english'] - Commit message language
+ * @param {Object} [config.standardOptions={}] - Standard options (workflow, merge_strategy, etc.)
+ * @param {string} [config.projectPath] - Project root path for detecting build tools
+ * @returns {string} AGENTS.md content (≤ 150 lines)
+ */
+export function generateAgentsMdSummary(config = {}) {
+  const {
+    installedStandards = [],
+    language = 'en',
+    commitLanguage = 'english',
+    standardOptions = {},
+    projectPath
+  } = config;
+
+  const lines = [];
+
+  // Header
+  lines.push('# AGENTS.md');
+  lines.push('');
+  lines.push('> Auto-generated by [Universal Dev Standards (UDS)](https://github.com/AsiaOstrich/universal-dev-standards).');
+  lines.push('> Full standards available in the `.standards/` directory.');
+  lines.push('');
+
+  // Build & Test Commands (auto-detect project type)
+  lines.push('## Build & Test');
+  lines.push('');
+  lines.push('```bash');
+  const buildCommands = detectBuildCommands(projectPath);
+  for (const cmd of buildCommands) {
+    lines.push(cmd);
+  }
+  lines.push('```');
+  lines.push('');
+
+  // Code Style
+  lines.push('## Code Style');
+  lines.push('');
+  lines.push('Follow the project\'s linter and formatter configuration.');
+  lines.push('See `.standards/` for detailed coding standards.');
+  lines.push('');
+
+  // Git Workflow
+  lines.push('## Git Workflow');
+  lines.push('');
+  const workflow = standardOptions.workflow || 'github-flow';
+  const mergeStrategy = standardOptions.merge_strategy || 'squash';
+  lines.push(`- **Workflow**: ${workflow}`);
+  lines.push(`- **Merge Strategy**: ${mergeStrategy}`);
+
+  // Commit language
+  if (commitLanguage === 'english') {
+    lines.push('- **Commit Language**: English');
+    lines.push('- **Format**: `<type>(<scope>): <subject>`');
+  } else if (commitLanguage === 'traditional-chinese') {
+    lines.push('- **Commit Language**: Traditional Chinese (繁體中文)');
+    lines.push('- **Format**: `<type>(<scope>): <主旨>`');
+  } else if (commitLanguage === 'bilingual') {
+    lines.push('- **Commit Language**: Bilingual (English + Chinese)');
+    lines.push('- **Format**: `<type>(<scope>): <subject>. <主旨>`');
+  }
+  lines.push('');
+
+  // Testing
+  lines.push('## Testing');
+  lines.push('');
+  lines.push('- Write tests for all new features');
+  lines.push('- Run tests before committing');
+  lines.push('- Follow the testing pyramid: Unit (70%) > Integration (20%) > E2E (10%)');
+  lines.push('');
+
+  // Installed Standards Index
+  lines.push('<!-- UDS:STANDARDS:START -->');
+  lines.push('## Installed Standards');
+  lines.push('');
+
+  if (installedStandards.length > 0) {
+    lines.push('All standards are in `.standards/`. Key standards:');
+    lines.push('');
+
+    // Group and show key standards (limited to keep within 150 lines)
+    const keyStandards = installedStandards
+      .filter(s => {
+        const name = basename(s);
+        return name.endsWith('.ai.yaml');
+      })
+      .slice(0, 30); // Limit to avoid exceeding 150 lines
+
+    for (const std of keyStandards) {
+      const name = basename(std).replace('.ai.yaml', '');
+      lines.push(`- \`.standards/${basename(std)}\` — ${name}`);
+    }
+  } else {
+    lines.push('No standards installed yet. Run `npx uds init` to install.');
+  }
+
+  lines.push('');
+  lines.push('<!-- UDS:STANDARDS:END -->');
+  lines.push('');
+
+  // Boundaries
+  lines.push('## Important Notes');
+  lines.push('');
+  lines.push('- Read `.standards/` files for complete rules before making changes');
+  lines.push('- Do not fabricate APIs, configs, or requirements without verification');
+  lines.push('- Follow the anti-hallucination standard: evidence-based responses only');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write universal AGENTS.md summary file
+ * Handles marker-based updates if file already exists
+ *
+ * @param {Object} config - Generation configuration
+ * @param {string} projectPath - Project root path
+ * @returns {Object} Result with success status
+ */
+export function writeAgentsMdSummary(config, projectPath) {
+  const filePath = join(projectPath, 'AGENTS.md');
+
+  try {
+    let content = generateAgentsMdSummary({ ...config, projectPath });
+
+    // Handle merge if file exists (preserve user content outside markers)
+    if (existsSync(filePath)) {
+      const existingContent = readFileSync(filePath, 'utf-8');
+      const newParts = extractMarkedContent(content, 'markdown');
+      if (newParts.content) {
+        content = updateMarkedSection(existingContent, newParts.content, 'markdown');
+      }
+    }
+
+    writeFileSync(filePath, content);
+
+    const blockHashInfo = computeIntegrationBlockHash(filePath);
+
+    return {
+      success: true,
+      path: 'AGENTS.md',
+      absolutePath: filePath,
+      blockHashInfo
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
 /**
  * Get all supported tools
  * @returns {string[]} Array of tool names