jsharness 1.0.0

package/.harness/workflow/validate.js

@@ -0,0 +1,320 @@
+/**
+ * Harness Workflow 校验脚本
+ * 
+ * 用途：检查 workflow 定义文件的完整性和一致性
+ * 运行：node .harness/workflow/validate.js
+ * 
+ * 校验项目：
+ * 1. 阶段完整性 — 7 个核心阶段是否全部定义
+ * 2. Agent-阶段映射一致性 — 每个 stage 有对应的 agent 定义
+ * 3. 回退引用有效性 — 所有的 transition.to 引用的阶段都存在
+ * 4. 契约文件齐全性 — 每个 agent 目录下都有 contract.yaml
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
+// 配置常量
+// ============================================================
+
+const HARNESS_ROOT = path.resolve(__dirname, '..');
+const WORKFLOW_DIR = path.join(HARNESS_ROOT, 'workflow');
+const AGENTS_DIR = path.join(HARNESS_ROOT, 'agents');
+const DEFINITION_FILE = path.join(WORKFLOW_DIR, 'definition.yaml');
+const VARIANTS_FILE = path.join(WORKFLOW_DIR, 'variants.yaml');
+
+// 核心阶段 ID 列表（必须存在）
+const REQUIRED_STAGES = [
+  'requirements-analysis',
+  'solution-design', 
+  'gate-evaluation',
+  'development',
+  'code-review',
+  'testing',
+  'delivery'
+];
+
+// Agent ID 到目录名的映射
+const AGENT_MAP = {
+  'project-manager': 'project-manager',
+  'requirements-analyst': 'requirements-analyst',
+  'solution-designer': 'solution-designer',
+  'gate-controller': 'gate-controller',
+  'developer': 'developer',
+  'code-reviewer': 'code-reviewer',
+  'tester': 'tester'
+};
+
+// ============================================================
+// 校验逻辑
+// ============================================================
+
+class WorkflowValidator {
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+    this.passed = [];
+  }
+
+  /**
+   * 执行所有校验
+   */
+  validateAll() {
+    console.log('=== Harness Workflow Validator ===\n');
+    
+    this.checkStageCompleteness();
+    this.checkAgentMapping();
+    this.checkTransitionValidity();
+    this.checkContractFiles();
+    this.checkVariantsFile();
+    
+    this.printResults();
+    return this.errors.length === 0;
+  }
+
+  // ----------------------------------------------------------
+  // 1. 阶段完整性检查
+  // ----------------------------------------------------------
+  checkStageCompleteness() {
+    console.log('📋 检查 1/5: 阶段完整性...');
+    
+    if (!fs.existsSync(DEFINITION_FILE)) {
+      this.errors.push(`❌ 定义文件不存在: ${DEFINITION_FILE}`);
+      return;
+    }
+    
+    const content = fs.readFileSync(DEFINITION_FILE, 'utf-8');
+    
+    for (const stageId of REQUIRED_STAGES) {
+      // 使用正则匹配阶段定义
+      const pattern = new RegExp(`id:\\s*${stageId.replace('-', '\\-')}`, 'i');
+      if (pattern.test(content)) {
+        this.passed.push(`  ✅ 阶段 "${stageId}" 已定义`);
+      } else {
+        this.errors.push(`  ❌ 缺少阶段定义: ${stageId}`);
+      }
+    }
+
+    // 检查顺序连续性
+    const orderPattern = /order:\s*(\d+)/g;
+    let orders = [];
+    let match;
+    while ((match = orderPattern.exec(content)) !== null) {
+      orders.push(parseInt(match[1]));
+    }
+    orders.sort((a, b) => a - b);
+    
+    if (orders.length >= REQUIRED_STAGES.length) {
+      for (let i = 0; i < orders.length; i++) {
+        if (orders[i] !== i + 1) {
+          this.warnings.push(`  ⚠️ 阶段序号可能不连续: 期望 ${i+1}, 找到 ${orders[i]}`);
+          break;
+        }
+      }
+    }
+  }
+
+  // ----------------------------------------------------------
+  // 2. Agent-阶段映射检查
+  // ----------------------------------------------------------
+  checkAgentMapping() {
+    console.log('📋 检查 2/5: Agent-阶段映射一致性...');
+    
+    if (!fs.existsSync(AGENTS_DIR)) {
+      this.errors.push(`❌ Agents 目录不存在: ${AGENTS_DIR}`);
+      return;
+    }
+    
+    const content = fs.readFileSync(DEFINITION_FILE, 'utf-8');
+    
+    for (const [agentId, dirName] of Object.entries(AGENT_MAP)) {
+      const contractPath = path.join(AGENTS_DIR, dirName, 'contract.yaml');
+      
+      // 检查契约文件是否存在
+      if (fs.existsSync(contractPath)) {
+        this.passed.push(`  ✅ Agent "${agentId}" 契约文件存在`);
+        
+        // 检查 workflow 中是否引用了此 agent
+        const agentPattern = new RegExp(`agent:\\s*${agentId.replace('-', '\\-')}`, 'i');
+        if (agentPattern.test(content)) {
+          this.passed.push(`  ✅ Agent "${agentId}" 在 workflow 中被使用`);
+        } else {
+          this.warnings.push(`  ⚠️ Agent "${agentId}" 有契约但在 workflow 中未被分配阶段`);
+        }
+      } else {
+        this.errors.push(`  ❌ Agent "${agentId}" 缺少契约文件: ${contractPath}`);
+      }
+      
+      // 检查 Prompt 模板
+      const promptPath = path.join(AGENTS_DIR, dirName, 'prompt.md') ||
+                         path.join(AGENTS_DIR, 'prompt-templates.md');
+      // prompt 可以在统一文件中，这里只做警告
+    }
+  }
+
+  // ----------------------------------------------------------
+  // 3. 回退引用有效性检查
+  // ----------------------------------------------------------
+  checkTransitionValidity() {
+    console.log('📋 检查 3/5: Transition 引用有效性...');
+    
+    if (!fs.existsSync(DEFINITION_FILE)) return;
+    
+    const content = fs.readFileSync(DEFINITION_FILE, 'utf-8');
+    
+    // 收集所有已定义的阶段 ID（包括特殊状态）
+    const validTargets = new Set([
+      ...REQUIRED_STAGES,
+      'cancelled', 'completed', 'self', '*'
+    ]);
+    
+    // 匹配所有 transition targets
+    const transPattern = /to:\s*([\w-]+)/g;
+    let match;
+    const foundTargets = new Set();
+    
+    while ((match = transPattern.exec(content)) !== null) {
+      const target = match[1];
+      foundTargets.add(target);
+      
+      if (validTargets.has(target)) {
+        // 有效引用
+      } else {
+        // 可能是子流程中的自定义目标，只警告
+        if (!target.startsWith('_')) {
+          this.warnings.push(
+            `  ⚠️ Transition 目标 "${target}" 可能不在已知阶段列表中`
+          );
+        }
+      }
+    }
+    
+    this.passed.push(`  ✅ 检查了 ${foundTargets.size} 个 transition 目标`);
+  }
+
+  // ----------------------------------------------------------
+  // 4. 契约文件齐全性检查
+  // ----------------------------------------------------------
+  checkContractFiles() {
+    console.log('📋 检查 4/5: Agent 契约文件齐全性...');
+    
+    if (!fs.existsSync(AGENTS_DIR)) {
+      this.errors.push(`  ❌ Agents 目录不存在`);
+      return;
+    }
+    
+    const dirs = fs.readdirSync(AGENTS_DIR, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    
+    for (const dirName of dirs) {
+      const dirPath = path.join(AGENTS_DIR, dirName);
+      const files = fs.readdirSync(dirPath);
+      
+      const hasContract = files.some(f => f === 'contract.yaml' || f === 'contract.yml');
+      const hasPrompt = files.some(f => 
+        f === 'prompt.md' || f === 'prompt.yaml' || f === 'prompt.yml'
+      );
+      
+      if (hasContract && hasPrompt) {
+        this.passed.push(`  ✅ ${dirName}/: contract + prompt 都存在`);
+      } else if (hasContract) {
+        this.warnings.push(`  ⚠️ ${dirName}/: 有 contract 但缺少 prompt`);
+      } else {
+        this.errors.push(`  ❌ ${dirName}/: 缺少 contract.yaml`);
+      }
+    }
+  }
+
+  // ----------------------------------------------------------
+  // 5. 变体文件检查
+  // ----------------------------------------------------------
+  checkVariants() {
+    console.log('📋 检查 5/5: 变体定义文件...');
+    
+    if (fs.existsSync(VARIANTS_FILE)) {
+      const content = fs.readFileSync(VARIANTS_FILE, 'utf-8');
+      const variantCount = (content.match(/variant_id:/g) || []).length;
+      this.passed.push(`  ✅ variants.yaml 存在，包含 ${variantCount} 个变体定义`);
+      
+      // 检查必要变体
+      const expectedVariants = ['bugfix-lightweight', 'hotfix-emergency', 'doc-config-micro'];
+      for (const v of expectedVariants) {
+        if (content.includes(v)) {
+          this.passed.push(`  ✅ 变体 "${v}" 已定义`);
+        } else {
+          this.warnings.push(`  ⚠️ 推荐的变体 "${v}" 未找到`);
+        }
+      }
+    } else {
+      this.warnings.push(`  ⚠️ variants.yaml 不存在（变体流程将不可用）`);
+    }
+  }
+
+  // ----------------------------------------------------------
+  // 结果输出
+  // ----------------------------------------------------------
+  printResults() {
+    console.log('\n═════════════════════════════════════════');
+    console.log('校验结果\n');
+    
+    if (this.passed.length > 0) {
+      console.log(`✅ 通过 (${this.passed.length}):`);
+      this.passed.forEach(p => console.log(p));
+    }
+    
+    if (this.warnings.length > 0) {
+      console.log(`\n⚠️  警告 (${this.warnings.length}):`);
+      this.warnings.forEach(w => console.log(w));
+    }
+    
+    if (this.errors.length > 0) {
+      console.log(`\n❌ 错误 (${this.errors.length}):`);
+      this.errors.forEach(e => console.log(e));
+    }
+    
+    console.log('\n═════════════════════════════════════════');
+    
+    const status = this.errors.length === 0 ? '✅ PASSED' : '❌ FAILED';
+    const summary = `总计: ${this.passed.length} 通过, ${this.warnings.length} 警告, ${this.errors.length} 错误`;
+    console.log(`${status} | ${summary}\n`);
+    
+    // 输出 JSON 格式供程序调用
+    const resultJson = JSON.stringify({
+      status: this.errors.length === 0 ? 'pass' : 'fail',
+      passed: this.passed.length,
+      warnings: this.warnings.length,
+      errors: this.errors.length,
+      details: {
+        passed: this.passed,
+        warnings: this.warnings,
+        errors: this.errors
+      }
+    }, null, 2);
+    
+    // 写入校验结果文件
+    const outputPath = path.join(HARNESS_ROOT, '..', '..', '.workflow-validation-result.json');
+    try {
+      // 尝试写到 openspec 目录层级
+      fs.writeFileSync(
+        path.join(__dirname, '..', '..', '..', '.workflow-validation-result.json'),
+        resultJson
+      );
+    } catch (e) {
+      // 如果写失败就跳过，不影响主流程
+    }
+  }
+}
+
+// ============================================================
+// 执行入口
+// ============================================================
+
+if (require.main === module) {
+  const validator = new WorkflowValidator();
+  const success = validator.validateAll();
+  process.exit(success ? 0 : 1);
+}
+
+module.exports = WorkflowValidator;

package/.harness/workflow/variants.yaml

@@ -0,0 +1,253 @@
+# Workflow 流程变体定义
+
+> 除了标准的七阶段流程外，针对不同场景提供轻量化的变体流程。
+> PM Agent 根据需求分类选择合适的变体。
+
+---
+
+## 变体一：Bug 修复轻量流程
+
+**适用场景**: 已知 Bug 的修复，不需要从需求分析开始
+
+```
+PM路由 → Gate快速评估(影响面) → 开发修复 → 代码审查 → 测试验证 → 交付归档
+```
+
+```yaml
+variant_id: bugfix-lightweight
+name: "Bug 修复轻量流程"
+trigger_condition: |
+  需求来源为 Bug Report / Issue
+  且 已有复现步骤和期望行为
+stages:
+  - id: impact-assessment
+    name: "影响面快速评估"
+    agent: gate-controller
+    model_tier: lite
+    purpose: "判断 Bug 的严重程度和影响范围，决定是否走完整流程"
+    outputs:
+      - severity_rating: [P0/P1/P2/P3]
+      - affected_modules: []
+      - recommended_variant: [this | hotfix | full_flow]
+    
+  - id: fix-development
+    name: "Bug 修复"
+    agent: developer
+    steps:
+      - 定位根因（阅读相关代码）
+      - 编写修复代码
+      - 编写/更新回归测试用例
+      - 运行 Build + Test + Lint
+      - 提交 Fix Commit（`fix(scope): description (#issue)`）
+      - 创建 PR
+    
+  - id: fix-review
+    name: "修复审查"
+    agent: code-reviewer
+    focus_areas:
+      - "修复是否彻底（是否引入新问题）"
+      - "回归测试是否充分"
+      - "是否影响了其他模块"
+    
+  - id: regression-testing
+    name: "回归验证"
+    agent: tester
+    focus_areas:
+      - "原 Bug 是否已修复"
+      - "关联功能是否受影响"
+      - "是否有新的回归问题"
+
+skipped_stages: [requirements-analysis, solution-design]
+estimated_time_reduction: "50-70% vs full flow"
+```
+
+---
+
+## 变体二：紧急热修复最快路径
+
+**适用场景**: 生产环境严重故障，需要最短时间内上线修复
+
+```
+PM确认 → 紧急授权 → 开发热修 → 最小化审查 → 冒烟测试 → 直接发布
+```
+
+```yaml
+variant_id: hotfix-emergency
+name: "热修复最快路径"
+trigger_condition: |
+  P0/P1 级生产事故
+  且 需要在 4 小时内修复上线
+approval_required: true           # 需要技术负责人或 on-call 授权
+approval_role: "tech_lead / on_call_engineer"
+
+stages:
+  - id: emergency-routing
+    name: "紧急路由"
+    agent: project-manager
+    special_rules:
+      - "立即通知相关人员"
+      - "暂停该模块其他任务避免冲突"
+      - "记录事件时间线"
+  
+  - id: hotfix-dev
+    name: "热修复开发"
+    agent: developer
+    time_box: "2 hours"
+    constraints:
+      - 只修复问题，不做优化
+      - 最小化改动范围
+      - 必须附带回归测试
+    branch_naming: "hotfix/{description}-{issue}"
+    
+  - id: expedited-review
+    name: "加急审查"
+    agent: code-reviewer
+    time_box: "30 minutes"
+    simplified_checklist:
+      - 安全性（必须）
+      - 修复正确性（必须）
+      - 回归风险（必须）
+      - 跳过：风格、优化建议
+    
+  - id: smoke-test
+    name: "冒烟测试"
+    agent: tester
+    scope: "仅修复点 + 关联路径"
+    test_types:
+      - 单元测试（修改的函数）
+      - API 测试（影响的端点）
+      - E2E 测试（核心用户路径）
+    
+  - id: direct-deploy
+    name: "直接发布"
+    deploy_method: "hotfix branch → main (fast-forward)"
+    post_deploy:
+      - 监控告警 30 分钟
+      - 确认修复生效
+      - 补充完整事后文档
+
+skipped_stages: [requirements-analysis, solution-design, full-gate-evaluation, full-test-suite]
+post_completion_required:
+  - 事后复盘（Post-mortem）
+  - 补充完整的测试覆盖
+  - 更新 dev-map 和文档
+  - 如果是安全漏洞 → 更新 security-baseline 规则
+```
+
+---
+
+## 变体三：文档/配置微型流程
+
+**适用场景**: 仅涉及文档更新、配置调整、非功能性变更
+
+```
+PM路由 → 直接执行 → Lint检查 → 交付归档
+```
+
+```yaml
+variant_id: doc-config-micro
+name: "文档/配置微型流程"
+trigger_condition: |
+  变更范围仅限于：
+  - README / CHANGELOG / 文档文件
+  - 配置文件（非敏感）
+  - 类型定义文件
+  - 测试文件（新增测试用例）
+excluded_changes:
+  - 源代码业务逻辑
+  - 数据库迁移
+  - API 接口变更
+  - 依赖版本变更
+
+stages:
+  - id: micro-change
+    name: "微型变更执行"
+    agent: developer 或 project-manager（根据内容）
+    steps:
+      - 执行变更
+      - 运行 Lint Check
+      - 如涉及代码 → 运行 Build + Test
+      - 提交 Commit
+    review_requirement:
+      - "文档变更": 可选审查
+      - "配置变更": 需要 1 人审查（ack 即可）
+      - "测试文件": 不需要审查
+
+skipped_stages: [requirements-analysis, solution-design, gate-evaluation, code-review(conditional), full-testing]
+estimated_time_reduction: "80% vs full flow"
+quality_gates:
+  - Lint 必须通过
+  - 如涉及代码 → Build 和 Unit Test 必须通过
+```
+
+---
+
+## 变体四：安全漏洞响应流程
+
+**适用场景**: 安全扫描发现漏洞或收到安全报告
+
+```
+安全确认 → 风险评级 → (P0→热修复) / (P1-P2→标准流程加严) → 安全复查 → 发布
+```
+
+```yaml
+variant_id: security-response
+name: "安全漏洞响应流程"
+trigger_condition: |
+  来源为：
+  - npm audit / Snyk 报告
+  - 安全团队报告
+  - 渗透测试发现
+  - HackerOne / SRC 报告
+
+special_roles:
+  - security_reviewer: "安全专员参与每个阶段"
+  - tech_lead: "P0 必须 Tech Lead 审批"
+
+severity_routing:
+  CRITICAL:
+    variant: hotfix-emergency
+    additional_steps:
+      - 安全团队深度分析
+      - 影响面全面排查（不只修一点）
+      - 强制安全培训回顾
+  HIGH:
+    variant: full_flow
+    modifications:
+      gate_evaluation: "安全专员共同评审"
+      code_review: "增加安全审计维度（权重提升至 40%）"
+      testing: "增加渗透测试和安全回归"
+  MODERATE:
+    variant: bugfix-lightweight
+    modifications:
+      code_review: "安全检查项必查"
+      testing: "安全回归测试必跑"
+  LOW:
+    variant: doc-config-micro or next_sprint
+    based_on_effort: true
+
+post_completion:
+  - 更新 security-baseline 规则（如需要）
+  - 记录到 security-incidents.md（dev-map 中）
+  - 如果是外部报告 → 按 disclosure policy 处理
+```
+
+---
+
+## 变体选择决策树
+
+```
+                    收到需求
+                       │
+              ┌────────┼────────┐
+              ▼         ▼        ▼
+           安全漏洞？  Bug？   新功能？
+           │         │         │
+       ┌───┴───┐  ┌──┴──┐   标准七阶段流程
+       ▼       ▼  ▼     ▼
+    CRITICAL HIGH  P0/P1 P2-P3
+       │       │   │     │
+       ▼       ▼   ▼     ▼
+    热修复  标准+加严 热修复  Bug轻量
+             安全重点  轻量    流程
+```