jsharness 1.0.0

package/.harness/docs/integration-test-plan.md

@@ -0,0 +1,248 @@
+# 集成测试与试点验证指南
+
+## 11.1 端到端测试用例 — 模拟完整七阶段工作流跑通
+
+### 测试目标
+验证 Harness 工作流引擎的完整性，确保一个需求从接收到交付的完整链路可以正确运行。
+
+### E2E 测试场景：完整标准流程
+
+```yaml
+test_case_id: "E2E-HARNESS-FULL-001"
+name: "标准七阶段流程端到端测试"
+description: |
+  模拟一个完整的「用户注册功能」需求，走通从 PM 路由到最终交付的全流程。
+
+scenario:
+  # === Phase 0: 准备 ===
+  - given: "一个新功能需求（用户邮箱注册）已提交"
+    input:
+      raw_requirement: "用户需要通过邮箱和密码注册账号"
+      source: "product_manager"
+      task_board_status: "空"
+  
+  # === Phase 1: PM 路由 (Task 1) ===
+  - when: "PM Agent 接收需求并路由"
+    then:
+      routing_decision:
+        variant_selected: "standard"  # 新功能 → 标准流程
+        assigned_to: "requirements-analyst"
+        task_board_updated: true
+        assert: "task_board 包含新任务且状态为 待开始"
+  
+  # === Phase 2: 需求分析 (Tasks 2-3) ===
+  - when: "需求分析 Agent 处理需求"
+    then:
+      output_exists:
+        - "requirements-TASK-001.md"
+        - "acceptance-criteria.md"
+        - "stories.md"
+      quality_checks:
+        - "每个验收标准可测"
+        - "范围边界清晰（包含/不包含）"
+        - "无技术实现细节混入"
+      task_board_status_changed: "待开始 → 进行中(需求分析)"
+  
+  # === Phase 3: 方案设计 (Tasks 4-5) ===
+  - when: "方案设计 Agent 基于需求文档设计方案"
+    then:
+      output_exists:
+        - "design-TASK-001.md"
+        - "api-definition.yaml"
+        - "data-model.md"
+      references_dev_map: true  # 引用了既有模块
+      api_spec_complete: true     # API 定义覆盖所有验收场景
+  
+  # === Phase 4: 闸门评估 (Task 6) ===
+  - when: "闸门总控 Agent 评估方案可行性"
+    then:
+      gate_decision: one_of ["PASS", "HOLD"]
+      if_PASS: "进入开发阶段"
+      if_HOLD: "有明确的解除条件"
+      risk_identified: true       # 风险清单不为空
+  
+  # === Phase 5: 开发实现 (Tasks 7-8) ===
+  - when: "开发者 Agent 按方案编码"
+    steps_verified:
+      - step_1_design_read: "阅读了 design 文档"
+      - step_2_code_written: "源码文件存在"
+      - step_3_tests_written: "单元测试存在且覆盖率 ≥85%"
+      - step_4_build_pass: "npm run build 通过"
+      - step_5_test_pass: "npm run test 通过"
+      - step_6_lint_pass: "ESLint + Prettier 通过"
+      - step_7_devmap_updated: "dev-map 已同步更新"
+      - step_8_commit_made: "Commit 符合 Conventional Commits"
+      - step_9_pr_created: "PR/MR 已创建"
+    
+  # === Phase 6: 代码审查 (Task 9) ===
+  - when: "代码审查 Agent 审查 PR"
+    then:
+      review_dimensions_checked:
+        - A_quality: "得分 ≥60%"
+        - B_compliance: "得分存在"
+        - C_security: "无安全红线违规"
+        - D_performance: "已检查"
+        - E_testing: "覆盖率未下降 >5%"
+      decision: one_of ["PASS", "CONDITIONAL_PASS", "FAIL"]
+      
+  # === Phase 7: 测试验证 (Task 10) ===
+  - when: "测试验证 Agent 执行全面测试"
+    then:
+      test_types_executed:
+        - unit: "PASS, coverage >= baseline"
+        - api_integration: "PASS, no breaking changes"
+        - e2e_critical_path: "PASS"
+        - security_scan: "no HIGH/CRITICAL vulnerabilities"
+      defect_report:
+        P0_count: 0
+        P1_count: 0
+      regression_check: "no new regressions"
+      
+  # === Phase 8: 交付归档 (Task 11) ===
+  - when: "PM Agent 完成交付归档"
+    then:
+      task_board_status: "已完成"
+      deliverables_archived: true
+      metrics_recorded: true
+
+# 最终断言
+assertions:
+  - "所有阶段产出物齐全"
+  - "TaskBoard 状态流转正确（每个阶段只推进一次或按规则回退）"
+  - "无流程违规记录"
+  - "Gate 报告显示 PASS 或 CONDITIONAL_PASS"
+```
+
+### E2E 测试场景：Bug 修复轻量流程
+
+```yaml
+test_case_id: "E2E-HARNESS-BUGFIX-001"
+name: "Bug 修复流程端到端测试"
+description: "验证 Bug 修复变体流程的正确性"
+
+scenario:
+  given: "一个 P2 级 Bug 报告：登录后页面标题不显示"
+  when: "PM 路由为 bugfix 变体"
+  then:
+    skipped_stages: ["requirements-analysis", "solution-design", "full-gate"]
+    executed_stages: ["impact-assessment", "fix-development", "fix-review", "regression-testing"]
+    total_steps: "< 标准流程的 50%"
+    fix_includes_regression_test: true
+```
+
+### E2E 测试场景：安全红线阻断
+
+```yaml
+test_case_id: "E2E-HARNESS-SECURITY-001"
+name: "安全红线阻断测试"
+description: "验证安全问题时工作流能正确阻断"
+
+scenario:
+  given: "开发者在代码中硬编码了 API Key"
+  when: "经过 Gate 安全检查 (D 类)"
+  then:
+    gate_result: "FAIL"
+    auto_reject_triggered: true
+    block_merge: true
+    escalation_sent: true
+    workflow_state: "blocked at code-review or testing"
+```
+
+---
+
+## 11.2 试点运行计划
+
+### 试点需求选择标准
+
+| 标准 | 要求 | 说明 |
+|------|------|------|
+| 规模 | 中小型 | 理想：1-3 天开发量 |
+| 复杂度 | 中等 | 不太简单（无法验证流程），不太复杂（周期太长）|
+| 风险可控 | 低 | 不涉及核心业务、不影响线上稳定性 |
+| 可测量 | 高 | 有明确的验收标准和可量化结果 |
+
+### 推荐试点需求示例
+
+```
+候选 1: 「用户头像上传与裁剪」功能
+  ✅ 涉及前后端、有 API 设计、有文件处理
+  ✅ 有明确验收标准（格式、大小、裁剪比例）
+  ✅ 预计 2-3 天开发量
+  ⚠️ 涉及文件存储，需要基础设施配合
+
+候选 2: 「用户个人资料页展示」功能
+  ✅ 纯读取型功能，风险低
+  ✅ 涉及 API 对接和数据组装
+  ✅ 预计 1-2 天开发量
+  ❌ 可能过于简单，不足以充分验证流程
+
+候选 3: 「通知消息列表 + 已读标记」功能
+  ✅ 涉及数据模型变更、API 设计、状态管理
+  ✅ 有明确的交互逻辑
+  ✅ 适合验证多角色协作
+```
+
+### 试点执行步骤
+
+```markdown
+## 试点前准备（Day 0）
+- [ ] 选择试点需求
+- [ ] 确认参与人员（PM / 开发者 / 测试各 1 人）
+- [ ] 准备独立的 Git 分支 `feature/harness-pilot-{name}`
+- [ ] 确认 Rule/Skill/Gate 配置就绪
+
+## 试点执行（Day 1-3）
+- [ ] Day 1: PM 路由 → 需求分析 → 方案设计 → 闸门评估
+- [ ] Day 2: 开发实现 → 代码审查
+- [ ] Day 3: 测试验证 → 交付归档
+
+## 试点回顾（Day 4）
+- [ ] 收集各方反馈（每个角色的体验）
+- [ ] 记录遇到的问题和卡点
+- [ ] 统计度量数据（实际耗时 vs 预期、打回次数等）
+- [ ] 识别需要调整的配置项
+```
+
+---
+
+## 11.3 反馈收集模板
+
+```markdown
+# Harness 试点反馈表
+
+**试点需求**: {name}
+**参与者**: {role_name}
+**填写日期**: {date}
+
+## 流程体验评分 (1-5 分)
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 流程清晰度 | ?/5 | 各阶段的输入输出是否明确？ |
+| 工具易用性 | ?/5 | Rule/Skill/Gate 是否容易使用？ |
+| 协作顺畅度 | ?/5 | 角色交接是否顺利？ |
+| 效率感知 | ?/5 | 相比之前的方式是快还是慢？ |
+| 整体满意度 | ?/5 | 是否愿意在后续工作中继续使用？ |
+
+## 最大痛点（Top 3）
+
+1. 
+   影响程度: 🟡🟠🔴
+   改进建议:
+
+2. 
+
+3. 
+
+## 最有价值的部分（Top 3）
+
+1. 
+
+2. 
+
+3. 
+
+## 其他建议
+
+{free_text}
+```

package/.harness/docs/team-guidelines/README.md

@@ -0,0 +1,161 @@
+# 公司各团队 Harness 使用规范总纲
+
+> **版本**: v1.0.0  
+> **生效日期**: 2026-05-21  
+> **适用范围**: 全公司产研测相关团队  
+> **维护人**: 工程效能组  
+
+---
+
+## 一、背景与目标
+
+### 1.1 为什么需要这套规范
+
+公司已建立完整的 **Harness 产研测作战地图** 体系（`.harness/`），包含：
+- **7 个角色 Agent**（PM/需求分析/方案设计/闸门/开发/审查/测试）
+- **5 类 Rule 规则**（编码规范/提交规范/安全红线/流程纪律/Web规则）
+- **9 个 Skill 技能库**（构建/测试/Lint/审查/Docker/文档等）
+- **7 阶段 Workflow 工作流**（需求→设计→闸门→开发→审查→测试→交付）
+- **5 类 Gate 门禁检查**（静态/构建/测试/安全/一致性）
+
+本规范的目的是：**让每个团队清楚知道自己在 Harness 体系中的角色、职责、操作流程和考核标准**。
+
+### 1.2 规范覆盖的团队
+
+| 团队 | 对应 Agent | 核心职责 |
+|------|-----------|---------|
+| **产品团队 (PM)** | PM 路由 Agent | 需求接入、流程调度、看板维护 |
+| **研发团队 (RD)** | 开发实现 Agent + 代码审查 Agent | 编码实现、单元测试、代码审查 |
+| **测试团队 (QA)** | 测试验证 Agent | 测试策略、用例执行、质量把关 |
+| **架构/技术方案组** | 方案设计师 Agent + 闸门总控 Agent | 技术设计、可行性评估、风险控制 |
+
+---
+
+## 二、通用协作原则（所有团队必须遵守）
+
+### 2.1 三不原则
+
+```
+┌─────────────────────────────────────────────┐
+│           Harness 三不原则                    │
+├─────────────────────────────────────────────┤
+│  ❌ 不跳过阶段 — 必须按七阶段流程推进          │
+│  ❌ 不越界干预 — 不做不属于自己角色的事        │
+│  ❌ 不私自放行 — 闸门判定为 BLOCK 时不得强行推进│
+└─────────────────────────────────────────────┘
+```
+
+### 2.2 下游不改上游原则
+
+| 上游产出 | 谁可以修改 | 其他人能做什么 |
+|---------|----------|-------------|
+| 需求文档 | 需求分析师 / PM（变更请求） | 提出澄清问题 |
+| 技术设计 | 方案设计师 | 提出实现疑问 |
+| 代码实现 | 开发者 | Code Review 评论 |
+| 测试报告 | 测试人员 | 确认缺陷复现 |
+
+### 2.3 文档即契约原则
+
+- 每个阶段必须产出规定格式的文档
+- 文档是下游工作的唯一依据
+- 文档变更必须走正式流程，不能口头约定
+
+### 2.4 度量透明原则
+
+所有关键指标在 TaskBoard 可见：
+- 需求交付周期（需求提出 → 交付完成）
+- 各阶段耗时分布
+- 打回率和打回原因统计
+- Gate 通过率
+
+---
+
+## 三、约束硬度层级说明
+
+```
+Rule (软约束)     Skill (半硬约束)      Gate Scripts (硬约束)
+   ↓                  ↓                      ↓
+ 自然语言指导       标准步骤流程          自动化检查
+ 有解释空间         步骤固定              PASS/FAIL 无商量
+ 违反 → 记录警告    违反 → 重做          违反 → 直接阻断
+```
+
+| 层级 | 执行方式 | 违反后果 |
+|-----|---------|---------|
+| **Rule** | 自觉遵循 + AI 辅助检查 | 警告记录，累计影响绩效 |
+| **Skill** | 按标准步骤执行 | 未执行则该阶段不通过 |
+| **Gate Scripts** | 自动化脚本检查 | FAIL 则直接阻断流程 |
+
+---
+
+## 四、各团队规范索引
+
+请各团队成员详细阅读对应的团队规范：
+
+| 团队 | 规范文件 | 必读内容 |
+|------|---------|---------|
+| 产品团队 | `team-guidelines/pm-team.md` | 需求提交流程、路由规则、看板维护 |
+| 研发团队 | `team-guidelines/rd-team.md` | 编码规范、自检流程、CR 要求、dev-map 更新 |
+| 测试团队 | `team-guidelines/qa-team.md` | 测试策略、缺陷分级、验收标准、回归要求 |
+| 架构/设计 | `team-guidelines/arch-team.md` | 设计文档标准、接口定义、风险评估、ADR |
+| 全体通用 | `team-guidelines/collaboration.md` | 跨团队协作、争议升级、应急处理 |
+
+---
+
+## 五、快速参考：七阶段流程速查
+
+```
+① 需求分析 ──→ ② 方案设计 ──→ ③ 闸门评估 ──→ ④ 开发实现 
+     ↑  ↓打回        ↓打回/变更需求    │PASS         ↓PR+自检通过
+     └──┘                          │BLOCK/HOLD   ⑤ 代码审查
+                                    ↓             ↓PASS/条件PASS
+                              取消/BLOCK          ⑥ 测试验证
+                                                   ↓全部PASS
+                                                ⑦ 交付归档
+                                                   ↓
+                                                  完成 ✓
+```
+
+**各阶段负责人**：
+
+| 阶段 | 负责角色 | 模型档位 | 关键产出 |
+|-----|---------|---------|---------|
+| ① 需求分析 | 需求分析师 | Standard | 需求文档 + 验收标准 |
+| ② 方案设计 | 方案设计师 | Standard | 设计文档 + API 定义 |
+| ③ 闸门评估 | 闸门总控 | Strong | 可行性报告 + PASS/BLOCK/HOLD |
+| ④ 开发实现 | 开发者 | Standard | 代码 + 单元测试 + PR |
+| ⑤ 代码审查 | 审查者 | Strong | 审查报告 + PASS/条件PASS/FAIL |
+| ⑥ 测试验证 | 测试员 | Strong | 测试报告 + 缺陷列表 |
+| ⑦ 交付归档 | PM | Lite | 交付摘要 + 归档 |
+
+---
+
+## 六、常见问题 FAQ
+
+**Q1: 紧急 Bug 修复要走完整七阶段吗？**  
+A: 不必。使用「热修复变体」流程（见 `workflow/variants.yaml`），可压缩至 3-4 阶段，但安全检查不可省略。
+
+**Q2: PM 可以指定技术方案吗？**  
+A: 绝对不可以。PM 的职责是路由和协调，「指定技术实现」是明确的违规行为（见 `rules/global/process-discipline.md`）。
+
+**Q3: 发现设计文档和实际代码严重不符怎么办？**  
+A: 开发者应立即发起「上游变更请求」，回退到方案设计阶段修正。不能自行修改设计文档。
+
+**Q4: Gate 检查 FAIL 了但我觉得没问题，能强行通过吗？**  
+A: 不能。Gate 是硬约束，FAIL 必须修复后重新检查。如有异议，可申请人工复审。
+
+**Q5: dev-map 由谁维护？**  
+A: 原则是「谁改代码谁改地图」。开发者在有结构性变更时必须同步更新 dev-map。
+
+---
+
+## 七、规范更新机制
+
+- **定期评审**: 每两周 Review 一次 Rule/Skill/Workflow 配置
+- **变更提案**: 通过 `/opsx:propose` 提交改进建议
+- **版本管理**: 所有规范变更记录在 ADR 中（`dev-map/decisions.md`）
+- **培训同步**: 规范变更后一周内完成全员培训
+
+---
+
+*本文档是公司 Harness 体系的顶层规范入口，具体操作细节请参阅各团队专属规范。*