create-harness-vibe-coding 0.8.16 → 0.8.18

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.8.18] - 2026-07-29
+
+- Add explicit task capsule management with list, archive, record/open state recovery, create-or-resume matching, task dependency metadata, and validator coverage.
+- Add `wf-command-create` as the atomic command/skill creation workflow so new Harness commands update command files, skills, templates, mirrors, validators, and tests together.
+- Add global install metadata for Claude, Codex, and OpenCode while keeping Harness tasks and progress project-local.
+- Separate project/global memory and settings policy, with project settings taking precedence and task capsules remaining project-scoped.
+- Harden host-global ownership and validation rules so framework-owned global command/skill files can update safely while user-authored files remain protected.
+- Strengthen `wf-review`, `wf-agents-docs`, and WF-MAX guidance around explicit WF triggers, bounded peer output, and task capsule recording.
+
+## [0.8.17] - 2026-07-26
+
+- Add HarnessBench v0.2 as an external-only lifecycle proof: 15 runs per mode, direct file writes safe in 3/15 runs, Harness safe path safe in 15/15 runs.
+- Keep benchmark fixtures, raw results, and scorer scripts out of generated installs and npm package files while publishing the summary in README and README-CN.
+- Make `wf-browser` the built-in browser automation entry and retire `browser-e2e` as a warning no-op optional id.
+- Add `wf-help` compatibility surfaces for Claude, Codex, and OpenCode with guards against nonexistent OpenCode skill paths.
+- Harden WF-MAX fan-out docs and OpenCode manager allowlists while preserving the Codex config guard against unsupported scalar subagent caps.
+- Add deterministic task-state/archive reconciliation tooling and validators for active task consistency.
+
 ## [0.8.16] - 2026-07-23
 
 - Fix `scan-clean` default source selection so it honors the installed `Harness/.harness-version.source` before falling back to npm/GitHub, preventing false dead-file reports before npm publish catches up.

package/README-CN.md

@@ -11,122 +11,146 @@
 
 <h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
-  <b>让 AI agent 在真实仓库里先理解，再执行，最后验证。</b><br>
-  <sub>面向 Claude Code、Codex 和 OpenCode 的 AI 编程工作流脚手架</sub>
+  <b>给 AI coding agent 一个仓库内的执行契约。</b><br>
+  <sub>支持 Claude Code、Codex 和 OpenCode</sub>
 </p>
 
 <p align="center">
-  <a href="README.md">English</a> ·
-  <a href="https://github.com/LiWeny16/create-harness-vibe-coding">GitHub</a> ·
+  <a href="README.md">English</a> |
+  <a href="https://github.com/LiWeny16/create-harness-vibe-coding">GitHub</a> |
   <a href="https://www.npmjs.com/package/create-harness-vibe-coding">npm</a>
 </p>
 
----
-
 ## 这是什么？
 
-`create-harness-vibe-coding` 是一个 Node.js CLI。它为 AI 编程 agent 生成一套放在仓库里的工作契约，让 agent 在长任务中保持目标、上下文、边界、验证和记忆的一致。
+`create-harness-vibe-coding` 是一个 Node.js CLI。它在仓库里生成 Harness：一套给 AI coding agent 使用的工作契约，覆盖目标、上下文、写入边界、验证、任务状态和长期记忆。
+
+它不是模型、不是 prompt 集，也不会生成业务代码。它解决的是工程流程问题：agent 在长任务里容易忘记上下文、扩大改动范围、跳过验证，或者中断后重新扫描仓库。
 
-它不是 prompt 集合，也不是模型本身。它解决的是另一个问题：同一个 agent 为什么第一轮看起来很好，第二轮却开始忘记决策、扩大修改范围、跳过验证？
+## 当前实测
 
-## 0.8.15 新增重点
+0.8.16 这版只写已经跑出来的数据：
 
-这一版把“cache-first 设计”从原则推进到可复现实测：
+- HarnessBench v0.2 本地生命周期 benchmark：每个模式 15 轮。直接写文件 baseline 安全完成 3/15；Harness safe path 安全完成 15/15。
+- 受保护文件覆盖次数：baseline 21 次；Harness safe path 0 次。
+- Claude Code L2 prompt-cache 样本：`harness-thin` warm median cache read 为 `98.7%`，比 provider-control 高 `+5.4` 个百分点；`/wf` wf-light 为 `99.1%`，高 `+5.8` 个百分点。
+- 启动和更新链路：正常会话保持 thin startup，`Harness/specs/guides/SETUP.md` 只作为安装、迁移、升级参考；`/wf-update` 要汇报 `agent.releaseHighlights` 和验证结果。
 
-- 新增真实 Claude Code L2 telemetry：`Harness/scripts/l2-cache-telemetry.mjs` 会用受控预算采集 provider-control、thin-startup 和 `/wf` light-route 的 usage、费用、耗时和 session 证据。
-- 本 dogfood 仓库的实测结果已经写入 README：`harness-thin` warm median cache read 为 `98.7%`，相对 provider-control 提升 `+5.4` 个百分点；`/wf` wf-light 为 `99.1%`，提升 `+5.8` 个百分点。
-- 增加缓存回归防线：L0 结构校验、L1 SHA-256 stable-prefix 模拟、L2 provider telemetry claim gate、以及 route-profile context budget。
-- 启动与升级链路更清晰：正常会话保持 thin startup，`Harness/specs/guides/SETUP.md` 保留为安装/bootstrap/迁移/升级参考，`/wf-update` 完成后必须向用户汇报 changelog 核心改进点和验证结果。
-- 新增 `wf-agents-docs`：沉淀 Claude Code、Codex、OpenCode 的 CLI 调用、JSON telemetry 解析、peer review 和 batch probe 规则。
+完整的模型任务成功率 A/B 还没有发布。要对外说“模型解题成功率提升”，必须用同一个模型、同一个 fixture、同一个 prompt、同一个预算和同一套验证命令跑完 raw logs。
 
-## 一句话安装（已有项目推荐）
+## 一句话安装
 
-把下面这句话原样丢给正在使用的 Agent：
+把下面这句话交给当前正在使用的 Agent：
 
 > 请根据 https://github.com/LiWeny16/create-harness-vibe-coding/blob/main/README-CN.md 安装 Harness 框架。
 
 ## 安装说明（Agent instruction）
 
-Agent 读取本 README 后，按项目状态选择安装路径：
+Agent 读取本 README 后，按项目状态选择路径：
 
 | 项目状态 | Agent 执行 |
 |---|---|
 | 新项目 | `npx create-harness-vibe-coding@latest my-project -y` |
 | 已有项目 | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json` |
-| 已有 `Harness/` 且存在 `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`，走更新流程，不要重复安装；apply/finalize 后要汇报 `agent.releaseHighlights` 和验证结果 |
+| 已有 `Harness/` 且存在 `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`，走更新流程，不要重复安装；apply/finalize 后汇报 `agent.releaseHighlights` 和验证结果 |
 | 已有 `Harness/` 但缺少 `Harness/scripts/wf-update-check.mjs` | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json`。然后执行 `node Harness/scripts/wf-update-check.mjs --json` |
 | 安装或更新完成 | `node Harness/scripts/validate-harness.mjs --strict` |
 
-安装后的 handoff 按阶段区分：正常会话入口是 `CLAUDE.md`；`Harness/specs/guides/SETUP.md` 只用于安装/bootstrap、迁移或升级决策；需要 Harness 工作流路由时再读 `Harness/README.md`。遵守项目已有边界；先研究和计划，再修改代码；完成后运行测试、校验和审查，未验证不要声称完成。
+安装范围：默认是项目内安装。要写入一份机器级共享 runtime，用 `--install-scope global --global-dir <dir>`；commands/skills/agents 会以 copy 方式写入 Claude Code、Codex、OpenCode 的全局可发现目录，但每个项目自己的 `Harness/tasks/`、`Harness/PROGRESS.md`、项目 memory、项目事实和项目 settings 仍然留在项目内。
+
+用户不需要手动执行这些命令。Agent 负责安装、冲突处理、校验和汇报。
+
+安装后的入口按阶段区分：
 
-用户不需要手动执行命令。把上面一句话交给 Agent，Agent 负责安装、冲突处理、校验和汇报。
+- 正常会话入口是 `CLAUDE.md`。
+- `Harness/specs/guides/SETUP.md` 只用于安装、bootstrap、迁移或升级决策。
+- 需要 Harness 工作流路由时再读 `Harness/README.md`。
 
 ## WF 命令怎么选
 
-不确定时，直接用 `/wf-help`。它会返回完整命令表；复杂任务优先用 `/wf`，需要多人并行时用 `/wf-max`。
+不确定时，用 `/wf-help`。在 Codex 里用 `$wf-help`。它只返回命令说明，不会启动工作流。
 
-| 命令 | 什么时候用 | 它会做什么 | 示例 |
+| 命令 | 什么时候用 | 做什么 | 示例 |
 |---|---|---|---|
-| `/wf <任务>` | 多文件、架构、迁移、风险较高或反复失败 | 研究 → 计划 → 实现 → 测试 → 审查 → 验证 → 复盘 | `/wf 重构支付模块并补齐测试` |
-| `/wf-max <任务>` | 任务可拆成多个互不冲突的部分，需要最大并行度 | 在完整 WF 链路上增加 CEO → Manager → Worker 分工和并行波次 | `/wf-max 并行升级前端、后端和文档` |
-| `/wf-auto` | 希望 Agent 持续自我优化，通过自适应探测选择 | 持续执行优化循环，每轮保留计划、证据和反馈 | `/wf-auto 优化这个项目的稳定性` |
+| `/wf <任务>` | 多文件、架构、迁移、风险较高或反复失败 | 研究 -> 计划 -> 实现 -> 测试 -> 审查 -> 验证 -> 复盘 | `/wf 重构支付模块并补齐测试` |
+| `/wf-max <任务>` | 任务能拆成互不冲突的部分，需要最大并行度 | 在 WF 链路上增加 CEO -> Manager -> Worker 分工和并行波次 | `/wf-max 并行升级前端、后端和文档` |
+| `/wf-auto` | 希望 Agent 持续自我优化 | 连续执行优化循环，每轮保留计划、证据和反馈 | `/wf-auto 优化这个项目的稳定性` |
 | `/wf-auto-spark` | 需要外部灵感、竞品方向或长期路线图 | 搜索外部 spark，绑定 North Star 和里程碑，限制偏离范围 | `/wf-auto-spark 探索产品增长方向` |
-| `/wf-review [重点]` | 需要第二意见、同行审查或上线前复核 | 优先调用可用 peer CLI；没有时使用独立 reviewer 角色，并按严重程度反馈 | `/wf-review 重点检查安全和数据丢失` |
-| `/wf-learn` | 同类错误反复出现，或一次任务结束后要沉淀经验 | 汇总上下文、记忆和项目经验，形成下一次可复用规则 | `/wf-learn 总结这次返修原因` |
-| `/wf-browser <任务>` | 浏览器冒烟、E2E、截图、表单或页面验证 | 使用真实浏览器完成操作并提供截图、追踪和验证证据 | `/wf-browser 验证登录和支付流程` |
-| `/wf-readme <任务>` | README、安装文档、架构图或项目说明需要重写 | 保留事实，整理结构，补充安装和使用说明 | `/wf-readme 优化中文 README` |
-| `/wf-update` | 已经安装 Harness，需要检查和应用框架更新 | 比较版本，自动处理安全变更，把语义冲突留给 Agent，并从 changelog metadata 汇报本次升级核心变化 | `/wf-update` |
+| `/wf-review [重点]` | 需要第二意见、同行审查或上线前复核 | 优先调用可用 peer CLI；没有时使用独立 reviewer 角色 | `/wf-review 重点检查安全和数据丢失` |
+| `/wf-learn` | 同类错误反复出现，或一次任务结束后要沉淀经验 | 汇总上下文、记忆和项目经验 | `/wf-learn 总结这次返修原因` |
+| `/wf-browser <任务>` | 浏览器冒烟、E2E、截图、表单或页面验证 | 使用真实浏览器并提供截图、trace 或状态证据 | `/wf-browser 验证登录和支付流程` |
+| `/wf-readme <任务>` | README、安装文档、架构图或项目说明需要整理 | 保留事实，整理结构，补充安装和使用说明 | `/wf-readme 优化中文 README` |
+| `/wf-update` | 已安装 Harness，需要检查和应用框架更新 | 比较版本，自动处理安全变更，把语义冲突留给 Agent | `/wf-update` |
 | `/wf-remove` | 需要卸载 Harness | 自动清理安全文件，保留用户数据，冲突文件先确认 | `/wf-remove` |
-| `/wf-help` | 不知道该用哪个命令 | 只返回命令、用途和用法，不启动工作流 | `/wf-help` |
 
-Claude Code 使用 `/wf-*`；Codex 使用对应的 `$wf-*`；OpenCode 使用已注册的命令或 Agent instruction。`/wf-auto` 和 `/wf-auto-spark` 是持续模式，启动前要给 Agent 清晰的目标、范围和验收标准。
-
-常见场景可以这样起步：Web/API 先看正确性、安全、可靠性和验证；CLI/SDK 先看契约、兼容性、错误体验和文档；AI Agent 先看上下文质量、工具安全、评测和恢复；数据任务先看幂等性、失败恢复和可观测性。完整的自适应选择规则见 [WF-AUTO-ANGLES.md](Harness/specs/workflows/WF-AUTO-ANGLES.md)。
+Claude Code 使用 `/wf-*`；Codex 使用对应的 `$wf-*`；OpenCode 使用已注册命令或 Agent instruction。常见任务起点见 [WF-AUTO-ANGLES.md](Harness/specs/workflows/WF-AUTO-ANGLES.md)。
 
 ## 它改变了什么？
 
-| 没有工作契约 | 使用 Harness |
-|---|---|
-| 想到哪写到哪，靠 prompt 维持方向 | 目标 → 约束 → 验收条件，先定义完成边界 |
-| Agent 读取整个仓库，关键信息被噪声淹没 | 路由按任务加载最小必要上下文 |
-| 长任务中断后重新发现项目事实 | `PROGRESS.md`、任务胶囊和 Memory 保存接力信息 |
-| 文件冲突靠人工临场判断 | 脚本先分类 create / skip / backup / overwrite / conflict |
-| “看起来完成了”就结束 | 测试、校验器、审查和人工证据共同决定完成 |
-
-模型不是唯一变量。给它一个有边界、有记忆、会自检的工作台，普通模型也能少忘事、少跑偏、少让你回来救火。
-
-## 工作方式
-
-Harness 把一次模糊请求变成一条可以追踪的路径：
-
-```text
-需求
- ↓
-研究 → PRD → 架构 → 验收条件
- ↓
-任务拆分 → 实现 → 测试 → 审查
- ↓
-验证 → 学习 → 更新下一次任务
+| 问题 | 没有 Harness | 使用 Harness |
+|---|---|---|
+| 完成标准 | 看起来能跑就结束 | 验收条件、测试、validator 和 review 一起决定是否完成 |
+| 文件边界 | 靠 agent 临场判断 | 写入前先分类 create / skip / backup / overwrite / conflict |
+| 中断恢复 | 重新扫描仓库和历史决策 | `Harness/PROGRESS.md`、任务状态和 Memory 提供接力信息 |
+| 人工纠偏 | 人不断补上下文、盯冲突、催验证 | 人主要处理语义冲突和关键决策，`humanInterventions` 可记录 |
+| 成本 | 前期省步骤，后期返工不可见 | 初始化成本明确，duration、token 和验证证据可记录 |
+
+## HarnessBench 本地生命周期 benchmark
+
+2026-07-26，本仓库运行 v0.2 本地 benchmark：
+
+```bash
+node scripts/harness-bench-local.mjs --output benchmarks/results/harnessbench-local-v0.2.json
+node scripts/harness-bench.mjs --input benchmarks/results/harnessbench-local-v0.2.json --markdown
 ```
 
-### 三个核心支柱
+| Mode | Tasks | Runs | Verified safe | Protected overwrites | Repair-triggering runs | Manual repair events | Required-file misses | Benchmark leaks | Boundary violations |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| No Harness baseline (direct file writes) (`direct-run`) | 5 | 15 | 3/15 (20%) | 21 | 12 | 21 | 0 | 0 | 12 |
+| Harness safe path (`harness-wf`) | 5 | 15 | 15/15 (100%) | 0 | 0 | 0 | 0 | 0 | 0 |
 
-1. **目标与约束**：明确要解决什么、不能改什么、怎样算完成。
-2. **上下文与记忆**：通过路由、按需加载和持久记忆，把正确的信息交给正确的 agent。
-3. **分解与反馈**：把长任务切成有边界的小任务，每一步都留下验证和恢复入口。
+这组数据只证明本仓库内可复现的生命周期能力：新项目安装、已有 README/agent entry 保护、用户同名 skill 保护、旧 Harness 缺 updater 的恢复、以及 benchmark 不进入生成产物。
+
+它还不能证明任意前端、后端或嵌入式任务的模型成功率提升。完整 HarnessBench 会继续覆盖 Web/API、前端交互、嵌入式 UART/I2C/watchdog，以及生命周期恢复任务。未发布 raw logs 前，README 不写泛化成功率。
+
+Benchmark runner、fixture、scorer 和 raw JSON 都是外部证明材料，不会打进用户安装后的 Harness。
+
+## Prompt-cache L2 样本
+
+2026-07-23，本 dogfood 仓库运行了一次有预算上限的 Claude Code L2 prompt-cache probe：
+
+```bash
+node Harness/scripts/l2-cache-telemetry.mjs --groups provider-control,harness-thin,wf-light --turns 11 --turn-budget-usd 0.32 --total-budget-usd 1.20 --timeout-ms 240000
+```
+
+数据来自 Claude Code JSON usage 字段，尤其是 `usage.cache_read_input_tokens` 和 `usage.cache_creation_input_tokens`。读缓存比例按 `cache_read_input_tokens / (input_tokens + cache_creation_input_tokens + cache_read_input_tokens)` 计算。原始本地报告不提交进仓库，位置是 `~/.claude/cache-telemetry/harness-l2-claim-20260723-130331.json`。
+
+| 路由 | Turns | 成功率 | Warm median cache read | Warm 区间 | Warm median latency | 相对 provider-control |
+|---|---:|---:|---:|---:|---:|---:|
+| provider-control | 11 | 11/11 | 93.3% | 91.1%-95.4% | 2123.5 ms | baseline |
+| harness-thin | 11 | 11/11 | 98.7% | 98.1%-99.2% | 1786.5 ms | +5.4 个百分点 |
+| `/wf` wf-light | 11 | 11/11 | 99.1% | 98.7%-99.7% | 2900 ms | +5.8 个百分点 |
+
+边界：这只说明本次 Claude Code 受控样本里有真实缓存读取，并测到了提升；不是对所有模型、仓库、任务或 provider 的承诺。
 
 ## 架构图
 
 <p align="center">
   <a href="docs/images/harness-architecture-light.png">
-    <img src="docs/images/harness-architecture-light.png" alt="Harness Light 架构图：开发者请求经过目标与约束、优质上下文、分解与反馈，进入执行、验证、学习、更新闭环" width="100%">
+    <img src="docs/images/harness-architecture-light.png" alt="Harness Light 架构图：开发者请求经过目标与约束、上下文、分解与反馈，进入执行、验证、学习、更新闭环" width="100%">
   </a>
   <br>
   <sub>
-    Light 风格架构图 · <a href="docs/images/harness-architecture.drawio">下载可编辑 Drawio 源文件</a>
+    Light 风格架构图 | <a href="docs/images/harness-architecture.drawio">可编辑 Drawio 源文件</a>
   </sub>
 </p>
 
+三个核心支柱：
+
+1. **目标与约束**：明确要解决什么、不能改什么、怎样算完成。
+2. **上下文与记忆**：通过路由、按需加载和持久记忆，把正确的信息交给正确的 agent。
+3. **分解与反馈**：把长任务切成有边界的小任务，每一步都留下验证和恢复入口。
+
 ## 你会得到什么
 
 | 目录或文件 | 作用 |
@@ -134,61 +158,31 @@ Harness 把一次模糊请求变成一条可以追踪的路径：
 | `CLAUDE.md`、`AGENTS.md` | agent 会话入口契约和兼容指针 |
 | `Harness/README.md`、`Harness/MEMORY.md` | Harness 工作流路由和资源索引 |
 | `Harness/tasks/`、`Harness/PROGRESS.md` | 跨会话保存任务状态和接力信息 |
-| `.claude/`、`.agents/`、`.codex/`、`.opencode/` | 不同 coding agent 的发现入口和配置 |
+| `.claude/`、`.agents/skills/`、`.codex/`、`.opencode/` | 不同 coding agent 的发现入口和配置 |
 | `templates/common/`、`templates/optional/` | 可生成脚手架的声明式源文件 |
 | `Harness/scripts/validate-harness.mjs` | 检查脚手架结构和 bootstrap 完整度 |
 
-生成项目不会替你选择业务技术栈，也不会生成业务代码。你可以在 bootstrap 后自由选择 React、FastAPI 或其他技术栈。
-
-## 稳定性、返修率与人工纠偏：别让 Agent 靠运气交付
-
-先把话说满：Harness 不是更花哨的 prompt，而是给 Agent 装上刹车、仪表盘和黑匣子。没有工作契约，任务能不能收尾往往靠运气；有了 Harness，目标、边界、验证和返修都会留下证据。
-
-数字也必须说清楚：当前仓库还没有发布受控 A/B 实验，因此不能把“稳定性提升 50%”冒充成真实结果。真正能对外说的数字，只有用同一个模型、同一个仓库、同一个任务、同一个预算跑出来的结果。基准对比使用 `bare-agent`、`harness-wf`、`harness-wf-max` 三种模式。
-
-### Prompt-cache L2 实测样本
-
-2026-07-23，本 dogfood 仓库运行了一次有预算上限的 Claude Code L2 prompt-cache 探针：`node Harness/scripts/l2-cache-telemetry.mjs --groups provider-control,harness-thin,wf-light --turns 11 --turn-budget-usd 0.32 --total-budget-usd 1.20 --timeout-ms 240000`。
+生成项目不会替你选择业务技术栈，也不会生成业务代码。你可以在 bootstrap 后选择 React、FastAPI、嵌入式 C/C++ 或其他技术栈。
 
-数据来源是 Claude Code JSON usage 字段，尤其是 `usage.cache_read_input_tokens` 和 `usage.cache_creation_input_tokens`。读缓存比例按 `cache_read_input_tokens / (input_tokens + cache_creation_input_tokens + cache_read_input_tokens)` 计算。原始本地报告不提交进仓库，位置是 `~/.claude/cache-telemetry/harness-l2-claim-20260723-130331.json`。
+## 和相邻工具相比
 
-| 路由 | Turns | 成功率 | Warm median cache read | Warm 区间 | Warm median latency | 相对 provider-control |
-|---|---:|---:|---:|---:|---:|---:|
-| provider-control | 11 | 11/11 | 93.3% | 91.1%-95.4% | 2123.5 ms | baseline |
-| harness-thin | 11 | 11/11 | 98.7% | 98.1%-99.2% | 1786.5 ms | +5.4 个百分点 |
-| `/wf` wf-light | 11 | 11/11 | 99.1% | 98.7%-99.7% | 2900 ms | +5.8 个百分点 |
-
-边界：这能证明本次 Claude Code 有真实缓存读取，并且在这个受控样本里测到了提升；它不是对所有模型、仓库、任务或 provider 的泛化承诺。
+Harness 是 repo-local operating contract，可以叠在 Claude Code、Codex、OpenCode 或其他 agent 之上，不替代模型或编辑器本身。
 
-| 你真正关心的结果 | 没有 Harness | 使用 Harness | 可复现实测口径 |
-|---|---|---|---|
-| 稳定性 | 能跑就算完成，覆盖文件和漏验证常常事后才发现 | 写入前分类冲突，完成后必须经过测试、校验和审查 | 验证通过率、未授权覆盖次数、安全事故数 |
-| 返修率 | 返工藏在下一轮 prompt 里，没人知道到底重做了多少 | 任务胶囊、验收条件和验证闭环把返修显性化 | 后续纠偏运行次数 ÷ 已完成任务数 |
-| 人工纠偏 | 人类不断补上下文、盯进度、救火 | 人类只处理语义冲突和关键决策 | 每个任务的 `humanInterventions` |
-| 中断恢复 | Agent 重新扫描仓库，决策和背景再来一遍 | `PROGRESS.md`、任务状态和持久记忆直接接力 | 恢复时间、重复发现时间 |
-| 成本 | 前期省几分钟，后期可能付出几小时返工 | 有明确初始化成本，但时间、token 和验证开销可记录 | duration、tokenEstimate、验证命令 |
-
-当前仓库能直接验证的是工程底座：冲突策略、写入边界、验证器、任务记录和 `humanInterventions` 指标已经存在；收益百分比要由 HarnessBench 实测产生。详见 [HarnessBench v0.1 评分设计](Harness/tasks/task-framework-metrics-and-entry-contract/PLAN.md#5-metrics-and-scoring)。
-
-## 为什么人们会需要它
-
-用三个真实顾虑来理解它：
-
-| 顾虑 | 你担心什么 | Harness 怎么回答 |
+| 对比对象 | 主要层级 | Harness 的重点 |
 |---|---|---|
-| **嗔：损失厌恶** | 文件被覆盖、上下文漂移、任务返工 | 安全合并、冲突分类、写入边界、验证器 |
-| **贪：效率杠杆** | 同一个 agent 反复解释，长任务总要重来 | 路由、任务胶囊、并行角色、持久记忆 |
-| **痴：流程盲点** | 以为更好的 prompt 就能解决所有问题 | 把目标、约束、测试、审查和反馈变成可检查的流程 |
+| Direct agent run | 一次 prompt 加临时上下文 | 持久任务状态、显式写入边界、验证 gate、可恢复 handoff |
+| [Claude Code](https://code.claude.com/docs/en/overview)、[Codex](https://developers.openai.com/codex)、[OpenCode](https://opencode.ai/docs/) | Coding agent / runtime | 跨 runtime 的同一套 repo contract、命令面、memory 形状、validator 和更新策略 |
+| [Aider](https://github.com/aider-ai/aider) | Terminal pair-programming、repo map、git/test loop | 安装/更新安全、任务胶囊、外部 benchmark 证据和多 runtime 工作流路由 |
+| [Superpowers](https://github.com/obra/Superpowers) | Skills-based development methodology | npm scaffold、机器可读 ownership/version manifest、安全合并/更新脚本和生成后的 repo-local state |
 
 ## 可选工作流
 
 把需求直接交给 Agent：
 
-> 请为当前 Harness 项目加入 `browser-e2e` 和 `ui-ux-review`，保留已有文件，完成后运行严格校验，并准确汇报发生了什么变化。
+> 请为当前 Harness 项目加入 `ui-ux-review` 和 `ts-react-frontend`，保留已有文件，完成后运行严格校验，并准确汇报发生了什么变化。
 
 | 工作流 | 适合场景 |
 |---|---|
-| `browser-e2e` | 浏览器截图、追踪、冒烟测试 |
 | `ui-ux-review` | 响应式、无障碍和界面打磨 |
 | `ts-react-frontend` | TypeScript、React、Vite 项目 |
 | `python-backend` | FastAPI、pytest 项目 |
@@ -222,11 +216,11 @@ npm run check:mirrors
 
 ## 所有权清单
 
-`Harness/ownership.manifest.json` 是安装/更新时文件分类的机器可读唯一事实来源，由 `node scripts/build-version.mjs` 从 `templates/common/` + `templates/optional/catalog.json` 自动生成。框架拥有的文件覆盖升级；用户数据（tasks、memory、research、README、package、PROGRESS）一律保留；CLAUDE/AGENTS/Harness README 走合并；同名用户 agent/command/skill（无 marker）绝不覆盖。
+`Harness/ownership.manifest.json` 是安装和更新时文件分类的机器可读事实来源，由 `node scripts/build-version.mjs` 从 `templates/common/` 和 `templates/optional/catalog.json` 生成。框架拥有的文件走安全升级；用户数据（tasks、memory、research、README、package、PROGRESS）保留；CLAUDE、AGENTS、Harness README 走合并；同名用户 agent、command、skill（无 marker）不会被覆盖。
 
 ## 发布门禁
 
-铁律：每次 Harness 更新发版都必须同时保持两个更新通道可用：
+每次 Harness 更新发版都必须同时保持两个更新通道可用：
 
 - Canonical：npm `create-harness-vibe-coding@latest` 和 `https://github.com/LiWeny16/create-harness-vibe-coding`
 - 低版本兼容镜像：`https://github.com/zingspark/create-harness-vibe-coding`
@@ -238,29 +232,8 @@ npm run check:mirrors
 ## 适配范围与体积
 
 - 支持 Claude Code、Codex 和 OpenCode 的共享 Harness 工作流。
-- Node.js ≥ 18。
+- Node.js >= 18。
 - 运行时无额外依赖；CLI 依赖 `@clack/prompts` 和 `picocolors`。
 - 生成的是工作基础设施，不是业务应用代码。
 
-## 项目结构
-
-```text
-my-project/
-├── CLAUDE.md / AGENTS.md       ← agent 入口
-├── Harness/
-│   ├── README.md               ← 文档路由器
-│   ├── MEMORY.md               ← 资源索引
-│   ├── PROGRESS.md             ← 任务追踪器
-│   ├── settings.json           ← 框架配置
-│   ├── specs/                  ← 工作流、协议、运行时与安装指南
-│   ├── project/                ← 项目架构文档
-│   ├── tasks/                  ← 任务胶囊
-│   ├── research/               ← PRD 与研究模板
-│   └── scripts/                ← 校验器
-├── .claude/                    ← Claude Code 配置
-├── .agents/skills/             ← Codex repo skills
-├── .codex/                     ← Codex 配置
-└── .opencode/                 ← OpenCode 配置
-```
-
 MIT © [LiWeny16](https://github.com/LiWeny16)

package/README.md

@@ -16,8 +16,8 @@
 </p>
 
 <p align="center">
-  <a href="README-CN.md">Chinese</a> ·
-  <a href="https://github.com/LiWeny16/create-harness-vibe-coding">GitHub</a> ·
+  <a href="README-CN.md">Chinese</a> |
+  <a href="https://github.com/LiWeny16/create-harness-vibe-coding">GitHub</a> |
   <a href="https://www.npmjs.com/package/create-harness-vibe-coding">npm</a>
 </p>
 
@@ -30,25 +30,24 @@ It is not a prompt pack and it does not generate business code. It gives Claude
 Without a framework:
 
 ```text
-Idea → prompt → patch → demo → rediscover context → repair drift
+Idea -> prompt -> patch -> demo -> rediscover context -> repair drift
 ```
 
 With Harness:
 
 ```text
-Idea → Research → PRD → Architecture → Acceptance Criteria
-     → Build → Test → Review → Verify → Learn → Update
+Idea -> Research -> PRD -> Architecture -> Acceptance Criteria
+     -> Build -> Test -> Review -> Verify -> Learn -> Update
 ```
 
-## What's new in 0.8.15
+## Measured status in 0.8.16
 
-This release turns cache-friendliness from documentation into measured evidence:
+Current evidence in this repository:
 
-- Real Claude Code L2 telemetry: `Harness/scripts/l2-cache-telemetry.mjs` runs bounded provider-control, thin-startup, and `/wf` light-route probes with usage/cost/duration/session evidence.
-- Measured prompt-cache result in this dogfood repo: `harness-thin` reached `98.7%` warm median cache read (`+5.4` percentage points vs provider-control), and `/wf` wf-light reached `99.1%` (`+5.8` percentage points).
-- Cache regression guardrails: L0 validator checks, L1 SHA-256 stable-prefix simulation, L2 provider telemetry claim gates, and route-profile context budgets.
-- Cleaner startup and upgrade chain: normal sessions stay thin, `Harness/specs/guides/SETUP.md` is retained as a setup/migration reference, and `/wf-update` now reports the release highlights as well as file-level update results.
-- Cross-runtime CLI docs: `wf-agents-docs` records source-backed Claude Code, Codex, and OpenCode invocation patterns for peer review, batch probes, and cache telemetry.
+- HarnessBench v0.2 local lifecycle proof: 15 runs per mode. Direct file writes completed safely in 3/15 runs; the Harness safe path completed safely in 15/15 runs.
+- Protected overwrites in that proof: 21 for direct file writes, 0 for the Harness safe path.
+- Claude Code L2 prompt-cache sample: `harness-thin` reached `98.7%` warm median cache read (`+5.4` percentage points vs provider-control); `/wf` wf-light reached `99.1%` (`+5.8` percentage points).
+- Startup and update chain: thin startup remains the default, `Harness/specs/guides/SETUP.md` is only setup/migration reference material, and `/wf-update` reports `agent.releaseHighlights` plus validation results.
 
 ## One-line install (recommended for existing repos)
 
@@ -68,18 +67,20 @@ After reading this README, the agent selects the path that matches the project:
 | Existing `Harness/` but missing `Harness/scripts/wf-update-check.mjs` | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json`. Then run `node Harness/scripts/wf-update-check.mjs --json` |
 | After install or update | `node Harness/scripts/validate-harness.mjs --strict` |
 
+Install scope: project-local is the default. To seed a shared machine-level runtime, use `--install-scope global --global-dir <dir>`; commands/skills/agents are copied into Claude Code, Codex, and OpenCode host-global directories, while `Harness/tasks/`, `Harness/PROGRESS.md`, project memory, project facts, and project settings stay inside each target project.
+
 After installation, hand off by phase: use `CLAUDE.md` as the normal session entry, use `Harness/specs/guides/SETUP.md` only for install/bootstrap, migration, or upgrade decisions, and use `Harness/README.md` as the Harness workflow router when a routed task needs it. Preserve project boundaries; research and plan before editing; run tests, validation, and review before claiming completion.
 
 The user does not need to run commands manually. The agent handles installation, conflict handling, validation, and the handoff.
 
 ## Which WF command should you use?
 
-When in doubt, use `/wf-help`. It returns the full command table. Use `/wf` for complex work and `/wf-max` when the work can be safely parallelized.
+When in doubt, use `/wf-help` (or `$wf-help` in Codex). It returns the full command table. Use `/wf` for complex work and `/wf-max` when the work can be safely parallelized.
 
 | Command | Use it when | What it does | Example |
 |---|---|---|---|
-| `/wf <task>` | Multi-file, architectural, risky, migration, or repeatedly failing work | Research → plan → implement → test → review → verify → reflect | `/wf refactor the payment module and add tests` |
-| `/wf-max <task>` | The task splits into independent work and needs maximum parallelism | Adds CEO → Manager → Worker roles and parallel waves to the full WF chain | `/wf-max upgrade frontend, backend, and docs in parallel` |
+| `/wf <task>` | Multi-file, architectural, risky, migration, or repeatedly failing work | Research -> plan -> implement -> test -> review -> verify -> reflect | `/wf refactor the payment module and add tests` |
+| `/wf-max <task>` | The task splits into independent work and needs maximum parallelism | Adds CEO -> Manager -> Worker roles and parallel waves to the full WF chain | `/wf-max upgrade frontend, backend, and docs in parallel` |
 | `/wf-auto` | You want continuous self-directed optimization with adaptive probe selection | Runs repeated optimization cycles with plans, evidence, and feedback | `/wf-auto improve this project's stability` |
 | `/wf-auto-spark` | You need external inspiration, competitive direction, or a long-term roadmap | Searches for sparks, anchors work to a North Star and milestones, and guards scope drift | `/wf-auto-spark explore product growth directions` |
 | `/wf-review [focus]` | You need a second opinion, peer review, or a pre-release check | Uses a peer CLI when available, otherwise an independent reviewer role, and classifies findings by severity | `/wf-review focus on security and data loss` |
@@ -90,26 +91,46 @@ When in doubt, use `/wf-help`. It returns the full command table. Use `/wf` for
 | `/wf-remove` | You need to uninstall Harness | Removes safe files, preserves user data, and asks before touching conflicts | `/wf-remove` |
 | `/wf-help` | You do not know which command to use | Returns command usage without starting a workflow | `/wf-help` |
 
-Claude Code uses `/wf-*`; Codex uses the matching `$wf-*`; OpenCode uses the registered command or Agent instruction. `/wf-auto` and `/wf-auto-spark` are continuous modes, so give the agent a clear goal, scope, and acceptance criteria before starting.
+Claude Code uses `/wf-*`; Codex uses the matching `$wf-*`; OpenCode uses the registered command or Agent instruction. Browser E2E guidance is built into `wf-browser`. `/wf-auto` and `/wf-auto-spark` are continuous modes, so give the agent a clear goal, scope, and acceptance criteria before starting.
 
 Common starting points: Web/API work starts with correctness, security, reliability, and verification; CLI/SDK work starts with contracts, compatibility, error UX, and docs; AI-agent work starts with context quality, tool safety, evaluation, and recovery; data jobs start with idempotency, failure recovery, and observability. See the full [WF-AUTO-ANGLES.md](Harness/specs/workflows/WF-AUTO-ANGLES.md) selection protocol.
 
 Chinese README: [README-CN.md](README-CN.md)
 
-## Why this matters: the measurable difference
+## Measured difference
 
-Better prompts can improve one turn. A harness improves the conditions around every turn: what the agent may read, what it may change, how success is checked, and how the next session recovers.
+Harness does not make the model smarter. It reduces uncontrolled parts of agent
+work: which files may change, how conflicts are handled, how recovery works, and
+what evidence counts as complete.
 
-| Dimension | Prompt-only / no Harness | With Harness | What to measure |
-|---|---|---|---|
-| Verified completion | “It looks finished” after a demo | Acceptance criteria, tests, validators, and review are part of the task boundary | Verified completion rate |
-| Stability and safety | File ownership and conflict handling are ad hoc | Script-first plans classify create/skip/backup/overwrite/conflict before writes | Safety incidents and unauthorized overwrites |
-| Rework rate | Drift is discovered late, so correction work is hidden in follow-up prompts | Task capsules, explicit boundaries, and closed-loop verification expose and reduce avoidable rework | `follow-up corrective runs ÷ completed tasks` |
-| Human correction | People repeatedly restate context and rescue the agent | Humans focus on semantic conflicts and decisions; deterministic work stays in scripts | `humanInterventions` per task |
-| Recovery after interruption | Rediscover the repository and decisions from scratch | `Harness/PROGRESS.md`, task capsules, and durable memory preserve the handoff | Recovery time and duplicated discovery |
-| Cost | Lower setup cost, unpredictable downstream cost | More upfront structure, with token/time overhead recorded against the baseline | Duration, tokens, and cost overhead |
+The current published benchmark is a deterministic local lifecycle proof, not a
+full LLM feature-success A/B result. It creates 5 fixture families x 3 seeds per
+mode and checks the filesystem after each run. See
+[HarnessBench v0.2](docs/benchmarks/HarnessBench.md).
+
+Benchmark assets stay outside generated installs: users get the published
+summary, not the runner, fixtures, scorer, or raw logs.
+
+### HarnessBench local lifecycle proof
+
+Run on 2026-07-26:
+
+```bash
+node scripts/harness-bench-local.mjs --output benchmarks/results/harnessbench-local-v0.2.json
+node scripts/harness-bench.mjs --input benchmarks/results/harnessbench-local-v0.2.json --markdown
+```
+
+| Mode | Tasks | Runs | Verified safe | Protected overwrites | Repair-triggering runs | Manual repair events | Required-file misses | Benchmark leaks | Boundary violations |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| No Harness baseline (direct file writes) (`direct-run`) | 5 | 15 | 3/15 (20%) | 21 | 12 | 21 | 0 | 0 | 12 |
+| Harness safe path (`harness-wf`) | 5 | 15 | 15/15 (100%) | 0 | 0 | 0 | 0 | 0 | 0 |
 
-The honest status: this repository defines the comparison protocol, but it does not publish fabricated “50% fewer bugs” numbers. Run the same model, repo, prompt, budget, and verification in three modes—`bare-agent`, `harness-wf`, and `harness-wf-max`—before making a quantitative claim. See the [HarnessBench v0.1 scoring design](Harness/tasks/task-framework-metrics-and-entry-contract/PLAN.md#5-metrics-and-scoring).
+What this proves: Harness has measurable boundary value for fresh install,
+existing-project preservation, same-name user skill protection, old-Harness
+updater recovery, and generated-install benchmark exclusion. It does not prove
+that any model solves arbitrary frontend, backend, or embedded feature work at a
+higher rate. That requires the full HarnessBench LLM A/B suite with raw run
+logs.
 
 ### Prompt-cache L2 sample
 
@@ -125,15 +146,16 @@ Source: Claude Code JSON usage fields, especially `usage.cache_read_input_tokens
 
 Claim boundary: this proves real cache reads and a measured improvement in this bounded Claude Code sample. It is not a universal claim for every model, repository, task, or provider.
 
-## Three human motivations, used ethically
+### Compared with adjacent tools
 
-README structure should meet people where decisions actually happen. Harness uses the three motivations below to make the trade-off explicit—not to manufacture urgency or hide uncertainty.
+Harness is a repo-local operating contract. It can sit above Claude Code, Codex, OpenCode, or another agent instead of replacing them.
 
-| Motivation | The reader is thinking | Harness answers with |
+| Compared with | Primary layer | Harness advantage |
 |---|---|---|
-| **Loss aversion** | “I cannot afford lost files, silent drift, or another repair cycle.” | Safe-merge conflict policies, scoped write sets, validators, and review evidence |
-| **Leverage** | “I want the same agent to finish more work with less repeated explanation.” | Router-based context loading, task capsules, parallel role dispatch, and durable memory |
-| **Blind spot** | “A better prompt should be enough.” | A visible process: goal → constraints → tests → feedback, plus a benchmarkable baseline |
+| Direct agent run | One prompt plus ad hoc context | Persistent task state, explicit write boundaries, verification gates, and recoverable handoff |
+| [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://developers.openai.com/codex), [OpenCode](https://opencode.ai/docs/) | Coding agents and runtimes | Cross-runtime repo contract with the same commands, memory shape, validator, and update policy |
+| [Aider](https://github.com/aider-ai/aider) | Terminal pair-programming, repo map, git/test loop | Harness focuses on install/update safety, task capsules, external benchmark evidence, and multi-runtime workflow routing |
+| [Superpowers](https://github.com/obra/Superpowers) | Skills-based development methodology | Harness adds an npm scaffold, machine-readable ownership/version manifests, safe merge/update scripts, and generated repo-local state |
 
 ## Architecture
 
@@ -143,15 +165,15 @@ README structure should meet people where decisions actually happen. Harness use
   </a>
   <br>
   <sub>
-    Light infographic · <a href="docs/images/harness-architecture.drawio">editable Drawio source</a>
+    Light infographic - <a href="docs/images/harness-architecture.drawio">editable Drawio source</a>
   </sub>
 </p>
 
 The architecture has three pillars:
 
-1. **Goals & Constraints** — PRD → research → architecture → acceptance criteria.
-2. **Quality Context** — a router, context-loading protocol, and durable memory keep attention on the right evidence.
-3. **Decomposition & Feedback** — `/wf` and `/wf-max` assign bounded work, then review, verify, learn, and update the next task.
+1. **Goals & Constraints** - PRD -> research -> architecture -> acceptance criteria.
+2. **Quality Context** - a router, context-loading protocol, and durable memory keep attention on the right evidence.
+3. **Decomposition & Feedback** - `/wf` and `/wf-max` assign bounded work, then review, verify, learn, and update the next task.
 
 ## What gets scaffolded
 
@@ -182,11 +204,10 @@ If `Harness/` already exists, first check whether `Harness/scripts/wf-update-che
 
 Ask your agent to add the capability you need:
 
-> Add `browser-e2e` and `ui-ux-review` to this Harness project, preserve existing files, run the strict validator, and report exactly what changed.
+> Add `ui-ux-review` and `ts-react-frontend` to this Harness project, preserve existing files, run the strict validator, and report exactly what changed.
 
 | Workflow | Use it for |
 |---|---|
-| `browser-e2e` | Screenshots, traces, and smoke tests |
 | `ui-ux-review` | Responsive, accessibility, and polish review |
 | `ts-react-frontend` | TypeScript, React, and Vite projects |
 | `python-backend` | FastAPI and pytest projects |
@@ -239,11 +260,11 @@ Low-version installs can have updater scripts hardcoded to the legacy mirror. Do
 |---|---|
 | Runtime | None |
 | Dependencies | 2 (`@clack/prompts`, `picocolors`) |
-| Node.js | ≥ 18 |
+| Node.js | >=18 |
 | Generated application code | None until you choose a stack |
 
 ## Keywords and related concepts
 
-AI coding agent framework · agentic workflow · context engineering · long-running coding tasks · task orchestration · durable memory · safe merge · conflict handling · acceptance criteria · Claude Code · Codex · OpenCode · Node.js CLI · developer productivity
+AI coding agent framework; agentic workflow; context engineering; long-running coding tasks; task orchestration; durable memory; safe merge; conflict handling; acceptance criteria; Claude Code; Codex; OpenCode; Node.js CLI; developer productivity
 
-MIT © [LiWeny16](https://github.com/LiWeny16)
+MIT (c) [LiWeny16](https://github.com/LiWeny16)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.16",
+  "version": "0.8.18",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {