| name | harness-onboard |
| description | 需求分类 + 影响面分析 + 动态流程确认。从用户描述推断工作类型，fetch-first 扫描代码，输出影响面报告，解析 workflow/dev.md 的 rules 动态调整插槽列表，展示流程供用户确认调整，最终输出 resolved_slots JSON 交给 harness-roles 执行。 |
harness-onboard：引导 + 流程确认
输入
由 harness-dev 调用，接收：
requirement：用户原始需求描述context：已加载的 .harness/context/ 文件内容（module/deps/arch/constraints）workflow_config：workflow/dev.md 的 YAML 解析结果（roles/overdraft/slots/rules）
Step 1：工作类型推断
从 requirement 推断工作类型，能推断就直接用，推断不出才给用户选择题：
| 描述关键词 | 推断类型 | 流程影响 |
|---|
| "加个功能"、"新增"、"支持"、"实现" | new-feature | 完整流程 |
| "修一下"、"bug"、"报错"、"崩了"、"hotfix"、"fix" | bugfix | 跳过 plan 插槽 |
| "重构"、"整理"、"优化"、"清理" | refactor | 跳过 plan，影响面加风险警告 |
| "新模块"、"新服务"、"新 cmd"、"新 app" | new-module | 先触发 harness-init，再进流程 |
| "新项目" | new-project | 引导项目结构创建 |
| "配置"、"config"、"env"、"环境变量" | config-change | 跳过 plan，跳过 implement，只需 lint + review（极简流程） |
| "文档"、"doc"、"readme"、"注释" | docs-only | 跳过 plan，跳过 implement，跳过 review，只需更新文档 |
| "依赖"、"upgrade"、"bump"、"版本" | dependency-upgrade | plan 前插入兼容性检查插槽 |
| 无法推断 | — | 展示选择题 |
bugfix 和 hotfix 等价处理：两者推断为相同类型，流程影响相同（跳过 plan 插槽）。
推断不出时展示：
这次是什么类型的工作？
A. 新功能（完整流程）
B. Bug 修复（跳过方案设计，直接编码）
C. 重构/优化
D. 新模块/新服务
Step 2：fetch-first 数据收集
推断工作类型后，按优先级静默扫描，不向用户提问直到所有来源都已尝试：
| 优先级 | 来源 | 动作 |
|---|
| 1 | context（已加载） | 直接使用 |
| 2 | 相关文件代码 | Grep 需求中的关键词，Read 相关文件 |
| 3 | git log | git log --oneline -30 -- {相关路径} |
| 4 | 相关 pkg 的 .harness/ | 读取 contract.md + constraints.md |
| 5 | 测试文件 | 了解现有行为和边界 |
| 6 | ❓ 向用户提问 | 仅当以上来源均无法回答时 |
提问原则：只问"代码里找不到、文档里没有、不知道则无法继续"的内容。禁止模糊提问（如"请描述背景"）。
Step 3：位置确认（按需触发）
当用户描述里没有明确模块，且 context 中无法推断时触发：
这个改动要加在哪里？
A. {模块名1}（{职责描述}）
B. {模块名2}（{职责描述}）
C. 两者都要改
D. 其他（请说明）
选项来自 context/module.md 和 context/deps.md 中的模块列表。
Step 4：影响面分析（强制输出，不可跳过）
📊 影响面分析
工作类型：{work_type}（{需求一句话摘要}）
直接修改：
- {文件路径}（原因：{对应的变更点}）
需要协商（涉及 pkg 公开接口）：
- pkg/{name}：需要 {新增/修改} {接口名}
→ 包主人：{从 pkg/.harness/owner.md 读取}
→ 已知调用方：{从 pkg/.harness/contract.md 读取}
只读引用，无需改动：
- {包名}
潜在风险：
⚠️ {文件名} 是高频变更文件（近30天 {N} 次提交）
⚠️ {接口名} 有 {N} 个调用方，改接口需通知
Step 5：应用定制规则（动态插槽修改）
读取 workflow_config.rules，逐条解读，修改插槽列表。
三种操作：
| 操作 | 效果 | 示例规则 |
|---|
| skip | 从列表移除该插槽 | "bugfix 跳过 plan" |
| insert-before | 在目标插槽前插入新条目 | "接口变更前插入 pkg 主人确认" |
| insert-after | 在目标插槽后插入新条目 | "implement 后插入性能测试" |
动态插入的 checkpoint 格式（无 skill/role，纯人工确认节点）：
{
"name": "pkg-owner-confirm",
"skill": null,
"role": null,
"type": "checkpoint",
"message": "请确认已与 pkg 主人对齐接口设计"
}
type: "checkpoint" 表示纯人工确认节点，无需调用 skill 或 subagent。message 为必填字段，由插入该 checkpoint 的规则决定内容。
所有规则应用后，生成 resolved_slots 数组。
Step 6：流程确认
展示最终流程，附预算，等待用户确认或调整：
为你准备的流程：
1. 🎩 Planner — {plan 插槽的 skill 简称} ({model}, 预算 ${budget} 估算)
2. 🔨 Builder — {implement 插槽的 skill 简称} ({model}, 预算 ${budget} 估算)
3. 🔍 Critic — {review 插槽的 skill 简称} ({model}, 预算 ${budget} 估算)
4. ✅ Finalizer — {finish 插槽的 skill 简称} ({model}, 预算 ${budget} 估算)
估算总预算：${total}
这个流程 OK？还是要调整？
· 直接说 y 开始
· "跳过 review"、"Planner 用 Sonnet"、"总预算控制在 $2"
用户调整处理规则：
- "跳过 {插槽名}" → 从 resolved_slots 移除该条目
- "{角色名} 用 {模型}" → 覆盖该角色的 model
- "总预算 $X" → 按默认比例等比缩减各角色 budget
- "加上 {自定义步骤}" → 询问绑定哪个 skill 和哪个 role，insert-after 最后一个相关插槽
每次调整后重新展示更新后的流程，用户说 y 后进入下一步。
提示持久化：
已调整（仅本次）：Planner opus → sonnet，Critic 已跳过
如果想永久生效，说"保存这次的配置"
用户说"保存这次的配置"时：
- 将当前
role_config 和 resolved_slots 写入 .harness/workflow/dev.md 的对应字段
rules 部分保留不动- 写入前展示 diff，等用户确认
注意：保存的是 resolved_slots（规则应用后的结果）。如用户意图是永久移除某插槽（非条件性跳过），建议直接编辑 dev.md 文件。
Step 7：输出 JSON 交给 harness-roles
用户说 y 后，输出以下结构（harness-dev 将其原样传入 harness-roles）：
{
"work_type": "new-feature",
"requirement": "{用户原始需求}",
"impact_analysis": "{影响面分析全文}",
"resolved_slots": [
{ "name": "plan", "skill": "brainstorming", "role": "planner", "milestone": true },
{ "name": "implement", "skill": "subagent-driven-development", "role": "builder", "milestone": true },
{ "name": "review", "skill": "harness-review", "role": "critic", "milestone": false,
"review_config": {
"pass_threshold": { "spec_compliance": 8, "evaluator": 7 },
"max_iterations": 3
}
},
{ "name": "finish", "skill": "finishing-a-development-branch", "role": "finalizer", "milestone": true }
],
"role_config": {
"planner": { "model": "sonnet", "budget": 0.50 },
"builder": { "model": "sonnet", "budget": 2.00 },
"critic": { "model": "sonnet", "budget": 0.50 },
"finalizer": { "model": "haiku", "budget": 0.20 }
},
"overdraft": "ask",
"session_overrides": "Planner opus → sonnet，Critic 已跳过"
}
review_config 告诉 harness-roles：Spec Compliance ≥ 8 且 Evaluator ≥ 7 才算通过。最多迭代 3 次。
Step 6.5：Sprint Contract 格式验证门（强制）
这是硬性门控：未通过验证的 Plan 不允许进入 Builder 阶段。
Planner 产出后，读取其输出，逐项验证：
验证规则
🔍 Sprint Contract 格式验证
✓ sprint_contract 字段存在
✓ features 数组非空
✓ 每个 feature 有 name 和 acceptance_criteria
对每个 AC：
✓ 有 id（格式：AC-1, AC-2...）
✓ 有 description（非空，描述具体行为）
✓ 有 verifiable_from（值为 ui | api | cli | log 之一）
✓ 有 test_method（非空，描述具体验证手段）
✓ description 不包含源码引用（grep 检查：import / from src / function( / -> ）
✓ blackbox_constraint 字段存在且值为 "✅"
✓ 无源码读取类 AC
验证通过：允许进入 Builder
验证失败：阻断，返回 Planner 重做
AC 可测试性判断标准
✅ 通过：
"Click Submit → success modal appears"
"POST /api/users returns 201 with id field"
"CLI: ./mytool --version outputs semver string"
"Log contains 'connection established' after startup"
❌ 不通过（源码引用）：
"UserService.Create() is called with valid input"
"the validate() function returns true for valid emails"
"the db.Update() call includes a timestamp"
"import path 'pkg/user' is referenced in the handler"
验证失败时的阻断输出
🔴 Sprint Contract 验证失败 — Plan 不允许进入 Builder
阻断原因：
✗ AC-3 的 description 引用了内部实现（"UserService.Create() 被调用"）
✗ AC-1 缺少 test_method
✗ AC-5 的 verifiable_from 值为 "code"，不是有效值
请 Planner 重新输出符合格式的 Sprint Contract。
具体修正要求：
1. AC 描述必须是外部可观测行为（UI/API/CLI/Log）
2. 禁止引用函数名、类名、import 路径等内部实现细节
3. 每个 AC 必须有具体的 test_method
修正后再次提交验证。
黑盒约束快速判断
快速检测 AC 是否违规（只要匹配以下任一模式即为不通过）：
- 包含
function( () -> .method( 等代码模式
- 包含
import from "pkg/ from './ 等引用模式
- 包含
src/ /internal/ /pkg/ 路径模式
- 描述的是"如何实现"而非"外部表现"
Sprint Contract 格式（harness-onboard 输出）
Planner 产出必须符合 Sprint Contract 格式，包含：
{
"sprint_contract": {
"sprint": 1,
"features": [
{
"name": "{feature name}",
"acceptance_criteria": [
{
"id": "AC-1",
"description": "{specific, externally observable behavior}",
"verifiable_from": "ui",
"test_method": "Playwright: click #submit → modal appears"
},
{
"id": "AC-2",
"description": "{another external behavior}",
"verifiable_from": "api",
"test_method": "curl -X POST /api/order -d '{...}' returns 201"
}
],
"blackbox_constraint": "✅ All ACs are verifiable from UI/API/CLI. No source code reading required."
}
],
"sprint_rules": [
"Max 3 ACs per feature",
"AC must describe externally observable behavior, not internal implementation",
"Sprint 1 must deliver one independently testable feature"
]
}
}
Planner（brainstorming skill）在 plan 插槽中必须输出符合此格式的 sprint contract。
通过 Step 6.5 验证后，才允许进入 Builder 阶段。
Review 评分阈值说明
harness-review 使用以下通过标准：
| Reviewer | 维度 | 通过阈值 |
|---|
| Spec Compliance | Overall 平均 | ≥ 8/10 |
| Evaluator | Overall 平均 | ≥ 7/10 |
如果 Overall 处于 6-7 分区，展示警告但不阻断。
如果 Overall < 6，进入迭代改进循环（Generator → Evaluator → 重评分）。3 次迭代后仍失败，停止并汇报用户。
