@cyning/harness 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-07-26
+
+### Added
+
+- **多帽 invoke 留档硬闸**：task 元信息 `required_invoke_hats` / `invoke_retention_profile`（`default`=`10,30,40` · `minimal`=`30` · `full`=`00,10,20,30,40,CLOSE`）。
+- `task close` 检查 1 按集合覆盖校验；文件名 `30_40` 可同时满足 30 与 40；`--allow-invoke-gap` 豁免留痕。
+- `verify --task` 对 invoke hats 缺口 **WARN**（不挡 30）；`task lint` **W6** 提醒未设字段。
+- `lib/task-meta.js`：`resolveRequiredInvokeHats` · `scanInvokeHats` · `evaluateInvokeHatsRetention` · `extractHatsFromInvokeFilename`。
+
+### Changed
+
+- `lifecycle.yaml` close 守卫登记 `invoke_hats_retention`；`discipline-coverage.yaml` `as_of` → **2.12.0** · gaps `INVOKE-HATS`。
+- TASK_TEMPLATE / TEMPLATE_invoke / 10·20·30 帽文同步字段与纪律。
+
+### Notes
+
+- SPEC：`docs/spec/SPEC-invoke-hats-retention-gate_v1.md`
+- **破坏性（close）**：无字段时按 default 要求 10+30+40；存量仅 30 的 active 须补档、改 `minimal` 或 `--allow-invoke-gap`
+- minor · 建议业务仓 upgrade 后按 RUNBOOK 勾选 invoke 集合
+
+## [2.11.1] - 2026-07-25
+
+### Fixed
+
+- **F1 · `upgrade` 自绊 S5（ops-desk-web dogfood）**：`local.json` 改为 **sync apply 成功后** 写入（compare-before-write）。避免 npx 缓存路径变化时先脏工作区再被 git-clean 中止。
+- **F2 · manifest 静默丢字段**：`write_manifest_upgrade` 重写前对 schema 外字段与 `ide` 裁剪打 **WARN** 清单（知情）；**仍不**合并保留（`additionalProperties: false`）。
+
+### Notes
+
+- 摩擦报告：`Projects/docs/harness/guides/ANALYSIS_upgrade_wizard_friction_20260725_v1_zh.md`
+- patch · 2.3+ manifest 仅五字段：`version` / `preset` / `ide` / `from_version` / `upgraded_at`（`name` / `tech_graph_dir` / `tasks_dir` / `hooks` 等已废弃）
+- **已发布**：`@cyning/harness@2.11.1`（npm `latest` · 2026-07-26）· tag `v2.11.1` 已推送
+
 ## [2.11.0] - 2026-07-25
 
 ### Added
@@ -19,6 +52,7 @@
 - SPEC：`docs/spec/SPEC-lifecycle-guard-expand_v1.md` · `docs/spec/SPEC-discipline-show_v1.md`
 - minor · `lifecycle show` / verify 硬闸语义不变
 - `discipline-coverage.yaml` `as_of_package_version` → **2.11.0**
+- **已发布**：`@cyning/harness@2.11.0`（npm `latest` · 2026-07-25）· tag `v2.11.0` 已推送
 
 ## [2.10.0] - 2026-07-25
 

package/docs/ARCHITECTURE.md

@@ -68,5 +68,5 @@ CLI/Worker 与模板 **同一仓库** 演进，避免多仓割裂。
 Track / Hat / Sync / SDD 公理与扩展规则见 [`methodology/product/DESIGN_ONTOLOGY_v1_zh.md`](./methodology/product/DESIGN_ONTOLOGY_v1_zh.md)（**v1.3**）。  
 **帽链流程（人读）**：[`methodology/product/SDD_HAT_FLOW_v2_zh.md`](./methodology/product/SDD_HAT_FLOW_v2_zh.md)  
 **方法论总指引**：[`methodology/README.md`](./methodology/README.md) · 关系图 [`methodology/DOCUMENT_MAP_v1_zh.md`](./methodology/DOCUMENT_MAP_v1_zh.md)  
-远期 **过程实例图 + 事件历史** 见 [`methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md`](./methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md)（HGM · **v2.0+** 提案 · v1.0 后）。  
+远期 **过程实例图 + 事件历史** 见 [`methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md`](./methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md)（**PIP（过程实例投影）** · **v2.0+** · v1.0 后）。  
 与 **战略本体**（工作区 `docs/harness/guides/STRATEGY_ONTOLOGY_*`）分层：本文件描述 **产品如何实现**，战略文档描述 **对外演进**。

package/docs/ONBOARDING.md

@@ -26,6 +26,10 @@ npx @cyning/harness check    # 仅检查是否有新版本
 写入 `.cyning-harness/manifest.json`（钉版本 · preset · ide）与 `profile.json`。  
 Schema：[`schema/manifest.v1.schema.json`](../schema/manifest.v1.schema.json)
 
+**manifest（2.3+）仅五字段**：`version` / `preset` / `ide` / `from_version` / `upgraded_at`（`additionalProperties: false`）。  
+旧字段 `name` / `harness_version` / `tech_graph_dir` / `tasks_dir` / `hooks` 已废弃且无消费方；`upgrade` 会整体重写并（v2.11.1+）对将被移除的字段打 WARN，**不会**合并保留。  
+`upgrade` 的 `local.json` 簿记在 sync apply **成功之后**写入（v2.11.1+），避免自绊 S5 git-clean。
+
 **维护者 / 离线 · clone 路径：**
 
 ```bash

package/docs/USER_GUIDE_v1.0_zh.md

@@ -185,9 +185,10 @@ Schema：[`schema/verify_result.v1.schema.json`](../schema/verify_result.v1.sche
 | 命令 | 用途 |
 | --- | --- |
 | `npx @cyning/harness init` | 首次安装模板与 manifest（可选 `--with-scripts`） |
-| `npx @cyning/harness upgrade` | 同步产品包更新（可加 `--gate-check` 先 audit） |
+| `npx @cyning/harness upgrade` | 同步产品包更新（可加 `--gate-check`）；v2.11.1+：`local.json` 在 apply 后写入；manifest 重写前 WARN 非标准字段（2.3+ 仅五字段） |
 | `npx @cyning/harness check` | 检查是否有新版本 |
-| `npx @cyning/harness verify` | 全量：双路径 + reviews（v2.9+）；`--task`：30 前聚合；`--spec`：SPEC→00（v2.8+ · 互斥） |
+| `npx @cyning/harness verify` | 全量：双路径 + reviews（v2.9+）；`--task`：30 前聚合 + invoke hats WARN（v2.12+）；`--spec`：SPEC→00（v2.8+ · 互斥） |
+| `npx @cyning/harness task close` | 受闸归档；v2.12+ 按 `required_invoke_hats` / `invoke_retention_profile` 校验多帽 invoke（缺省 `10,30,40`；`--allow-invoke-gap`） |
 | `npx @cyning/harness lifecycle show` | 只读展示 `harness/lifecycle.yaml`（登记 · v2.7+） |
 | `npx @cyning/harness lifecycle dry-run` | 转移资格判定（引擎消费 yaml · v2.10+ · 旁路 · 非 G7） |
 | `npx @cyning/harness discipline show` | 只读展示 `harness/discipline-coverage.yaml`（v2.11+ · 非 audit UI） |
@@ -284,9 +285,9 @@ npm run harness -- check --target /tmp/foo
 | --- | --- | --- | --- |
 | **MD 人类轨** | `docs/_tech_graph/*.md` | 代码审阅、README 引用、Mermaid 渲染 | v1.0+ |
 | **YAML 编辑源** | `docs/_tech_graph/*.graph.yaml` | 结构化编辑、diff、CI 校验 | **v1.1+** |
-| **HGM 过程轨** | `.cyning-harness/events/*.jsonl` | Task / Gate / Review 实例与事件史 | **v2.0+** |
+| **PIP（过程实例投影）过程轨** | `.cyning-harness/events/*.jsonl` | Task / Gate / Review 实例与事件史 | **v2.0+** |
 
-**原则**：YAML 为 Inform 编辑源，HGM 为过程事件图；YAML **不替代** task/review 真值，HGM **不替代** YAML/MD Inform 正文。
+**原则**：YAML 为 Inform 编辑源，PIP（过程实例投影）为过程事件图；YAML **不替代** task/review 真值，PIP（过程实例投影）**不替代** YAML/MD Inform 正文。
 
 ### 10.2 最小工作流
 
@@ -327,9 +328,9 @@ npx @cyning/harness graph yaml check --all --input docs/_tech_graph
 | bench `100` | [SDD-Compliance](../examples/compliance_bench/README.md) 五场景合规率 · 见上文 §6.1 |
 | Extended 帽 | 00/50/链式 PROMPT 不在 Starter 默认包 · 见 [`harness/prompts/README.md`](../harness/prompts/README.md) |
 | Inform-YAML | **v1.1+** · 可选编辑源 · 须 `graph yaml check` 与 `graph.json` 一致 |
-| HGM / 图数据库 | **v2.0+ 已实现** `graph ingest|snapshot|axioms` · 本地 JSONL + snapshot；Neo4j / 远端同步 **仍提案** |
+| PIP（过程实例投影）/ 图数据库 | **v2.0+ 已实现** `graph ingest|snapshot|axioms` · 本地 JSONL + snapshot；Neo4j / 远端同步 **仍提案** |
 | Agent-shell | 研究轨 #9，非 npm 功能 |
-| rejected→draft | **v2.0.1+** bench S5 + HGM axioms 事件流精确匹配 |
+| rejected→draft | **v2.0.1+** bench S5 + PIP（过程实例投影）axioms 事件流精确匹配 |
 
 ---
 
@@ -350,21 +351,21 @@ A：不会（S2 域）。若 prompts 模板有更新，apply 会更新 **模板
 **Q：如何编辑 Inform 架构图？**  
 A：v1.1+ 可选 `docs/_tech_graph/*.graph.yaml` 作为编辑源，运行 `npx @cyning/harness graph yaml compile|check` 生成 MD / 校验 graph.json。
 
-**Q：HGM 与 Inform-YAML 是什么关系？**  
-A：Inform-YAML 是 **架构图谱** 的编辑源；HGM（v2.0+）是 **过程协作** 的事件图。二者并列，HGM 通过 `InformArtifact` 节点引用 Inform 产物，但不覆盖其正文。
+**Q：PIP（过程实例投影）与 Inform-YAML 是什么关系？**  
+A：Inform-YAML 是 **架构图谱** 的编辑源；PIP（过程实例投影，v2.0+）是 **过程协作** 的事件图。二者并列，PIP（过程实例投影）通过 `InformArtifact` 节点引用 Inform 产物，但不覆盖其正文。
 
 **Q：如何贡献或报 issue？**  
 A：GitHub [Cyning12/cyning-harness](https://github.com/Cyning12/cyning-harness) · MIT。
 
 ---
 
-## 13. HGM 过程轨（v2.0+）
+## 13. PIP（过程实例投影）过程轨（v2.0+）
 
-Harness Graph Model（HGM）把 task、gate、review、invoke、sync 等过程实例变成 **append-only 事件流** 与 **可重放图快照**，用于机械检查 SDD 公理。
+PIP（过程实例投影；Process Instance Projection）把 task、gate、review、invoke、sync 等过程实例变成 **append-only 事件流** 与 **可重放图快照**，用于机械检查 SDD 公理。
 
 ### 13.1 事件文件
 
-HGM 事件写入 `.cyning-harness/events/YYYY-MM.jsonl`，修正 = 追加 `CorrectionEvent`，**禁止删改历史**。
+PIP（过程实例投影） 事件写入 `.cyning-harness/events/YYYY-MM.jsonl`，修正 = 追加 `CorrectionEvent`，**禁止删改历史**。
 
 ### 13.2 CLI
 
@@ -397,7 +398,7 @@ chmod +x .git/hooks/pre-commit
 
 - `InformArtifact` 节点 ID：`inform:{repo_rel_path}`
 - Task → InformArtifact 边：`MUST_READ`
-- HGM **不存储** Inform 正文，只存路径指针与 schema 版本
+- PIP（过程实例投影）**不存储** Inform 正文，只存路径指针与 schema 版本
 
 ### 13.5 局限
 
@@ -432,4 +433,4 @@ chmod +x .git/hooks/pre-commit
 | 2026-06-16 | v1.0.1：verify / gate-check / sync index CLI · `--with-scripts` · QUICKREF |
 | 2026-06-17 | v1.1.0：新增 §10 Inform-YAML · `graph yaml compile|check` · 三轨边界说明 |
 | 2026-06-17 | v2.0.1：D4-a axioms · rejected→draft 精确化 · S5 bench · optional pre-commit hook |
-| 2026-06-17 | v2.0.0：新增 §13 HGM 过程轨 · `graph ingest|snapshot|axioms` · InformArtifact 与 MUST_READ 边 |
+| 2026-06-17 | v2.0.0：新增 §13 PIP（过程实例投影）过程轨 · `graph ingest|snapshot|axioms` · InformArtifact 与 MUST_READ 边 |

package/docs/methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md

@@ -1,4 +1,6 @@
-# Harness Graph Model (HGM) · 设计草案 v0
+# PIP（过程实例投影；Process Instance Projection）· 设计草案 v0
+
+> 文件名历史：`HARNESS_GRAPH_MODEL_*`（路径兼容）。
 
 
 | 项        | 内容                                                                                                                               |
@@ -20,7 +22,7 @@
 ### 0.1 一句话
 
 ```text
-Harness Graph Model (HGM)
+PIP（过程实例投影）
   = OOP 的结构化对象（本体 Class 的实例）
   + 显式带类型的边（ObjectProperty · HatRef · 基数）
   + 不可变事件历史（append-only · 可重放投影）

package/docs/methodology/graph/README.md

@@ -1,6 +1,8 @@
-# graph · Harness Graph Model (HGM)
+# graph · PIP（过程实例投影；Process Instance Projection）
 
-> **Track G · G1 / v2.0+**：HGM 为 **v1.0 公理稳定后的可选增强**（proposal · 未实现）· 详见 [`../ROADMAP_v1_zh.md`](../ROADMAP_v1_zh.md) §2.0 · §2.2。
+> **对外名**：PIP（过程实例投影）。对内历史文件名可含 `HGM` / `hgm_*`（路径兼容，正文不用曾称括注）。
+
+> **Track G · G1 / v2.0+**：PIP（过程实例投影）本地 JSONL + `graph ingest|snapshot|axioms` **已实现**；Neo4j / 远端同步仍提案 · 详见 [`../ROADMAP_v1_zh.md`](../ROADMAP_v1_zh.md) §2.0 · §2.2。
 
 | 文档 | 状态 | 说明 |
 | --- | --- | --- |
@@ -10,7 +12,7 @@
 | [`HARNESS_GRAPH_MODEL_dialogue_archive_v1_zh.md`](./HARNESS_GRAPH_MODEL_dialogue_archive_v1_zh.md) | archive | 对话参考 · **非真值** |
 
 ```text
-HGM = 结构化对象 + 显式带类型的边 + 不可变事件历史 + 可推理的公理
+PIP（过程实例投影） = 结构化对象 + 显式带类型的边 + 不可变事件历史 + 可推理的公理
 ```
 
 **勿混淆**：
@@ -19,6 +21,6 @@ HGM = 结构化对象 + 显式带类型的边 + 不可变事件历史 + 可推
 | --- | --- |
 | **GraphTrack** | `docs/_tech_graph/` · Inform 架构地图 |
 | **gate-check --graph** | Inform 模块依赖图（Q3 · v1.0） |
-| **HGM** | Process 实例图 · Task / Gate / Review 时序 |
+| **PIP（过程实例投影）** | Process 实例图 · Task / Gate / Review 时序 |
 
 **依赖**：[`../product/DESIGN_ONTOLOGY_v1_zh.md`](../product/DESIGN_ONTOLOGY_v1_zh.md) v1.2

package/docs/spec/SPEC-invoke-hats-retention-gate_v1.md

@@ -0,0 +1,59 @@
+# SPEC：多帽 invoke 留档硬闸（可配置）（v1）
+
+> **状态**：`signed`  
+> **track**：`feature`  
+> **关联图谱**：无（纯 Harness 工具链）  
+> **下游**：30 实现 → 40 → close  
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `invoke-hats-retention-gate` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | close/lint/verify 集合校验与 profile 展开须可失败测试驱动 |
+| **skip_spec_audit** | `true` |
+
+---
+
+## 1. 背景与目标
+
+close 检查 1 仅要求 `by-task/<slug>/` ≥1 个 `.md`，业务仓理性只交 30。  
+目标：按 task 元信息 `required_invoke_hats` / `invoke_retention_profile` 做**集合覆盖**硬闸；默认 `10,30,40`；40 允许与 30 合并文件名。
+
+## 2. 范围
+
+- `lib/task-meta.js`：profile 预置、解析、文件名 hat 扫描、缺口计算
+- `lib/task-close.js`：检查 1 升级；`--allow-invoke-gap`
+- `lib/task-lint.js`：缺字段 WARN
+- `lib/verify.js`：缺口 WARN（不挡 30）
+- lifecycle / discipline / 模板 / CHANGELOG · **v2.12.0**
+
+## 3. 非范围
+
+- 强制 CLOSE invoke 文件（关账= close 命令）
+- 默认要求 20 invoke（reviews 已硬闸）
+- 同步 Ink 全套 TEMPLATE-*-invoke.md
+- 历史 done invoke 补录
+
+## 4. 验收标准
+
+- [x] 无字段 → 默认要求 `10,30,40`；仅有 30 → CLOSE BLOCKED
+- [x] `invoke_retention_profile: minimal` → 仅需 30
+- [x] `required_invoke_hats` 优先于 profile
+- [x] `invoke_*_30_40_*.md` 同时满足 30 与 40
+- [x] `--allow-invoke-gap` 豁免并留痕
+- [x] verify --task 对缺口 WARN、不挡 may_start_30
+- [x] `npm test` 全绿
+
+> **复检**（2026-07-26 · cyning-harness `task/invoke-hats-retention-gate`）：`npm test` **187/187** 绿；行为与上表一致。非阻塞备注见对话复检报告。
+
+## 5. 预置
+
+| profile | hats |
+|---------|------|
+| default | 10,30,40 |
+| minimal | 30 |
+| full | 00,10,20,30,40,CLOSE |

package/harness/discipline-coverage.yaml

@@ -6,7 +6,7 @@
 # 禁止：把本文件当「每周全量重盘」流程；不做 audit --discipline UI（本波）
 
 version: "1"
-as_of_package_version: "2.11.0"
+as_of_package_version: "2.12.0"
 scope: "Starter · harness/prompts （10/22/30/40 + FRAGMENT）+ TEMPLATE_invoke"
 source_audit: "rethink/2026-07-mechanization-rate · 02 转录 + 03 聚合 · 状态已按 G1–G4/N1–N4 刷新（非第二轮通读盘点）"
 
@@ -61,6 +61,11 @@ gaps:
     status: closed
     closed_in: "2.10.0"
     note: "Epic T2 · 旁路报告"
+  - id: INVOKE-HATS
+    title: 多帽 invoke 留档集合闸
+    status: closed
+    closed_in: "2.12.0"
+    note: "close evaluateInvokeHatsRetention · default 10,30,40"
 
 statements:
   - id: A1
@@ -105,11 +110,11 @@ statements:
     mechanism_quality: null
   - id: A6
     source: 30-execute-code.md
-    summary: invoke 快照落盘 by-task/<slug>/
+    summary: invoke 快照落盘 by-task/<slug>/（按 required_invoke_hats 集合）
     status: mechanical
-    mechanism: "M5 close + M6 lint-done"
+    mechanism: "M5 close evaluateInvokeHatsRetention + M6 lint-done"
     gap: null
-    notes: null
+    notes: "v2.12.0 默认 10,30,40；profile minimal/full；--allow-invoke-gap"
     mechanism_quality: null
   - id: A7
     source: 30-execute-code.md
@@ -265,11 +270,11 @@ statements:
     mechanism_quality: null
   - id: F1
     source: TEMPLATE_invoke.md
-    summary: 落盘路径 by-task/<task_slug>/
+    summary: 落盘路径 by-task/<task_slug>/ 且帽子集合覆盖
     status: mechanical
-    mechanism: "M5/M6"
+    mechanism: "M5 evaluateInvokeHatsRetention / M6"
     gap: null
-    notes: null
+    notes: "v2.12.0 文件名 hat token · 合并 30_40 可双计"
     mechanism_quality: null
   - id: F2
     source: TEMPLATE_invoke.md

package/harness/invokes/TEMPLATE_invoke.md

@@ -9,7 +9,7 @@
 
 | 字段 | 值 |
 |------|-----|
-| hat_id | 10 / 22 / 30 / 40 / 50 / 00 / CLOSE |
+| hat_id | 10 / 22 / 30 / 40 / 50 / 00 / CLOSE（合并可写 `30（含 40）`） |
 | task_slug | `<slug>` |
 | freeze_id | （可选） |
 | task_paths | `docs/tasks/active/task_….md` |
@@ -44,7 +44,8 @@
 | 同帽追问 | **不** 新增 invoke；沿用本节路径 |
 | 打回重开 | 新文件或 `_r2` 后缀 |
 | 与 reviews 分工 | reviews = 结论；invoke = **当时指令** |
-| close 机械闸 | `harness task close` 归档前校验 `by-task/<task_slug>/` 存在且含 ≥1 个 `.md`（v2.2+） |
+| close 机械闸 | `harness task close` 按 task 元信息 `required_invoke_hats` / `invoke_retention_profile` 校验帽集合覆盖（v2.12+；缺省 `10,30,40`；文件名含 `30_40` 可双计；`--allow-invoke-gap` 豁免） |
+| 命名 | `invoke_YYYYMMDD_<hat>_<slug>.md` 或 `invoke_YYYYMMDD_30_40_<slug>.md` |
 | commit | 落盘 + task 回填后再 commit（见 HANDOFF） |
 
 ---

package/harness/lifecycle.yaml

@@ -66,8 +66,14 @@ transitions:
     description: "task close · active→done 归档"
     guards:
       - id: close_invoke
-        command_or_check: "task close 检查1 · invoke 快照存在"
+        command_or_check: "task close 检查1 · invoke hats 集合覆盖（required_invoke_hats / profile · v2.12+）"
         severity: block
+        allow_flag: "--allow-invoke-gap"
+        note: "缺省 default=10,30,40；minimal=30；full 含 CLOSE；40 可与 30 合并文件名"
+      - id: invoke_hats_retention
+        command_or_check: "evaluateInvokeHatsRetention · 同 close_invoke（登记别名）"
+        severity: block
+        allow_flag: "--allow-invoke-gap"
       - id: close_self_check
         command_or_check: "task close 检查2 · 自检结论已回填"
         severity: block

package/harness/prompts/10-task-requirements.md

@@ -15,6 +15,7 @@
 - 补齐 **`failure_paths`**（触发 → 行为 → 可重试 → 用户可见）
 - 写清 **非范围**、**依赖**（相对路径链接）
 - 建议 `test_strategy` + `code_quality_bar`
+- **选定 invoke 留档集合**（v2.12+）：写 `invoke_retention_profile`（`default`=`10,30,40` / `minimal`=`30` / `full`）或显式 `required_invoke_hats`；并落盘本帽 `invoke_*_10_*.md`
 - 承接 **20-task-audit 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task
 
 ## 禁止什么
@@ -48,7 +49,8 @@
 |------|------|
 | 2026-07-24 | V2 拆分收编：自 `10-requirements.md` 改名为 `10-task-requirements.md`（来源：工作区 `10-task-requirements.md` · 2026-06-12 v2） |
 | 2026-07-24 | G4：思考轮摘要节补 v2.6+ `task lint` 条件触发结构检查 |
+| 2026-07-26 | v2.12：起草时选定 `required_invoke_hats` / `invoke_retention_profile` |
 
 ## 给 Cursor
 
-`Harness`、`10-task`、`验收`、`failure_paths`、`test_strategy`、`task lint`、`拒开工`
+`Harness`、`10-task`、`验收`、`failure_paths`、`test_strategy`、`task lint`、`required_invoke_hats`、`拒开工`

package/harness/prompts/20-task-audit.md

@@ -62,7 +62,8 @@
 
 ## 交接物
 
-- 审查 md 路径 + invoke 快照（可选）
+- 审查 md 路径（**必须** · `docs/harness/reviews/`）
+- invoke 快照：仅当 task `required_invoke_hats` / profile **含 20** 时必须落盘；默认 default 集合不含 20（与 reviews 硬闸分工）
 - 按 HANDOFF 分仓 commit
 
 ## 修订记录
@@ -70,6 +71,7 @@
 | 日期 | 摘要 |
 |------|------|
 | 2026-07-24 | V2 拆分收编：自 `22-task-audit.md` 改名为 `20-task-audit.md`（来源：工作区 `20-task-audit.md` · 2026-06-21 v3 + 原包内人工闸联动节保留） |
+| 2026-07-26 | v2.12：澄清 20 invoke 仅在 required 集合含 20 时强制；默认靠 reviews |
 
 ## 给 Cursor
 

package/harness/prompts/30-execute-code.md

@@ -20,8 +20,8 @@
 - 读 task **必读列表** + `AGENTS.md` + `_tech_graph/` + L2（涉码）
 - `test_strategy: required` → **先** 可失败测试再改实现
 - 闸扫描通过后：运行 task **验证命令**；回填 `### 自检结论（执行者）`
-- invoke 快照落盘 `docs/harness/invokes/by-task/<task_slug>/`
-- 归档（active→done）**只能**走 `npx @cyning/harness task close --file <task> --yes`：`CLOSE: PASS` 后方可归档；机械校验 invoke 留档 / 自检结论 / 验收勾选 / slug / 状态，任一不过 **不执行** mv（v2.2+）
+- invoke 快照落盘 `docs/harness/invokes/by-task/<task_slug>/`（须覆盖 task 要求的 hats；40 可与 30 合并为 `invoke_*_30_40_*.md`）
+- 归档（active→done）**只能**走 `npx @cyning/harness task close --file <task> --yes`：`CLOSE: PASS` 后方可归档；机械校验 **invoke hats 集合** / 自检结论 / 验收勾选 / slug / 状态 / R1 review，任一不过 **不执行** mv（v2.2+ · hats 集合 v2.12+）
 
 ## 禁止什么
 

package/harness/templates/TASK_TEMPLATE.md

@@ -19,6 +19,8 @@
 | **chain_prompt** | `docs/harness/prompts/PROMPT_cursor_task_chain_serial_v1.md`（嵌入后路径） |
 | **semi_auto** | **`false`**（禁止作总闸） |
 | **audit_profile** | `full` / `post_close` / `human_only` |
+| **invoke_retention_profile** | `default` / `minimal` / `full`（10 起草时选定） |
+| **required_invoke_hats** | `10,30,40`（显式列表优先于 profile；缺省=default） |
 | **git_branch** | `task/<slug>` |
 | **worktree_root** | （并行时填独立 worktree 目录） |
 | **experience_capture** | `required` / `recommended` / `not_applicable` |

package/lib/cli.js

@@ -404,11 +404,11 @@ async function cmdVerify(args) {
     formatAgentHint,
   } = await import('./verify.js');
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH] [--allow-no-review] [--allow-lint-fail] [--allow-no-spec-review]
+    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH] [--allow-no-review] [--allow-lint-fail] [--allow-no-spec-review] [--allow-invoke-gap]
 
 无 --task/--spec：扫描 docs/tasks/active ∪ docs/harness/tasks/active（同 basename 优先 Starter）；
   闸表 + 全量 reviews 存在性（v2.9+）· 不跑 task lint / D5 · --allow-no-review。
---task：30 前聚合（gate + audit + reviews + lint WARN）· --allow-no-review / --allow-lint-fail。
+--task：30 前聚合（gate + audit + reviews + lint WARN + invoke hats WARN）· --allow-no-review / --allow-lint-fail / --allow-invoke-gap。
 --spec：SPEC→00 前查审查文存在性（v2.8+ · 与 --task 互斥）· --allow-no-spec-review。
   推荐：--spec <产品仓 SPEC> --workspace-root <含 docs/harness/reviews 的工作区根>
 --json / --agent-hint：Agent handoff。
@@ -431,6 +431,7 @@ async function cmdVerify(args) {
   const allowNoReview = rest.includes('--allow-no-review');
   const allowLintFail = rest.includes('--allow-lint-fail');
   const allowNoSpecReview = rest.includes('--allow-no-spec-review');
+  const allowInvokeGap = rest.includes('--allow-invoke-gap');
   rest = rest.filter(
     (a) =>
       a !== '--graph' &&
@@ -438,7 +439,8 @@ async function cmdVerify(args) {
       a !== '--agent-hint' &&
       a !== '--allow-no-review' &&
       a !== '--allow-lint-fail' &&
-      a !== '--allow-no-spec-review',
+      a !== '--allow-no-spec-review' &&
+      a !== '--allow-invoke-gap',
   );
 
   if (rest.length > 0) {
@@ -469,7 +471,13 @@ async function cmdVerify(args) {
     });
     label = path.basename(specFile);
   } else {
-    result = verifyTarget(target, { taskFile, graph, allowNoReview, allowLintFail });
+    result = verifyTarget(target, {
+      taskFile,
+      graph,
+      allowNoReview,
+      allowLintFail,
+      allowInvokeGap,
+    });
     handoff = buildVerifyHandoff(target, {
       taskFile,
       workspaceRoot: ws,
@@ -709,13 +717,16 @@ async function cmdTask(args) {
 
 async function cmdTaskClose(args) {
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness task close --file PATH [--target PATH] [--yes] [--allow-unchecked]
+    console.log(`用法: npx @cyning/harness task close --file PATH [--target PATH] [--yes] [--allow-unchecked] [--allow-no-review] [--allow-invoke-gap]
 
-受闸归档（方案 A · invoke 留档机械闸）：
-  5 项机械校验：invoke 留档 · 自检结论回填 · 验收标准勾选 · task_slug 一致 · 状态 done/completed
+受闸归档（方案 A · invoke 留档机械闸 · v2.12+ 多帽集合）：
+  机械校验：invoke hats 覆盖（required_invoke_hats / profile）· 自检结论 · 验收勾选 · slug · 状态 · R1 review
   默认 dry-run（只检不 mv）；--yes 才执行 mv 到 active/ 同级 done/（basename 保留）
-  --target PATH    显式覆盖归档目标完整路径
-  --allow-unchecked  验收标准未勾选项 warn 放行
+  --target PATH         显式覆盖归档目标完整路径
+  --allow-unchecked     验收标准未勾选项 warn 放行
+  --allow-no-review     缺 R<n> 审查文 warn 放行
+  --allow-invoke-gap    缺 required invoke hats warn 放行（v2.12+）
+  缺省 required hats：10,30,40（可用 invoke_retention_profile=minimal|full 或显式列表覆盖）
 任一校验失败 → exit 2 + CLOSE: BLOCKED · 不执行 mv。末行协议：CLOSE: PASS · <slug>。
 `);
     return;
@@ -724,7 +735,14 @@ async function cmdTaskClose(args) {
   const yes = args.includes('--yes');
   const allowUnchecked = args.includes('--allow-unchecked');
   const allowNoReview = args.includes('--allow-no-review');
-  let rest = args.filter((a) => a !== '--yes' && a !== '--allow-unchecked' && a !== '--allow-no-review');
+  const allowInvokeGap = args.includes('--allow-invoke-gap');
+  let rest = args.filter(
+    (a) =>
+      a !== '--yes' &&
+      a !== '--allow-unchecked' &&
+      a !== '--allow-no-review' &&
+      a !== '--allow-invoke-gap',
+  );
   const { value: fileArg, rest: r1 } = takeOption(rest, '--file');
   rest = r1;
   const { value: targetArg, rest: r2 } = takeOption(rest, '--target');
@@ -746,6 +764,7 @@ async function cmdTaskClose(args) {
     target: targetArg,
     allowUnchecked,
     allowNoReview,
+    allowInvokeGap,
     cwd: process.cwd(),
   });
 

package/lib/task-close.js

@@ -5,6 +5,7 @@ import {
   PLACEHOLDER_RE,
   STATUS_RE,
   UNCHECKED_RE,
+  evaluateInvokeHatsRetention,
   extractSection,
   extractTaskSlug,
   findReview,
@@ -23,6 +24,7 @@ export function closeTaskFile(filePath, options = {}) {
     target: targetArg,
     allowUnchecked = false,
     allowNoReview = false,
+    allowInvokeGap = false,
     cwd = process.cwd(),
   } = options;
 
@@ -60,7 +62,8 @@ export function closeTaskFile(filePath, options = {}) {
   const inActive = path.basename(activeDir) === 'active';
   const repoRoot = findRepoRoot(activeDir);
 
-  // 检查 1 · invoke 留档
+  // 检查 1 · invoke 留档（v2.12+：按 required_invoke_hats / profile 集合覆盖）
+  let invokeHatsEval = null;
   if (!repoRoot) {
     blockers.push(`无法定位 repo root（${activeDir} 无 docs 祖先）`);
   } else if (slug) {
@@ -69,12 +72,29 @@ export function closeTaskFile(filePath, options = {}) {
       'docs/harness/invokes/by-task',
       slug,
     );
-    const hasMd =
-      fs.existsSync(invokeDir) &&
-      fs.readdirSync(invokeDir).some((f) => f.endsWith('.md'));
-    if (!hasMd) {
-      blockers.push(
-        `missing invoke snapshots: ${path.relative(repoRoot, invokeDir)} 不存在或无 .md`,
+    invokeHatsEval = evaluateInvokeHatsRetention(meta, invokeDir);
+    const relDir = path.relative(repoRoot, invokeDir).replace(/\\/g, '/');
+    if (invokeHatsEval.missingDir || invokeHatsEval.files.length === 0) {
+      const msg = `missing invoke snapshots: ${relDir} 不存在或无 .md（要求 hats: ${invokeHatsEval.required.join(',')})`;
+      if (allowInvokeGap) {
+        warnings.push(`warn: ${msg}（--allow-invoke-gap 豁免 · 留痕）`);
+      } else {
+        blockers.push(msg);
+      }
+    } else if (invokeHatsEval.missing.length > 0) {
+      const msg =
+        `missing invoke hats: ${invokeHatsEval.missing.join(',')} ` +
+        `（要求 ${invokeHatsEval.required.join(',')} · 已有 ${invokeHatsEval.covered.join(',') || '∅'} · ` +
+        `source=${invokeHatsEval.resolution.source}` +
+        `${invokeHatsEval.resolution.unknown_profile ? ` · unknown_profile=${invokeHatsEval.resolution.unknown_profile}` : ''}）`;
+      if (allowInvokeGap) {
+        warnings.push(`warn: ${msg}（--allow-invoke-gap 豁免 · 留痕）`);
+      } else {
+        blockers.push(msg);
+      }
+    } else if (invokeHatsEval.resolution.unknown_profile) {
+      warnings.push(
+        `warn: unknown invoke_retention_profile '${invokeHatsEval.resolution.unknown_profile}' · 已回退 default`,
       );
     }
   }
@@ -167,6 +187,14 @@ export function closeTaskFile(filePath, options = {}) {
     dest,
     dryRun: !yes,
     moved,
+    invoke_hats: invokeHatsEval
+      ? {
+          required: invokeHatsEval.required,
+          covered: invokeHatsEval.covered,
+          missing: invokeHatsEval.missing,
+          source: invokeHatsEval.resolution.source,
+        }
+      : null,
   };
 }
 

package/lib/task-lint.js

@@ -193,6 +193,33 @@ export function lintTaskFile(filePath, options = {}) {
     warnings.push(warn('W2', '缺 ### 人工闸 节（轻量 task 可忽略本提醒）'));
   }
 
+  // W6 · invoke 留档集合字段（v2.12+ · 缺则 close 按 default=10,30,40）
+  if (
+    meta.task_slug &&
+    !meta.required_invoke_hats &&
+    !meta.invoke_retention_profile
+  ) {
+    warnings.push(
+      warn(
+        'W6',
+        '未设 required_invoke_hats / invoke_retention_profile · close 将按 default=10,30,40（紧急 fix 可写 minimal）',
+      ),
+    );
+  } else if (
+    meta.invoke_retention_profile &&
+    !['default', 'minimal', 'full'].includes(
+      String(meta.invoke_retention_profile).trim().toLowerCase(),
+    ) &&
+    !meta.required_invoke_hats
+  ) {
+    warnings.push(
+      warn(
+        'W6',
+        `未知 invoke_retention_profile '${meta.invoke_retention_profile}' · 将回退 default`,
+      ),
+    );
+  }
+
   // G4 · 思考轮结构（条件触发）
   lintThinkingRounds(content, lines, errors, warnings);
 

package/lib/task-meta.js

@@ -396,6 +396,158 @@ export function normalizeSlug(slug) {
   return String(slug).replace(/_/g, '-');
 }
 
+/**
+ * invoke 留档 profile → 帽集合（v2.12+）。
+ * default=10,30,40 · minimal=30 · full=00,10,20,30,40,CLOSE
+ */
+export const INVOKE_RETENTION_PROFILES = Object.freeze({
+  default: Object.freeze(['10', '30', '40']),
+  minimal: Object.freeze(['30']),
+  full: Object.freeze(['00', '10', '20', '30', '40', 'CLOSE']),
+});
+
+/** 已知 hat token（文件名扫描白名单） */
+export const KNOWN_INVOKE_HAT_TOKENS = Object.freeze(
+  new Set([
+    '00',
+    '10',
+    '20',
+    '22',
+    '30',
+    '40',
+    '50',
+    'CLOSE',
+    'close',
+  ]),
+);
+
+/**
+ * 解析 required_invoke_hats / invoke_retention_profile。
+ * 显式列表优先；皆无 → default。
+ * @returns {{ hats: string[], profile: string|null, source: 'explicit'|'profile'|'default', unknown_profile?: string }}
+ */
+export function resolveRequiredInvokeHats(meta = {}) {
+  const explicit = meta.required_invoke_hats;
+  if (explicit != null && String(explicit).trim() !== '') {
+    const hats = parseHatList(explicit);
+    return { hats, profile: meta.invoke_retention_profile ?? null, source: 'explicit' };
+  }
+
+  const profileRaw = meta.invoke_retention_profile;
+  if (profileRaw != null && String(profileRaw).trim() !== '') {
+    const key = String(profileRaw).trim().toLowerCase();
+    const preset = INVOKE_RETENTION_PROFILES[key];
+    if (preset) {
+      return { hats: [...preset], profile: key, source: 'profile' };
+    }
+    return {
+      hats: [...INVOKE_RETENTION_PROFILES.default],
+      profile: key,
+      source: 'default',
+      unknown_profile: key,
+    };
+  }
+
+  return {
+    hats: [...INVOKE_RETENTION_PROFILES.default],
+    profile: 'default',
+    source: 'default',
+  };
+}
+
+/**
+ * 从 invoke 文件名提取 hat token 集合。
+ * 兼容：invoke_YYYYMMDD_30_slug.md · invoke_YYYYMMDD_30_40_slug.md · invoke_*_CLOSE_*.md
+ * 亦认 22→20（V2 改名等价，计为 20）。
+ */
+export function extractHatsFromInvokeFilename(fileName) {
+  const base = path.basename(fileName, '.md');
+  const hats = new Set();
+
+  if (/CLOSE/i.test(base)) {
+    hats.add('CLOSE');
+  }
+
+  // 去 invoke_ 前缀与可选日期段
+  let rest = base.replace(/^invoke[_-]?/i, '');
+  rest = rest.replace(/^\d{8}[_-]?/, '');
+  rest = rest.replace(/^\d{4}-\d{2}-\d{2}[_-]?/, '');
+
+  const parts = rest.split(/[_-]+/).filter(Boolean);
+  for (const p of parts) {
+    const upper = p.toUpperCase();
+    if (upper === 'CLOSE') {
+      hats.add('CLOSE');
+      continue;
+    }
+    if (KNOWN_INVOKE_HAT_TOKENS.has(p)) {
+      hats.add(normalizeHatToken(p));
+    }
+  }
+
+  // V2：22 与 20 等价（审 task）
+  if (hats.has('22')) {
+    hats.add('20');
+  }
+
+  return hats;
+}
+
+/**
+ * 扫描 by-task/<slug>/ 目录，聚合已覆盖 hat。
+ * @returns {{ covered: Set<string>, files: string[], missingDir: boolean }}
+ */
+export function scanInvokeHats(invokeDir) {
+  if (!invokeDir || !fs.existsSync(invokeDir)) {
+    return { covered: new Set(), files: [], missingDir: true };
+  }
+  const files = fs
+    .readdirSync(invokeDir)
+    .filter((f) => f.endsWith('.md'));
+  const covered = new Set();
+  for (const f of files) {
+    for (const h of extractHatsFromInvokeFilename(f)) {
+      covered.add(h);
+    }
+  }
+  return { covered, files, missingDir: false };
+}
+
+/**
+ * 计算 required vs covered 缺口。
+ * @returns {{ required: string[], covered: string[], missing: string[], ok: boolean, resolution }}
+ */
+export function evaluateInvokeHatsRetention(meta, invokeDir) {
+  const resolution = resolveRequiredInvokeHats(meta);
+  const { covered, files, missingDir } = scanInvokeHats(invokeDir);
+  const required = resolution.hats.map(normalizeHatToken);
+  const missing = required.filter((h) => !covered.has(h));
+  return {
+    required,
+    covered: [...covered].sort(),
+    missing,
+    ok: missing.length === 0 && !missingDir && files.length > 0,
+    missingDir,
+    files,
+    resolution,
+  };
+}
+
+function parseHatList(raw) {
+  return String(raw)
+    .split(/[,，\s]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(normalizeHatToken);
+}
+
+function normalizeHatToken(token) {
+  const t = String(token).trim();
+  if (/^close$/i.test(t)) return 'CLOSE';
+  if (t === '22') return '22';
+  return t;
+}
+
 function normalizeCell(cell) {
   return cell.replace(/[`\\*]/g, '').trim();
 }

package/lib/verify.js

@@ -5,10 +5,12 @@ import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
 import { auditTarget } from './audit.js';
 import {
   buildTaskHandoff,
+  evaluateInvokeHatsRetention,
   extractSpecSlug,
   findReview,
   findSpecReview,
   listActiveTasks,
+  parseHarnessMeta,
   shouldSkipSpecAudit,
 } from './task-meta.js';
 import { lintTaskFile } from './task-lint.js';
@@ -16,10 +18,17 @@ import { lintTaskFile } from './task-lint.js';
 /**
  * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸
  *（--task 与全量 · N4/v2.9+）+ task lint WARN（仅 --task · v2.7+）
+ * + invoke hats 缺口 WARN（仅 --task · v2.12+ · 不挡 30）
  * + S5 git-clean warn + 可选 --graph
  */
 export function verifyTarget(target, options = {}) {
-  const { taskFile, graph, allowNoReview = false, allowLintFail = false } = options;
+  const {
+    taskFile,
+    graph,
+    allowNoReview = false,
+    allowLintFail = false,
+    allowInvokeGap = false,
+  } = options;
   const harnessRoot = resolveHarnessRootForTarget(target);
 
   // 1. gate-check（含 --graph）
@@ -70,6 +79,35 @@ export function verifyTarget(target, options = {}) {
         gateResult.stdout += `WARN: task lint FAIL · ${rules || 'errors'}（不挡 may_start_30 · 修结构或 --allow-lint-fail）\n`;
       }
     }
+
+    // 3d. invoke hats 缺口（v2.12+）：WARN 不挡 30 · close 才 block
+    const absTask = path.isAbsolute(taskFile)
+      ? taskFile
+      : path.join(target, taskFile);
+    if (fs.existsSync(absTask)) {
+      const content = fs.readFileSync(absTask, 'utf8');
+      const meta = parseHarnessMeta(content);
+      const slug = meta.task_slug;
+      if (slug) {
+        const invokeDir = path.join(
+          target,
+          'docs/harness/invokes/by-task',
+          slug,
+        );
+        const hatsEval = evaluateInvokeHatsRetention(meta, invokeDir);
+        if (hatsEval.missing.length > 0 || hatsEval.missingDir || hatsEval.files.length === 0) {
+          const detail =
+            hatsEval.missingDir || hatsEval.files.length === 0
+              ? `目录缺失/空 · 要求 ${hatsEval.required.join(',')}`
+              : `缺 ${hatsEval.missing.join(',')}（要求 ${hatsEval.required.join(',')} · 已有 ${hatsEval.covered.join(',') || '∅'}）`;
+          if (allowInvokeGap) {
+            gateResult.stdout += `WARN: invoke hats gap suppressed（--allow-invoke-gap · 留痕）· ${detail}\n`;
+          } else {
+            gateResult.stdout += `WARN: invoke hats gap · ${detail}（不挡 may_start_30 · close 前须补齐或 --allow-invoke-gap）\n`;
+          }
+        }
+      }
+    }
   } else {
     // 3c. 全量 reviews 闸（N4 · v2.9+）：不跑 lint / D5
     const taskFiles = listActiveTasks(target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/wizard/lib/common.sh

@@ -198,6 +198,23 @@ profile_ide_cursor_rel() {
   echo "$rel"
 }
 
+# 写入 .cyning-harness/local.json（compare-before-write · 内容不变则跳过）
+# 供 upgrade post-apply 簿记；避免在 sync apply 前改已跟踪文件触发 S5
+write_local_json_if_changed() {
+  local target="$1" root="$2"
+  local dir="$target/.cyning-harness"
+  local path="$dir/local.json"
+  local payload
+  payload="$(printf '%s\n' "{\"cyning_harness_root\":\"$root\"}")"
+  mkdir -p "$dir"
+  if [[ -f "$path" ]] && [[ "$(cat "$path")" == "$payload" ]]; then
+    echo "local.json 未变（跳过写入）→ cyning_harness_root=$root"
+    return 0
+  fi
+  printf '%s\n' "$payload" > "$path"
+  echo "已更新 local.json → cyning_harness_root=$root"
+}
+
 # 从 CLAUDE.md / AGENTS.md 剥离 Harness marker 块；若仅剩空文件则删除
 # S5 · sync/apply 前检测 Git 工作区干净（v0.3+）
 # 非 git 仓跳过；--force 或 HARNESS_SYNC_FORCE=1 跳过

package/wizard/lib/manifest.sh

@@ -77,6 +77,38 @@ EOF
   echo "已写入 manifest: $mf"
 }
 
+# upgrade 重写前：对 schema 外字段 / ide 裁剪打 warning（知情而非静默）
+# 标准五字段：version / preset / ide / from_version / upgraded_at（additionalProperties: false）
+warn_manifest_upgrade_drops() {
+  local mf="$1" new_ide_json="$2"
+  [[ -f "$mf" ]] || return 0
+  if ! command -v node >/dev/null 2>&1; then
+    echo "WARN: 未找到 node，跳过 manifest 字段变更预检" >&2
+    return 0
+  fi
+  node -e '
+const fs = require("fs");
+const mf = process.argv[1];
+const newIde = JSON.parse(process.argv[2]);
+const schema = new Set(["version", "preset", "ide", "from_version", "upgraded_at"]);
+let old;
+try { old = JSON.parse(fs.readFileSync(mf, "utf8")); } catch { process.exit(0); }
+const extra = Object.keys(old).filter((k) => !schema.has(k));
+if (extra.length) {
+  console.log(
+    "WARN: manifest 以下非标准字段将被移除（2.3+ 仅五字段 · 见 ONBOARDING）: " +
+      extra.join(", "),
+  );
+}
+const oldIde = old.ide;
+const oldS = JSON.stringify(oldIde ?? null);
+const newS = JSON.stringify(newIde);
+if (oldS !== newS) {
+  console.log("WARN: manifest.ide 将从 profile 重算: " + oldS + " → " + newS);
+}
+' "$mf" "$new_ide_json"
+}
+
 # upgrade apply 后更新 manifest
 write_manifest_upgrade() {
   local target="$1" version="$2"
@@ -96,6 +128,8 @@ write_manifest_upgrade() {
     preset="$(grep '"preset"' "$mf" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]+)".*/\1/' || echo "$preset")"
   fi
 
+  warn_manifest_upgrade_drops "$mf" "$ide_json"
+
   mkdir -p "$target/.cyning-harness"
   cat > "$mf" <<EOF
 {

package/wizard/upgrade.sh

@@ -101,10 +101,8 @@ echo "preset: $(profile_preset_name "$PROFILE_FILE")"
 echo "当前 IDE: $(profile_ide_summary "$PROFILE_FILE")"
 echo ""
 
-# 始终刷新 local.json，避免路径漂移（如 Desktop → Projects）
-printf '%s\n' "{\"cyning_harness_root\":\"$CYNING_HARNESS\"}" > "$TARGET/.cyning-harness/local.json"
-echo "已更新 local.json → cyning_harness_root=$CYNING_HARNESS"
-echo ""
+# 注意：local.json / manifest 簿记放在 sync apply **成功之后**（F1）。
+# 勿在 apply 前改已跟踪的 .cyning-harness/local.json，否则 S5 git-clean 自绊。
 
 if [[ -z "$IDE_LIST" ]] && [[ "$ASSUME_YES" -eq 0 ]]; then
   if prompt_yes_no "是否更新 IDE 勾选（cursor / claude / agents）？" "n"; then
@@ -140,14 +138,16 @@ if [[ "$DO_APPLY" -eq 1 ]]; then
   SYNC_ARGS=(apply --target "$TARGET")
   [[ "$SYNC_FORCE" -eq 1 ]] && SYNC_ARGS+=(--force)
   "$SCRIPT_DIR/harness-sync.sh" "${SYNC_ARGS[@]}"
+  # post-sync 簿记：apply 失败则不落（set -e 已中止）
+  write_local_json_if_changed "$TARGET" "$CYNING_HARNESS"
   write_manifest_upgrade "$TARGET" "$VERSION"
   cp "$CYNING_HARNESS/harness/templates/QUICKREF_v1_zh.md" "$TARGET/.cyning-harness/QUICKREF.md"
-echo ""
-echo "升级完成。"
-echo "常用命令:"
-echo "  npx @cyning/harness verify --target $TARGET"
-echo "  npx @cyning/harness gate-check --target $TARGET"
-echo "  npx @cyning/harness upgrade --target $TARGET --yes"
+  echo ""
+  echo "升级完成。"
+  echo "常用命令:"
+  echo "  npx @cyning/harness verify --target $TARGET"
+  echo "  npx @cyning/harness gate-check --target $TARGET"
+  echo "  npx @cyning/harness upgrade --target $TARGET --yes"
 else
   echo "已取消 apply（仅预览）。"
   exit 0