@hunter-harness/workflow-harness 0.2.83 → 0.2.85

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

@@ -378,6 +378,121 @@ def _normalize_verify_command(
     return result
 
 
+# 合并态验证的兜底优先级：先跑覆盖面最广的，再退到窄的。profile 里这些命令
+# 本来就是 ledger 一直在用的规范命令，没有理由让调用方在合并时另行手敲一遍。
+MERGE_VERIFICATION_FALLBACK_ORDER = ("unitTestFull", "unitTest", "apiTest", "compile")
+
+
+def verify_plan_recovery_action() -> str:
+    """把 VERIFY_PLAN_MISSING 补成一句能照做的话。
+
+    此前它只说 "requires at least one executable command"。于是调用方要么去读
+    实现，要么随手塞一条命令让门过去——两条路都走过，后者更糟：它让"验证通过"
+    这句话失去含义。
+    """
+    return (
+        "合并态验证没有可执行计划。两条正规出路："
+        "(1) 在 .harness/config/build-profile.json 增加 mergeVerification.requiredOnMerge "
+        "声明合并时必跑的命令（推荐，一次配置长期生效）；"
+        "(2) 本次用 --command 传入。注意 --command 可重复，每次只接**一条**命令，"
+        "且按 argv 直接执行（不经过 shell）——`&&`、`|`、`cd x && y` 都不成立，"
+        "需要拆成多个 --command。"
+        "示例：--command \"npm test\" --command \"npm run lint\"。"
+    )
+
+
+def _fallback_merge_commands(profile: Any) -> list[dict[str, Any]]:
+    """从 profile 已有的验证目标推导合并态计划。"""
+    commands = profile.get("commands") if isinstance(profile, dict) else None
+    if not isinstance(commands, dict):
+        return []
+    for name in MERGE_VERIFICATION_FALLBACK_ORDER:
+        entry = commands.get(name)
+        if not isinstance(entry, dict):
+            continue
+        argv = entry.get("argvTemplate")
+        if isinstance(argv, list) and argv and all(
+            isinstance(item, str) and item for item in argv
+        ):
+            return [{
+                "command": [str(item) for item in argv],
+                "kind": "heavyweight",
+                "verification": name,
+                "source": "profile-fallback",
+                "reuseContext": {},
+            }]
+        raw = entry.get("command")
+        if isinstance(raw, str) and raw.strip():
+            return [{
+                "command": _split_verify_command(raw.strip()),
+                "kind": "heavyweight",
+                "verification": name,
+                "source": "profile-fallback",
+                "reuseContext": {},
+            }]
+    return []
+
+
+def merge_verification_plan(profile: Any) -> list[dict[str, Any]]:
+    """声明优先，推导兜底；两者都没有才返回空计划。"""
+    merge = profile.get("mergeVerification") if isinstance(profile, dict) else None
+    required = merge.get("requiredOnMerge") if isinstance(merge, dict) else None
+    if isinstance(required, list) and required:
+        plan: list[dict[str, Any]] = []
+        for index, item in enumerate(required):
+            if isinstance(item, str) and item.strip():
+                plan.append({
+                    "command": _split_verify_command(item.strip()),
+                    "kind": "smoke",
+                    "verification": None,
+                    "source": "profile",
+                    "reuseContext": {},
+                })
+                continue
+            if not isinstance(item, dict):
+                raise ValueError(f"requiredOnMerge[{index}] must be string or object")
+            raw = item.get("command")
+            if isinstance(raw, list) and raw and all(
+                isinstance(value, str) and value for value in raw
+            ):
+                command = [str(value) for value in raw]
+            elif isinstance(raw, str) and raw.strip():
+                command = _split_verify_command(raw.strip())
+            else:
+                raise ValueError(f"requiredOnMerge[{index}].command missing")
+            kind = str(item.get("kind") or "smoke")
+            plan.append({
+                "command": command,
+                "kind": kind,
+                "verification": item.get("verification"),
+                "source": "profile",
+                "reuseContext": {
+                    field: str(item.get(field)).strip()
+                    for field in (
+                        "environmentHash",
+                        "toolchainHash",
+                        "lockHash",
+                        "dbSchemaHash",
+                    )
+                    if str(item.get(field) or "").strip()
+                },
+            })
+        return plan
+    return _fallback_merge_commands(profile)
+
+
+def verification_depth(plan: Sequence[dict[str, Any]]) -> str:
+    """一条临时探测命令通过，不该和跑完整条链读起来一样。
+
+    2026-08-19 那次合并，verify 只跑了一个测试文件就 DONE，报告里看不出任何差别。
+    真正的全链验证是人工在事务外补跑的——账面与事实脱节，正是这种静默造成的。
+    """
+    entries = [item for item in plan if isinstance(item, dict)]
+    if len(entries) == 1 and entries[0].get("source") not in {"profile", "profile-fallback"}:
+        return "thin"
+    return "declared"
+
+
 class IntegrationError(Exception):
     code = "INTEGRATION_ERROR"
 
@@ -1330,47 +1445,16 @@ class IntegrationTransaction:
         return commands
 
     def _required_on_merge_plan(self) -> list[dict[str, Any]]:
-        """Classify profile commands without breaking the legacy command API."""
+        """合并态验证计划：profile 声明优先，缺声明时从既有验证目标推导。
+
+        此前只读 mergeVerification.requiredOnMerge，没配就是空计划 → VERIFY_PLAN_MISSING。
+        但 profile 里本来就有 ledger 一直在用的规范命令；让调用方在合并时另行手敲一遍，
+        换来的通常是一条随手写的探测命令。
+        """
         import harness_profile
 
         profile = harness_profile.load_profile(self.project_root)
-        merge = profile.get("mergeVerification") if isinstance(profile, dict) else None
-        required = merge.get("requiredOnMerge") if isinstance(merge, dict) else []
-        if not isinstance(required, list):
-            return []
-        plan: list[dict[str, Any]] = []
-        for index, item in enumerate(required):
-            if isinstance(item, str) and item.strip():
-                plan.append({"command": _split_verify_command(item.strip()), "kind": "smoke"})
-                continue
-            if not isinstance(item, dict):
-                raise ValueError(f"requiredOnMerge[{index}] must be string or object")
-            raw = item.get("command")
-            if isinstance(raw, list) and raw and all(isinstance(value, str) and value for value in raw):
-                command = [str(value) for value in raw]
-            elif isinstance(raw, str) and raw.strip():
-                command = _split_verify_command(raw.strip())
-            else:
-                raise ValueError(f"requiredOnMerge[{index}].command missing")
-            kind, verification = _merge_command_kind(item)
-            plan.append(
-                {
-                    "command": command,
-                    "kind": kind,
-                    "verification": verification,
-                    "reuseContext": {
-                        field: str(item.get(field)).strip()
-                        for field in (
-                            "environmentHash",
-                            "toolchainHash",
-                            "lockHash",
-                            "dbSchemaHash",
-                        )
-                        if str(item.get(field) or "").strip()
-                    },
-                }
-            )
-        return plan
+        return merge_verification_plan(profile)
 
     def verify(
         self,
@@ -1384,7 +1468,12 @@ class IntegrationTransaction:
         except Exception as exc:  # noqa: BLE001 — surface as verify plan error
             raise VerifyPlanMissingError(f"mergeVerification load failed: {exc}") from exc
         plan = [
-            {"command": list(command), "kind": "smoke", "verification": None}
+            {
+                "command": list(command),
+                "kind": "smoke",
+                "verification": None,
+                "source": "cli",
+            }
             for command in commands
         ]
         plan.extend(profile_plan)
@@ -1399,7 +1488,21 @@ class IntegrationTransaction:
             ):
                 raise VerifyPlanMissingError(
                     "integration verification requires at least one executable command"
+                    " — " + verify_plan_recovery_action()
                 )
+            # 计划先落盘：verify 失败时也要看得见"打算跑什么"，
+            # 而不是只剩一个 FAILED 状态。
+            journal["verifyPlan"] = [
+                {
+                    "command": list(item["command"]),
+                    "kind": item.get("kind"),
+                    "verification": item.get("verification"),
+                    "source": item.get("source"),
+                }
+                for item in plan
+            ]
+            journal["verificationDepth"] = verification_depth(plan)
+            self._save(journal)
             evidence_change = self._bound_evidence_change(journal)
             intg_root = Path(journal["integrationRoot"]).resolve()
             results: list[dict[str, Any]] = []
@@ -2253,6 +2356,20 @@ class IntegrationTransaction:
             "steps": journal["steps"],
             "mergeCommit": journal.get("mergeCommit"),
             "pushedHead": journal.get("pushedHead"),
+            # "verify = DONE" 单独一句什么也没说明。把计划、来源和退出码一起回显，
+            # 调用方才看得出这次合并到底验证了什么。
+            "verifyPlan": journal.get("verifyPlan") or [],
+            "verificationDepth": journal.get("verificationDepth"),
+            "verifyResults": [
+                {
+                    "command": item.get("command"),
+                    "exitCode": item.get("exitCode"),
+                    "reused": bool(item.get("reused")),
+                    "durationMs": item.get("durationMs"),
+                }
+                for item in (journal.get("verifyResults") or [])
+                if isinstance(item, dict)
+            ],
         }
 
 

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

@@ -515,13 +515,42 @@ def cmd_validate_codegraph_identity(args: argparse.Namespace) -> int:
     return _emit(payload, as_json=True)
 
 
+def _input_document(args: argparse.Namespace) -> Any:
+    """--input <file> 或 --stdin，二选一。
+
+    为了把一段 JSON 交给命令而先在 runtime/ 落一个临时文件，既多一次往返，
+    也给 runtime/ 又添一件没人清的草稿。
+    """
+    use_stdin = bool(getattr(args, "stdin", False))
+    raw_input_path = getattr(args, "input", None)
+    if use_stdin and raw_input_path:
+        raise ValueError("--input 与 --stdin 只能二选一")
+    if use_stdin:
+        text = getattr(args, "_stdin_text", None)
+        if text is None:
+            text = sys.stdin.read()
+        return json.loads(text)
+    if not raw_input_path:
+        raise ValueError("需要 --input <file> 或 --stdin")
+    return _read_json(Path(raw_input_path))
+
+
 def cmd_write_findings(args: argparse.Namespace) -> int:
-    doc = _read_json(Path(args.input))
+    try:
+        doc = _input_document(args)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return _emit({"ok": False, "code": "FINDINGS_INPUT_INVALID", "error": str(exc)}, as_json=True)
     return _emit(write_findings(Path(args.change_dir), doc), as_json=True)
 
 
 def cmd_write_dispositions(args: argparse.Namespace) -> int:
-    doc = _read_json(Path(args.input))
+    try:
+        doc = _input_document(args)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return _emit(
+            {"ok": False, "code": "DISPOSITIONS_INPUT_INVALID", "error": str(exc)},
+            as_json=True,
+        )
     return _emit(write_dispositions(Path(args.change_dir), doc), as_json=True)
 
 
@@ -547,12 +576,18 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_findings = sub.add_parser("write-findings")
     p_findings.add_argument("--change-dir", required=True)
-    p_findings.add_argument("--input", required=True)
+    p_findings.add_argument("--input", help="findings JSON 文件路径")
+    p_findings.add_argument(
+        "--stdin", action="store_true", help="从标准输入读 JSON，免落临时文件"
+    )
     p_findings.set_defaults(func=cmd_write_findings)
 
     p_dispositions = sub.add_parser("write-dispositions")
     p_dispositions.add_argument("--change-dir", required=True)
-    p_dispositions.add_argument("--input", required=True)
+    p_dispositions.add_argument("--input", help="dispositions JSON 文件路径")
+    p_dispositions.add_argument(
+        "--stdin", action="store_true", help="从标准输入读 JSON，免落临时文件"
+    )
     p_dispositions.set_defaults(func=cmd_write_dispositions)
 
     p_status = sub.add_parser("status")
@@ -562,9 +597,12 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] | None = None) -> int:
+def main(argv: list[str] | None = None, *, stdin_text: str | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
+    if stdin_text is not None:
+        # 测试注入用；正式路径仍然读真正的 stdin。
+        args._stdin_text = stdin_text
     return int(args.func(args))
 
 

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": "c7a0172375d8975e"
+  "coreHash": "123134be5333129c"
 }

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=c7a0172375d8975e; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=123134be5333129c; 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=c7a0172375d8975e; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -151,6 +151,44 @@ 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） | **不提供豁免。** 必须真正脱敏后重新打包 |
+
+> ⚠️ 行内标注是**申报**，不是绕过：它把"这是设计决策"写进文档本身，可审计、可追溯。
+> **不要**为了过扫描去删改设计文档的事实内容——那是篡改证据。
+>
+> ✅ 行内标注**服务端确认生效**：平台归档入口跑的是同一个 `scanSensitiveFiles`，
+> 它直接从文件内容里解析 `hunter-harness-ignore`，命中转为 `overridden`、不再阻断。
+> 上传端点只收裸 ZIP、没有独立申报通道，靠的就是这条写在文档里的标注。
+>
+> ⚠️ 一处已知的服务端滞后：**不带凭据的连接串**（如 `postgres://dbhost:5432/appdb`）
+> 本地预检判 `low`/可豁免，而线上服务端目前仍判 `high`——high 不接受行内标注，
+> 这类设计文档暂时无法上传。平台侧修复已提交（见 hunter-platform
+> `fix(archive): 归档 422 给出可执行出路`），**部署后**两侧一致。在那之前遇到这一条：
+> 等平台部署，不要为了过扫描删掉连接串。带凭据的连接串（`user:pass@host`）两侧都是
+> `high`，必须真正脱敏。
+
 ### 二·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=c7a0172375d8975e; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=123134be5333129c; 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=c7a0172375d8975e; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=123134be5333129c; 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=c7a0172375d8975e; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：