create-harness-vibe-coding 0.8.13 → 0.8.17

package/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+## [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.
+- Register `/wf-update` in `Harness/MEMORY.md` as a direct command and add validator coverage for the route.
+- Clean `wf-remove.mjs` human-readable output to remove replacement characters and add a validator guard against future encoding pollution.
+
+## [0.8.15] - 2026-07-23
+
+- Add real Claude Code L2 prompt-cache telemetry via `Harness/scripts/l2-cache-telemetry.mjs`, including bounded provider-control, thin-startup, and `/wf` light-route probes.
+- Record the measured cache result in README: harness-thin warm median cache read `98.7%` (`+5.4` percentage points vs provider-control) and `/wf` wf-light `99.1%` (`+5.8` percentage points), with the raw local report path and the exact usage-field formula.
+- Add cache regression gates: L0 structure checks, L1 SHA-256 stable-prefix simulation, L2 claim-gated provider telemetry, and context-budget guards for route profiles.
+- Tighten startup routing: normal sessions stay thin (`CLAUDE.md` + `Harness/memory/startup-hints.md`), `Harness/specs/guides/SETUP.md` is retained only as install/bootstrap/migration/upgrade reference, and `Harness/README.md` remains the routed workflow router.
+- Add `wf-agents-docs` CLI invocation guidance for Claude Code, Codex, and OpenCode automation, including JSON telemetry parsing and cache-attribution boundaries.
+- Align `/wf-update` direct commands with the 8-step safe update flow: safe apply first, script-recorded conflict decisions, finalize only after conflicts are resolved, then validate and scan.
+- Harden update/remove consistency: remove script recognizes new built-in agents/skills, updater keeps `Harness/specs/guides/SETUP.md` instead of treating it as disposable bootstrap debt, and validators catch route/cache/update drift.
+
+## [0.8.14] - 2026-07-22
+
+- Introduce `Harness/ownership.manifest.json` as the machine-readable source of truth for install/update file classification; auto-generated by `node scripts/build-version.mjs` from `templates/common/` + `templates/optional/catalog.json`, manifest-first with content-marker fallback for old installs.
+- Fix optional-skill collision: user same-name skills (e.g. `browser-e2e`) are no longer overwritten when the option is not installed (`optionalOwned` → `safe-if-installed`).
+- Normalize line endings via `.gitattributes` so `git diff --check` stays clean across Windows/POSIX.
+- Release gate reminder: legacy `zingspark` mirror sync AND `npm publish` must both complete before announcing an update as available to existing users.
+- Install collision guard: same-name user-authored agents/commands/skills are preserved under overwrite/backup/skip and surface as conflicts under fail; only files carrying a Harness ownership marker upgrade, and a warning names each preserved user file.
+- Tighten Harness-ownership detection: drop the broad `/wf` substring marker that false-matched user files merely mentioning `/wf`; frontmatter and specific identity markers remain.
+- Docs: align `/wf-update` command and skill with updater behavior — carry-forward covers all merge-tier files (CLAUDE.md, AGENTS.md, MEMORY.md, Harness/MEMORY.md, Harness/README.md), root README.md is PRESERVE while Harness/README.md is merge-tier, and safe-apply covers SAFE/NEW/adopted files.
+- Release gate: legacy mirror must also publish the tag's GitHub Release, not only commit/tag/manifest.
+- Carry forward unchanged accepted CLAUDE.md/AGENTS.md conflict decisions so update checks do not re-ask for the same keep-local choice every release.
+- Detect existing untracked Harness-owned agent/command/skill files by content markers before overwriting; same-name user files remain real conflicts.
+- Add `harness: wf-agent` markers to built-in agent frontmatter for future content-based ownership checks.
+- Prepare SAFE/NEW update files concurrently while preserving all-or-nothing checksum validation before writing.
+
+## [0.8.13] - 2026-07-22
+
+- Make Harness updates resolve from npm `create-harness-vibe-coding@latest` first, with `LiWeny16/create-harness-vibe-coding` as the canonical GitHub fallback and `zingspark/create-harness-vibe-coding` as the legacy mirror fallback.
+- Keep generated installs on the canonical `LiWeny16` source while requiring `zingspark` legacy mirror sync for old updaters.
+- Make `--apply-safe` validate all remote hashes before writing any SAFE/NEW files.
+- Force the latest install CLI's existing-Harness update switch to pass the canonical `LiWeny16` source to older updater scripts.
+
+## [0.8.12] - 2026-07-22
+
+- Harden `/wf-auto-spark` with documented search fallbacks, reflector escalation, and drift/delegation anti-pattern guards.
+- Make task-scribe the default process-file writer for spark and WF-MAX task-state updates.
+- Add validator and generator coverage for the new spark protocol contract.
+- Refresh the homepage 3D Act 1 opening layout and interaction refinements.
+
+## [0.8.11] - 2026-07-21
+
+- Move repository metadata, README links, and Harness update sources to `LiWeny16/create-harness-vibe-coding`.
+- Prepare personal-repo maintenance as the canonical public source.
+
+## [0.8.10] - 2026-07-21
+
+- Move Harness update reminders to startup-only hooks for Claude, Codex, and OpenCode.
+- Harden `wf-update-check.mjs` so stable updates prefer a usable GitHub release, ignore prerelease generators, and fall back to `main` when release metadata is stale.
+- Add validator, generator, E2E, pack-smoke, and CI/pre-push coverage for startup-only update checks.
+- Reject drive-letter paths in Harness update/remove/clean scripts across platforms.
+
+## [0.8.9] - 2026-07-17
+
+- Add safe recovery for older Harness installs missing `wf-update-check.mjs`.
+- Tighten update-check JSON output and WF-AUTO hook output to keep default agent context small.
+- Add L2 startup memory hints and L3 memory route indexing to generated Harness installs.
+- Add symlink write-path protection and P0 regressions for scaffold safety.
+- Include the README icon in the published npm package.
+
+## [0.5.0] - 2026-06-25
+
+- `/wf-learn` command: force memory learning cycle (context-master → memory-master → project + global memory).
+- Fix auto-trigger: replace unreliable "3x failure" rule with mandatory closeout gate in wf-mode.
+- Register `/wf-learn` in all routers (CLAUDE.md, MEMORY.md, README.md).
+
+## [0.4.3] - 2026-06-25
+
+- Add CHANGELOG.md with full version history (0.1.4 → 0.4.2).
+- Create git tags v0.3.0–v0.4.2 and GitHub Releases for all major versions.
+- Bump harness-version to 0.4.2.
+
+## [0.4.2] - 2026-06-25
+
+- Simplify CLAUDE.md Section 7: route to WF.md/WF-MAX.md instead of inline dispatch rules.
+
+## [0.4.1] - 2026-06-25
+
+- CEO must not write code directly in `/wf` or `/wf-max` mode — delegate only.
+- Reinforce CEO constraint in WF-MAX.md.
+
+## [0.4.0] - 2026-06-25
+
+- `/wf <task/mission>`: command now accepts a required task argument.
+- `/wf-max [task]`: renamed from `/wf max`, accepts an optional task argument.
+- Remove `wf-mode` as a standalone slash command (skill still handles natural-language triggers).
+- CEO must not call `EnterPlanMode` — delegate planning to `planner` subagents.
+- Sync all trigger keywords across CLAUDE.md, Harness docs, validators, and templates.
+
+## [0.3.4] - 2026-06-25
+
+- Fix markdown bold syntax — move punctuation outside `**` markers.
+- Full README rewrite: concise, punchy, scannable.
+- Sync README EN/CN: agent prompt top, full CN alignment.
+
+## [0.3.3] - 2026-06-24
+
+- WF-MAX cross-reference integrity fix.
+- Sync harness dogfood to 0.3.3: version bump, SETUP.md, recompute checksums.
+
+## [0.3.2] - 2026-06-24
+
+- `/wf max`: three-tier enterprise hierarchy (CEO → Managers → Workers).
+- Span formula, leaf condition, wave orchestration, manager synthesis protocol.
+
+## [0.3.1] - 2026-06-23
+
+- Fix README-CN mermaid syntax.
+- Sync README-CN with English, add mermaid workflow diagram.
+
+## [0.3.0] - 2026-06-23
+
+- PROGRESS.md + tasks/ task capsules.
+- WF update mechanism (`/wf update`).
+- memory-master and context-master agents.
+- Cohesion rule (feature doc < Worker granularity).
+
+## [0.2.1] - 2026-06-22
+
+- WF multi-agent routing with subagent orchestration.
+
+## [0.2.0] - 2026-06-22
+
+- Harness root workflow (`/wf`).
+- CLAUDE.md, Harness/ docs structure, and initial agent roster.
+
+## [0.1.10] - 2026-06-21
+
+- Non-invasive harness bootstrap.
+- Optional skills catalog.
+- `--json` output flag.
+
+## [0.1.9] - 2026-06-21
+
+- Feature versioning: iterate vs new based on 85% overlap rule.
+
+## [0.1.8] - 2026-06-21
+
+- Template Fill Guide in SETUP.md: map every placeholder to expected content.
+
+## [0.1.7] - 2026-06-21
+
+- Skill-discovery guide.
+- CLAUDE.md renumbering.
+- SETUP.md isolation.
+
+## [0.1.6] - 2026-06-20
+
+- Wire architecture research refs, seed repos, and user-confirmation protocol into harness.
+
+## [0.1.5] - 2026-06-20
+
+- Add `-y`/`--yes` and `-h`/`--help` flags.
+- Document agent self-bootstrapping.
+
+## [0.1.4] - 2026-06-20
+
+- Initial public release.

package/README-CN.md

@@ -11,166 +11,182 @@
 
 <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.16 这版只写已经跑出来的数据：
 
-## 一句话安装（已有项目推荐）
+- 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` 和验证结果。
 
-把下面这句话原样丢给正在使用的 Agent：
+完整的模型任务成功率 A/B 还没有发布。要对外说“模型解题成功率提升”，必须用同一个模型、同一个 fixture、同一个 prompt、同一个预算和同一套验证命令跑完 raw logs。
+
+## 一句话安装
+
+把下面这句话交给当前正在使用的 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`，走更新流程，不要重复安装 |
+| 已有 `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` |
 
-安装后的 instruction：先读取 `CLAUDE.md`、`AGENTS.md`、`Harness/SETUP.md` 和 `Harness/README.md`；遵守项目已有边界；先研究和计划，再修改代码；完成后运行测试、校验和审查，未验证不要声称完成。
+用户不需要手动执行这些命令。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 | `/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/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. **分解与反馈**：把长任务切成有边界的小任务，每一步都留下验证和恢复入口。
+
 ## 你会得到什么
 
 | 目录或文件 | 作用 |
 |---|---|
-| `CLAUDE.md`、`AGENTS.md` | agent 启动入口和角色注册 |
-| `Harness/README.md`、`Harness/MEMORY.md` | 按任务路由文档和资源 |
+| `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 靠运气交付
+生成项目不会替你选择业务技术栈，也不会生成业务代码。你可以在 bootstrap 后选择 React、FastAPI、嵌入式 C/C++ 或其他技术栈。
 
-先把话说满：Harness 不是更花哨的 prompt，而是给 Agent 装上刹车、仪表盘和黑匣子。没有工作契约，任务能不能收尾往往靠运气；有了 Harness，目标、边界、验证和返修都会留下证据。
+## 和相邻工具相比
 
-数字也必须说清楚：当前仓库还没有发布受控 A/B 实验，因此不能把“稳定性提升 50%”冒充成真实结果。真正能对外说的数字，只有用同一个模型、同一个仓库、同一个任务、同一个预算跑出来的结果。基准对比使用 `bare-agent`、`harness-wf`、`harness-wf-max` 三种模式。
+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 项目 |
 | `github-pr-review` | PR diff 审查和 CI 证据 |
 
-外部推荐只会记录到 `Harness/SETUP.md`，不会自动安装：
+外部推荐只会记录到 `Harness/specs/guides/SETUP.md`，不会自动安装：
 
 | 推荐 | 用途 | 来源 |
 |---|---|---|
@@ -196,39 +212,26 @@ node Harness/scripts/validate-harness.mjs --strict
 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 更新发版都必须同时保持两个更新通道可用：
+每次 Harness 更新发版都必须同时保持两个更新通道可用：
 
 - Canonical：npm `create-harness-vibe-coding@latest` 和 `https://github.com/LiWeny16/create-harness-vibe-coding`
 - 低版本兼容镜像：`https://github.com/zingspark/create-harness-vibe-coding`
 
-低版本用户的 updater 可能已经硬编码到旧的 `zingspark` 仓库。发布不能只更新新仓库；必须等 legacy mirror 拥有同一份 commit、tag 和生成后的 template manifest，才算发版完成。新安装生成的 `Harness/.harness-version` 仍然记录 canonical `LiWeny16` source；`zingspark` 只作为旧用户兼容镜像保留。
+低版本用户的 updater 可能已经硬编码到旧的 `zingspark` 仓库。发布不能只更新新仓库；必须等 legacy mirror 拥有同一份 `main` 分支 commit、版本 tag、生成后的 template manifest（`templates/common/.harness-version` 与 `templates/common/Harness/ownership.manifest.json`），且该 tag 对应的 GitHub Release artifact 已在 legacy mirror 上发布，且全部与 canonical 一致，才算发版完成。新安装生成的 `Harness/.harness-version` 仍然记录 canonical `LiWeny16` source；`zingspark` 只作为旧用户兼容镜像保留。
+
+“代码就绪”不等于“用户可更新”。已发布 npm 的用户只有在 `npm publish` 完成、GitHub release/tag 已创建、且两个镜像都已同步之后，才能拿到新版本。在三者全部完成之前，不要向现有用户宣布更新可用。
 
 ## 适配范围与体积
 
 - 支持 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               ← 文档路由器
-│   ├── SETUP.md                ← bootstrap 指南
-│   ├── MEMORY.md               ← 资源索引
-│   ├── PROGRESS.md             ← 任务追踪器
-│   ├── tasks/                  ← 任务胶囊
-│   ├── research/               ← PRD 与研究模板
-│   └── scripts/                ← 校验器
-├── .claude/                    ← Claude Code 配置
-├── .agents/skills/             ← Codex repo skills
-├── .codex/                     ← Codex 配置
-└── .opencode/                 ← OpenCode 配置
-```
-
 MIT © [LiWeny16](https://github.com/LiWeny16)