@hunter-harness/workflow-harness 0.2.4 → 0.2.5

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

@@ -0,0 +1,502 @@
+#!/usr/bin/env python3
+"""Record and force-stage only explicitly touched test files.
+
+Python 3.10+ stdlib only. Git is always invoked with an argv list.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import fnmatch
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 1
+MODE = "force-track-touched"
+MANIFEST_REL = Path("evidence") / "test-tracking.json"
+PROFILE_REL = Path(".harness") / "config" / "build-profile.json"
+REASONS = ("tdd-created", "stale-test-repair", "test-updated")
+
+
+class LockUnavailable(RuntimeError):
+    """A compatible lock file is already held by another process."""
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+def _result(ok: bool, action: str, code: str, files: list[str], **extra: Any) -> dict[str, Any]:
+    return {"ok": ok, "action": action, "code": code, "files": files, **extra}
+
+
+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"
+    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 _read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return "sha256:" + digest.hexdigest()
+
+
+def _git(
+    project: Path,
+    *args: str,
+    index_file: Path | None = None,
+) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    if index_file is not None:
+        env["GIT_INDEX_FILE"] = str(index_file)
+    return subprocess.run(
+        [
+            "git",
+            "--literal-pathspecs",
+            "-c",
+            "core.quotepath=false",
+            "-C",
+            str(project),
+            *args,
+        ],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=30,
+        check=False,
+        env=env,
+    )
+
+
+def _is_ignored(project: Path, rel: str) -> bool:
+    status = _git(
+        project,
+        "status",
+        "--ignored=matching",
+        "--untracked-files=all",
+        "--porcelain=v1",
+        "--",
+        rel,
+    )
+    return status.returncode == 0 and any(
+        line.startswith("!! ") for line in status.stdout.splitlines()
+    )
+
+
+def _inside(path: Path, root: Path) -> bool:
+    try:
+        normalized_path = os.path.normcase(str(path))
+        normalized_root = os.path.normcase(str(root))
+        return os.path.commonpath((normalized_path, normalized_root)) == normalized_root
+    except ValueError:
+        return False
+
+
+@contextlib.contextmanager
+def _exclusive_lock(path: Path, *, wait_seconds: float) -> Any:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + wait_seconds
+    descriptor: int | None = None
+    while descriptor is None:
+        try:
+            descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError as exc:
+            if time.monotonic() >= deadline:
+                raise LockUnavailable(str(path)) from exc
+            time.sleep(0.01)
+    try:
+        os.write(descriptor, f"{os.getpid()}\n".encode("ascii"))
+        yield
+    finally:
+        os.close(descriptor)
+        path.unlink(missing_ok=True)
+
+
+def _change_dir(project: Path, change_dir: Path | str) -> Path | None:
+    candidate = Path(change_dir)
+    if not candidate.is_absolute():
+        candidate = project / candidate
+    resolved = candidate.resolve()
+    return resolved if _inside(resolved, project) else None
+
+
+def _manifest_path(project: Path, change_root: Path) -> Path | None:
+    evidence = change_root / MANIFEST_REL.parent
+    manifest = change_root / MANIFEST_REL
+    expected_evidence = evidence.absolute()
+    resolved_evidence = evidence.resolve()
+    if (
+        not _inside(change_root.resolve(), project)
+        or not _inside(resolved_evidence, project)
+        or os.path.normcase(str(resolved_evidence))
+        != os.path.normcase(str(expected_evidence))
+    ):
+        return None
+    return manifest
+
+
+def _manifest_target_inside(project: Path, manifest: Path) -> bool:
+    resolved = manifest.resolve()
+    return _inside(resolved, project) and _inside(resolved, manifest.parent.absolute())
+
+
+def _profile_config(project: Path) -> tuple[list[str], list[str]] | None:
+    profile_path = project / PROFILE_REL
+    if not profile_path.is_file():
+        return None
+    try:
+        profile = _read_json(profile_path)
+    except (OSError, json.JSONDecodeError):
+        return [], []
+    tracking = profile.get("testTracking") if isinstance(profile, dict) else None
+    paths = tracking.get("paths") if isinstance(tracking, dict) else None
+    if not isinstance(paths, list):
+        return [], []
+    excluded = profile.get("excludedRoots") if isinstance(profile, dict) else None
+    excluded_roots = (
+        [item.replace("\\", "/").strip("/") for item in excluded if isinstance(item, str) and item]
+        if isinstance(excluded, list)
+        else []
+    )
+    patterns = [
+        item.replace("\\", "/") for item in paths if isinstance(item, str) and item
+    ]
+    return patterns, excluded_roots
+
+
+def _matches_pattern(rel: str, pattern: str) -> bool:
+    # fnmatch does not give **/ its usual zero-or-more-directory meaning, so
+    # also try the form with every **/ removed.
+    if fnmatch.fnmatchcase(rel, pattern):
+        return True
+    compact = pattern
+    while "**/" in compact:
+        compact = compact.replace("**/", "", 1)
+        if fnmatch.fnmatchcase(rel, compact):
+            return True
+    if pattern.endswith("/**"):
+        prefix = pattern[:-3].rstrip("/")
+        return rel == prefix or rel.startswith(prefix + "/")
+    return False
+
+
+def _standard_test_path(rel: str) -> bool:
+    parts = rel.split("/")
+    if len(parts) >= 2 and parts[0] in ("test", "tests"):
+        return True
+    if any(parts[index:index + 2] == ["src", "test"] for index in range(len(parts) - 1)):
+        return True
+    return False
+
+
+def _allowed_test_path(project: Path, rel: str) -> bool:
+    config = _profile_config(project)
+    if config is None:
+        return _standard_test_path(rel)
+    patterns, excluded_roots = config
+    rel_parts = tuple(os.path.normcase(part) for part in rel.split("/"))
+    for excluded in excluded_roots:
+        excluded_parts = tuple(os.path.normcase(part) for part in excluded.split("/"))
+        if rel_parts[: len(excluded_parts)] == excluded_parts:
+            return False
+    return any(_matches_pattern(rel, pattern) for pattern in patterns)
+
+
+def _validate_file(project: Path, raw: str) -> tuple[Path | None, str | None, str | None]:
+    candidate = Path(raw)
+    if not candidate.is_absolute():
+        candidate = project / candidate
+    resolved = candidate.resolve()
+    if not _inside(resolved, project):
+        return None, None, "PATH_OUTSIDE_PROJECT"
+    if not resolved.exists():
+        return None, None, "FILE_NOT_FOUND"
+    if not resolved.is_file():
+        return None, None, "NOT_REGULAR_FILE"
+    rel = resolved.relative_to(project).as_posix()
+    if not _allowed_test_path(project, rel):
+        return None, rel, "TEST_PATH_NOT_ALLOWED"
+    return resolved, rel, None
+
+
+def _entry_shape_valid(item: Any) -> bool:
+    return (
+        isinstance(item, dict)
+        and isinstance(item.get("path"), str)
+        and bool(item["path"])
+        and isinstance(item.get("sha256"), str)
+        and re.fullmatch(r"sha256:[0-9a-f]{64}", item["sha256"]) is not None
+        and item.get("reason") in REASONS
+        and type(item.get("ignored")) is bool
+        and type(item.get("trackedBefore")) is bool
+    )
+
+
+def _validate_existing_manifest(
+    project: Path,
+    manifest: Any,
+    *,
+    allow_hash_drift: set[str] | None = None,
+    require_files: bool,
+) -> tuple[str | None, dict[str, dict[str, Any]]]:
+    if (
+        not isinstance(manifest, dict)
+        or manifest.get("schemaVersion") != SCHEMA_VERSION
+        or manifest.get("mode") != MODE
+    ):
+        return "MANIFEST_INVALID", {}
+    if manifest.get("projectRoot") != str(project):
+        return "MANIFEST_PROJECT_MISMATCH", {}
+    entries = manifest.get("files")
+    if not isinstance(entries, list):
+        return "MANIFEST_INVALID", {}
+    if require_files and not entries:
+        return "EMPTY_MANIFEST", {}
+
+    allowed_drift = allow_hash_drift or set()
+    validated: dict[str, dict[str, Any]] = {}
+    for item in entries:
+        if not _entry_shape_valid(item):
+            return "MANIFEST_INVALID", {}
+        rel = item["path"]
+        if rel in validated:
+            return "MANIFEST_INVALID", {}
+        path, normalized, error = _validate_file(project, rel)
+        if error or normalized != rel or path is None:
+            return error or "MANIFEST_INVALID", {}
+        if item["sha256"] != _sha256(path) and rel not in allowed_drift:
+            return "HASH_DRIFT" if require_files else "MANIFEST_INVALID", {}
+        ignored_now = _is_ignored(project, rel)
+        tracked_now = _git(
+            project, "ls-files", "--error-unmatch", "--", rel
+        ).returncode == 0
+        if item["ignored"] != ignored_now or item["trackedBefore"] != tracked_now:
+            return "MANIFEST_INVALID", {}
+        validated[rel] = dict(item)
+    return None, validated
+
+
+def record(
+    project: Path | str,
+    change_dir: Path | str,
+    files: list[str],
+    reason: str,
+) -> dict[str, Any]:
+    action = "record"
+    project_root = Path(project).resolve()
+    if not files:
+        return _result(False, action, "EMPTY_FILES", [])
+    if reason not in REASONS:
+        return _result(False, action, "INVALID_REASON", [])
+    change_root = _change_dir(project_root, change_dir)
+    if change_root is None:
+        return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
+
+    validated: list[tuple[Path, str]] = []
+    for raw in files:
+        path, rel, error = _validate_file(project_root, raw)
+        if error:
+            return _result(False, action, error, [rel or str(raw)])
+        assert path is not None and rel is not None
+        validated.append((path, rel))
+
+    manifest_path = _manifest_path(project_root, change_root)
+    if manifest_path is None:
+        return _result(False, action, "MANIFEST_PATH_OUTSIDE_PROJECT", [])
+    lock_path = manifest_path.with_name(manifest_path.name + ".lock")
+    try:
+        with _exclusive_lock(lock_path, wait_seconds=5.0):
+            if not _manifest_target_inside(project_root, manifest_path):
+                return _result(
+                    False, action, "MANIFEST_PATH_OUTSIDE_PROJECT", []
+                )
+            existing_files: dict[str, dict[str, Any]] = {}
+            if manifest_path.is_file():
+                try:
+                    existing = _read_json(manifest_path)
+                except (OSError, json.JSONDecodeError) as exc:
+                    return _result(
+                        False, action, "MANIFEST_INVALID", [], error=str(exc)
+                    )
+                error, existing_files = _validate_existing_manifest(
+                    project_root,
+                    existing,
+                    allow_hash_drift={rel for _, rel in validated},
+                    require_files=False,
+                )
+                if error:
+                    return _result(False, action, error, [])
+
+            for path, rel in validated:
+                ignored = _is_ignored(project_root, rel)
+                tracked = _git(
+                    project_root, "ls-files", "--error-unmatch", "--", rel
+                ).returncode == 0
+                existing_files[rel] = {
+                    "path": rel,
+                    "sha256": _sha256(path),
+                    "reason": reason,
+                    "ignored": ignored,
+                    "trackedBefore": tracked,
+                }
+
+            manifest = {
+                "schemaVersion": SCHEMA_VERSION,
+                "mode": MODE,
+                "projectRoot": str(project_root),
+                "files": [existing_files[key] for key in sorted(existing_files)],
+            }
+            _write_json(manifest_path, manifest)
+    except LockUnavailable:
+        return _result(False, action, "MANIFEST_LOCKED", [])
+    return _result(True, action, "RECORDED", [rel for _, rel in validated], manifestPath=str(manifest_path))
+
+
+def _stage_locked(
+    project_root: Path, manifest_path: Path, index_path: Path
+) -> dict[str, Any]:
+    action = "stage"
+    if not _manifest_target_inside(project_root, manifest_path):
+        return _result(False, action, "MANIFEST_PATH_OUTSIDE_PROJECT", [])
+    try:
+        manifest = _read_json(manifest_path)
+    except FileNotFoundError:
+        return _result(False, action, "MANIFEST_MISSING", [])
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result(False, action, "MANIFEST_INVALID", [], error=str(exc))
+    error, entries = _validate_existing_manifest(
+        project_root, manifest, require_files=True
+    )
+    if error:
+        return _result(False, action, error, [])
+    rels = list(entries)
+
+    before_cached_result = _git(project_root, "diff", "--cached", "--name-only")
+    if before_cached_result.returncode != 0:
+        return _result(False, action, "CACHED_DIFF_FAILED", rels)
+    before_cached = set(before_cached_result.stdout.splitlines())
+
+    handle, temp_name = tempfile.mkstemp(
+        prefix=f".{index_path.name}.test-guard.", dir=index_path.parent
+    )
+    os.close(handle)
+    temp_index = Path(temp_name)
+    temp_index.unlink(missing_ok=True)
+    try:
+        if index_path.is_file():
+            shutil.copy2(index_path, temp_index)
+        added = _git(project_root, "add", "-f", "--", *rels, index_file=temp_index)
+        if added.returncode != 0:
+            return _result(
+                False,
+                action,
+                "GIT_ADD_FAILED",
+                rels,
+                error=added.stderr.strip(),
+            )
+        cached = _git(
+            project_root,
+            "diff",
+            "--cached",
+            "--name-only",
+            index_file=temp_index,
+        )
+        if cached.returncode != 0:
+            return _result(False, action, "CACHED_DIFF_FAILED", rels)
+        after_cached = set(cached.stdout.splitlines())
+        missing = [rel for rel in rels if rel not in after_cached]
+        unexpected = sorted((after_cached - before_cached) - set(rels))
+        if missing or unexpected:
+            return _result(
+                False,
+                action,
+                "CACHED_DIFF_MISMATCH",
+                missing or unexpected,
+            )
+        os.replace(temp_index, index_path)
+        return _result(True, action, "STAGED", rels)
+    finally:
+        temp_index.unlink(missing_ok=True)
+
+
+def stage(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
+    action = "stage"
+    project_root = Path(project).resolve()
+    change_root = _change_dir(project_root, change_dir)
+    if change_root is None:
+        return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
+    manifest_path = _manifest_path(project_root, change_root)
+    if manifest_path is None:
+        return _result(False, action, "MANIFEST_PATH_OUTSIDE_PROJECT", [])
+
+    index_result = _git(project_root, "rev-parse", "--git-path", "index")
+    if index_result.returncode != 0 or not index_result.stdout.strip():
+        return _result(False, action, "GIT_INDEX_NOT_FOUND", [])
+    index_path = Path(index_result.stdout.strip())
+    if not index_path.is_absolute():
+        index_path = (project_root / index_path).resolve()
+    index_path.parent.mkdir(parents=True, exist_ok=True)
+
+    index_lock = index_path.with_name(index_path.name + ".lock")
+    try:
+        with _exclusive_lock(index_lock, wait_seconds=0.0):
+            manifest_lock = manifest_path.with_name(manifest_path.name + ".lock")
+            try:
+                with _exclusive_lock(manifest_lock, wait_seconds=0.0):
+                    return _stage_locked(project_root, manifest_path, index_path)
+            except LockUnavailable:
+                return _result(False, action, "MANIFEST_LOCKED", [])
+    except LockUnavailable:
+        return _result(False, action, "INDEX_LOCKED", [])
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    record_parser = sub.add_parser("record")
+    record_parser.add_argument("--project", required=True)
+    record_parser.add_argument("--change-dir", required=True)
+    record_parser.add_argument("--files", required=True)
+    record_parser.add_argument("--reason", required=True, choices=REASONS)
+    record_parser.add_argument("--json", action="store_true")
+    stage_parser = sub.add_parser("stage")
+    stage_parser.add_argument("--project", required=True)
+    stage_parser.add_argument("--change-dir", required=True)
+    stage_parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    if args.action == "record":
+        files = [item.strip() for item in args.files.split(",") if item.strip()]
+        result = record(args.project, args.change_dir, files, args.reason)
+    else:
+        result = stage(args.project, args.change_dir)
+    print(json.dumps(result, ensure_ascii=False, indent=2 if args.json else None))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/java/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "959b22fdc1e7af33"
+  "coreHash": "a90894841bbf814e"
 }

package/harness/bundles/java/codebuddy/harness-apidoc/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

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

package/harness/bundles/java/codebuddy/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=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/codebuddy/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=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/java/codebuddy/harness-knowledge-query/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。

package/harness/bundles/java/codebuddy/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。使用场景：打包、package、发版准备
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -56,7 +56,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 0. 加载上下文（change-name、spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback）→ append `phase.start`
 0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + 写 ledger（diffHash 三部分合并，`reference.md` Step 2c）
+2. 构建验证 + 写 ledger（`harness_ledger.py diff-hash --change-dir` 纳入 ignored tests，`reference.md` Step 2c）
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
 4. **关门检查**（10 项）+ 计划状态持久化
 
@@ -86,12 +86,24 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | **变更簇 TDD** | 一簇一次 RED/GREEN；低价值项豁免；新分支必须 RED |
 | **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过；greenfield 大重写豁免见 reference |
 | **Mapper/DB** | 纯 Mock 不得宣称 DB 验证通过；迁移脚本**永不自动执行** |
-| **探测/ledger** | 基础设施先探测；每次构建/测试写 ledger；三部分 diffHash |
+| **探测/ledger** | 基础设施先探测；每次构建/测试写 ledger；用 canonical `diff-hash --change-dir` |
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
 | **Worktree** | `requested=true` 时代码只写 worktree |
 | **PowerShell** | 所有 git/构建经 `powershell.exe -NoProfile -Command` |
 
+### 陈旧测试安全修复与精确跟踪
+
+测试编译或 RED/GREEN 失败时，先区分当前实现缺陷、测试基础设施故障与陈旧测试。只有同时满足以下条件才允许自动修复陈旧测试：当前生产代码、已批准计划或可验证的历史变更能唯一确定新契约；修改范围仅限测试文件；修复后会立即重跑该测试及本变更目标测试。符合时以 `stale-test-repair` 记录：
+
+```text
+python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
+```
+
+新建或正常更新测试分别使用 `tdd-created` / `test-updated`。若预期行为存在业务歧义，停止测试修复并记录 `BLOCKED_PREEXISTING`，不得猜测新断言。
+
+**禁止临时排除测试**：不得将测试改名为 `.bak`、移出测试目录、删除、添加 `@Disabled`/`@Ignore`、修改 Surefire/Gradle exclude 或跳过测试来制造绿色结果；也不得仅为满足陈旧测试而修改生产代码。`.gitignore` 中的测试只能通过 manifest 的精确路径闭环处理，禁止全局放宽 ignore。
+
 ### Java TDD / 数据访问补充
 
 | 项 | 规则 |
@@ -99,7 +111,9 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | **低价值豁免** | ErrorCode 常量、VO/DTO 字段、注释、import 清理、格式化、SQL 脚本、配置模板、文档 — 不单独建测试类；禁止为单个错误码单独跑 Maven |
 | **Mapper / LambdaQueryWrapper / SQL** | 纯 Mock 返回值**不得**宣称 DB 验证通过 → 🟡 静态验证，交 harness-test 真实 DB |
 | **行为性新分支** | 正则/条件/分支逻辑变更新增分支须 RED→GREEN；不属于低价值豁免 |
-| **ledger** | compile 必写；执行了 test 写 unitTest，否则 `NOT_RUN_BY_RUN`；diffHash 三部分合并（见 reference） |
+| **ledger** | compile 必写；执行了 test 写 unitTest，否则 `NOT_RUN_BY_RUN`；diffHash 用 `harness_ledger.py diff-hash --change-dir`（见 reference） |
+| **陈旧 Java 测试** | `cannot find symbol`/mapper 方法改名/DTO 字段迁移只有在当前接口和批准计划唯一确定替代契约时才允许只改测试；修复后定向 `mvn test -Dtest=<class>`，再跑目标测试并记录 `stale-test-repair` |
+| **禁止规避** | 禁止把 `*Test.java` 改成 `.bak`、删除、`@Disabled`/`@Ignore`、Surefire exclude 或以 `-DskipTests` 充当 GREEN |
 ## Output Format
 
 变更文件表 + 构建/测试证据 + 场景覆盖摘要 + 最终状态（✅OK / 🟡WARN / ❌FAIL）。→ `reference.md`