@hunter-harness/workflow-harness 0.2.82 → 0.2.84

package/harness/bundles/general/cursor/scripts/harness_runtime.py

@@ -18,6 +18,8 @@ import threading
 import time
 import uuid
 from pathlib import Path
+import fnmatch
+from collections.abc import Sequence
 from typing import Any, Callable
 
 SCRIPTS_DIR = Path(__file__).resolve().parent
@@ -35,6 +37,11 @@ RUN_TERMINAL_STATUSES = {"OK", "FAIL", "INCOMPLETE", "CANCELLED"}
 _CHANGE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
 SECRET_SCAN_RULES_VERSION = "secret-scan-v2"
 SECRET_SCAN_RECEIPT_REL = Path("meta") / "secret-scan-receipt.json"
+# 变更目录里只有一部分内容会被发布：归档包成员是 reports/final/summary-data.json、
+# spec/**.md、plans/**.md、candidates/knowledge.json、meta/archive-meta.md、
+# meta/change-context.json。runtime/ 是各阶段的草稿（review 的 diff、临时校验
+# 脚本、命令输出重定向），从不入包——拿它挡发布，挡的是永远不会离开本机的字节。
+PUBLICATION_EXCLUDED_DIRS: tuple[str, ...] = ("runtime",)
 _SENSITIVE_ASSIGNMENT = re.compile(
     rb"(?i)[\"']?(?:password|passwd|token|secret|cookie|database[_-]?url)"
     rb"[\"']?\s*[:=]\s*[\"']?(?P<value>[^\s\"']{4,})"
@@ -126,7 +133,15 @@ def _sha256_json(value: Any) -> str:
     return "sha256:" + hashlib.sha256(encoded).hexdigest()
 
 
-def _publishable_tree_digest(root: Path) -> str:
+def _is_excluded(relative: str, exclude_dirs: Sequence[str]) -> bool:
+    """Path is inside one of the excluded top-level directories."""
+    head = relative.split("/", 1)[0]
+    return head in exclude_dirs
+
+
+def _publishable_tree_digest(
+    root: Path, *, exclude_dirs: Sequence[str] = ()
+) -> str:
     """Hash publishable bytes while excluding the self-referential scan receipt."""
     root = root.expanduser().resolve()
     digest = hashlib.sha256()
@@ -136,6 +151,10 @@ def _publishable_tree_digest(root: Path) -> str:
     for path in sorted(root.rglob("*")):
         if not path.is_file() or path.resolve() == receipt:
             continue
+        if exclude_dirs and _is_excluded(
+            path.relative_to(root).as_posix(), exclude_dirs
+        ):
+            continue
         relative = path.relative_to(root).as_posix()
         data = path.read_bytes()
         digest.update(relative.encode("utf-8"))
@@ -215,8 +234,73 @@ def _secure_private_path(path: Path, *, directory: bool) -> str:
         return "WINDOWS_ACL_UNVERIFIED"
 
 
-def _sensitive_candidates(root: Path) -> list[dict[str, Any]]:
-    """Find high-confidence plaintext assignments without treating prose as a secret."""
+# runtime/ 下哪些是**过程草稿**。白名单式判断：只删明确列举的形态，
+# 其余一律保留——门禁、租约、恢复和证据都住在这棵树里，宁可留垃圾也不能误删。
+SCRATCH_PATTERNS: tuple[str, ...] = (
+    "*.patch",
+    "*.diff",
+    "*-input.json",
+    "*-input[0-9].json",
+    "findings-rereview.json",
+    "archive-out*.json",
+    "fixback-*-check.*",
+)
+# 即便命中上面的形态也必须留下的名字：它们是运行态，不是草稿。
+SCRATCH_KEEP: frozenset[str] = frozenset({
+    "context-lease.json",
+    "fixback-session.json",
+    "preflight.json",
+})
+
+
+def sweep_scratch(change_root: Path, *, dry_run: bool = False) -> dict[str, Any]:
+    """清掉 runtime/ 顶层的过程草稿，保留运行态、会话、证据与报告。
+
+    一轮流程下来 runtime/ 会堆满 diff、临时校验脚本和命令输出重定向。没人清，
+    而且它们会被其他门禁读到——2026-08-19 那次，review 自己生成的两个 diff
+    直接把归档挡住了。
+
+    只扫 runtime/ 顶层文件：run-sessions/ 等子目录是托管会话证据，不进扫描。
+    """
+    change_root = change_root.expanduser().resolve()
+    runtime_dir = change_root / "runtime"
+    removed: list[str] = []
+    if not runtime_dir.is_dir():
+        return {"ok": True, "code": "SCRATCH_SWEPT", "removed": [], "dryRun": dry_run}
+    errors: list[dict[str, str]] = []
+    for path in sorted(runtime_dir.iterdir()):
+        if not path.is_file() or path.name in SCRATCH_KEEP:
+            continue
+        if not any(fnmatch.fnmatch(path.name, pattern) for pattern in SCRATCH_PATTERNS):
+            continue
+        relative = path.relative_to(change_root).as_posix()
+        if dry_run:
+            removed.append(relative)
+            continue
+        try:
+            path.unlink()
+        except OSError as exc:
+            errors.append({"path": relative, "error": str(exc)})
+            continue
+        removed.append(relative)
+    return {
+        "ok": not errors,
+        "code": "SCRATCH_SWEPT" if not errors else "SCRATCH_SWEEP_PARTIAL",
+        "removed": removed,
+        "errors": errors,
+        "dryRun": dry_run,
+    }
+
+
+def _sensitive_candidates(
+    root: Path, *, exclude_dirs: Sequence[str] = ()
+) -> list[dict[str, Any]]:
+    """Find high-confidence plaintext assignments without treating prose as a secret.
+
+    ``exclude_dirs`` scopes the scan to what a caller actually publishes. The
+    default stays whole-tree: the quarantine flow depends on seeing legacy
+    plaintext anywhere under the change, including scratch directories.
+    """
     # Compare by relative path, not by resolve() per file: this loop covers the
     # whole change tree, and on Windows each resolve() is a realpath syscall.
     receipt_rel = SECRET_SCAN_RECEIPT_REL.as_posix()
@@ -224,7 +308,10 @@ def _sensitive_candidates(root: Path) -> list[dict[str, Any]]:
     for path in sorted(root.rglob("*")):
         if not path.is_file():
             continue
-        if path.relative_to(root).as_posix() == receipt_rel:
+        relative = path.relative_to(root).as_posix()
+        if relative == receipt_rel:
+            continue
+        if exclude_dirs and _is_excluded(relative, exclude_dirs):
             continue
         try:
             raw = path.read_bytes()
@@ -263,17 +350,21 @@ def _is_sensitive_placeholder(value: bytes) -> bool:
     )
 
 
-def publishable_tree_digest(root: Path) -> str:
+def publishable_tree_digest(
+    root: Path, *, exclude_dirs: Sequence[str] = ()
+) -> str:
     """Public digest helper shared by the archive publication gate."""
-    return _publishable_tree_digest(root)
+    return _publishable_tree_digest(root, exclude_dirs=exclude_dirs)
 
 
 def sensitive_evidence_receipt_path(change_root: Path) -> Path:
     return _sensitive_evidence_receipt_path(change_root)
 
 
-def sensitive_evidence_candidates(root: Path) -> list[dict[str, Any]]:
-    return _sensitive_candidates(root)
+def sensitive_evidence_candidates(
+    root: Path, *, exclude_dirs: Sequence[str] = ()
+) -> list[dict[str, Any]]:
+    return _sensitive_candidates(root, exclude_dirs=exclude_dirs)
 
 
 def _build_sensitive_scan_receipt(
@@ -282,6 +373,7 @@ def _build_sensitive_scan_receipt(
     entries: list[dict[str, Any]],
     unresolved: list[dict[str, Any]],
     status: str,
+    exclude_dirs: Sequence[str] = (),
 ) -> dict[str, Any]:
     change_root = change_root.expanduser().resolve()
     return {
@@ -291,7 +383,12 @@ def _build_sensitive_scan_receipt(
         "status": status,
         "unresolvedFailures": unresolved,
         "entries": entries,
-        "publishableTreeDigest": _publishable_tree_digest(change_root),
+        "publishableTreeDigest": _publishable_tree_digest(
+            change_root, exclude_dirs=exclude_dirs
+        ),
+        # 收据自述扫描范围：复算摘要的一方据此排除同样的目录，
+        # 否则两侧口径不同会误报 digest 漂移。
+        "publicationExcludedDirs": list(exclude_dirs),
         "publicationExcluded": True,
         "recordedAt": now_iso(),
     }
@@ -303,6 +400,7 @@ def _write_sensitive_scan_receipt(
     entries: list[dict[str, Any]],
     unresolved: list[dict[str, Any]],
     status: str,
+    exclude_dirs: Sequence[str] = (),
 ) -> dict[str, Any]:
     change_root = change_root.expanduser().resolve()
     receipt = _build_sensitive_scan_receipt(
@@ -310,6 +408,7 @@ def _write_sensitive_scan_receipt(
         entries=entries,
         unresolved=unresolved,
         status=status,
+        exclude_dirs=exclude_dirs,
     )
     atomic_write_json(_sensitive_evidence_receipt_path(change_root), receipt)
     return receipt
@@ -463,6 +562,7 @@ def refresh_sensitive_evidence_scan_receipt(
     change_root: Path,
     *,
     persist: bool = True,
+    exclude_dirs: Sequence[str] = (),
 ) -> dict[str, Any]:
     """Rescan current bytes while preserving valid quarantine audit entries."""
     change_root = change_root.expanduser().resolve()
@@ -508,7 +608,7 @@ def refresh_sensitive_evidence_scan_receipt(
             }
         entries = list(prior_entries)
 
-    unresolved = _sensitive_candidates(change_root)
+    unresolved = _sensitive_candidates(change_root, exclude_dirs=exclude_dirs)
     status = "FAIL" if unresolved else "QUARANTINED" if entries else "OK"
     if persist:
         try:
@@ -517,6 +617,7 @@ def refresh_sensitive_evidence_scan_receipt(
                 entries=entries,
                 unresolved=unresolved,
                 status=status,
+                exclude_dirs=exclude_dirs,
             )
         except OSError as exc:
             return {
@@ -531,6 +632,7 @@ def refresh_sensitive_evidence_scan_receipt(
             entries=entries,
             unresolved=unresolved,
             status=status,
+            exclude_dirs=exclude_dirs,
         )
     return {
         "ok": not unresolved,
@@ -2019,6 +2121,15 @@ def build_parser() -> argparse.ArgumentParser:
         help="override the private root; must be outside the project root and on its drive",
     )
     p_quarantine.add_argument("--json", action="store_true")
+    p_sweep = sub.add_parser(
+        "sweep-scratch",
+        help="删除 runtime/ 顶层的过程草稿（diff、临时输入、命令输出）",
+    )
+    p_sweep.add_argument("--change-dir", required=True)
+    p_sweep.add_argument(
+        "--dry-run", action="store_true", help="只列出会删什么，不真删"
+    )
+    p_sweep.add_argument("--json", action="store_true")
     p_adapter = sub.add_parser("adapter")
     p_adapter.add_argument("--agent", choices=sorted(_ADAPTERS), required=True)
     p_adapter.add_argument("--change", required=True)
@@ -2069,6 +2180,10 @@ def main(argv: list[str] | None = None) -> int:
             result = doctor(Path(args.project), Path(args.change_dir), agent=args.agent)
         elif args.command == "quarantine-evidence":
             result = cmd_quarantine_evidence(args)
+        elif args.command == "sweep-scratch":
+            result = sweep_scratch(
+                Path(args.change_dir), dry_run=bool(args.dry_run)
+            )
         elif args.command == "adapter":
             result = {"ok": True, "action": "adapter", **adapter_worktree(args.agent, args.change)}
         elif args.command == "_worker":

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "b95f3e3eb20d5959"
+  "coreHash": "c0f4b71956cfc910"
 }

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=b95f3e3eb20d5959; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c0f4b71956cfc910; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=b95f3e3eb20d5959; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c0f4b71956cfc910; overlay=java; 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/java/claude-code/harness-codebase-map/SKILL.md

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

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

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

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

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

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=b95f3e3eb20d5959; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c0f4b71956cfc910; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

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

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

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

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

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

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

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

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=b95f3e3eb20d5959; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c0f4b71956cfc910; overlay=java; 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` 硬阻断。
@@ -131,7 +149,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/java/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/java/claude-code/harness-submit/SKILL.md

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

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

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

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

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