@hunter-harness/workflow-harness 0.2.82 → 0.2.84

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "611f91f44adcd1d1"
+  "coreHash": "2e7fe0fb0fef6467"
 }

package/harness/bundles/general/claude-code/harness-archive/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -151,6 +151,37 @@ disallowed-tools:
 | `SENSITIVE_EVIDENCE_UNQUARANTINED`（默认只告警，`HUNTER_HARNESS_SENSITIVE_SCAN=block` 时才阻断） | `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` |
 
+### 二·A·1、发布内容预检与服务端 422
+
+`status`（`execute` 的预检）会用**与服务端同源的规则**（`packages/core` 的
+`scanSensitiveFiles`）扫描**真正会进 ZIP 的那批文件**——`reports/final/summary-data.json`、
+`spec/**.md`、`plans/**.md`、`candidates/knowledge.json`、`meta/archive-meta.md`、
+`meta/change-context.json`。`runtime/` 是过程草稿，从不入包，也不进这道扫描。
+
+结果在 `checks.publication_content_scan`：
+
+- `blocked=false` → 上传不会因内容被拒
+- `blocked=true` → **服务端会以 HTTP 422 `archive contains sensitive content` 拒收**。
+  归档不阻断（服务端策略不归本地裁决），但必须在此时处理，别等跑完全流程才发现
+- `reasonCode=PUBLICATION_CONTENT_SCAN_UNAVAILABLE` → CLI 不可用，预检没跑；归档继续，
+  上传仍可能 422
+
+每条 finding 都带 `rule_id / path / line / column / overridable / recovery_action`。
+
+**处置：**
+
+| 命中类型 | 出路 |
+|---|---|
+| `overridable=true`（medium/low，如 `HH_INTERNAL_ADDRESS` 内网地址、`HH_WINDOWS_ABSOLUTE_PATH`） | 若确属设计固有内容，在源文件该行附近加行内标注：`<!-- hunter-harness-ignore: <RULE_ID> reason=<简短理由> -->`，然后 `republish` 重建重传 |
+| `overridable=false`（high，如私钥、真实 token） | **不提供豁免。** 必须真正脱敏后重新打包 |
+
+> ⚠️ 行内标注是**申报**，不是绕过：它把"这是设计决策"写进文档本身，可审计、可追溯。
+> **不要**为了过扫描去删改设计文档的事实内容——那是篡改证据。
+>
+> ⚠️ 已知限制：`hunter-harness-ignore` 在本地扫描器上确认生效；**服务端是否认这条标注尚未验证**
+> （归档上传端点只收裸 ZIP，没有独立的豁免申报通道）。若加了标注仍被 422 拒收，
+> 剩余动作是在平台侧对该规则/内容加白，本地无法自解。
+
 ### 二·B、归档补传（上传失败或历史归档缺条目）
 
 归档上传成功后 ZIP 与回执会被清理，旧版本产生的归档从未入 outbox——所以

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/general/claude-code/harness-plan/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-pull/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-push/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-review/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -92,6 +92,24 @@ disallowed-tools:
 
 **Fixback**：入口只用 `launch-review`，后续问题处理通过 `resolve-issue/close` 驱动，不得把修复说明当成新的普通 Run。只读取返回的受影响问题和文件；验证仅失效与 `changedFiles` 相交的目标，其他 Test/Review 证据继续复用。RED 优先；`manual`、`workflow` 或未选用的建议不进入代码批次，使用中文记录处理结论。
 
+**构建/测试执行入口**：所有构建与测试命令（mvn / gradle / npm test / pytest 等）必须经 `harness_test_runner.py exec` 发起，**禁止**用 `powershell.exe -Command` 直接裸跑：
+
+```text
+python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
+```
+
+该入口持有项目级互斥锁并托管进程树。裸跑构建在宿主工具超时后会被推入后台，多个后台构建同时写同一个 `target/`、`build/` 或 `node_modules/.cache`，表现为编译产物被清空、日志文件被占用、"增量编译抖动"——这些都不是代码缺陷，是并发自相残杀，排查成本极高。`--timeout-seconds` 按最慢的一次全量构建估（默认 300 秒偏短），宁可给足也不要让命令被中途掐断。
+
+返回 `TEST_RUN_ALREADY_ACTIVE`（退出码 3）说明**已有构建在跑**：等它结束或用 `lock-status` 查明持有者，**不得**改用裸跑绕开锁，也不得另起一个并行构建。确认持有进程已消失时才用 `lock-reap` 回收。
+
+**长阶段租约续期**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，只会让最后的 `gate close` 报 `LEASE_ABSENT`。凡预计超过 1 小时的阶段，每完成一个变更簇就用本阶段**原 run-id** 续租一次（同 run-id 重复 claim 即刷新，不会新开 attempt）：
+
+```text
+python <skills-root>/scripts/harness_change.py claim --change <id> --phase run --run-id <本阶段 run-id> --ttl-seconds 3600 --json
+```
+
+已经报了 `LEASE_ABSENT` 也按同一条命令恢复——错误响应的 `resumeRunId` 就是要用的 run-id；**不要**重跑 `gate begin`，那会新开 attempt 并丢失本轮 capsule。
+
 **执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。
 
 **Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
@@ -123,7 +141,9 @@ disallowed-tools:
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；仅 run-owned P0 静态-only 导致 WARN；test-owned 待办正常移交 |
 | **Worktree** | `requested=true` 时代码只写 worktree |
-| **PowerShell** | 所有 git/构建经 `powershell.exe -NoProfile -Command` |
+| **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑 mvn/gradle/npm test；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
+| **租约** | 阶段超 1 小时按变更簇用原 run-id 续租；`LEASE_ABSENT` 用 `harness_change.py claim` 恢复，不重跑 begin |
+| **PowerShell** | 所有 git 经 `powershell.exe -NoProfile -Command` |
 
 ### 陈旧测试安全修复与精确跟踪
 

package/harness/bundles/general/claude-code/harness-run/protocols.md

@@ -79,3 +79,63 @@ REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回
 ```
 
 RED 问题必须在当前 run 中处理或明确记录为未处理风险；YELLOW 问题可交给后续 `/harness-review`。
+
+## fixback 证据契约
+
+> `launch-review` 的返回体里带 `evidenceContract` 字段，内容与本节一致。这里写一份是因为
+> 光靠运行时返回，调用方往往已经动手改代码了才看到。
+
+### 命令链
+
+```text
+run-start（修复前，采 RED）→ 改代码 → run-start（修复后，采 GREEN）
+  → evidence-template ×2 → register-evidence ×2 → resolve-issue
+  → run-start（受影响链）→ evidence-template --kind verification
+  → evidence-template --kind review → close
+```
+
+### 别手写证据 JSON
+
+证据文件的 `provenance` 需要 `sessionId` / `commandHash` / `resultDigest` / `runReceiptPath`
+四个字段，全部能从 `session.json` 直接读出来。用模板生成，不要手抄：
+
+```text
+python <skills-root>/scripts/harness_fixback.py evidence-template \
+  --change-dir <change-dir> --kind red|green|verification|review \
+  --session <sessionId> --out <证据 JSON 路径> --json
+```
+
+输出即可直接喂给 `register-evidence`。撞 `FIXBACK_RUN_PROVENANCE_INVALID` 时，错误体会点名
+**哪个字段、期望什么、实际什么**——按它改，不要去读实现反推。
+
+### `--product-identity`
+
+产品身份指纹，把 RED/GREEN 绑定到同一产品状态。规范取值是**当前 git HEAD**。省略即自动推导，
+`launch-review` 会在返回体的 `resolvedProductIdentity` 里回显；`close --final-product-identity`
+**原样引用那个值**，不要另行推导——推导方式不同就会撞 `FIXBACK_GREEN_IDENTITY_MISMATCH`。
+
+### RED 必须在修复之前
+
+RED 证明问题真实存在，GREEN 证明修复真的生效。先改完再把改动回退来凑 RED，证明的只是回退后的
+状态，不是原始缺陷，中途还会留下脏工作树。
+
+### close 的两张收据与 review-findings.json
+
+`close` 要 `--affected-receipt`（`kind=verification`，受影响链的托管会话）和 `--review-receipt`
+（`kind=review`，指向 `reports/review/review-findings.json`）。
+
+review 收据的放行规则按 **disposition**，不按 severity：
+
+| disposition | 是否阻塞 | 说明 |
+|---|---|---|
+| `OPEN` / 未登记 | ❌ 阻塞 | 还没人处置，必须先给结论 |
+| `FIXED` / `NOT_APPLICABLE` | ✅ 放行 | 已闭环 |
+| `ACCEPTED_RISK` / `DEFERRED` | ✅ 放行 | 记入收据 `residualRisks` 留痕 |
+
+> ⚠️ **不要为了让 close 通过而清空或删改 `review-findings.json`。** 它是发现的真相源，写空等于
+> 抹掉整轮审查的审计轨迹。处置结论属于另一个 sidecar：
+>
+> ```text
+> python <skills-root>/scripts/harness_review.py write-dispositions \
+>   --change-dir <change-dir> --input <dispositions.json>
+> ```

package/harness/bundles/general/claude-code/harness-run/reference.md

@@ -94,7 +94,7 @@ requested=true + path missing
 6. **读取测试场景表**：`.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` → 获取测试真相源
 7. **读取验证账本**：通过 state layout resolver 定位 `evidence/verification-ledger.json`（如存在）→ 复用已有 compile/unitTest 结果
 8. **读取任务状态**：`.harness/changes/<change-name>/evidence/run-task-status.md`（如存在）→ 恢复上次运行状态
-9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并用 `harness_fixback.py` 将相关 RED/YELLOW 条目合并为一个批次；每条问题保留 RED/GREEN 证据，批次关闭后只触发一次 affected verification 与一次 review
+9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并用 `harness_fixback.py` 将相关 RED/YELLOW 条目合并为一个批次；每条问题保留 RED/GREEN 证据，批次关闭后只触发一次 affected verification 与一次 review。证据契约见下方[fixback 证据契约](#fixback-证据契约)——**动手前先读**，它决定了 RED 必须在修复之前采集
 10. 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 11. **执行测试基础设施探测**（见下方"步骤 0.5"）
 12. 确认构建环境正常（构建命令按技术栈，见项目 CLAUDE.md 或 `.harness/config/harness-build-config.md`；如 Java 的 `powershell.exe -Command "mvn compile -pl <module> -o -q"`）

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=611f91f44adcd1d1; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2e7fe0fb0fef6467; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/general/claude-code/scripts/harness_archive.py

@@ -2167,6 +2167,185 @@ def _advisory_sensitive_gate(result: dict[str, Any], policy: str) -> dict[str, A
     }
 
 
+ARCHIVE_EXECUTE_RESULT_REL = Path("meta") / "archive-execute-result.json"
+
+
+def resolve_execute_result_path(change_dir: Path, raw_path: str) -> dict[str, Any]:
+    """校验 `--output`：execute 会移走 change 目录，写进去的结果必然丢失。
+
+    这个错误只能在**动手前**报。等 execute 跑完再发现输出文件不见了，steps 结果
+    已经随目录被移走且无法重建——调用方只剩考古一条路。
+    """
+    change_dir = change_dir.expanduser().resolve()
+    target = Path(raw_path).expanduser()
+    target = target if target.is_absolute() else (Path.cwd() / target)
+    target = target.resolve()
+    try:
+        target.relative_to(change_dir)
+    except ValueError:
+        return {"ok": True, "path": str(target)}
+    suggestion = change_dir.parent / f"{change_dir.name}-archive-result.json"
+    return {
+        "ok": False,
+        "reasonCode": "ARCHIVE_RESULT_PATH_VOLATILE",
+        "path": str(target),
+        "changeDir": str(change_dir),
+        "recoveryAction": (
+            f"归档会把 {change_dir} 整个移进 .harness/archive/，写在它内部的输出文件"
+            f"会随之消失。把 --output 指到目录之外，例如 {suggestion}；"
+            "归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。"
+        ),
+    }
+
+
+def persist_execute_result(archive_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
+    """把 execute 的完整结果写进归档目录——移动之后的位置，不会再被搬走。
+
+    调用方此前只能靠 shell 重定向抓 stdout，而唯一"顺手"的落点（change 目录）正是
+    要被移走的那个。结果落盘在归档里，并把路径回显进 payload，重定向就不再必要。
+    """
+    archive_dir = archive_dir.expanduser().resolve()
+    path = archive_dir / ARCHIVE_EXECUTE_RESULT_REL
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, default=str) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+    except (OSError, TypeError, ValueError) as exc:
+        return {"ok": False, "reasonCode": "ARCHIVE_RESULT_WRITE_FAILED", "error": str(exc)}
+    payload["resultPath"] = str(path)
+    return {"ok": True, "path": str(path)}
+
+
+def publication_member_paths(source_dir: Path) -> list[str]:
+    """归档包会包含哪些文件——由 `_archive_core_file_specs` 单一定义，不另起一套。
+
+    包成员在 execute 之前就已确定：`reports/final/summary-data.json`、`spec/**.md`、
+    `plans/**.md`、`candidates/knowledge.json`、`meta/archive-meta.md`、
+    `meta/change-context.json`。其中 summary-data.json / archive-meta.md 由 execute
+    生成，预检时尚不存在，会被自动跳过——它们是机器产物，承载不了人写的敏感串。
+    """
+    project_root = find_project_root(source_dir)
+    try:
+        _, _, specs = _archive_core_file_specs(project_root, source_dir)
+    except (OSError, ValueError):
+        return []
+    return sorted(package_path for _, package_path, _, _ in specs)
+
+
+def precheck_publication_content(
+    source_dir: Path,
+    *,
+    timeout_seconds: int = 60,
+) -> dict[str, Any]:
+    """用**发布同款规则**扫描**会被发布的那批文件**，在归档开始时就给出结论。
+
+    此前这两件事都不成立：本地跑的是 harness_runtime 自建的赋值式正则，扫的是整棵
+    change 树（含从不入包的 runtime/）；服务端跑的是 packages/core 的
+    `scanSensitiveFiles`，扫的是 ZIP 里那几个文件。范围与规则双双错位，于是本地在
+    草稿上误报阻塞，真正会被拒的设计文档一个字没查——直到 upload 收到 422。
+
+    这里改为调用 CLI 的 `scan-sensitive`（直接复用 core 的导出），保证与服务端同源。
+    CLI 不可用时降级为警告：预检本身不该变成新的卡点。
+    """
+    members = publication_member_paths(source_dir)
+    if not members:
+        return {
+            "ok": True,
+            "reasonCode": "PUBLICATION_CONTENT_SCAN_EMPTY",
+            "blocked": False,
+            "findings": [],
+            "members": [],
+        }
+    project_root = find_project_root(source_dir)
+    try:
+        prefix = resolve_hunter_cli_command(project_root)
+    except (FileNotFoundError, OSError) as exc:
+        return _publication_scan_unavailable(members, str(exc))
+    command = [*prefix, "scan-sensitive", "--root", str(source_dir), "--json"]
+    for member in members:
+        command.extend(["--file", member])
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return _publication_scan_unavailable(members, str(exc))
+    try:
+        report = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        return _publication_scan_unavailable(
+            members, f"scan-sensitive output was not JSON: {exc}"
+        )
+    if not isinstance(report, dict) or "findings" not in report:
+        return _publication_scan_unavailable(
+            members, "scan-sensitive output missing findings"
+        )
+    findings = [item for item in report.get("findings") or [] if isinstance(item, dict)]
+    blocked = [item for item in findings if item.get("disposition") == "blocked"]
+    hard = [item for item in blocked if item.get("overridable") is False]
+    return {
+        "ok": True,
+        "reasonCode": (
+            "PUBLICATION_CONTENT_SCAN_FLAGGED" if blocked
+            else "PUBLICATION_CONTENT_SCAN_CLEAN"
+        ),
+        "scannerVersion": report.get("scanner_version"),
+        "members": members,
+        "blocked": bool(blocked),
+        "hardBlocked": bool(hard),
+        "findings": findings,
+        "nextAction": _publication_scan_next_action(blocked, hard),
+    }
+
+
+def _publication_scan_unavailable(members: list[str], error: str) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "reasonCode": "PUBLICATION_CONTENT_SCAN_UNAVAILABLE",
+        "blocked": False,
+        "findings": [],
+        "members": members,
+        "error": error,
+        "message": (
+            "无法运行发布内容预检（hunter-harness CLI 不可用）。归档继续，但上传时"
+            "仍可能被服务端以 422 拒收；装好 CLI 后可用 "
+            "`hunter-harness scan-sensitive` 单独复查。"
+        ),
+    }
+
+
+def _publication_scan_next_action(
+    blocked: list[dict[str, Any]], hard: list[dict[str, Any]]
+) -> str:
+    if not blocked:
+        return "发布内容预检通过。"
+    if hard:
+        names = ", ".join(
+            f"{item.get('path')}:{item.get('line')} {item.get('rule_id')}"
+            for item in hard
+        )
+        return (
+            f"以下命中不可豁免（high）：{names}。必须真正脱敏后重新打包，"
+            "不要用行内标注绕过。"
+        )
+    lines = "; ".join(
+        str(item.get("recovery_action") or "") for item in blocked
+    )
+    return (
+        "服务端会以同款规则拒收这些内容（HTTP 422）。若确属设计固有内容，"
+        f"按下列写法加行内标注后重新打包：{lines}"
+    )
+
+
 def validate_sensitive_evidence_publication_gate(
     change_dir: Path,
     *,
@@ -2194,7 +2373,11 @@ def validate_sensitive_evidence_publication_gate(
             "receiptPath": str(receipt_path),
             "unresolvedFailures": [],
         }
-    candidates = hruntime.sensitive_evidence_candidates(change_dir)
+    # 只扫会被发布出去的字节。runtime/ 是各阶段草稿（review 的 diff、临时校验脚本、
+    # 命令输出），从不进归档包——拿它挡发布，挡的是永远不会离开本机的内容。
+    candidates = hruntime.sensitive_evidence_candidates(
+        change_dir, exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS
+    )
     if candidates:
         return _advisory_sensitive_gate(
             {
@@ -2265,8 +2448,17 @@ def validate_sensitive_evidence_publication_gate(
         issues.append({"code": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED", "count": len(unresolved)})
     elif unresolved not in (None, []):
         issues.append({"code": "SECRET_SCAN_UNRESOLVED_INVALID"})
+    # 用收据自己声明的排除项复算，两侧口径才一致；写死一套常量会让旧收据
+    # 在升级后集体报 digest 漂移。
+    receipt_excluded = receipt.get("publicationExcludedDirs")
+    if not isinstance(receipt_excluded, list) or any(
+        not isinstance(item, str) for item in receipt_excluded
+    ):
+        receipt_excluded = []
     try:
-        actual_digest = hruntime.publishable_tree_digest(change_dir)
+        actual_digest = hruntime.publishable_tree_digest(
+            change_dir, exclude_dirs=tuple(receipt_excluded)
+        )
     except OSError as exc:
         actual_digest = None
         issues.append({"code": "SECRET_SCAN_TREE_UNREADABLE", "error": str(exc)})
@@ -2407,6 +2599,24 @@ def check_status(
             }
         )
 
+    # 发布内容预检：与服务端同源的规则，扫的是真正会进 ZIP 的那批文件。
+    # 服务端策略不归本地裁决，所以只预警不阻断——但必须在归档开始时就说出来，
+    # 而不是等跑完全流程由 upload 返回 422。
+    content_scan = precheck_publication_content(change_dir)
+    checks["publication_content_scan"] = content_scan
+    if content_scan.get("blocked"):
+        warnings.append({
+            "code": "PUBLICATION_CONTENT_SCAN_FLAGGED",
+            "message": str(content_scan.get("nextAction") or ""),
+        })
+    elif not content_scan.get("ok"):
+        warnings.append({
+            "code": str(
+                content_scan.get("reasonCode") or "PUBLICATION_CONTENT_SCAN_UNAVAILABLE"
+            ),
+            "message": str(content_scan.get("message") or ""),
+        })
+
     sensitive_gate = validate_sensitive_evidence_publication_gate(
         change_dir,
         copy_root=change_dir,
@@ -7842,6 +8052,7 @@ def cmd_finalize(
     source_sensitive_refresh = hruntime.refresh_sensitive_evidence_scan_receipt(
         original_change_dir,
         persist=False,
+        exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS,
     )
     payload["steps"]["sensitive_evidence_source_refresh"] = source_sensitive_refresh
     if not source_sensitive_refresh.get("ok"):
@@ -7981,7 +8192,8 @@ def cmd_finalize(
                 "stateDir": str(split_state_dir),
             }
         staged_sensitive_refresh = hruntime.refresh_sensitive_evidence_scan_receipt(
-            work_dir
+            work_dir,
+            exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS,
         )
         payload["steps"][
             "sensitive_evidence_staging_refresh"
@@ -8742,6 +8954,12 @@ def cmd_finalize(
     payload["finalStatus"] = "OK"
     payload["warnings"] = warnings
     payload["summary_data"] = str(summary_path)
+    # 结果落在归档里（移动之后的位置），调用方不必再靠 shell 重定向去接 stdout。
+    persisted = persist_execute_result(archive_dir, payload)
+    if not persisted.get("ok"):
+        warnings.append(
+            f"could not persist archive execute result: {persisted.get('error')}"
+        )
     return 0, payload
 
 
@@ -10120,9 +10338,45 @@ def cmd_certify_local_cli(args: argparse.Namespace) -> int:
     return 0
 
 
+def _emit_with_optional_output(args: argparse.Namespace, payload: dict[str, Any]) -> int | None:
+    """Write the result to --output, refusing a path the archive will delete."""
+    raw = getattr(args, "output", None)
+    if not raw:
+        return None
+    resolved = resolve_execute_result_path(resolve_path(args.change_dir), str(raw))
+    if not resolved.get("ok"):
+        emit_json(resolved)
+        return 2
+    try:
+        target = Path(resolved["path"])
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, default=str) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+    except (OSError, TypeError, ValueError) as exc:
+        emit_json({
+            "ok": False,
+            "reasonCode": "ARCHIVE_RESULT_WRITE_FAILED",
+            "path": resolved["path"],
+            "error": str(exc),
+        })
+        return 2
+    payload["resultPath"] = resolved["path"]
+    return None
+
+
 def cmd_finalize_cli(args: argparse.Namespace) -> int:
     change_dir = resolve_path(args.change_dir)
     archive_root = resolve_path(args.archive_root)
+    # 先验路径再干活：跑完才发现输出落点会被移走，结果已经无法重建。
+    raw_output = getattr(args, "output", None)
+    if raw_output:
+        resolved = resolve_execute_result_path(change_dir, str(raw_output))
+        if not resolved.get("ok"):
+            emit_json(resolved)
+            return 2
     durable_root = (
         resolve_path(args.durable_root)
         if getattr(args, "durable_root", None)
@@ -10141,6 +10395,9 @@ def cmd_finalize_cli(args: argparse.Namespace) -> int:
         closure_disposition=str(getattr(args, "closure", "completed")),
         closure_reason=str(getattr(args, "closure_reason", "")),
     )
+    failure = _emit_with_optional_output(args, payload)
+    if failure is not None:
+        return failure
     emit_json(payload)
     return code
 
@@ -10151,6 +10408,14 @@ def cmd_execute_cli(args: argparse.Namespace) -> int:
         if getattr(args, "durable_root", None)
         else None
     )
+    raw_output = getattr(args, "output", None)
+    if raw_output:
+        resolved = resolve_execute_result_path(
+            resolve_path(args.change_dir), str(raw_output)
+        )
+        if not resolved.get("ok"):
+            emit_json(resolved)
+            return 2
     code, payload = execute_archive(
         resolve_path(args.change_dir),
         resolve_path(args.archive_root),
@@ -10164,6 +10429,9 @@ def cmd_execute_cli(args: argparse.Namespace) -> int:
         closure_disposition=str(getattr(args, "closure", "completed")),
         closure_reason=str(getattr(args, "closure_reason", "")),
     )
+    failure = _emit_with_optional_output(args, payload)
+    if failure is not None:
+        return failure
     emit_json(payload)
     return code
 
@@ -10771,6 +11039,7 @@ def build_parser() -> argparse.ArgumentParser:
         default="release-candidate",
         help="release-candidate enforces candidate evidence; record-only archives facts without release eligibility",
     )
+    p_fin.add_argument("--output", default=None, help="把完整结果另存到该路径。**不得**指向 --change-dir 内部：归档会把该目录整个移走，写在里面的文件必然丢失。归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。")
     p_fin.add_argument("--json", action="store_true", default=True)
     p_fin.set_defaults(func=cmd_finalize_cli)
 
@@ -10795,6 +11064,7 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("release-candidate", "record-only"),
         default="release-candidate",
     )
+    p_execute.add_argument("--output", default=None, help="把完整结果另存到该路径。**不得**指向 --change-dir 内部：归档会把该目录整个移走，写在里面的文件必然丢失。归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。")
     p_execute.add_argument("--json", action="store_true", default=True)
     p_execute.set_defaults(func=cmd_execute_cli)