@hunter-harness/workflow-harness 0.2.73 → 0.2.75

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "d79ae315e929446c"
+  "coreHash": "24b43afeb4dc4c52"
 }

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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -56,6 +56,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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`，不失败
@@ -143,6 +144,13 @@ disallowed-tools:
 
 `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**。移动失败时不删除原目录，报错退出让用户手动处理。
@@ -204,6 +212,23 @@ 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` | **plan/spec 文档、`.harness/codebase` 架构地图、`.harness/rules`**（push 会 walk 每个归档目录的 `spec/` 与 `plans/`） | `ok`/`reasonCode`/`exitCode`/`cliCode`/`detail` |
+
+```
+远端归档：arc_3ff325bb…（archiveStatus=durable，uploadStatus=ready，knowledgeStatus=ready，8 文件）
+受管快照：❌ MANAGED_SNAPSHOT_UPLOAD_FAILED（exitCode=1，detail=…）→ plan/spec 与规则/架构地图未上平台，需 npx hunter-harness push --yes --non-interactive 重试
+```
+
+**第二条尤其不能省**：它是 best-effort，失败不阻断归档，于是最容易被淹没成一句警告——而平台上"分支文件里没有 plan/spec"正是它失败的后果。成功时也要写明 `submitted` 数量；`ok=false` 时必须带上 `reasonCode` 与 `detail`，不得省略或写成"已完成"。
 
 ## 渐进披露
 

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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -38,6 +38,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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/general/claude-code/harness-pull/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -48,6 +48,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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/general/claude-code/harness-run/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -59,6 +59,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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`，不失败
@@ -81,7 +82,7 @@ disallowed-tools:
 0. 加载上下文：普通 Run 先 `harness_context.py prepare --project . --change <id> --phase run --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 **`harness_context.py begin --project . --change <id> --phase run --executor <tool> --json`** 校验交接，最后运行 **`harness_gate.py begin --phase run --change <id>`**。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → run` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。`harness_gate.py` 会从当前已安装适配器自动识别 skills root；只有执行复制到别处的脚本时才显式传 `--skills-root`。`--fixback` 不得拼装这些底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`：该命令会先筛选结构化评审项，再原子选择 Fixback 分支、确认上下文、取得 Run 门禁并创建已填充批次。返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告“本轮评审没有需要执行的代码修复”并停止；返回阻塞码时按 `recoveryAction` 停止，不搜索实现、不试探其他参数、不创建空批次。禁止手写 `events.ndjson` / `phase.end`。已连接平台时 begin 会 best-effort 补传事件，失败只告警。
 0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；测试基线已由上一步 gate begin 内部建立，不得再次执行 guard begin
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
+2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。detect 在嵌套/多组件仓库返回 `DETECTION_AMBIGUOUS` 时，响应里的 `profileTemplate` 就是可填骨架（已含 defaultsFingerprint、excludedRoots 默认集与 commands 条目形状），按 `hint` 填好写入 `.harness/config/build-profile.json` 即可，**不要去反读 `harness_profile.py` 源码凑结构**。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
 4. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 必须取返回的 `nextPhases` 或 `plannedPhases` 中 run 的真实后继，禁止写死 test。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
 

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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -47,6 +47,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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`，不失败
@@ -72,10 +73,11 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 
 ### 提交流程（步骤 0–7）
 
-0. **启动准备** — `harness_context.py prepare --phase submit --executor <tool> [--change <id>] --json` 确定唯一变更与 executionRoot；`harness_context.py begin --phase submit --change <id> --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
+0. **启动准备** — `harness_context.py prepare --project . --change <id> --phase submit --executor <tool> --json`（`--project` 必填）确定唯一变更与 executionRoot；`harness_context.py begin --project . --change <id> --phase submit --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
 1. **合并最新代码** — 主目录与 worktree 均**不在业务工作区 stash/pull**；远端同步由合并段 integration transaction 在隔离 integration worktree 内完成（见「worktree 合并流程」）；**正常路径禁止 `git stash` / `stash pop`**
 2. **最终验证** — ledger 复用优先；提交前只调用 `can-reuse --project . --profile-input unitTestFull --command <profile 规范命令>`。不得传入另一套 `--files`，不得把 runner 包装说明写进 `command`。`reuse=true` 时禁止重跑；只有真实输入、依赖、工具链或环境身份变化时才执行一次同一 profile 验证，并只登记一条结果。不要读取 ledger/archive 实现源码或临时编写散列脚本排查参数。
    - 无远端 CI 且 gate-policy 未强制 remote provider 时，验证通过/复用后运行 `harness_archive.py certify-local --change-dir ... --project . --json`，从同一 ledger 生成 `local-reproducible` 产品候选收据；该命令不执行测试。
+   - **被与本变更无关的预存失败卡住时的正规出路**：用 `harness_preflight.py record-quirk --project . --action skip-not-block --pattern "<具体错误签名，≥8 字符>" --reason "<为什么与本变更无关>"` 把它声明进 build-profile 的 `knownPreexistingErrors`，certify-local 会在**该失败的 ledger 证据里确实出现该签名**时放行，并把 `{validation, pattern, reason}` 写进收据的 `verification.preexistingExemptions` 留痕。**不得**改 gate-policy 的 `candidateVerification.requiredValidations` 来绕过——那是把门禁本身拆掉。声明了但证据对不上、或签名短到能匹配一切，仍然阻断。
    - gate-policy 要求 `remote-attested` 时不得降级成本地收据，等待远端 attestation。
 3. **.gitignore + 精确暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**。若存在 `evidence/test-tracking.json`，先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；失败即硬停止。无 manifest 时不使用 `-f`。manifest 之外的文件按精确业务路径正常暂存，**禁止全局 force-add**。
 4. **提交方式** — 主目录：blocking user confirmation 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**

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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; 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=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -51,6 +51,7 @@ disallowed-tools:
 
 ## 统一读取协议
 
+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`，不失败
@@ -105,7 +106,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+先 `harness_context.py prepare --project . --change <id> --phase test --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 `harness_context.py begin --project . --change <id> --phase test --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
 
 验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close`。`--to-phase` 取实际阶段计划的后继；Fixback 返回 run，普通流程可直接进入 Review、Submit 或 Archive。Fixback 只失效与改动文件相交的验证目标。
 

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

@@ -273,6 +273,8 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-run 单元测试结果"
 - [ ] 不复用 → 按 profile key resolve 重跑测试命令（`harness_profile.py resolve --key unitTest`，不复制示例 `-pl` 命令），结果写回 ledger 的 `unitTest` 项
 - [ ] HTTP/API 契约结果写入 `apiTest`；真实浏览器/真实栈 Playwright 结果写入 `browserTest`，两者不得互相覆盖
+- [ ] **本变更没有该维度场景时**（如全部为单元场景 → 无 API 场景）：用 `harness_ledger.py record --verification apiTest --status NOT_RUN --applicability NOT_APPLICABLE --applicability-reason "<为什么不适用>"` 登记，**不传 `--files`**。门禁 close 要求 requiredValidations 每项都有 entry，但**绝不能拿无关文件（比如单元测试文件）凑 `--files`**——那会让 ledger 声称该维度的输入是那些文件，是假证据
+- [ ] `can-reuse` 返回 `reuse:false` 时直接读默认输出里的 `reason`/`executionNeed`/`detail` 定位原因，不必再补跑 `--verbose`
 - [ ] 复用判断前以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 重算指纹；test-tracking manifest 无效或 hash 漂移即停止
 - [ ] 测试失败若明确为陈旧测试，仅在当前代码/批准计划/可验证历史唯一确定新契约且只改测试时自动修复；否则记录 `BLOCKED_PREEXISTING`
 - [ ] 自动修复后立即重跑该测试与目标测试，并以 `harness_test_guard.py record ... --reason stale-test-repair` 记录精确路径

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

@@ -991,6 +991,62 @@ def migrate_legacy_candidate_evidence(
     return receipt
 
 
+# 声明必须是具体的错误签名，不能是能匹配一切的短串。这个下限不是"安全边界"
+# ——审计线索才是——但它挡住最省事的滥用写法。
+_PREEXISTING_MIN_PATTERN = 8
+
+
+def _known_preexisting_patterns(
+    project_root: Path,
+) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    """build-profile 里声明的预存失败签名，按"是否足够具体"分成两组。
+
+    `knownPreexistingErrors` 由 `harness_preflight.py record-quirk --action
+    skip-not-block` 写入，此前没有任何消费方——于是预存失败在 certify-local 处
+    成为死结：要么去 gate-policy 降门禁，要么顺手改范围外的产品 bug。
+    """
+    path = project_root / ".harness" / "config" / "build-profile.json"
+    if not path.is_file():
+        return [], []
+    try:
+        profile = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, ValueError):
+        return [], []
+    declared = profile.get("knownPreexistingErrors") if isinstance(profile, dict) else None
+    if not isinstance(declared, list):
+        return [], []
+    usable: list[dict[str, str]] = []
+    vague: list[dict[str, str]] = []
+    for item in declared:
+        if not isinstance(item, dict) or item.get("action") != "skip-not-block":
+            continue
+        pattern = str(item.get("pattern") or "").strip()
+        reason = str(item.get("reason") or "").strip()
+        if not pattern or not reason:
+            continue
+        record = {"pattern": pattern, "reason": reason}
+        (usable if len(pattern) >= _PREEXISTING_MIN_PATTERN else vague).append(record)
+    return usable, vague
+
+
+def _match_preexisting(
+    entry: dict[str, Any], patterns: list[dict[str, str]]
+) -> dict[str, str] | None:
+    """失败证据里是否确实出现了某个已声明签名。
+
+    只看"声明过"是不够的——那等于声明一次豁免一切。必须是这一条失败的证据里
+    真的带着该签名，声明与现场才对得上。
+    """
+    evidence = entry.get("evidence")
+    haystack = evidence if isinstance(evidence, str) else json.dumps(
+        evidence, ensure_ascii=False, sort_keys=True
+    )
+    for record in patterns:
+        if record["pattern"] in haystack:
+            return record
+    return None
+
+
 def certify_local_candidate(
     change_dir: Path,
     *,
@@ -1029,14 +1085,28 @@ def certify_local_candidate(
         required = ["unitTestFull"]
     required = [str(item).strip() for item in required if str(item).strip()]
 
+    usable_patterns, vague_patterns = _known_preexisting_patterns(project_root)
+
     selected: list[dict[str, Any]] = []
+    exemptions: list[dict[str, Any]] = []
     for name in required:
         entry = validations.get(name)
         if not isinstance(entry, dict):
             raise ValueError(f"required validation missing: {name}")
         missing: list[str] = []
+        exempted = None
         if str(entry.get("status") or "").upper() != "OK":
-            missing.append("status=OK")
+            exempted = _match_preexisting(entry, usable_patterns)
+            if exempted is None:
+                vague = _match_preexisting(entry, vague_patterns)
+                if vague is not None:
+                    raise ValueError(
+                        f"required validation {name} failed and the declared "
+                        f"knownPreexistingErrors pattern {vague['pattern']!r} is too "
+                        "generic to identify it; declare the specific error signature "
+                        f"(at least {_PREEXISTING_MIN_PATTERN} characters)"
+                    )
+                missing.append("status=OK")
         for field in (
             "command",
             "evidence",
@@ -1048,6 +1118,15 @@ def certify_local_candidate(
             raise ValueError(
                 f"required validation {name} is incomplete: {', '.join(missing)}"
             )
+        if exempted is not None:
+            exemptions.append(
+                {
+                    "validation": name,
+                    "status": str(entry.get("status") or "").upper(),
+                    "pattern": exempted["pattern"],
+                    "reason": exempted["reason"],
+                }
+            )
         selected.append(
             {
                 "name": name,
@@ -1160,6 +1239,8 @@ def certify_local_candidate(
                 {str(item["inputsHash"]) for item in selected}
             ),
             "logHashes": sorted({str(item["logHash"]) for item in selected}),
+            # 豁免必须随收据一起留痕，否则事后无法把它与干净通过区分开
+            "preexistingExemptions": exemptions,
         },
     }
     if rebound_from_commit is not None:
@@ -8471,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"]))
 
@@ -9040,6 +9130,50 @@ 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."""
     project_root = project_root.resolve()
@@ -9095,16 +9229,25 @@ 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 也随这条推送上传）；"
+                "归档不受影响，稍后可运行 npx hunter-harness push --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
     summary = output.get("summary")
     submitted = summary.get("submitted", 0) if isinstance(summary, dict) else 0
     return {

package/harness/bundles/general/claude-code/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)

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

@@ -304,12 +304,23 @@ def _compact_record_payload(payload: dict[str, Any]) -> dict[str, Any]:
 
 
 def _compact_can_reuse_payload(payload: dict[str, Any]) -> dict[str, Any]:
-    """C5: can-reuse compact — ok/reuse/code only."""
-    return {
+    """C5: can-reuse compact — ok/reuse/code；拒绝复用时附带可执行的原因。
+
+    只回 ok/reuse/code 时，调用方拿到裸 `{"reuse": false}` 无从判断该怎么办，
+    只能再跑一次 `--verbose`——原因（profile 缺 verificationInputs、证据不完整等）
+    是单行短文本，值得留在默认输出里。允许复用时保持原样精简。
+    """
+    compact = {
         "ok": payload.get("ok", True),
         "reuse": payload.get("reuse"),
         "code": payload.get("code"),
     }
+    if payload.get("reuse") is not True:
+        for key in ("reason", "executionNeed", "detail"):
+            value = payload.get(key)
+            if value not in (None, "", [], {}):
+                compact[key] = value
+    return compact
 
 
 def emit_compact_or_verbose(
@@ -2581,9 +2592,19 @@ def cmd_record(args: argparse.Namespace) -> int:
                     error_code="PROFILE_INPUT_FILES_CONFLICT",
                 )
         files = profile_files
-    if not files:
+    # NOT_APPLICABLE 的 validation 没有输入文件可言。门禁 close 又要求
+    # requiredValidations 每项都有 entry——两条规则叠加会逼调用方拿无关文件凑数，
+    # ledger 从此声称该 validation 的输入是那些文件，是假证据。
+    not_applicable = str(getattr(args, "applicability", "") or "") == "NOT_APPLICABLE"
+    if not files and not not_applicable:
+        return emit_error(
+            "record requires --files or a non-empty --profile-input file set; "
+            "unless --applicability NOT_APPLICABLE (then --applicability-reason is required)",
+            as_json=as_json,
+        )
+    if not_applicable and not _nonempty_str(getattr(args, "applicability_reason", None)):
         return emit_error(
-            "record requires --files or a non-empty --profile-input file set",
+            "NOT_APPLICABLE requires --applicability-reason",
             as_json=as_json,
         )