create-harness-vibe-coding 0.8.13 → 0.8.16

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+## [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

@@ -29,6 +29,16 @@
 
 它不是 prompt 集合，也不是模型本身。它解决的是另一个问题：同一个 agent 为什么第一轮看起来很好，第二轮却开始忘记决策、扩大修改范围、跳过验证？
 
+## 0.8.15 新增重点
+
+这一版把“cache-first 设计”从原则推进到可复现实测：
+
+- 新增真实 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 规则。
+
 ## 一句话安装（已有项目推荐）
 
 把下面这句话原样丢给正在使用的 Agent：
@@ -43,11 +53,11 @@ Agent 读取本 README 后，按项目状态选择安装路径：
 |---|---|
 | 新项目 | `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`；遵守项目已有边界；先研究和计划，再修改代码；完成后运行测试、校验和审查，未验证不要声称完成。
+安装后的 handoff 按阶段区分：正常会话入口是 `CLAUDE.md`；`Harness/specs/guides/SETUP.md` 只用于安装/bootstrap、迁移或升级决策；需要 Harness 工作流路由时再读 `Harness/README.md`。遵守项目已有边界；先研究和计划，再修改代码；完成后运行测试、校验和审查，未验证不要声称完成。
 
 用户不需要手动执行命令。把上面一句话交给 Agent，Agent 负责安装、冲突处理、校验和汇报。
 
@@ -65,13 +75,13 @@ Agent 读取本 README 后，按项目状态选择安装路径：
 | `/wf-learn` | 同类错误反复出现，或一次任务结束后要沉淀经验 | 汇总上下文、记忆和项目经验，形成下一次可复用规则 | `/wf-learn 总结这次返修原因` |
 | `/wf-browser <任务>` | 浏览器冒烟、E2E、截图、表单或页面验证 | 使用真实浏览器完成操作并提供截图、追踪和验证证据 | `/wf-browser 验证登录和支付流程` |
 | `/wf-readme <任务>` | README、安装文档、架构图或项目说明需要重写 | 保留事实，整理结构，补充安装和使用说明 | `/wf-readme 优化中文 README` |
-| `/wf-update` | 已经安装 Harness，需要检查和应用框架更新 | 比较版本，自动处理安全变更，把语义冲突留给 Agent | `/wf-update` |
+| `/wf-update` | 已经安装 Harness，需要检查和应用框架更新 | 比较版本，自动处理安全变更，把语义冲突留给 Agent，并从 changelog metadata 汇报本次升级核心变化 | `/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)。
+常见场景可以这样起步：Web/API 先看正确性、安全、可靠性和验证；CLI/SDK 先看契约、兼容性、错误体验和文档；AI Agent 先看上下文质量、工具安全、评测和恢复；数据任务先看幂等性、失败恢复和可观测性。完整的自适应选择规则见 [WF-AUTO-ANGLES.md](Harness/specs/workflows/WF-AUTO-ANGLES.md)。
 
 ## 它改变了什么？
 
@@ -121,8 +131,8 @@ Harness 把一次模糊请求变成一条可以追踪的路径：
 
 | 目录或文件 | 作用 |
 |---|---|
-| `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 的发现入口和配置 |
 | `templates/common/`、`templates/optional/` | 可生成脚手架的声明式源文件 |
@@ -136,6 +146,20 @@ 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`。
+
+数据来源是 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 | 使用 Harness | 可复现实测口径 |
 |---|---|---|---|
 | 稳定性 | 能跑就算完成，覆盖文件和漏验证常常事后才发现 | 写入前分类冲突，完成后必须经过测试、校验和审查 | 验证通过率、未授权覆盖次数、安全事故数 |
@@ -170,7 +194,7 @@ Harness 把一次模糊请求变成一条可以追踪的路径：
 | `python-backend` | FastAPI、pytest 项目 |
 | `github-pr-review` | PR diff 审查和 CI 证据 |
 
-外部推荐只会记录到 `Harness/SETUP.md`，不会自动安装：
+外部推荐只会记录到 `Harness/specs/guides/SETUP.md`，不会自动安装：
 
 | 推荐 | 用途 | 来源 |
 |---|---|---|
@@ -196,6 +220,10 @@ 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 更新发版都必须同时保持两个更新通道可用：
@@ -203,7 +231,9 @@ npm run check:mirrors
 - 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 已创建、且两个镜像都已同步之后，才能拿到新版本。在三者全部完成之前，不要向现有用户宣布更新可用。
 
 ## 适配范围与体积
 
@@ -219,9 +249,11 @@ my-project/
 ├── CLAUDE.md / AGENTS.md       ← agent 入口
 ├── Harness/
 │   ├── README.md               ← 文档路由器
-│   ├── SETUP.md                ← bootstrap 指南
 │   ├── MEMORY.md               ← 资源索引
 │   ├── PROGRESS.md             ← 任务追踪器
+│   ├── settings.json           ← 框架配置
+│   ├── specs/                  ← 工作流、协议、运行时与安装指南
+│   ├── project/                ← 项目架构文档
 │   ├── tasks/                  ← 任务胶囊
 │   ├── research/               ← PRD 与研究模板
 │   └── scripts/                ← 校验器

package/README.md

@@ -40,6 +40,16 @@ Idea → Research → PRD → Architecture → Acceptance Criteria
      → Build → Test → Review → Verify → Learn → Update
 ```
 
+## What's new in 0.8.15
+
+This release turns cache-friendliness from documentation into measured evidence:
+
+- 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.
+
 ## One-line install (recommended for existing repos)
 
 Paste this into your agent:
@@ -54,11 +64,11 @@ After reading this README, the agent selects the path that matches the project:
 |---|---|
 | New project | `npx create-harness-vibe-coding@latest my-project -y` |
 | Existing project | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json` |
-| Existing `Harness/` with `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`; update, do not reinstall |
+| Existing `Harness/` with `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`; update, do not reinstall; after apply/finalize, report `agent.releaseHighlights` plus validation results |
 | 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` |
 
-After installation, read `CLAUDE.md`, `AGENTS.md`, `Harness/SETUP.md`, and `Harness/README.md`; preserve project boundaries; research and plan before editing; run tests, validation, and review before claiming completion.
+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.
 
@@ -76,13 +86,13 @@ When in doubt, use `/wf-help`. It returns the full command table. Use `/wf` for
 | `/wf-learn` | The same mistakes keep recurring or a completed task needs to become reusable knowledge | Consolidates context, memory, and project lessons | `/wf-learn summarize why this task needed rework` |
 | `/wf-browser <task>` | Browser smoke tests, E2E, screenshots, forms, or UI verification | Uses a real browser and returns screenshots, traces, and evidence | `/wf-browser verify login and checkout` |
 | `/wf-readme <task>` | README, install docs, architecture diagrams, or project docs need work | Preserves facts while improving structure, setup, and usage guidance | `/wf-readme improve the Chinese README` |
-| `/wf-update` | Harness is already installed and needs an update | Compares versions, applies safe changes, and leaves semantic conflicts to the agent | `/wf-update` |
+| `/wf-update` | Harness is already installed and needs an update | Compares versions, applies safe changes, leaves semantic conflicts to the agent, and reports release highlights from the changelog metadata | `/wf-update` |
 | `/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.
 
-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/WF-AUTO-ANGLES.md) selection protocol.
+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)
 
@@ -101,6 +111,20 @@ Better prompts can improve one turn. A harness improves the conditions around ev
 
 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).
 
+### Prompt-cache L2 sample
+
+On 2026-07-23, this dogfood repository ran a bounded Claude Code L2 prompt-cache probe with `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`.
+
+Source: Claude Code JSON usage fields, especially `usage.cache_read_input_tokens` and `usage.cache_creation_input_tokens`. Read ratio is `cache_read_input_tokens / (input_tokens + cache_creation_input_tokens + cache_read_input_tokens)`. The raw local report is outside the repo at `~/.claude/cache-telemetry/harness-l2-claim-20260723-130331.json`.
+
+| Route | Turns | Success | Warm median cache read | Warm range | Warm median latency | Uplift vs 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 percentage points |
+| `/wf` wf-light | 11 | 11/11 | 99.1% | 98.7%-99.7% | 2900 ms | +5.8 percentage points |
+
+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
 
 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.
@@ -133,8 +157,8 @@ The architecture has three pillars:
 
 | Layer | Purpose |
 |---|---|
-| `CLAUDE.md`, `AGENTS.md` | Agent entry contract and registry |
-| `Harness/README.md`, `Harness/MEMORY.md` | Task-based routing and resource index |
+| `CLAUDE.md`, `AGENTS.md` | Agent session entry contract and compatibility pointer |
+| `Harness/README.md`, `Harness/MEMORY.md` | Harness workflow router and resource index |
 | `Harness/tasks/`, `Harness/PROGRESS.md` | Resumable task state across sessions |
 | `.claude/`, `.agents/`, `.codex/`, `.opencode/` | Tool-specific discovery and configuration |
 | `templates/common/`, `templates/optional/` | Declarative scaffold source and optional workflows |
@@ -150,7 +174,7 @@ Paste this to your agent:
 Read and follow https://github.com/LiWeny16/create-harness-vibe-coding exactly to configure this project with create-harness-vibe-coding.
 ```
 
-The agent-first path previews the target before writing and preserves project-owned files. If you need the detailed CLI contract, the agent can read `Harness/SETUP.md` after setup.
+The agent-first path previews the target before writing and preserves project-owned files. `Harness/specs/guides/SETUP.md` is the retained bootstrap/migration reference created by the scaffold; it is not the normal session entry.
 
 If `Harness/` already exists, first check whether `Harness/scripts/wf-update-check.mjs` exists. If it does, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs --json` instead of reinstalling blindly. If it is missing, run the safe CLI recovery command from the installation table first, then run the updater.
 
@@ -168,7 +192,7 @@ Ask your agent to add the capability you need:
 | `python-backend` | FastAPI and pytest projects |
 | `github-pr-review` | PR diff review and CI evidence |
 
-External recommendations are recorded in `Harness/SETUP.md`; they are not auto-installed.
+External recommendations are recorded in `Harness/specs/guides/SETUP.md`; they are not auto-installed.
 
 | Recommendation | Use it for | Source |
 |---|---|---|
@@ -194,6 +218,10 @@ node Harness/scripts/validate-harness.mjs --strict
 npm run check:mirrors
 ```
 
+## Ownership manifest
+
+`Harness/ownership.manifest.json` is the machine-readable source of truth for file classification during install/update. It is auto-generated from `templates/common/` + `templates/optional/catalog.json` by `node scripts/build-version.mjs`. Framework-owned files overwrite-upgrade; user data (tasks, memory, research, README, package, PROGRESS) is preserved; CLAUDE/AGENTS/Harness README merge; same-name user agents/commands/skills (no marker) are never overwritten.
+
 ## Release gate
 
 Iron rule: every update release must keep both update channels live:
@@ -201,7 +229,9 @@ Iron rule: every update release must keep both update channels live:
 - Canonical: npm `create-harness-vibe-coding@latest` and `https://github.com/LiWeny16/create-harness-vibe-coding`
 - Legacy compatibility mirror: `https://github.com/zingspark/create-harness-vibe-coding`
 
-Low-version installs can have updater scripts hardcoded to the legacy mirror. Do not mark a release complete until the legacy mirror exposes the same commit, tag, and generated template manifest as canonical. Generated installs still record the canonical `LiWeny16` source; the `zingspark` repo is kept for backward compatibility.
+Low-version installs can have updater scripts hardcoded to the legacy mirror. Do not mark a release complete until the legacy mirror exposes the same commit on `main`, the version tag, the generated template manifest (`templates/common/.harness-version` AND `templates/common/Harness/ownership.manifest.json`), and the tag's GitHub Release artifact, all matching canonical. Generated installs still record the canonical `LiWeny16` source; the `zingspark` repo is kept for backward compatibility.
+
+"Code ready" is not "users can update". Users on published npm receive the new version only AFTER `npm publish` completes AND the GitHub release/tag is cut AND both mirrors are synced. Do not announce the update as available to existing users until all three are done.
 
 ## Footprint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.13",
+  "version": "0.8.16",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "docs/images/harness-icon.png",
     "docs/images/harness-architecture-light.png",
     "docs/images/harness-architecture.drawio",
+    "CHANGELOG.md",
     "README-CN.md"
   ],
   "scripts": {