@hunter-harness/workflow-harness 0.2.74 → 0.2.76

package/harness/bundles/java/codebuddy/harness-apidoc/SKILL.md

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -17,6 +17,7 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -38,6 +38,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
@@ -125,6 +126,13 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 `execute` 内部运行自动门禁。实际计划最后阶段已终态、边界快照存在且 `status.archivable=true` 时直接执行；未满足时返回阻断且不移动原目录。用户取消后不得重跑。
 
+### 二·A、两个常见阻断的正规出路（不要自己拼 python -c）
+
+| 阻断 | 出路 |
+|------|------|
+| `SENSITIVE_EVIDENCE_UNQUARANTINED` | `python <skills-root>/scripts/harness_runtime.py quarantine-evidence --project . --change-dir ".harness/changes/<cn>" --file "<相对 change-dir 的路径>" --reason "<为什么是敏感证据>" --json`（`--file` 可重复）。私有根默认已与项目同盘、且在项目根之外——**不要**手工指定项目内的路径，归档的密钥扫描会以 `SECRET_SCAN_PRIVATE_PATH_IN_COPY_ROOT` 拒绝 |
+| `DIFF_ZERO_WITH_NONEMPTY_COMMIT`（提交范围非空但 filesChanged=0） | 契约缺 `ownership.productPaths`，全部改动被判为 `foreignPaths`。用 `python <skills-root>/scripts/harness_change.py declare-ownership --change <cn> --product-path "<目录前缀或精确文件>" --json` 按计划的实际改动范围声明（可重复；只收精确路径，不支持通配）。**不要**手改 `change-context.json` |
+
 ### 三、文件移动只用内置工具或 PowerShell
 
 移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
@@ -186,6 +194,27 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 su
 - `.harness/archive/YYYY-MM-DD-<change-name>/events.ndjson` — 结构化事件层（新流程推荐；旧 archive 可缺失）
 - `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` — 最终报告数据源
 - `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
+- `.harness/state/local/archive-packages/<change-name>.remote.json` — 远端上传回执（`archiveId`/`archiveStatus`/`knowledgeStatus`/`uploadStatus`/`fileCount`）
+
+### 结束报告必须回显两条上传结果 ⚠️
+
+归档会做**两次**独立上传，二者成败无关，必须分别如实回显：
+
+| 上传 | 载什么 | 结果在哪 |
+|------|--------|---------|
+| `steps.archive_push` | 归档 ZIP（核心产物） | `archiveId`/`archiveStatus`/`uploadStatus`/`knowledgeStatus`，同时落盘 `state/local/archive-packages/<cn>.remote.json` |
+| `steps.managed_snapshot_push` | **归档交付物（每个变更目录的 `plans/`、`spec/`、`reports/`、`docs/`）、`.harness/codebase` 架构地图、`.harness/rules`、`.harness/project.yaml`、指令入口** | `ok`/`reasonCode`/`exitCode`/`cliCode`/`detail` |
+
+走 `harness-push`（remote-sync，产生分支快照）而非 legacy `push`（proposal 管道）。
+归档目录下的 `runtime/`、`meta/`、`evidence/`、`logs/`、`fixback/`、`.publication-staging/`
+等过程文件不上传；交付物目录里的 `*.log`、`*.tmp`、凭证与 `.env*` 也仍被安全规则拦下。
+
+```
+远端归档：arc_3ff325bb…（archiveStatus=durable，uploadStatus=ready，knowledgeStatus=ready，8 文件）
+受管快照：❌ MANAGED_SNAPSHOT_UPLOAD_FAILED（exitCode=1，detail=…）→ 归档 plan/spec/report 与规则/架构地图未上平台，需 npx hunter-harness harness-push --scope config,rules,architecture,instructions,branch_files --yes --non-interactive 重试
+```
+
+**第二条尤其不能省**：它是 best-effort，失败不阻断归档，于是最容易被淹没成一句警告——而平台上"分支文件里没有 plan/spec"正是它失败的后果。成功时也要写明 `submitted` 数量；`ok=false` 时必须带上 `reasonCode` 与 `detail`，不得省略或写成"已完成"。
 
 ## 渐进披露
 

package/harness/bundles/java/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/java/codebuddy/harness-knowledge-query/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/java/codebuddy/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose
@@ -23,6 +23,7 @@ description: 增量模块打包：拉取最新→编译验证→mvn package→
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -20,6 +20,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -30,6 +30,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-run/SKILL.md

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -40,6 +40,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -29,6 +29,7 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d8613ac610bcccc8; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -31,6 +31,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

package/harness/bundles/java/codebuddy/scripts/harness_archive.py

@@ -8552,8 +8552,17 @@ def cmd_finalize(
     payload["knowledgeMaintenance"] = _knowledge_maintenance_from_archive_push(
         push_result
     )
-    if push_result.get("archiveStatus") == "durable":
-        payload["archiveDurability"] = "ARCHIVED_REMOTE_DURABLE"
+    remote_durability = remote_durable_archive_durability(
+        payload.get("archiveDurability"), push_result
+    )
+    if remote_durability is not None:
+        payload["archiveDurability"] = remote_durability
+        # 报告必须跟着改口：上传发生在 summary 落盘之后，不回写就会出现
+        # "回执 durable / 报告 local-only" 的自相矛盾
+        if not persist_archive_durability(summary_path, remote_durability):
+            warnings.append(
+                "远端归档已持久化，但 summary-data.json 的 archiveDurability 回写失败"
+            )
     if push_result.get("warning"):
         warnings.append(str(push_result["warning"]))
 
@@ -9121,8 +9130,57 @@ def build_archive_package(
     }
 
 
+def remote_durable_archive_durability(
+    current: Any, push_result: Mapping[str, Any]
+) -> dict[str, Any] | None:
+    """远端上传成功后的耐久性投影；未 durable 时返回 None。
+
+    summary-data.json 在归档流程早期就以 ARCHIVED_LOCAL_ONLY 写盘，而 ZIP 上传在
+    那之后才发生。此前上传成功只改内存里的 payload、还把对象覆盖成裸字符串，落盘
+    报告从没跟着改——于是同一次归档，回执说 durable、报告说 local-only，平台和用户
+    读到的是后者。这里保持对象形状并带上回执标识，供调用方同时更新 payload 与文件。
+    """
+    if str(push_result.get("archiveStatus") or "") != "durable":
+        return None
+    projected = dict(current) if isinstance(current, dict) else {}
+    projected.update({
+        "status": "ARCHIVED_REMOTE_DURABLE",
+        # 已远端持久化：不再声称"只存在于本地、可能随工作区丢失"
+        "risk": None,
+        "archiveId": push_result.get("archiveId"),
+        "uploadStatus": push_result.get("uploadStatus"),
+        "knowledgeStatus": push_result.get("knowledgeStatus"),
+    })
+    return projected
+
+
+def persist_archive_durability(summary_path: Path, durability: dict[str, Any]) -> bool:
+    """把耐久性结论回写到已落盘的 summary，其余字段原样保留。
+
+    summary-data.json 本就被排除在归档校验和覆盖之外（它在覆盖快照之后才写），
+    所以这次回写不会破坏 manifest 对账。
+    """
+    try:
+        summary = json.loads(Path(summary_path).read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(summary, dict):
+        return False
+    summary["archiveDurability"] = durability
+    try:
+        write_json(Path(summary_path), summary)
+    except OSError:
+        return False
+    return True
+
+
 def auto_push_managed_snapshot(project_root: Path) -> dict[str, Any]:
-    """Best-effort upload of rules and Codebase Map through the normal push protocol."""
+    """Best-effort upload of rules, Codebase Map and archive deliverables via remote sync.
+
+    走 `harness-push`（remote-sync）而非 legacy `push`（proposal）。后者写的是
+    project_files_current，不产生分支快照，平台的「分支文件」与「项目资料」两个视图
+    都读不到；归档交付物在那条路上还会被 policy-never 全部跳过。
+    """
     project_root = project_root.resolve()
     credentials = _resolve_archive_remote_credentials(project_root, os.environ)
     if not credentials["configured"]:
@@ -9141,11 +9199,16 @@ def auto_push_managed_snapshot(project_root: Path) -> dict[str, Any]:
             "reasonCode": "MANAGED_SNAPSHOT_UPLOAD_DEFERRED",
             "warning": f"项目规则与架构地图上传已延后：{exc}",
         }
+    # 显式列出五个 scope 而非 `all`：含义固定，不随 `all` 的展开定义漂移。
+    # branch_files 覆盖归档交付物（plans/spec/reports/docs），其余四个覆盖配置、
+    # 规则、架构地图与指令入口。
     command = [
         *launcher,
         "--yes",
         "hunter-harness",
-        "push",
+        "harness-push",
+        "--scope",
+        "config,rules,architecture,instructions,branch_files",
         "--yes",
         "--non-interactive",
         "--json",
@@ -9159,6 +9222,10 @@ def auto_push_managed_snapshot(project_root: Path) -> dict[str, Any]:
             command,
             cwd=str(project_root),
             text=True,
+            # 不指定 encoding 时中文 Windows 会按 cp936 解码 UTF-8，静默损坏 CLI
+            # 的中文输出，并可能让下面的 json.loads 失败。
+            encoding="utf-8",
+            errors="replace",
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             timeout=180,
@@ -9176,24 +9243,37 @@ def auto_push_managed_snapshot(project_root: Path) -> dict[str, Any]:
     except (json.JSONDecodeError, TypeError):
         output = None
     if completed.returncode != 0 or not isinstance(output, dict):
-        return {
+        # 失败时丢掉 stdout/stderr 等于把线索一起丢了：plan/spec 与规则、架构地图
+        # 全靠这条推送上平台，用户在平台上只会看到"东西没上去"，却无从查为什么。
+        # 保留有界的诊断片段（push 本身拒绝上传 secret，这里再截断兜底）。
+        detail = (completed.stderr or completed.stdout or "").strip()
+        failure: dict[str, Any] = {
             "ok": False,
             "skipped": False,
             "exitCode": completed.returncode,
             "reasonCode": "MANAGED_SNAPSHOT_UPLOAD_FAILED",
+            "detail": detail[-2_048:],
             "warning": (
-                "项目规则与架构地图未能同步到平台；归档不受影响，"
-                "稍后可运行 npx hunter-harness push --yes --non-interactive 重试。"
+                "项目规则与架构地图未能同步到平台（归档 plan/spec/report 也随这条推送上传）；"
+                "归档不受影响，稍后可运行 npx hunter-harness harness-push "
+                "--scope config,rules,architecture,instructions,branch_files "
+                "--yes --non-interactive 重试。"
             ),
         }
+        cli_code = output.get("code") or output.get("reason_code") if isinstance(output, dict) else None
+        if isinstance(cli_code, str) and cli_code:
+            failure["cliCode"] = cli_code
+        return failure
+    # harness-push 的回执用 summary.applied 计已落盘的操作数（legacy push 用 submitted）。
     summary = output.get("summary")
-    submitted = summary.get("submitted", 0) if isinstance(summary, dict) else 0
+    applied = summary.get("applied", 0) if isinstance(summary, dict) else 0
     return {
         "ok": bool(output.get("ok", True)),
         "skipped": False,
         "projectId": output.get("project_id"),
-        "submitted": submitted if isinstance(submitted, int) else 0,
-        "unchanged": "MANAGED_SNAPSHOT_UNCHANGED" in output.get("warnings", []),
+        "submitted": applied if isinstance(applied, int) else 0,
+        # 无变更时 harness-push 直接短路为 no_changes，不产生快照——即"仅在有更新时推送"。
+        "unchanged": output.get("outcome") == "no_changes",
     }
 
 

package/harness/bundles/java/codebuddy/scripts/harness_change.py

@@ -1081,6 +1081,90 @@ def cmd_resolve(args: argparse.Namespace) -> int:
     )
 
 
+def declare_product_ownership(
+    project_root: Path, change_id: str, *, product_paths: list[str]
+) -> dict[str, Any]:
+    """把 `ownership.productPaths` 写进 change 契约。
+
+    这个字段此前没有任何写入方：plan 的 validate_product_ownership 只校验、缺失时
+    软放行，而归档的 compute_ownership_diff 会把全部改动判成 foreignPaths，
+    filesChanged=0 直接触发 DIFF_ZERO_WITH_NONEMPTY_COMMIT。两端口径不一致，中间
+    没工具能补——只能手改契约。这里给出正规入口。
+
+    规则与 plan 校验一致：只收精确文件或目录前缀，不接受通配。
+    """
+    resolved = resolve_change(project_root, change_id)
+    if not resolved.get("ok"):
+        return resolved
+    change_dir = Path(resolved["changeDir"])
+    normalized = sorted({
+        str(item).strip().replace("\\", "/").removeprefix("./")
+        for item in product_paths
+        if isinstance(item, str) and item.strip()
+    })
+    if not normalized:
+        return {
+            "ok": False,
+            "code": "PLAN_PRODUCT_PATHS_REQUIRED",
+            "message": "至少声明一条 productPaths（精确文件或目录前缀）",
+        }
+    unsupported = sorted(p for p in normalized if any(ch in p for ch in "*?[]"))
+    if unsupported:
+        return {
+            "ok": False,
+            "code": "PLAN_PRODUCT_PATHS_GLOB_UNSUPPORTED",
+            "message": "productPaths 只接受精确文件或目录前缀，不支持通配：" + ", ".join(unsupported),
+            "unsupportedPaths": unsupported,
+        }
+
+    context_path = change_dir / CHANGE_CONTEXT_REL
+    try:
+        context = _read_json(context_path)
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "code": "CHANGE_CONTEXT_INVALID", "message": str(exc)}
+    if not isinstance(context, dict):
+        return {"ok": False, "code": "CHANGE_CONTEXT_INVALID", "message": "change-context.json 不是对象"}
+
+    ownership = context.get("ownership")
+    ownership = dict(ownership) if isinstance(ownership, dict) else {}
+    if ownership.get("productPaths") == normalized:
+        return {
+            "ok": True,
+            "code": "PRODUCT_OWNERSHIP_DECLARED",
+            "idempotent": True,
+            "changeId": change_id,
+            "productPaths": normalized,
+            "path": str(context_path),
+        }
+    ownership["productPaths"] = normalized
+    context["ownership"] = ownership
+    _write_json(context_path, context)
+    return {
+        "ok": True,
+        "code": "PRODUCT_OWNERSHIP_DECLARED",
+        "idempotent": False,
+        "changeId": change_id,
+        "productPaths": normalized,
+        "path": str(context_path),
+    }
+
+
+def cmd_declare_ownership(args: argparse.Namespace) -> int:
+    project = resolve_main_project_root()
+    payload = declare_product_ownership(
+        project, args.change, product_paths=list(args.product_path)
+    )
+    if payload.get("ok"):
+        emit(payload, as_json=bool(args.json))
+        return 0
+    return emit_error(
+        str(payload.get("code", "PRODUCT_OWNERSHIP_FAILED")),
+        str(payload.get("message", "declare ownership failed")),
+        as_json=bool(args.json),
+        extra={k: v for k, v in payload.items() if k not in {"ok", "message"}},
+    )
+
+
 def cmd_migrate(args: argparse.Namespace) -> int:
     project = resolve_main_project_root()
     if not args.change:
@@ -1451,6 +1535,17 @@ def build_parser() -> argparse.ArgumentParser:
     p_migrate.add_argument("--change", required=True)
     p_migrate.set_defaults(func=cmd_migrate)
 
+    p_ownership = sub.add_parser(
+        "declare-ownership", parents=[shared],
+        help="declare ownership.productPaths so archive can project the real diff",
+    )
+    p_ownership.add_argument("--change", required=True)
+    p_ownership.add_argument(
+        "--product-path", required=True, action="append",
+        help="exact file or directory prefix (no globs); repeatable",
+    )
+    p_ownership.set_defaults(func=cmd_declare_ownership)
+
     p_claim = sub.add_parser("claim", parents=[shared])
     p_claim.add_argument("--change", required=True)
     p_claim.add_argument("--phase", required=True)