@hunter-harness/workflow-harness 0.2.1 → 0.2.3

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "70edc8ec35274c63"
+  "coreHash": "bcff8a45420f1380"
 }

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=70edc8ec35274c63; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=bcff8a45420f1380; overlay=none; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/general/cursor/harness-archive/reference.md

@@ -41,7 +41,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 
 ## summary-data.json 与 harness_archive.py
 
-默认由 `harness_archive.py finalize`（或 `replay`）生成/校验 `reports/final/summary-data.json`；CLI 不可用时按 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json`（schemaVersion 2.2）生成等价数据。必须保留原 final report 维度。必须包含：
+`reports/final/summary-data.json` 只能由 `harness_archive.py finalize`（归档时）或 `replay`（回放时）生成/校验；**禁止 agent 临场手写或拼装等价数据**，也不存在独立的 `report collect`/`report validate` CLI（参见 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json` schemaVersion 2.2）。必须保留原 final report 维度。必须包含：
 
 - `businessGoal`：本次变更为了做什么；
 - `stageStatus`：plan/run/test/review/submit/archive；
@@ -68,13 +68,7 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 禁止模型临场手写大段 HTML。确需临时修 HTML，只能修模板，不得让统计数字脱离 `summary-data.json`。
 
-渲染后必须执行：
-
-```powershell
-powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<date-change>' --json"
-```
-
-存在 validate error 时，不得删除原 `.harness/changes/<change>` 目录。
+`validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不再作为独立 `report validate` CLI 调用）。finalize 在 validate error 存在时恢复原 `.harness/changes/<change>` 目录并 exit 非 0，绝不归档未通过校验的变更。
 
 ## archive-meta.md 模板
 

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=70edc8ec35274c63; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=bcff8a45420f1380; overlay=none; agent=cursor; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -67,6 +67,7 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 | 4 | 不管理 CodeGraph |
 | 5 | 敏感信息脱敏 → `sensitive-info-protocol` |
 | 6 | 证据化输出 → `evidence-based-reporting-protocol` |
+| 7 | 扫描复用 `harness_profile` 的 `excludedRoots`（`DEFAULT_EXCLUDED_ROOTS`：node_modules/target/build/dist/cache 等）与 state snapshot 输入，不重复定义排除集；sync 只建议刷新，不自动触发全量 map（design §3.7） |
 
 ## Output Format
 

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

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=70edc8ec35274c63; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=bcff8a45420f1380; overlay=none; agent=cursor; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。