@hunter-harness/workflow-harness 0.2.0 → 0.2.2

package/harness/bundles/java/cursor/scripts/harness_service.py

@@ -125,7 +125,14 @@ def read_json(path: Path) -> Any:
 def write_json(path: Path, data: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
-    path.write_text(text, encoding="utf-8", newline="\n")
+    # 原子写 temp+os.replace：崩溃后不留半写文件（与 runtime-helpers.mjs writeJsonUtf8NoBom 一致）。
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
 
 
 def load_build_profile(project: Path) -> dict[str, Any]:
@@ -153,6 +160,72 @@ def get_service_start(profile: dict[str, Any]) -> dict[str, Any]:
     return svc
 
 
+# Worktree/change 路径标记：持久 profile 的 serviceStart 不得含这些具体路径。
+# runtime resolve 把具体 overlay/profile 注入到 session，不写回持久 profile
+# （spec §3.1 持久 profile 只保存模板；§3.4 修复输入端陈旧 profile）。
+STALE_WORKTREE_MARKERS: tuple[str, ...] = (
+    ".claude/worktrees/",
+    ".cursor/worktrees/",
+    ".codeium/worktrees/",
+)
+
+
+def _detect_stale_persistent_values(service_start: dict[str, Any]) -> list[str]:
+    """检测 serviceStart 是否含具体旧 worktree/change 持久路径。
+
+    持久 profile 只保存模板；command/overlayPath/profile 嵌入 worktree 路径
+    说明是 v1 残留或被错误写回的已解析 overlay，必须拒绝（spec §3.4）。
+    """
+    stale: list[str] = []
+    for field in ("command", "overlayPath", "profile"):
+        val = service_start.get(field)
+        if not isinstance(val, str) or not val:
+            continue
+        for marker in STALE_WORKTREE_MARKERS:
+            if marker in val:
+                stale.append(f"{field} contains stale worktree path: {marker}")
+                break
+    return stale
+
+
+def resolve_service_start(
+    profile: dict[str, Any],
+    *,
+    change_name: str | None = None,
+    worktree_root: Path | None = None,
+    overlay_path: str | None = None,
+) -> dict[str, Any]:
+    """从模板 serviceStart + runtime context 生成 resolved serviceStart。
+
+    spec §3.1：持久 profile 的 serviceStart 是模板（profile/overlayPath 留空）；
+    runtime 注入具体 overlay/profile 到返回值，写入 session，**不写回持久 profile**。
+    spec §3.4：含 worktree/change 陈旧持久值时拒绝（修复输入端陈旧 profile）。
+
+    向后兼容：持久 profile.profile 非空（如 v1 残留 "local-dev"）→ 保留；
+    overlay_path 未提供 → 保留持久 overlayPath（可能为空）。
+    """
+    service_start = get_service_start(profile)  # 校验 command 非空
+
+    stale = _detect_stale_persistent_values(service_start)
+    if stale:
+        raise ValueError(
+            "serviceStart contains stale persistent worktree/change values; "
+            "run harness_profile.py migrate to clear: " + "; ".join(stale)
+        )
+
+    resolved = dict(service_start)
+    # runtime overlay 注入：显式 overlay_path 覆盖；否则保留持久模板值
+    if overlay_path is not None:
+        resolved["overlayPath"] = overlay_path
+    # runtime profile 注入：持久 profile 留空时用 change_name；非空则保留
+    if not str(resolved.get("profile") or "").strip():
+        resolved["profile"] = change_name or "local-dev"
+    # worktree_root 预留给未来相对 overlay 路径解析（spec §3.6 state snapshot）；
+    # 不写入返回值，避免污染 session。
+    _ = worktree_root
+    return resolved
+
+
 def resolve_service_input_files(
     project: Path,
     service_start: dict[str, Any],
@@ -934,10 +1007,24 @@ def cmd_ensure(args: argparse.Namespace) -> int:
 
     try:
         profile = load_build_profile(project)
-        service_start = get_service_start(profile)
     except (OSError, ValueError, FileNotFoundError, json.JSONDecodeError) as exc:
         return emit_error(str(exc), as_json=as_json)
 
+    # cluster 3 (spec §3.1/§3.4): resolve 模板 serviceStart + runtime context。
+    # 持久 profile 只保存模板；runtime overlay/profile 注入到 session，不写回持久 profile。
+    # 含 worktree/change 陈旧持久值时拒绝（修复输入端陈旧 profile）。
+    change_name = getattr(args, "change_name", None) or change_dir.name
+    overlay = getattr(args, "overlay", None)
+    try:
+        service_start = resolve_service_start(
+            profile,
+            change_name=change_name,
+            worktree_root=project,
+            overlay_path=overlay,
+        )
+    except ValueError as exc:
+        return emit_error(str(exc), as_json=as_json)
+
     command = str(service_start["command"]).strip()
     port = extract_port(service_start)
 
@@ -1292,6 +1379,16 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="comma-separated service module source files for inputsHash",
     )
+    p_ensure.add_argument(
+        "--change-name",
+        default=None,
+        help="change-name for runtime profile resolve (default: change-dir name)",
+    )
+    p_ensure.add_argument(
+        "--overlay",
+        default=None,
+        help="runtime overlay path injected into resolved serviceStart",
+    )
     p_ensure.add_argument("--json", action="store_true")
     p_ensure.set_defaults(func=cmd_ensure)
 

package/harness/bundles/java/cursor/scripts/harness_state.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Harness state/context snapshot (cluster 3, spec §3.6).
+
+Per-segment fingerprints for project/worktree/git/profile/rules/map/knowledge/
+diff. Each segment fails independently; cache miss re-captures only the affected
+segment. plan/run/test/review/submit read this snapshot; stale segments are
+re-captured by the script. Never skip code or verification gates on cache alone.
+
+Python 3.10+ stdlib only. UTF-8 without BOM. Windows path friendly.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from harness_ledger import compute_inputs_hash  # noqa: E402
+
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+SNAPSHOT_SCHEMA_VERSION = 1
+SNAPSHOT_REL = Path("meta") / "state-snapshot.json"
+
+
+def now_iso() -> str:
+    return dt.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def read_json(path: Path) -> Any:
+    # utf-8-sig 兼容可能残留的 BOM（与 harness_ledger.py 保持一致）。
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    # 强制 LF，UTF-8 无 BOM（与 harness_ledger/harness_profile 保持一致）。
+    # 原子写 temp+os.replace：崩溃后不留半写文件（与 runtime-helpers.mjs writeJsonUtf8NoBom 一致）。
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def snapshot_path(change_dir: Path) -> Path:
+    return change_dir / SNAPSHOT_REL
+
+
+def _empty_segment_fingerprint() -> str:
+    return "sha256:" + hashlib.sha256(b"").hexdigest()
+
+
+def capture_file_segment(
+    files: list[str], *, captured_at: str | None = None
+) -> dict[str, Any]:
+    """对一组文件算指纹（compute_inputs_hash，order-independent），返回 segment dict。
+
+    空文件集 → 稳定空指纹 + 空 files（段存在但无输入，不算失效）。
+    缺失文件由 compute_inputs_hash 抛 FileNotFoundError（调用方应保证文件存在）。
+    """
+    if files:
+        fp, resolved = compute_inputs_hash(files)
+        return {
+            "fingerprint": fp,
+            "files": resolved,
+            "capturedAt": captured_at or now_iso(),
+        }
+    return {
+        "fingerprint": _empty_segment_fingerprint(),
+        "files": [],
+        "capturedAt": captured_at or now_iso(),
+    }
+
+
+def capture_snapshot(
+    change_dir: Path,
+    *,
+    change_name: str,
+    project: Path,
+    worktree_root: Path,
+    base: str | None = None,
+    head: str | None = None,
+    segment_files: dict[str, list[str]] | None = None,
+) -> dict[str, Any]:
+    """采集全段 state snapshot。
+
+    segment_files 指定每段（profile/rules/map/knowledge/...）的文件集；调用方
+    （各 skill）决定每段采什么文件，snapshot 只负责采集 + 比对 + 失效。
+    git 段记录 base/head；diff 指纹由调用方按需用 harness_ledger.compute_diff_hash
+    采后填入 segment_files（spec §3.6）。
+    """
+    _ = change_dir  # 预留给未来 write-back；当前 capture 只返回 dict
+    segment_files = segment_files or {}
+    segments: dict[str, Any] = {}
+    for name, files in segment_files.items():
+        segments[name] = capture_file_segment(files)
+
+    return {
+        "schemaVersion": SNAPSHOT_SCHEMA_VERSION,
+        "generatedAt": now_iso(),
+        "changeName": change_name,
+        "project": {"root": str(project.resolve())},
+        "worktree": {"root": str(Path(worktree_root).resolve())},
+        "git": {"base": base or "", "head": head or ""},
+        "segments": segments,
+    }
+
+
+def write_snapshot(change_dir: Path, snapshot: dict[str, Any]) -> Path:
+    path = snapshot_path(change_dir)
+    write_json(path, snapshot)
+    return path
+
+
+def load_snapshot(change_dir: Path) -> dict[str, Any] | None:
+    path = snapshot_path(change_dir)
+    if not path.is_file():
+        return None
+    try:
+        data = read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def is_segment_stale(
+    snapshot: dict[str, Any], segment: str, current_fingerprint: str
+) -> bool:
+    """某段指纹是否变化。段不存在 → True（需采集）。"""
+    segs = snapshot.get("segments") or {}
+    seg = segs.get(segment)
+    if not isinstance(seg, dict):
+        return True
+    return seg.get("fingerprint") != current_fingerprint
+
+
+def refresh_segments(
+    change_dir: Path,
+    snapshot: dict[str, Any],
+    *,
+    project: Path,
+    worktree_root: Path,
+    segment_files: dict[str, list[str]],
+    segments: list[str],
+) -> dict[str, Any]:
+    """只重采指定段；其他段保留原 capturedAt/fingerprint。
+
+    spec §3.6：缓存失效只重采受影响段，不得仅凭缓存跳过代码或验证门禁。
+    返回 refreshed snapshot（不写盘；调用方按需 write_snapshot）。
+    """
+    _ = change_dir  # 预留给未来 write-back
+    refreshed = dict(snapshot)
+    refreshed["project"] = {"root": str(project.resolve())}
+    refreshed["worktree"] = {"root": str(Path(worktree_root).resolve())}
+    refreshed_segments = dict(snapshot.get("segments") or {})
+    for name in segments:
+        files = segment_files.get(name, [])
+        refreshed_segments[name] = capture_file_segment(files)
+    refreshed["segments"] = refreshed_segments
+    refreshed["generatedAt"] = now_iso()
+    return refreshed

package/harness/manifests/general/claude-code.json

@@ -2,12 +2,12 @@
   "schema_version": 2,
   "profile": "general",
   "adapter": "claude-code",
-  "bundle_version": "0.2.0",
+  "bundle_version": "0.2.2",
   "generator": "harness_deploy.py",
   "files": [
     {
       "path": ".harness-build.json",
-      "sha256": "216257ca0cbb11df301252861225676058ddd11ecd259f7541388f9df58fceaf"
+      "sha256": "d26aab76c6bd8862dd0442852f4f2d7f760a3550e66d64f8d1bd8a6db22b4933"
     },
     {
       "path": "agents/harness-evaluator.md",
@@ -31,7 +31,7 @@
     },
     {
       "path": "harness-archive/reference.md",
-      "sha256": "9523f854b1d8ea5499c4ac0f297cf4828103a5b78943fe699e98abb568e237a5"
+      "sha256": "06c031d728c7f56c31be3b72004d3f82febfed4cd9c7ce5d046e7549ae8c994a"
     },
     {
       "path": "harness-archive/scripts/gen-manifest.ps1",
@@ -39,7 +39,7 @@
     },
     {
       "path": "harness-archive/SKILL.md",
-      "sha256": "ab423201ea2016a02de136381395628885562d9c28deb83897d4fe4b61ca8941"
+      "sha256": "9882482269bcce00e95c53a255d66fa9ba814c7f5fcbf234df0112a5c3d65f55"
     },
     {
       "path": "harness-archive/templates/render-summary.mjs",
@@ -59,7 +59,7 @@
     },
     {
       "path": "harness-codebase-map/SKILL.md",
-      "sha256": "25fdb18ca0255f01597b93f2e9ffbe4dcd3c78aabe3e26df4ba2c5dc04e99bb5"
+      "sha256": "b360737e805607b6549be4299ba02f0fec18bd52fb7756381b175ad07bae94d3"
     },
     {
       "path": "harness-codebase-map/templates/ARCHITECTURE.md",
@@ -111,23 +111,23 @@
     },
     {
       "path": "harness-knowledge-ingest/reference.md",
-      "sha256": "d7230a0a382224a854c375e006e2ec93b1a8a33554d18efa3161b657373139a8"
+      "sha256": "28665f8be71787e0eb67cf3f2d6ec8511ca484a228cd914e36c4082e05bd5d38"
     },
     {
       "path": "harness-knowledge-ingest/scripts/harness_knowledge_mcp.py",
-      "sha256": "7aa14a266b1e93dc7f5e65809d6a113153d8290c0c188420fb625ef101bbe49b"
+      "sha256": "5a6efd08a4a8f46f92d715051904bf118b4159d76199c318d8accb0122a2e20f"
     },
     {
       "path": "harness-knowledge-ingest/scripts/harness_knowledge.py",
-      "sha256": "2e880e3f925413def3921262bc33e30c1efdc4b9f26d838447cdea51ceb6bda2"
+      "sha256": "6ec4851ed5fd99975b9dc192e826d0b20c24df638da4f428773476d29f7db7de"
     },
     {
       "path": "harness-knowledge-ingest/SKILL.md",
-      "sha256": "cdd02075f2a656c4326e3e871866c834c9eb0ab6603d1d95d8d353709b5a66d4"
+      "sha256": "3516ab306d156bacb02af117632ecb25b22cbf9d1aba5e413be30140ad366c19"
     },
     {
       "path": "harness-knowledge-query/SKILL.md",
-      "sha256": "783526f861f1bae6bcee84e0f4e1a0db064cc4eb76e41ea0be60a30e124d0c38"
+      "sha256": "62c0dfc675f50af6e542b9bd9db45bc84cb50b3192ed7cf245ccc9d8d7204aee"
     },
     {
       "path": "harness-plan/checklist.md",
@@ -143,7 +143,7 @@
     },
     {
       "path": "harness-plan/SKILL.md",
-      "sha256": "31b09610cd445819fc9bd68f4113450c287b8b0be3a239843453faf87c5f4f9f"
+      "sha256": "a0b0957f46ef803c4e53eafea9a8b662c95a9752cf4a9acf87854673853049e6"
     },
     {
       "path": "harness-review/checklist.md",
@@ -159,11 +159,11 @@
     },
     {
       "path": "harness-review/SKILL.md",
-      "sha256": "958e2fc25d43c7834265077670cf96b420dff8da12d9bb3ec92469ac5275b579"
+      "sha256": "043c45183a4ca2df379e018ef0d960f7966318daf62bead04ff9e9808458d278"
     },
     {
       "path": "harness-run/checklist.md",
-      "sha256": "da98ed29d842ef00b2de68dcb848dd372631a041ebe245b66a18dc3e596e7c0c"
+      "sha256": "6804247fa8fcb0dd234b1dbb7f7cfbe93d7b8d1f4bf3486246e808725a5dae99"
     },
     {
       "path": "harness-run/protocols.md",
@@ -175,11 +175,11 @@
     },
     {
       "path": "harness-run/SKILL.md",
-      "sha256": "0a4722d318e8a6290729c62224838347a011304f7a27f960345ef232a4080bee"
+      "sha256": "178303783680bec6a71e7eb246fd31f0ef3457d14c7051497600b47aa1c3c5b0"
     },
     {
       "path": "harness-submit/checklist.md",
-      "sha256": "f2f2a8fe9f9510421e6ff55ec6c670f1e4c786c56591e911782b23f16a6d4094"
+      "sha256": "abe6e77386cc702b2edafdec69609f1064cbc0794d42a3b49949400019e73f76"
     },
     {
       "path": "harness-submit/reference.md",
@@ -187,7 +187,7 @@
     },
     {
       "path": "harness-submit/SKILL.md",
-      "sha256": "fdb2ba41012350bbe213fb9efc3f86cfea70954076f0a4620457c871e9e0795f"
+      "sha256": "3aaf462e279591911844c5bde4cd98c4615f7b7e8ae2ca2a15c0e6eff67f5433"
     },
     {
       "path": "harness-sync/reference.md",
@@ -195,27 +195,31 @@
     },
     {
       "path": "harness-sync/SKILL.md",
-      "sha256": "8d76a6e0e472fd0d604e3e89fae364e69ea46caed47bde6598ae6fee432f80c7"
+      "sha256": "e5b8234b4b934ebb199e500fe1ac2ce825f03ba7c113ca3b20c566e0d24834e5"
     },
     {
       "path": "harness-test/checklist.md",
-      "sha256": "e4815196c9163e3ab258965c018e407a53e401eeb3a05883b5f6bb9b76186e7c"
+      "sha256": "e4f27ba243fae50b69588bd327d164c8e1e1596dc2c111574ec5f43f1605f4a2"
     },
     {
       "path": "harness-test/pitfalls.md",
-      "sha256": "eafe949530ac04334aedf2117b314a54dfa68333f6f64c8a155001ab7a6a83d2"
+      "sha256": "074ee0b2fb710840b6a323c4d677f14ac89e5cc77c36466bc89f9772a8443842"
     },
     {
       "path": "harness-test/reference.md",
       "sha256": "add958d6c55037ed12b4c51ba5af77ef72eb89a5835249ea092d7f6d93031760"
     },
+    {
+      "path": "harness-test/scripts/runtime-helpers.mjs",
+      "sha256": "349fcdfb48bfbe4b16fcd4c349e14cd25dd6be0414d959a633eac9a06e5773c2"
+    },
     {
       "path": "harness-test/SKILL.md",
-      "sha256": "d19d852d86351e9efef1a3989b3243c658a4d47cff8969d137111a831f6061e6"
+      "sha256": "89133639c6814f4aeddb27b339509e7e878988b1b119971f46788d778a37d891"
     },
     {
       "path": "protocols/archive-report-protocol.md",
-      "sha256": "87b947bdd4fe5b9b2c0389dddbd98f5739f22deb58664325ab1b594f2d3f02dc"
+      "sha256": "e529e9e231f700e26b392105d290543e1347cb57e1ee940059a96a67a0ae9666"
     },
     {
       "path": "protocols/evidence-based-reporting-protocol.md",
@@ -223,7 +227,7 @@
     },
     {
       "path": "protocols/ledger-protocol.md",
-      "sha256": "4861260f64b817e10b67f24012bc2d7214b2772ea5588b8afd44ece41757bdd4"
+      "sha256": "1971153eac12051f434af08416593fa63fb03eb4b2348c059daa6a4855e4af99"
     },
     {
       "path": "protocols/powershell-protocol.md",
@@ -231,15 +235,15 @@
     },
     {
       "path": "protocols/report-pipeline-protocol.md",
-      "sha256": "8ae7426f4ba17ff2091884f9d713b994d85eb1d1fc5a08126afd29c6f8a214fe"
+      "sha256": "988a311db58b8ce88544d28919cf7858fe1fa225af70fb604ae715805ac76d9e"
     },
     {
       "path": "protocols/sensitive-info-protocol.md",
-      "sha256": "3cc74b6ae56fb1e2d73ebfc559aef94289f9a5f4ee340884e1eb053cf6880ef3"
+      "sha256": "152f87e3218c2eee89362c0ca00fea624e6e37e15c56ca7e28ad2202ef76acec"
     },
     {
       "path": "protocols/state-layout-protocol.md",
-      "sha256": "42e68133d120072313f5fdd53b54b02501f03b76caf83986063a7ce5f395ce52"
+      "sha256": "73fcaa67efb89714fd62896a7ce6b4e2932ea24cfcbf5c4e1faea5a451c97076"
     },
     {
       "path": "protocols/submit-protocol.md",
@@ -251,11 +255,15 @@
     },
     {
       "path": "scripts/harness_archive.py",
-      "sha256": "f7e7e8d287b4610881d893c910dc627101aa27c72b6c58605aaa3847ecf18d89"
+      "sha256": "ada5f736cd692eab1531288fecdf57ce36ff760b55dd470c4e0553a2c73608c4"
+    },
+    {
+      "path": "scripts/harness_check_gate.py",
+      "sha256": "184a546ab76e7b9d21bd8e27802fee1f6304c392c65bca041ff7914b7fa7722a"
     },
     {
       "path": "scripts/harness_deploy.py",
-      "sha256": "c298d2ec4b093db0ac7ae5d68e78885f7e50c058e2d771a6858b1dcfea9a4340"
+      "sha256": "54f1bcdae1326588db65eec20cc650c41365b14ceb55655430ddde8343b60798"
     },
     {
       "path": "scripts/harness_events.py",
@@ -263,15 +271,23 @@
     },
     {
       "path": "scripts/harness_ledger.py",
-      "sha256": "8ad5ac94883070158807e89371b2fcca7f97d748a998e1a6cac91de179dcaca0"
+      "sha256": "e91f2f02f46ebfd0946a25085abb02965c60051097c5b24e05a70b5d3808648e"
     },
     {
       "path": "scripts/harness_preflight.py",
-      "sha256": "79af66bf9ccc62abda578f0cb29a6ca1dc07125c495d4c662faa07fb54b2df36"
+      "sha256": "7ef079a96f0e76b7fd54eb06cdab915b0dd7f0e59d368494a72faf508d40ba2f"
+    },
+    {
+      "path": "scripts/harness_profile.py",
+      "sha256": "070bd61231285e09a83752ec5c5a7b9fdc4919f36ce497643131336c8a6d77f6"
     },
     {
       "path": "scripts/harness_service.py",
-      "sha256": "aa75630245acf1e37a830eeab387928c71c737327bfb2ab95cda3cd660d44360"
+      "sha256": "fc471f90efcf03e26fcb6cd7757af37a0a1eea1184e2b57046665547a77f240f"
+    },
+    {
+      "path": "scripts/harness_state.py",
+      "sha256": "b33efacf9aba471f9f542f738c653acf274ed3ce57c4326520036e6df0f18966"
     }
   ]
 }