@hunter-harness/workflow-harness 0.2.3 → 0.2.5

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "ab1182505b44093f"
+  "coreHash": "2df0efbebf1f603a"
 }

package/harness/bundles/general/codex/README.md

@@ -135,12 +135,12 @@
 
 ## 执行日志与结构化事件机制
 
-每个关联具体变更的 skill 都必须同时维护两类事实源：
+每个关联具体变更的 skill 只维护一个实时事实源：
 
-- `.harness/changes/<change-name>/logs/execution-log.md`：人类审计日志，保留上下文、降级原因、解释性文字。
-- `.harness/changes/<change-name>/events.ndjson`：程序化事件层，供 `harness_archive.py finalize` 生成 `summary-data.json`。
+- `.harness/changes/<change-name>/events.ndjson`：程序化事件层；人类可读上下文、降级原因和解释性文字写入事件 `note`。
+- `.harness/changes/<change-name>/logs/execution-log.md`：由 `harness_events.py` 在 `phase.end` 自动重建的人类审计投影，禁止 Write/Edit。
 
-`execution-log.md` 中记录开始和结束，格式统一：
+渲染后的 `execution-log.md` 阶段格式统一：
 
 ```markdown
 ### [<序号>] harness-<skill> — YYYY-MM-DD HH:MM
@@ -152,16 +152,17 @@
 - **摘要**: <一两句话描述主要产出或问题>
 ```
 
-- harness-plan 创建变更目录时初始化日志文件和 `events.ndjson`
-- 后续每个 skill 开始时追加开始条目和 `phase.start` 事件，结束时追加结束/耗时/结果和 `phase.end` 事件
-- **任何代码修改前必须先追加开始条目**（不得等执行完才补记录）
+- harness-plan 确定 change-name 后先追加 `phase.start`，脚本自动建立事件文件
+- 后续每个 skill 开始时追加 `phase.start` 事件，结束时追加包含耗时/结果的 `phase.end` 事件
+- **任何代码修改前必须先追加 `phase.start`**（不得等执行完才补记录）
 - **降级时必须记录明确原因**（如"Agent 不可用，降级为主会话只读探索"），不可仅写"完成"
-- **禁止末尾一次性补写**——每个阶段开始和结束都用 Edit 追加
+- **禁止末尾一次性补写**——各阶段实时 append 结构化事件，渲染日志不得直接编辑
 - **Bash 拒绝、PowerShell 重试、降级、跳过、用户确认都必须记录**
 - 日志状态统一使用 `✅OK / 🟡WARN(原因) / ❌FAIL(原因)`
 - harness-archive 归档时从日志汇总：时间线、总用时、Skill 调用统计
 - `harness_archive.py finalize/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
 - sync 默认不关联具体变更目录，仅在已有变更目录时追加日志和 events
+- archive 是例外：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加阶段边界
 
 ## Skill 目录结构
 
@@ -259,10 +260,10 @@ harness-skills/
 | 阶段 | 强制检查 |
 |------|---------|
 | **plan 阶段 0** | 检查工作区是否有未提交业务代码变更，已有则询问用户处理方式（继续/暂存/回滚/取消），不得假装"编码前规划" |
-| **plan 阶段 3** | 委派前 `harness_preflight.py check-agents --agent harness-explorer`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
+| **plan 阶段 3** | 委派前 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
 | **plan 阶段 4/6** | 原生规划协议必须记录风险/复用/替代方案/推荐方案/关键决策，以及任务拆分摘要 |
 | **plan 阶段 5** | 设计文档自审结果必须展示给用户；测试场景表未覆盖维度必须标记为 ⚠️ 缺口，不得全部 ✅ |
-| **run 步骤 0** | 任何代码修改前必须先追加执行日志开始记录和 `events.ndjson` 的 `phase.start` |
+| **run 步骤 0** | 任何代码修改前必须先向 `events.ndjson` 追加 `phase.start`；执行日志由阶段结束事件自动渲染 |
 | **run 轻量验证** | `/harness-run` 默认只做开发反馈：TDD RED/GREEN + REFACTOR + 构建命令增量编译（Java 的 `mvn compile -pl <module>` 等）+ 关门检查 + 写 verification-ledger；除非改了公共模块/数据访问层/sql/权限认证/接口层/数据契约 或用户要求 full-run-validation 或不打算继续 `/harness-test`，否则不默认跑全量测试命令（Java 的 `mvn test` 等）。若跑了全量测试必须写入 ledger 供 test/submit 复用 |
 | **run TDD 降级** | 输出必须写"🟡 静态逻辑验证通过，未执行真实单元测试"，**禁止写"测试全部通过"**；降级标注写在执行日志和覆盖报告中，**不污染业务代码注释**；记录三项：降级原因、静态验证场景列表、待部署后验证场景列表 |
 | **test ledger 复用** | Phase 1 单元测试前先读 `verification-ledger.json`：若 run 阶段已对同一 diffHash/module/profile 跑过单元测试命令（Java 的 `mvn test` 等）且测试通过（Java 的 `Tests run: N, Failures: 0, Errors: 0` / 前端 N passing），可跳过重跑并标记"✅ 复用 harness-run 单元测试结果"；diffHash 不一致 / profile 不一致 / 命令范围更窄 / run 后有行为性修改则不得复用 |
@@ -276,7 +277,7 @@ harness-skills/
 | **submit 步骤 4** | 提交前必须展示四项：实际 staged 文件列表、diff stat、commit message、是否 push |
 | **submit push 前** | `git fetch` 后检查远程是否有新提交；有则**不得直接 pull 后 push**，必须 pull/rebase + 重新 compile/test |
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
-| **archive 阶段 1** | 必须先 append `phase.start` 事件，**不得等归档完成后才补**；归档前确认：commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态 |
+| **archive 阶段 1** | 归档前确认 commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
 | **archive final-summary.html** | 默认运行 `harness_archive.py finalize`：由 events/ledger/log/manifest 生成 `summary-data.json`，再由 `templates/render-summary.mjs` 渲染 `final-summary.html`，内嵌 validate。无测试或无 review 时必须在 JSON 中标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。必须真实展示状态演进（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=2df0efbebf1f603a; overlay=none; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -82,11 +82,9 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 
 ### Phase 3：执行归档
 
-1. append `phase.start` 事件。
-2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（移动、collect、render、validate、manifest 比对）。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。
-4. 模型补写 `meta/archive-meta.md` 的维护者结论 / knownRisks / manualActions（脚本占位字段）。
-5. append `phase.end` 事件。**finalize 失败或 validate 报错时不删除原目录**。
+1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
+2. 如需维护者结论，在移动前补全 `meta/archive-meta.md`；不得在 finalize 后修改已校验的归档文件。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（事件、移动、collect、render、validate、manifest 比对）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构
@@ -153,9 +151,9 @@ API 测试 `USER_SKIPPED` 或 DB 兼容 `BLOCKED_BY_DBA` 时，最终状态必
 
 未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/` 并在 final-summary 中展示。
 
-### 十一、phase.start 事件前置
+### 十一、归档事件单一所有权
 
-阶段 0 之前必须先 append `phase.start` 事件（`harness_events.py append`）；不得等归档完成才补。归档后 events.ndjson 与自动渲染的 execution-log.md 一起移入 archive。
+finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，并在移动后继续向归档目录中的同一事件流追加。调用者不得在 finalize 前后重复追加阶段边界，否则会造成重复阶段或在原 changes 路径生成幽灵目录。归档后 events.ndjson 与自动渲染的 execution-log.md 一起位于 archive。
 
 ### 十二、Shell 安全 / 敏感信息 / 证据化报告
 
@@ -187,7 +185,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/codex/harness-archive/checklist.md

@@ -16,12 +16,12 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 ## 归档前检查（Phase 1）
 
-> ⚠️ **phase.start 前置**：在归档前检查的第一项前，必须先 append `phase.start` 事件（见 SKILL.md `## 执行日志`）。不得等归档完成才补。
+> ⚠️ **单一所有权**：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。
 
-- [ ] 已 append `phase.start` 事件（`harness_events.py append --change-dir ".harness/changes/<change-name>"`）
+- [ ] 未在调用 finalize 前手工追加 archive 阶段边界
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
 - [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
-- [ ] `logs/execution-log.md` 存在（需要追加归档记录；新路径缺失时兼容根目录 `execution-log.md`）
+- [ ] `events.ndjson` 存在；执行日志允许由 finalize 从事件流重新渲染（旧 archive 才兼容根目录 `execution-log.md`）
 - [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）
 - [ ] 准备生成 `summary-data.json`（业务目标、阶段状态、验证、产物、维护者结论）
 - [ ] git status 无未提交的重要变更（归档应对应已提交的代码）
@@ -40,7 +40,7 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - [ ] `.harness/archive/YYYY-MM-DD-<change-name>/` 目录存在（通过 Glob 实际扫描确认）
 - [ ] 所有子目录（plans/, tests/, reviews/, sqls/）已完整移入（通过 Glob 实际扫描确认，不仅看预期路径）
 - [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
-- [ ] archive-meta.md 已创建，frontmatter 字段完整
+- [ ] 如需 archive-meta.md，已在 finalize 前创建且 frontmatter 字段完整；finalize 后未再改动归档文件
 - [ ] summary-data.json 已生成，且为合法 JSON
 - [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
 - [ ] **final-summary.html 真实性检查**：

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

@@ -10,11 +10,9 @@ description: harness-archive 的归档流程、manifest、summary-data、final-s
 - **Phase 1 确认归档对象**：Glob `.harness/changes/*/plans/*-plan.md`（排除 archive），展示概要；多变更让用户选择或终止。
 - **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
 - **Phase 3 执行归档**：
-  1. append `phase.start` 事件（`harness_events.py append`）。
-  2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
-  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。
-  4. 模型补写 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`（脚本留空占位）。
-  5. append `phase.end` 事件。**finalize 报错或 validate 失败时不删除原 changes 目录**。
+  1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
+  2. 需要维护者结论时，在移动前补全 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`；finalize 后不再修改归档内容。
+  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 报错或 validate 失败时不删除原 changes 目录**。
 - **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
 
 ## manifest 生成