@hunter-harness/workflow-harness 0.2.82 → 0.2.84

package/harness/bundles/general/codex/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/general/cursor/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "bd7ebe189b5b88e3"
+  "coreHash": "697a20734610e985"
 }

package/harness/bundles/general/cursor/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=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -133,6 +133,37 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 | `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/cursor/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=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/cursor/harness-knowledge-ingest/SKILL.md

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

package/harness/bundles/general/cursor/harness-knowledge-query/SKILL.md

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

package/harness/bundles/general/cursor/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/cursor/harness-pull/SKILL.md

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

package/harness/bundles/general/cursor/harness-push/SKILL.md

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

package/harness/bundles/general/cursor/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/cursor/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=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -73,6 +73,24 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 **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` 硬阻断。
@@ -104,7 +122,9 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | **预存变更** | 保留 → 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/cursor/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/cursor/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/cursor/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=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/cursor/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=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/general/cursor/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=bd7ebe189b5b88e3; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=697a20734610e985; overlay=none; agent=cursor; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose