@cyning/harness 2.11.0 → 2.11.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [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` 等已废弃）
+
 ## [2.11.0] - 2026-07-25
 
 ### Added
@@ -19,6 +31,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,7 +185,7 @@ 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 lifecycle show` | 只读展示 `harness/lifecycle.yaml`（登记 · v2.7+） |
@@ -284,9 +284,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 +327,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 +350,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 +397,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 +432,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（过程实例投影）为 **v1.0 公理稳定后的可选增强**（proposal · 未实现）· 详见 [`../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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.11.0",
+  "version": "2.11.1",
   "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