@hunter-harness/workflow-harness 0.2.5 → 0.2.6

package/harness/bundles/java/codex/scripts/harness_events.py

@@ -2,7 +2,7 @@
 """Harness events.ndjson writer and execution-log renderer (D2).
 
 Subcommands:
-  append  — append one schema_version 2 event, then auto-render execution-log.md
+  append  — append one schema_version 3 event, then auto-render execution-log.md
   render  — full re-render of logs/execution-log.md from events.ndjson
   summary — phase durations, event counts, and issue list (JSON)
 
@@ -42,7 +42,7 @@ EVENT_TYPES = frozenset(
     }
 )
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 3
 HEADER_LINE = (
     "本文件由 harness_events.py 自动渲染，请勿手工编辑；事实源为 events.ndjson"
 )
@@ -62,6 +62,13 @@ OPTIONAL_FIELDS = (
     "message",
     "decision",
     "reason",
+    "run_id",
+    "attempt",
+    "executor_tool",
+    "executor_agent",
+    "executor_model",
+    "handoff_from_tool",
+    "handoff_reason",
 )
 
 
@@ -120,7 +127,7 @@ def duration_ms_between(start: Any, end: Any) -> int | None:
 
 
 def normalize_event(raw: dict[str, Any]) -> dict[str, Any]:
-    """Normalize schema_version 1/2 events for rendering and summary."""
+    """Normalize schema_version 1/2/3 events for rendering and summary."""
     event = dict(raw)
     version = event.get("schema_version", 1)
     try:
@@ -273,6 +280,15 @@ def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dic
         if value is None:
             continue
         event[field] = value
+    environment_defaults = {
+        "run_id": "HUNTER_HARNESS_RUN_ID",
+        "executor_tool": "HUNTER_HARNESS_TOOL",
+        "executor_agent": "HUNTER_HARNESS_AGENT",
+        "executor_model": "HUNTER_HARNESS_MODEL",
+    }
+    for field, env_name in environment_defaults.items():
+        if field not in event and os.environ.get(env_name):
+            event[field] = os.environ[env_name]
     if "note" not in event:
         event["note"] = ""
     return event
@@ -333,6 +349,46 @@ def group_events_by_phase(events: list[dict[str, Any]]) -> list[tuple[str, list[
     return [(phase, buckets[phase]) for phase in order]
 
 
+def split_phase_attempts(phase_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Split repeated starts into attempts and flag legacy events written after end."""
+    attempts: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    next_attempt = 1
+    for event in phase_events:
+        if event.get("type") == "phase.start":
+            if current is not None:
+                current["warnings"].append("new phase.start before prior phase.end")
+                attempts.append(current)
+            raw_attempt = event.get("attempt")
+            attempt = raw_attempt if isinstance(raw_attempt, int) and raw_attempt > 0 else next_attempt
+            next_attempt = max(next_attempt, attempt + 1)
+            current = {"attempt": attempt, "events": [event], "warnings": []}
+            continue
+        if current is None:
+            if attempts:
+                prior_type = attempts[-1]["events"][-1].get("type")
+                attempts[-1]["events"].append(event)
+                if prior_type == "phase.end":
+                    attempts[-1]["warnings"].append("event recorded after phase.end")
+                continue
+            raw_attempt = event.get("attempt")
+            attempt = raw_attempt if isinstance(raw_attempt, int) and raw_attempt > 0 else next_attempt
+            next_attempt = max(next_attempt, attempt + 1)
+            current = {
+                "attempt": attempt,
+                "events": [event],
+                "warnings": ["missing phase.start"],
+            }
+        else:
+            current["events"].append(event)
+        if event.get("type") == "phase.end":
+            attempts.append(current)
+            current = None
+    if current is not None:
+        attempts.append(current)
+    return attempts
+
+
 def phase_start_time(phase_events: list[dict[str, Any]]) -> str:
     for event in phase_events:
         if event.get("type") == "phase.start":
@@ -352,7 +408,9 @@ def phase_duration_ms(phase_events: list[dict[str, Any]]) -> int | None:
         elif etype == "phase.end":
             end_ts = event.get("timestamp")
     if start_ts and end_ts:
-        return duration_ms_between(start_ts, end_ts)
+        stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
+        effective_end = stamps[-1] if stamps else end_ts
+        return duration_ms_between(start_ts, effective_end)
     # Fallback: first to last timestamp in the phase bucket.
     stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
     if len(stamps) >= 2:
@@ -400,7 +458,15 @@ def render_event_line(event: dict[str, Any]) -> list[str]:
     if etype == "phase.start":
         note = str(event.get("note") or "").strip()
         suffix = f" — {note}" if note else ""
-        return [f"- phase.start @ {event.get('timestamp', '')}{suffix}"]
+        lines = [f"- phase.start @ {event.get('timestamp', '')}{suffix}"]
+        tool = str(event.get("executor_tool") or "").strip()
+        agent = str(event.get("executor_agent") or "").strip()
+        handoff = str(event.get("handoff_from_tool") or "").strip()
+        if handoff and tool:
+            lines.append(f"- 工具交接: {handoff} → {tool}")
+        elif tool:
+            lines.append(f"- 执行来源: {tool}" + (f" / {agent}" if agent else ""))
+        return lines
     if etype == "phase.end":
         note = str(event.get("note") or "").strip()
         suffix = f" — {note}" if note else ""
@@ -445,29 +511,34 @@ def render_execution_log(events: list[dict[str, Any]]) -> str:
         return "\n".join(lines)
 
     for phase, phase_events in group_events_by_phase(events):
-        start = phase_start_time(phase_events) or "—"
-        duration = phase_duration_ms(phase_events)
-        lines.append(f"## {phase} — {start}")
-        lines.append("")
-        if duration is not None:
-            lines.append(f"- 阶段耗时: {format_duration(duration)}")
-        # Collapse consecutive commands into one table.
-        buffer: list[dict[str, Any]] = []
-
-        def flush_commands() -> None:
-            nonlocal buffer
-            if buffer:
-                lines.extend(render_command_block(buffer))
-                buffer = []
-
-        for event in phase_events:
-            if event.get("type") == "command":
-                buffer.append(event)
-                continue
+        attempts = split_phase_attempts(phase_events)
+        for attempt_record in attempts:
+            attempt_events = attempt_record["events"]
+            start = phase_start_time(attempt_events) or "—"
+            duration = phase_duration_ms(attempt_events)
+            label = f"{phase}（尝试 {attempt_record['attempt']}）" if len(attempts) > 1 else phase
+            lines.append(f"## {label} — {start}")
+            lines.append("")
+            if duration is not None:
+                lines.append(f"- 阶段耗时: {format_duration(duration)}")
+            for warning in attempt_record["warnings"]:
+                lines.append(f"- 生命周期警告: {warning}")
+            buffer: list[dict[str, Any]] = []
+
+            def flush_commands() -> None:
+                nonlocal buffer
+                if buffer:
+                    lines.extend(render_command_block(buffer))
+                    buffer = []
+
+            for event in attempt_events:
+                if event.get("type") == "command":
+                    buffer.append(event)
+                    continue
+                flush_commands()
+                lines.extend(render_event_line(event))
             flush_commands()
-            lines.extend(render_event_line(event))
-        flush_commands()
-        lines.append("")
+            lines.append("")
 
     return "\n".join(lines).rstrip() + "\n"
 
@@ -485,21 +556,37 @@ def build_summary(change_dir: Path, events: list[dict[str, Any]]) -> dict[str, A
     issues: list[dict[str, Any]] = []
 
     for phase, phase_events in group_events_by_phase(events):
-        start_ts = None
-        end_ts = None
-        for event in phase_events:
-            if event.get("type") == "phase.start" and start_ts is None:
-                start_ts = event.get("timestamp")
-            elif event.get("type") == "phase.end":
-                end_ts = event.get("timestamp")
-        duration = None
-        if start_ts and end_ts:
-            duration = duration_ms_between(start_ts, end_ts)
+        attempt_records: list[dict[str, Any]] = []
+        for record in split_phase_attempts(phase_events):
+            attempt_events = record["events"]
+            starts = [e for e in attempt_events if e.get("type") == "phase.start"]
+            ends = [e for e in attempt_events if e.get("type") == "phase.end"]
+            start_ts = starts[0].get("timestamp") if starts else None
+            end_ts = ends[-1].get("timestamp") if ends else None
+            provenance = starts[0] if starts else (attempt_events[0] if attempt_events else {})
+            attempt_records.append({
+                "attempt": record["attempt"],
+                "event_count": len(attempt_events),
+                "started_at": start_ts,
+                "ended_at": end_ts,
+                "duration_ms": phase_duration_ms(attempt_events),
+                "status": ends[-1].get("status") if ends else None,
+                "run_id": provenance.get("run_id"),
+                "executor_tool": provenance.get("executor_tool"),
+                "executor_agent": provenance.get("executor_agent"),
+                "handoff_from_tool": provenance.get("handoff_from_tool"),
+                "warnings": record["warnings"],
+            })
+        durations = [a["duration_ms"] for a in attempt_records if a["duration_ms"] is not None]
+        first = attempt_records[0] if attempt_records else {}
+        last = attempt_records[-1] if attempt_records else {}
         phases[phase] = {
             "event_count": len(phase_events),
-            "started_at": start_ts,
-            "ended_at": end_ts,
-            "duration_ms": duration,
+            "started_at": first.get("started_at"),
+            "ended_at": last.get("ended_at"),
+            "duration_ms": sum(durations) if durations else None,
+            "status": last.get("status"),
+            "attempts": attempt_records,
         }
 
     for event in events:
@@ -649,6 +736,13 @@ def build_parser() -> argparse.ArgumentParser:
     p_append.add_argument("--message", default=None)
     p_append.add_argument("--decision", default=None)
     p_append.add_argument("--reason", default=None)
+    p_append.add_argument("--run-id", default=None)
+    p_append.add_argument("--attempt", type=int, default=None)
+    p_append.add_argument("--executor-tool", default=None)
+    p_append.add_argument("--executor-agent", default=None)
+    p_append.add_argument("--executor-model", default=None)
+    p_append.add_argument("--handoff-from-tool", default=None)
+    p_append.add_argument("--handoff-reason", default=None)
     p_append.set_defaults(func=cmd_append)
 
     p_render = sub.add_parser(

package/harness/bundles/java/codex/scripts/harness_preflight.py

@@ -313,7 +313,23 @@ def _parse_scalar(val: str) -> Any:
     return val
 
 
-def cmd_check_agents(skills_root: Path, agent: str) -> dict[str, Any]:
+def _resolve_agents_root(skills_root: Path, agents_root: Path | None) -> tuple[Path | None, str | None]:
+    """Resolve agent definitions without confusing a skills root with its sibling."""
+    if agents_root is not None:
+        return agents_root.resolve(), None
+    if skills_root.name == "skills" and skills_root.parent.name in (".claude", ".codebuddy"):
+        return (skills_root.parent / "agents").resolve(), None
+    if skills_root.name == "skills" and skills_root.parent.name in (".agents", ".cursor"):
+        return None, "CUSTOM_AGENTS_UNSUPPORTED"
+    return (skills_root / "agents").resolve(), None
+
+
+def cmd_check_agents(
+    skills_root: Path,
+    agent: str,
+    *,
+    agents_root: Path | None = None,
+) -> dict[str, Any]:
     skills_root = skills_root.resolve()
     agent_name = agent.strip()
     if not agent_name:
@@ -325,9 +341,23 @@ def cmd_check_agents(skills_root: Path, agent: str) -> dict[str, Any]:
             "reason": "agent name is empty",
         }
 
+    resolved_agents_root, capability_error = _resolve_agents_root(skills_root, agents_root)
+    if capability_error is not None:
+        return {
+            "ok": True,
+            "action": "check-agents",
+            "agent": agent_name,
+            "usable": False,
+            "definitionValid": False,
+            "runtimeSupported": False,
+            "reasonCode": capability_error,
+            "reason": "current adapter runtime does not support custom agent definitions; use main-session fallback",
+        }
+
+    assert resolved_agents_root is not None
     # Accept bare name or with .md
     filename = agent_name if agent_name.endswith(".md") else f"{agent_name}.md"
-    agent_path = skills_root / "agents" / filename
+    agent_path = resolved_agents_root / filename
 
     if not agent_path.is_file():
         return {
@@ -335,7 +365,11 @@ def cmd_check_agents(skills_root: Path, agent: str) -> dict[str, Any]:
             "action": "check-agents",
             "agent": agent_name,
             "path": str(agent_path),
+            "agentsRoot": str(resolved_agents_root),
             "usable": False,
+            "definitionValid": False,
+            "runtimeSupported": True,
+            "reasonCode": "AGENT_DEFINITION_NOT_FOUND",
             "reason": f"agent file not found: {agent_path}",
         }
 
@@ -390,7 +424,11 @@ def cmd_check_agents(skills_root: Path, agent: str) -> dict[str, Any]:
         "action": "check-agents",
         "agent": agent_name,
         "path": str(agent_path),
+        "agentsRoot": str(resolved_agents_root),
         "usable": True,
+        "definitionValid": True,
+        "runtimeSupported": True,
+        "reasonCode": "READY",
         "reason": "agent file exists; frontmatter parsed; tools declared",
         "name": name_field,
         "tools": tools,
@@ -431,6 +469,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_agents = sub.add_parser("check-agents", help="Validate agent definition usability")
     p_agents.add_argument("--skills-root", required=True, type=Path)
+    p_agents.add_argument("--agents-root", type=Path)
     p_agents.add_argument("--agent", required=True)
     p_agents.add_argument("--json", action="store_true")
 
@@ -459,7 +498,11 @@ def main(argv: list[str] | None = None) -> int:
         )
         return emit_json(result, ok=bool(result.get("ok", False)))
     if args.command == "check-agents":
-        result = cmd_check_agents(args.skills_root, args.agent)
+        result = cmd_check_agents(
+            args.skills_root,
+            args.agent,
+            agents_root=args.agents_root,
+        )
         return emit_json(result, ok=True)
 
     parser.error(f"unknown command: {args.command}")

package/harness/bundles/java/codex/scripts/harness_profile.py

@@ -223,8 +223,8 @@ def _java_commands(reactor_modules: list[str], pom_hash: str) -> dict[str, Any]:
             "basis": dict(basis),
         },
         "package": {
-            "command": "mvn -f pom.xml package '-Dmaven.test.skip=true'",
-            "argvTemplate": ["mvn", "-f", "pom.xml", "package", "-Dmaven.test.skip=true"],
+            "command": "mvn -f pom.xml clean package '-Dmaven.test.skip=true'",
+            "argvTemplate": ["mvn", "-f", "pom.xml", "clean", "package", "-Dmaven.test.skip=true"],
             "scope": "module",
             "inputs": _cmd_inputs(reactor_modules, pom=True, main=True, test=True),
             "coverage": "package",

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

@@ -12,9 +12,11 @@ Python 3.10+ stdlib only. UTF-8 without BOM. Windows path friendly.
 from __future__ import annotations
 
 import datetime as dt
+import argparse
 import hashlib
 import json
 import os
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any
@@ -177,3 +179,149 @@ def refresh_segments(
     refreshed["segments"] = refreshed_segments
     refreshed["generatedAt"] = now_iso()
     return refreshed
+
+
+def _git(project: Path, *args: str) -> str:
+    proc = subprocess.run(
+        ["git", "-C", str(project), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def _existing_files(paths: list[Path]) -> list[str]:
+    return sorted({str(path.resolve()) for path in paths if path.is_file()})
+
+
+def discover_segment_files(
+    project: Path, change_dir: Path, *, base: str = "", head: str = "HEAD"
+) -> dict[str, list[str]]:
+    """Discover the compact inputs shared by plan/run/test/review/submit."""
+    project = project.resolve()
+    rules = [project / "AGENTS.md", project / "CLAUDE.md"]
+    for pattern in (
+        ".claude/rules/**/*",
+        ".cursor/rules/**/*",
+        ".codebuddy/rules/**/*",
+        ".codebuddy/.rules/**/*",
+    ):
+        rules.extend(project.glob(pattern))
+
+    profile = [
+        project / ".harness/config/build-profile.json",
+        project / ".harness/context-index.json",
+        project / "project.yaml",
+        project / "harness.json",
+    ]
+    codebase_map = list((project / ".harness/codebase/map").glob("**/*"))
+    knowledge = [
+        project / ".harness/knowledge/index.json",
+        project / ".harness/knowledge/status.json",
+        project / ".harness/knowledge/config.json",
+    ]
+    change_inputs: list[Path] = []
+    for folder in ("spec", "plans", "meta"):
+        change_inputs.extend((change_dir / folder).glob("**/*"))
+    change_inputs = [path for path in change_inputs if path != snapshot_path(change_dir)]
+
+    changed_names: list[str] = []
+    if base:
+        raw = _git(project, "diff", "--name-only", "--diff-filter=ACMRT", f"{base}..{head}")
+        changed_names = [line for line in raw.splitlines() if line.strip()]
+    code = [project / name for name in changed_names]
+    return {
+        "profile": _existing_files(profile),
+        "rules": _existing_files(rules),
+        "map": _existing_files(codebase_map),
+        "knowledge": _existing_files(knowledge),
+        "change": _existing_files(change_inputs),
+        "code": _existing_files(code),
+    }
+
+
+def capture_current_state(
+    *,
+    project: Path,
+    change_dir: Path,
+    change_name: str,
+    worktree_root: Path,
+    base: str = "",
+    head: str = "HEAD",
+) -> tuple[dict[str, Any], list[str]]:
+    resolved_head = _git(project, "rev-parse", head) or head
+    resolved_base = _git(project, "rev-parse", base) if base else ""
+    files = discover_segment_files(project, change_dir, base=resolved_base, head=resolved_head)
+    previous = load_snapshot(change_dir)
+    fresh = capture_snapshot(
+        change_dir,
+        change_name=change_name,
+        project=project,
+        worktree_root=worktree_root,
+        base=resolved_base,
+        head=resolved_head,
+        segment_files=files,
+    )
+    changed: list[str] = []
+    if previous:
+        old_segments = previous.get("segments") or {}
+        for name, segment in fresh["segments"].items():
+            old = old_segments.get(name)
+            if isinstance(old, dict) and old.get("fingerprint") == segment.get("fingerprint"):
+                segment["capturedAt"] = old.get("capturedAt", segment["capturedAt"])
+            else:
+                changed.append(name)
+    else:
+        changed = list(fresh["segments"])
+    write_snapshot(change_dir, fresh)
+    return fresh, changed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Capture reusable Harness state")
+    sub = parser.add_subparsers(dest="command", required=True)
+    capture = sub.add_parser("capture", help="capture or refresh changed segments")
+    capture.add_argument("--project", default=".")
+    capture.add_argument("--change-dir", required=True)
+    capture.add_argument("--change-name")
+    capture.add_argument("--worktree-root")
+    capture.add_argument("--base", default="")
+    capture.add_argument("--head", default="HEAD")
+    capture.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    project = Path(args.project).resolve()
+    change_dir = Path(args.change_dir).resolve()
+    name = args.change_name or change_dir.name
+    worktree = Path(args.worktree_root).resolve() if args.worktree_root else project
+    snapshot, changed = capture_current_state(
+        project=project,
+        change_dir=change_dir,
+        change_name=name,
+        worktree_root=worktree,
+        base=args.base,
+        head=args.head,
+    )
+    result = {
+        "ok": True,
+        "path": str(snapshot_path(change_dir)),
+        "changedSegments": changed,
+        "reusedSegments": sorted(set(snapshot["segments"]) - set(changed)),
+        "git": snapshot["git"],
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False))
+    else:
+        print(f"state snapshot: {result['path']}")
+        print(f"changed: {', '.join(changed) if changed else 'none'}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "cursor",
-  "coreHash": "fa41b1de952e802a"
+  "coreHash": "a7decc4da50d0b7f"
 }

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

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=fa41b1de952e802a; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=a7decc4da50d0b7f; overlay=java; agent=cursor; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -24,6 +24,7 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
@@ -57,7 +58,7 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 
 ## 执行日志
 
-`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]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`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 "<触发指令>"
@@ -66,3 +67,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=fa41b1de952e802a; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=a7decc4da50d0b7f; overlay=java; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -49,6 +49,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
@@ -185,7 +186,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 执行日志
 
-`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]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`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 "<触发指令>"
@@ -194,3 +195,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

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

@@ -92,4 +92,4 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 ## 执行日志记录
 
-归档只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。
+归档只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。