@hunter-harness/workflow-harness 0.2.1 → 0.2.3

package/harness/bundles/java/claude-code/protocols/report-pipeline-protocol.md

@@ -24,14 +24,7 @@ python <skills-root>/scripts/harness_archive.py replay --archive-dir ".harness/a
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase "<phase>" --type <type> [--note "..."]
 ```
 
-若项目安装 Hunter-Harness CLI，collect/validate 亦可使用（与 finalize 内嵌步骤等价）：
-
-```powershell
-powershell.exe -NoProfile -Command "npx hunter-harness report collect --change-id '<change-name>' --json"
-powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<change-name>' --json"
-```
-
-CLI 不可用时，agent 仍必须按本协议生成等价的 `summary-data.json` 并执行一致性校验，不得退回手写汇总。
+归档报告流水线只有两个入口，均由 `harness_archive.py` 提供：`collect`/`render`/`validate` 是 `finalize` 的内嵌同进程步骤，**不再作为独立 CLI 暴露**（不存在 `report collect`/`report validate` 子命令）。`summary-data.json` 只能由 `finalize`（归档时）或 `replay`（回放时）生成；**禁止 agent 临场手写或拼装等价的 `summary-data.json`**。`harness_archive.py` 不可用时归档失败退出，不得退回手写汇总。
 
 ## events.ndjson
 

package/harness/bundles/java/claude-code/protocols/sensitive-info-protocol.md

@@ -90,3 +90,16 @@ spring:
 - API 测试报告的持久化记录中
 
 > 对于 API 测试中获取的 token，在测试执行过程中可临时使用（如 Playwright 请求），但测试报告中必须用 `<TOKEN_REDACTED>` 替换。
+
+## 6. profile / 规则 / Markdown 凭据扫描
+
+profile `build-profile.json`、规则文档、Skill Markdown **不得包含凭据明文值**（spec §3.4 凭据边界：配置只含 env key、cache path、角色，不含值）。发布前用 `harness-test/scripts/runtime-helpers.mjs` 的 `findCredentialValues(text)` 扫描：
+
+- 命中 `password/token/secret/accessKey/Authorization: Bearer/jdbc password=` 等明文值 → ❌FAIL，必须改为占位符 `<*_REDACTED>` 或 env 引用 `${ENV}` / `$ENV`。
+- 占位符 `<TOKEN_REDACTED>` 与 env 引用 `${TEST_TOKEN}` / `$DB_PASSWORD` 不报（credential 配置允许 env key）。
+
+```js
+import { findCredentialValues } from '<skills-root>/harness-test/scripts/runtime-helpers.mjs';
+const findings = findCredentialValues(fs.readFileSync('build-profile.json', 'utf8'));
+if (findings.length > 0) { /* ❌FAIL: 列出 line/code/snippet，改为 env key 或占位符 */ }
+```

package/harness/bundles/java/claude-code/protocols/state-layout-protocol.md

@@ -98,6 +98,30 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 
 后续阶段应优先从该文件读取路径，避免手拼 change-name 导致路径拼写错误。
 
+## state-snapshot.json（cluster 3 §3.6）
+
+`meta/state-snapshot.json`（由 `harness_state.py` 写入）集中记录 project/worktree root、HEAD/base、profile/rules/map/knowledge/diff 各段指纹与相关文件。plan/run/test/review/submit 读取该快照；失效时由脚本刷新，**不得仅凭缓存跳过代码或验证门禁**。
+
+schema：
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "<iso>",
+  "changeName": "<change-name>",
+  "project": {"root": "<abs>"},
+  "worktree": {"root": "<abs>"},
+  "git": {"base": "<sha>", "head": "<sha>"},
+  "segments": {
+    "<segment>": {"fingerprint": "sha256:...", "files": ["..."], "capturedAt": "<iso>"}
+  }
+}
+```
+
+各段独立失效：`is_segment_stale(snapshot, segment, current_fingerprint)` 比较单段指纹；段不存在 → stale（需采集）。`refresh_segments(..., segments=["profile"])` 只重采受影响段，其他段保留原 capturedAt/fingerprint（缓存失效只重采受影响段）。
+
+segment 的文件集由调用方（各 skill）决定：`capture_snapshot(..., segment_files={"profile": [...], "rules": [...]})`。snapshot 只负责采集 + 比对 + 失效，不负责发现文件。git 段记录 base/head；diff 段指纹由调用方按需用 `harness_ledger.compute_diff_hash` 采集后填入 segment_files。
+
 ## archive 结构
 
 archive 后保持同样分层结构，不把 `.bak`、脚本、manifest、HTML 全部放在 archive 根目录。

package/harness/bundles/java/claude-code/scripts/harness_archive.py

@@ -102,11 +102,15 @@ def read_json(path: Path) -> Any:
 
 def write_json(path: Path, data: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(
-        json.dumps(data, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-        newline="\n",
-    )
+    text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    # 强制 LF，UTF-8 无 BOM；原子写 temp+os.replace（与 runtime-helpers.mjs 一致）。
+    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 sha256_file(path: Path) -> str:
@@ -490,16 +494,29 @@ def check_status(change_dir: Path) -> dict[str, Any]:
         if head_hash.startswith(expected_hash) or expected_hash.startswith(head_hash[:7]):
             checks["final_hash_match"] = True
         else:
-            checks["final_hash_match"] = False
-            blockers.append(
-                {
-                    "code": "final-hash-mismatch",
-                    "message": (
-                        f"HEAD={head_hash} != expected={expected_hash} "
-                        f"(source={hash_source})"
-                    ),
-                }
+            # main may have advanced since this change merged (a later change
+            # merged on top); the change's final hash is still pushed as long as
+            # it is an ancestor of HEAD. Strict == would block archiving whenever
+            # the repo moved on, which is the normal case in a multi-change
+            # workflow.
+            anc_code, _, _ = git_run(
+                project, "merge-base", "--is-ancestor", expected_hash, head_hash
             )
+            if anc_code == 0:
+                checks["final_hash_match"] = True
+                checks["final_hash_ancestor"] = True
+            else:
+                checks["final_hash_match"] = False
+                blockers.append(
+                    {
+                        "code": "final-hash-mismatch",
+                        "message": (
+                            f"HEAD={head_hash} != expected={expected_hash} "
+                            f"(source={hash_source}) and expected is not an ancestor "
+                            f"of HEAD (not pushed?)"
+                        ),
+                    }
+                )
     elif head_hash and expected_hash is None:
         warnings.append(
             {

package/harness/bundles/java/claude-code/scripts/harness_check_gate.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Pre-push gate: skip `npm run check` when a recent check-ok marker matches
+the tree of the commit being pushed.
+
+Triple check (all must pass to skip, else exit 1 → hook runs npm run check):
+  1. marker exists and its `ts` is within MAX_AGE_S (10 min) of now
+  2. marker `command` == EXPECTED_CMD ("npm run check")
+  3. current `git rev-parse HEAD^{tree}` == marker `treeHash`
+
+The marker is written by harness-submit M5 after a green `npm run check` and
+records `git write-tree`. This remains valid after commit because the new HEAD
+has the same tree. Any mismatch (no marker, stale, command or tree changed)
+forces a full re-run — the safe default. This is a local convenience only;
+non-harness pushes have no marker and always run the check.
+
+Exit 0 = skip (recent verified), exit 1 = run npm run check.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]  # harness/scripts/../.. = repo root
+MARKER = ROOT / ".harness" / "check-ok.marker"
+MAX_AGE_S = 600  # 10 minutes
+EXPECTED_CMD = "npm run check"
+
+
+def _git_output(args: list[str]) -> str | None:
+    try:
+        r = subprocess.run(
+            ["git", *args],
+            cwd=str(ROOT),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return r.stdout.strip() if r.returncode == 0 else None
+
+
+def _current_index_tree() -> str | None:
+    return _git_output(["write-tree"])
+
+
+def _current_head_tree() -> str | None:
+    return _git_output(["rev-parse", "HEAD^{tree}"])
+
+
+def write_marker() -> int:
+    """Record the verified index tree so the marker survives the next commit."""
+    tree = _current_index_tree()
+    if tree is None:
+        return 1
+    MARKER.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"ts": time.time(), "treeHash": tree, "command": EXPECTED_CMD}
+    MARKER.write_text(
+        json.dumps(payload, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    print(f"check-ok marker written for tree {tree[:7]}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    ap = argparse.ArgumentParser(description="pre-push check gate")
+    ap.add_argument(
+        "--write",
+        action="store_true",
+        help="write a check-ok marker for current HEAD (harness-submit M5)",
+    )
+    args = ap.parse_args(argv)
+    if args.write:
+        return write_marker()
+    if not MARKER.is_file():
+        return 1
+    try:
+        data = json.loads(MARKER.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return 1
+    if not isinstance(data, dict):
+        return 1
+    ts = data.get("ts")
+    if not isinstance(ts, (int, float)) or time.time() - ts > MAX_AGE_S:
+        return 1
+    if data.get("command") != EXPECTED_CMD:
+        return 1
+    marker_tree = data.get("treeHash")
+    if not isinstance(marker_tree, str):
+        return 1
+    tree = _current_head_tree()
+    if tree is None or tree != marker_tree:
+        return 1
+    # All three checks passed: a green npm run check ran on this exact HEAD
+    # within the last 10 minutes. Safe to skip.
+    print(
+        f"pre-push: skipping npm run check (verified {int(time.time() - ts)}s ago "
+        f"for tree {tree[:7]})"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/harness/bundles/java/claude-code/scripts/harness_deploy.py

@@ -14,6 +14,7 @@ import json
 import os
 import re
 import shutil
+import subprocess
 import sys
 import uuid
 from pathlib import Path
@@ -33,6 +34,25 @@ HEADING_RE = re.compile(r"^(#{2,6})\s+(.+?)\s*$")
 FRAGMENT_HINT_RE = re.compile(r"^>\s*片段：\[\[shared/[^\]]+\]\]\s*.*$")
 
 BUILD_MARKER = ".harness-build.json"
+# Install-side managed manifests record which files a prior install owned, so a
+# later conservative install can delete removed managed files while preserving
+# user-owned files (design §3.8 要点4). Skills manifest lives in the skills
+# target dir; agents manifest lives in .claude/agents.
+MANIFEST_NAME = ".harness-managed.json"
+AGENTS_MANAGED_NAME = ".harness-managed-agents.json"
+INSTALL_METADATA = frozenset({MANIFEST_NAME, AGENTS_MANAGED_NAME})
+
+
+def _read_managed_set(path: Path) -> set[str]:
+    """Return the ``managedFiles`` set from a prior install manifest, or empty."""
+    if not path.is_file():
+        return set()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, ValueError):
+        return set()
+    files = data.get("managedFiles") if isinstance(data, dict) else None
+    return set(files) if isinstance(files, list) else set()
 
 SKIP_DIR_NAMES = {
     "__pycache__",
@@ -270,6 +290,48 @@ def validate_build_paths(skills_root: Path, out_dir: Path) -> tuple[Path, Path]:
     return skills_root, out_dir
 
 
+def _git_repo_root(start: Path) -> Path | None:
+    """Return the git toplevel containing ``start``, or None if not a git repo."""
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(start),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if r.returncode != 0 or not r.stdout.strip():
+        return None
+    return Path(r.stdout.strip())
+
+
+def _git_blob_sha(path: Path, repo_root: Path) -> str | None:
+    """Return the git blob sha for a tracked file (CRLF-normalized by .gitattributes),
+    or None if untracked / git unavailable. Caller falls back to working-copy sha256
+    for untracked build inputs (deterministic enough outside git's normalization)."""
+    try:
+        rel = path.resolve().relative_to(repo_root.resolve())
+    except ValueError:
+        return None
+    try:
+        r = subprocess.run(
+            ["git", "ls-files", "-s", "--", rel.as_posix()],
+            cwd=str(repo_root),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if r.returncode != 0 or not r.stdout.strip():
+        return None
+    # format: "<mode> <sha> <stage>\t<path>"
+    parts = r.stdout.strip().splitlines()[0].split()
+    return parts[1] if len(parts) >= 2 else None
+
+
 def core_content_hash(
     skills_root: Path,
     overlay_dir: Path | None,
@@ -298,11 +360,18 @@ def core_content_hash(
         files.extend(p for p in overlay_dir.rglob("*") if p.is_file())
     if agent_overlay_dir and agent_overlay_dir.is_dir():
         files.extend(p for p in agent_overlay_dir.rglob("*") if p.is_file())
+    skills_root_resolved = skills_root.resolve()
+    repo_root = _git_repo_root(skills_root_resolved)
     for f in sorted(set(files)):
-        rel = f.resolve().relative_to(skills_root.resolve()).as_posix()
+        rel = f.resolve().relative_to(skills_root_resolved).as_posix()
         h.update(rel.encode("utf-8"))
         h.update(b"\0")
-        h.update(sha256_file(f).encode("ascii"))
+        # Prefer the git blob sha: .gitattributes eol=lf normalization makes the
+        # hash independent of working-copy CRLF state (the CRLF working-copy drift
+        # that previously caused core hash mismatches across main/worktree). Fall
+        # back to working-tree bytes for untracked build inputs (templates, etc.).
+        blob = _git_blob_sha(f, repo_root) if repo_root else None
+        h.update((blob or sha256_file(f)).encode("ascii"))
         h.update(b"\0")
     return h.hexdigest()[:16]
 
@@ -560,10 +629,37 @@ def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str
     dest = (target or project / ".claude" / "skills").resolve()
     if not (build_out / BUILD_MARKER).is_file():
         raise ValueError(f"install source is not a marked harness build: {build_out}")
+
+    # Managed set = real files in the build (exclude build marker). Recorded so a
+    # later conservative install can delete removed managed files and preserve
+    # user-owned files (design §3.8 要点4). Paths are relative to dest, which
+    # mirrors build_out (agents/ included because copy_tree keeps it there).
+    managed_new = {p for p in collect_files(build_out) if p != BUILD_MARKER}
+    managed_agents_new = {
+        p[len("agents/"):]
+        for p in managed_new
+        if p.startswith("agents/") and "/" not in p[len("agents/"):]
+    }
+
     backup: str | None = None
     staging = dest.parent / f".{dest.name}.staging-{uuid.uuid4().hex[:8]}"
     shutil.copytree(build_out, staging)
     if dest.exists() and any(dest.iterdir()):
+        managed_old = _read_managed_set(dest / MANIFEST_NAME)
+        # Preserve user-owned files: anything in dest that was NOT managed by a
+        # prior install is copied into staging (never overwriting managed files
+        # that staging already carries from build_out). Removed managed files
+        # (in managed_old but not managed_new) are simply not carried over.
+        for rel in collect_files(dest):
+            if rel in (BUILD_MARKER, MANIFEST_NAME) or rel in INSTALL_METADATA:
+                continue
+            if rel in managed_old:
+                continue
+            dst = staging / rel
+            if dst.exists():
+                continue
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(dest / rel, dst)
         stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
         backup_path = dest.parent / f"skills-backup-{stamp}"
         os.replace(dest, backup_path)
@@ -576,12 +672,41 @@ def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str
             os.replace(Path(backup), dest)
         raise
 
+    # Record the managed set so the next conservative install can distinguish
+    # managed vs user-owned files.
+    (dest / MANIFEST_NAME).write_text(
+        json.dumps(
+            {"schemaVersion": 1, "managedFiles": sorted(managed_new)},
+            ensure_ascii=False,
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
     agents_src = build_out / "agents"
     agents_dest = project / ".claude" / "agents"
     if agents_src.is_dir():
         agents_dest.mkdir(parents=True, exist_ok=True)
+        agents_old = _read_managed_set(agents_dest / AGENTS_MANAGED_NAME)
+        # Delete managed agents removed since the prior install; user agents
+        # (never in a managed set) are left untouched.
+        for name in list(agents_old):
+            if name not in managed_agents_new:
+                (agents_dest / name).unlink(missing_ok=True)
         for agent in agents_src.glob("*.md"):
             shutil.copy2(agent, agents_dest / agent.name)
+        (agents_dest / AGENTS_MANAGED_NAME).write_text(
+            json.dumps(
+                {"schemaVersion": 1, "managedFiles": sorted(managed_agents_new)},
+                ensure_ascii=False,
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
 
     return {
         "ok": True,
@@ -613,11 +738,14 @@ def cmd_diff(build_out: Path, project: Path, target: Path | None) -> dict[str, A
     current = collect_files(installed)
     outdated = [p for p, h in built.items() if p in current and current[p] != h]
     missing = [p for p in built if p not in current]
-    extra = [p for p in current if p not in built]
+    # extra includes install-side managed manifests only as metadata, so they
+    # are excluded from the extra set; every other untracked file is a real
+    # extra and must mark the install stale (design §3.8 要点3).
+    extra = [p for p in current if p not in built and p not in INSTALL_METADATA]
     return {
         "ok": True,
         "action": "diff",
-        "stale": bool(outdated or missing),
+        "stale": bool(outdated or missing or extra),
         "outdated": sorted(outdated),
         "missing": sorted(missing),
         "extra": sorted(extra),
@@ -625,6 +753,35 @@ def cmd_diff(build_out: Path, project: Path, target: Path | None) -> dict[str, A
     }
 
 
+def cmd_validate_manifest(
+    bundle_dir: Path, manifest_entries: list[dict[str, Any]]
+) -> dict[str, Any]:
+    """Compare a bundle directory's actual file set against the manifest's
+    declared set. Both missing (declared but absent) and extra (present but
+    undeclared) fail validation (design §3.8 要点2)."""
+    bundle_dir = bundle_dir.resolve()
+    actual = collect_files(bundle_dir)
+    declared: dict[str, str] = {}
+    for entry in manifest_entries:
+        path = entry.get("path")
+        sha = entry.get("sha256")
+        if isinstance(path, str) and isinstance(sha, str):
+            declared[path] = sha
+    missing = sorted(p for p in declared if p not in actual)
+    extra = sorted(p for p in actual if p not in declared)
+    hash_mismatch = sorted(
+        p for p in declared if p in actual and actual[p] != declared[p]
+    )
+    return {
+        "ok": not (missing or extra or hash_mismatch),
+        "action": "validate-manifest",
+        "missing": missing,
+        "extra": extra,
+        "hashMismatch": hash_mismatch,
+        "comparedAt": now_iso(),
+    }
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(description="Harness skills deploy (build/install/diff)")
     sub = p.add_subparsers(dest="command", required=True)
@@ -647,6 +804,13 @@ def build_parser() -> argparse.ArgumentParser:
     d.add_argument("--project", type=Path, required=True)
     d.add_argument("--target", type=Path)
     d.add_argument("--json", action="store_true")
+
+    v = sub.add_parser(
+        "validate-manifest", help="Validate bundle dir vs manifest (missing/extra/hash)"
+    )
+    v.add_argument("--bundle", type=Path, required=True)
+    v.add_argument("--manifest", type=Path, required=True)
+    v.add_argument("--json", action="store_true")
     return p
 
 
@@ -662,6 +826,17 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "diff":
             result = cmd_diff(args.from_dir, args.project, args.target)
             return emit_json(result) if args.json else 0
+        if args.command == "validate-manifest":
+            manifest_data = json.loads(args.manifest.read_text(encoding="utf-8"))
+            entries = (
+                manifest_data.get("files", [])
+                if isinstance(manifest_data, dict)
+                else []
+            )
+            result = cmd_validate_manifest(args.bundle, entries)
+            if args.json:
+                return emit_json(result)
+            return 0 if result["ok"] else 1
     except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
         if getattr(args, "json", False):
             return emit_json({"ok": False, "error": str(exc)}, ok=False)