@hunter-harness/workflow-harness 0.2.60 → 0.2.62

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

@@ -810,10 +810,15 @@ def close_transition(
     artifact_entries: list[dict[str, Any]] = []
     for raw in artifacts or []:
         requested = Path(raw)
+        artifact_bases: list[Path] = []
+        for base in (project, contract_root, state_root):
+            resolved_base = base.resolve()
+            if resolved_base not in artifact_bases:
+                artifact_bases.append(resolved_base)
         candidates = (
             [requested]
             if requested.is_absolute()
-            else [project / requested, contract_root / requested]
+            else [base / requested for base in artifact_bases]
         )
         valid: list[Path] = []
         for candidate in candidates:
@@ -838,10 +843,11 @@ def close_transition(
                 "ok": False,
                 "code": "TRANSITION_ARTIFACT_INVALID",
                 "path": raw,
-                "acceptedBases": [str(project), str(contract_root)],
+                "acceptedBases": [str(base) for base in artifact_bases],
                 "examples": [
                     str(contract_root / "meta" / "plan-finalization.json"),
                     f".harness/changes/{change}/meta/plan-finalization.json",
+                    f".harness/state/changes/{change}/evidence/verification-ledger.json",
                     "meta/plan-finalization.json",
                 ],
             }

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

@@ -1077,6 +1077,11 @@ def split_phase_attempts(phase_events: list[dict[str, Any]]) -> list[dict[str, A
         "external.wait",
         "issue",
         "ci.wait",
+        # Preparation is intentionally outside the formal phase lifecycle.
+        # A blocked preflight must remain visible in the raw timeline without
+        # manufacturing an attempt or inflating the phase duration/count.
+        "phase.prepare.start",
+        "phase.prepare.end",
     }
     for event in phase_events:
         if event.get("type") == "phase.start":

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

@@ -350,36 +350,97 @@ def _state_dir(change_dir: Path) -> Path:
     return Path(harness_paths.resolve_state_dir_for_contract(change_dir))
 
 
-def load_cursor(
+def _cursor_values(path: Path) -> tuple[int, int, bool]:
+    if not path.is_file():
+        return 0, 0, True
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0, 0, False
+    raw_acked = data.get("acked_lines") if isinstance(data, dict) else None
+    raw_base = data.get("producer_seq_base", 0) if isinstance(data, dict) else None
+    acked_valid = (
+        not isinstance(raw_acked, bool)
+        and isinstance(raw_acked, int)
+        and raw_acked >= 0
+    )
+    base_valid = (
+        not isinstance(raw_base, bool)
+        and isinstance(raw_base, int)
+        and raw_base >= 0
+    )
+    return (
+        raw_acked if acked_valid else 0,
+        raw_base if base_valid else 0,
+        acked_valid and base_valid,
+    )
+
+
+def _complete_line_count(path: Path) -> int:
+    if not path.is_file():
+        return 0
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return 0
+    if not data:
+        return 0
+    return data.count(b"\n")
+
+
+def _initial_producer_seq_base(change_dir: Path) -> int:
+    """Keep producer sequence monotonic when a legacy stream becomes split-v1."""
+    state_dir = _state_dir(change_dir).resolve()
+    contract_dir = change_dir.resolve()
+    if state_dir == contract_dir:
+        return 0
+    legacy_acked, legacy_base, _ = _cursor_values(
+        contract_dir / "meta" / "events-sync-cursor.json"
+    )
+    legacy_lines = _complete_line_count(contract_dir / "events.ndjson")
+    return legacy_base + max(legacy_acked, legacy_lines)
+
+
+def load_cursor_state(
     change_dir: Path,
     *,
     maximum_lines: int | None = None,
     repair: bool = False,
-) -> int:
+) -> dict[str, int]:
     path = cursor_path(change_dir)
-    if not path.is_file():
-        return 0
-    valid = True
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        data = None
-        valid = False
-    raw = data.get("acked_lines") if isinstance(data, dict) else None
-    if isinstance(raw, bool) or not isinstance(raw, int) or raw < 0:
-        valid = False
-        value = 0
-    else:
-        value = raw
+    exists = path.is_file()
+    acked, producer_seq_base, valid = _cursor_values(path)
+    if not exists:
+        producer_seq_base = _initial_producer_seq_base(change_dir)
     if maximum_lines is not None:
         if maximum_lines < 0:
             raise ValueError("maximum_lines must be non-negative")
-        if value > maximum_lines:
+        if acked > maximum_lines:
+            acked = 0
             valid = False
-            value = 0
-    if not valid and repair:
-        save_cursor(change_dir, 0)
-    return value
+    if (not valid or not exists) and repair:
+        save_cursor(
+            change_dir,
+            acked,
+            producer_seq_base=producer_seq_base,
+        )
+    return {
+        "acked_lines": acked,
+        "producer_seq_base": producer_seq_base,
+    }
+
+
+def load_cursor(
+    change_dir: Path,
+    *,
+    maximum_lines: int | None = None,
+    repair: bool = False,
+) -> int:
+    return load_cursor_state(
+        change_dir,
+        maximum_lines=maximum_lines,
+        repair=repair,
+    )["acked_lines"]
 
 
 def _fsync_parent(path: Path) -> None:
@@ -392,14 +453,31 @@ def _fsync_parent(path: Path) -> None:
         os.close(descriptor)
 
 
-def save_cursor(change_dir: Path, acked_lines: int) -> None:
+def save_cursor(
+    change_dir: Path,
+    acked_lines: int,
+    *,
+    producer_seq_base: int | None = None,
+) -> None:
     if isinstance(acked_lines, bool) or not isinstance(acked_lines, int) or acked_lines < 0:
         raise ValueError("acked_lines must be a non-negative integer")
     path = cursor_path(change_dir)
+    if producer_seq_base is None:
+        _, producer_seq_base, _ = _cursor_values(path)
+    if (
+        isinstance(producer_seq_base, bool)
+        or not isinstance(producer_seq_base, int)
+        or producer_seq_base < 0
+    ):
+        raise ValueError("producer_seq_base must be a non-negative integer")
     path.parent.mkdir(parents=True, exist_ok=True)
     temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
     encoded = (
-        json.dumps({"schemaVersion": 1, "acked_lines": acked_lines}, indent=2) + "\n"
+        json.dumps({
+            "schemaVersion": 2,
+            "acked_lines": acked_lines,
+            "producer_seq_base": producer_seq_base,
+        }, indent=2) + "\n"
     ).encode("utf-8")
     descriptor = os.open(
         str(temporary), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600
@@ -489,6 +567,85 @@ def _event_lines_snapshot(events_file: Path) -> list[str]:
     return data.decode("utf-8-sig").splitlines()
 
 
+def _complete_stream_bytes(path: Path) -> bytes:
+    data = path.read_bytes() if path.is_file() else b""
+    if data and not data.endswith(b"\n"):
+        last_newline = data.rfind(b"\n")
+        data = b"" if last_newline < 0 else data[:last_newline + 1]
+    return data
+
+
+def _atomic_replace_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    descriptor = os.open(
+        str(temporary), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            descriptor = -1
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        _fsync_parent(path)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def _migrate_pending_legacy_stream(change_dir: Path) -> None:
+    """Prefix unsent colocated events before the first split-v1 state upload."""
+    contract_dir = change_dir.resolve()
+    state_dir = _state_dir(change_dir).resolve()
+    legacy_events = contract_dir / "events.ndjson"
+    target_events = state_dir / "events.ndjson"
+    target_cursor = state_dir / "meta" / "events-sync-cursor.json"
+    if state_dir == contract_dir or not legacy_events.is_file() or target_cursor.exists():
+        return
+    legacy_cursor = contract_dir / "meta" / "events-sync-cursor.json"
+    legacy_acked, _, _ = _cursor_values(legacy_cursor)
+    legacy_line_count = _complete_line_count(legacy_events)
+    if legacy_acked >= legacy_line_count:
+        return
+
+    locks = [
+        _CrossProcessLock(path.with_name(path.name + ".lock"))
+        for path in sorted((legacy_events, target_events), key=lambda item: str(item).casefold())
+    ]
+    for lock in locks:
+        lock.acquire(blocking=True)
+    try:
+        if target_cursor.exists() or not legacy_events.is_file():
+            return
+        legacy_data = _complete_stream_bytes(legacy_events)
+        target_data = _complete_stream_bytes(target_events)
+        if target_data.startswith(legacy_data):
+            merged = target_data
+        else:
+            merged = legacy_data + target_data
+        _atomic_replace_bytes(target_events, merged)
+
+        target_cursor.parent.mkdir(parents=True, exist_ok=True)
+        if legacy_cursor.is_file():
+            os.replace(legacy_cursor, target_cursor)
+        else:
+            save_cursor(change_dir, 0, producer_seq_base=0)
+
+        legacy_quarantine = contract_dir / "meta" / "events-sync-quarantine.ndjson"
+        target_quarantine = state_dir / "meta" / "events-sync-quarantine.ndjson"
+        if legacy_quarantine.is_file() and not target_quarantine.exists():
+            os.replace(legacy_quarantine, target_quarantine)
+        legacy_events.unlink()
+    finally:
+        for lock in reversed(locks):
+            lock.release()
+
+
 def sync_change(
     project: Path,
     change_dir: Path,
@@ -525,6 +682,7 @@ def sync_change(
     if heartbeat_only:
         return {"ok": True, "heartbeat": True, "run_id": rid, "change_key": resolved_key}
 
+    _migrate_pending_legacy_stream(change_dir)
     events_file = _state_dir(change_dir) / "events.ndjson"
     if not events_file.is_file():
         return {
@@ -536,11 +694,13 @@ def sync_change(
         }
 
     lines = _event_lines_snapshot(events_file)
-    acked = load_cursor(
+    cursor = load_cursor_state(
         change_dir,
         maximum_lines=len(lines),
         repair=True,
     )
+    acked = cursor["acked_lines"]
+    producer_seq_base = cursor["producer_seq_base"]
     pending_raw = lines[acked:]
     phase_plan = _workflow_plan(change_dir)
     uploaded = 0
@@ -571,7 +731,7 @@ def sync_change(
             event_id = str(event.get("id") or f"{resolved_key}:{line_number}")
             item: dict[str, Any] = {
                 "event_id": event_id,
-                "producer_seq": line_number,
+                "producer_seq": producer_seq_base + line_number,
                 "event_type": str(event.get("type") or "unknown"),
                 "occurred_at": str(event.get("timestamp") or event.get("ts") or client_time),
                 "payload": _event_payload(event, phase_plan),
@@ -664,7 +824,11 @@ def sync_change(
                 status="local_invalid",
             )
             quarantined += 1
-        save_cursor(change_dir, acked + chunk_start + len(raw_chunk))
+        save_cursor(
+            change_dir,
+            acked + chunk_start + len(raw_chunk),
+            producer_seq_base=producer_seq_base,
+        )
 
     return {
         "ok": True,
@@ -674,6 +838,7 @@ def sync_change(
         "quarantined": quarantined,
         "batch_size": min(MAX_BATCH_SIZE, len(pending_raw)),
         "acked_lines": len(lines),
+        "producer_seq_base": producer_seq_base,
         "server": last_result,
     }
 

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

@@ -1053,6 +1053,40 @@ def ledger_evidence_identity(ledger: dict[str, Any]) -> str:
     return "sha256:" + hashlib.sha256(canonical).hexdigest()
 
 
+def _immutable_change_base(
+    change_dir: Path,
+    project_root: Path,
+) -> str:
+    roots = [change_dir]
+    try:
+        state_root = harness_paths.resolve_state_dir_for_contract(
+            change_dir,
+            project_root,
+        )
+        if state_root.resolve() != change_dir.resolve():
+            roots.insert(0, state_root)
+    except (OSError, ValueError):
+        pass
+    for root in roots:
+        for relative in (
+            Path("meta") / "state-snapshot.json",
+            Path("state-snapshot.json"),
+        ):
+            path = root / relative
+            if not path.is_file():
+                continue
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            except (OSError, json.JSONDecodeError, TypeError):
+                continue
+            if not isinstance(payload, dict):
+                continue
+            value = str(payload.get("changeBase") or "").strip()
+            if value:
+                return value
+    return ""
+
+
 def migrate_ledger_for_write(
     change_dir: Path,
     ledger: dict[str, Any],
@@ -1089,6 +1123,15 @@ def migrate_ledger_for_write(
     if not _nonempty_str(resolved_base):
         resolved_base = ledger.get("baseCommit")
     if not _nonempty_str(resolved_base):
+        resolved_base = _immutable_change_base(change_dir, repo_root)
+    if not _nonempty_str(resolved_base):
+        if record_migration:
+            raise LedgerMigrationError(
+                "immutable change base is missing; recapture the Plan boundary "
+                "or pass an explicit --base-commit instead of using write-time HEAD"
+            )
+        # A genuinely new ledger establishes its identity at the first write.
+        # Existing ledgers are handled above and may never take this fallback.
         resolved_base = current_head
     resolved_diff = diff_hash
     if not _nonempty_str(resolved_diff):
@@ -2795,9 +2838,43 @@ def cmd_diff_hash(args: argparse.Namespace) -> int:
     repo_raw = getattr(args, "repo", None)
     repo = Path(repo_raw).expanduser().resolve() if repo_raw else Path.cwd().resolve()
     base = getattr(args, "base", None)
-    change_dir = getattr(args, "change_dir", None)
+    change_dir_raw = getattr(args, "change_dir", None)
     try:
-        diff_hash, meta = compute_diff_hash(repo, base=base, change_dir=change_dir)
+        change_dir = resolve_path(change_dir_raw) if change_dir_raw else None
+        if change_dir is not None and _contract_is_v2(change_dir):
+            resolved_base = str(base or "").strip()
+            if not resolved_base:
+                existing, _ = load_ledger(change_dir)
+                if isinstance(existing, dict):
+                    resolved_base = str(existing.get("baseCommit") or "").strip()
+            if not resolved_base:
+                resolved_base = _immutable_change_base(change_dir, repo)
+            if not resolved_base:
+                raise ValueError(
+                    "immutable change base is missing; capture the Plan boundary "
+                    "or pass --base"
+                )
+            detail = compute_ownership_diff(
+                repo,
+                base=resolved_base,
+                change_dir=change_dir,
+            )
+            payload = {
+                "ok": True,
+                "action": "diff-hash",
+                "identityScope": "change-ownership",
+                "algorithmVersion": "ownership-content-changeset-1",
+                "base": resolved_base,
+                "head": _git_text(repo, "rev-parse", "--verify", "HEAD"),
+                **detail,
+            }
+            emit_json(payload, as_json=as_json)
+            return 0
+        diff_hash, meta = compute_diff_hash(
+            repo,
+            base=base,
+            change_dir=str(change_dir) if change_dir is not None else None,
+        )
     except (OSError, RuntimeError, ValueError) as exc:
         return emit_error(str(exc), as_json=as_json)
     payload = {"ok": True, "action": "diff-hash", "diffHash": diff_hash}

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

@@ -838,13 +838,20 @@ def _node_commands(project: Path) -> dict[str, Any]:
         "src/**/*.tsx",
         "test/**/*.ts",
         "test/**/*.tsx",
+        "tests/**/*.ts",
+        "tests/**/*.tsx",
         "packages/*/src/**/*.ts",
         "packages/*/src/**/*.tsx",
         "packages/*/test/**/*.ts",
         "packages/*/test/**/*.tsx",
+        "packages/*/tests/**/*.ts",
+        "packages/*/tests/**/*.tsx",
         "apps/*/src/**/*.ts",
         "apps/*/src/**/*.tsx",
         "apps/*/test/**/*.ts",
+        "apps/*/test/**/*.tsx",
+        "apps/*/tests/**/*.ts",
+        "apps/*/tests/**/*.tsx",
     ]
     # harness dogfood: canonical Python + .mjs sources feed npm run check (vitest
     # imports harness-test/scripts; smoke:pack runs sync-harness.mjs).

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

@@ -119,6 +119,10 @@ def capture_snapshot(
         "schemaVersion": SNAPSHOT_SCHEMA_VERSION,
         "generatedAt": now_iso(),
         "changeName": change_name,
+        # The first captured Git boundary is the immutable identity of the
+        # change.  Later phases may advance HEAD, but must never silently move
+        # the base and collapse the archive range.
+        "changeBase": base or "",
         "project": {"root": str(project.resolve())},
         "worktree": {"root": str(Path(worktree_root).resolve())},
         "git": {"base": base or "", "head": head or ""},
@@ -250,10 +254,25 @@ def capture_current_state(
     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)
+    git_head = _git(project, "rev-parse", head)
+    resolved_head = git_head or head
     previous = load_snapshot(change_dir)
+    previous_git = previous.get("git") if isinstance(previous, dict) else None
+    previous_base = (
+        str(previous.get("changeBase") or "").strip()
+        if isinstance(previous, dict)
+        else ""
+    )
+    if not previous_base and isinstance(previous_git, dict):
+        previous_base = str(
+            previous_git.get("base") or previous_git.get("baseCommit") or ""
+        ).strip()
+    requested_base = _git(project, "rev-parse", base) if base else ""
+    # First capture establishes the boundary.  A later --base value is an
+    # observation hint only; changing the boundary requires the explicit
+    # archive range-adoption receipt.
+    resolved_base = previous_base or requested_base or git_head
+    files = discover_segment_files(project, change_dir, base=resolved_base, head=resolved_head)
     fresh = capture_snapshot(
         change_dir,
         change_name=change_name,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "cursor",
-  "coreHash": "4e6d08edd1bed76d"
+  "coreHash": "a18ab1857e283a92"
 }

package/harness/bundles/java/cursor/README.md

@@ -34,7 +34,7 @@
 | `protocols/state-layout-protocol.md` | 状态目录分层：`.harness/changes/<cn>/` 下按 `meta/`、`logs/`、`evidence/`、`reports/`、`scripts/`、`backups/` 子目录分层写入；读取时先读新路径再兼容旧路径 |
 | `protocols/submit-protocol.md` | 固定提交交互：提交方式与 commit message 确认使用固定选项模板，禁止 AI footer |
 | `protocols/archive-report-protocol.md` | 归档报告：`summary-data.json`、manifest/checksum 与真实性规则 |
-| `protocols/report-pipeline-protocol.md` | 报告流水线：`events.ndjson` + `harness_archive.py finalize/replay` + 数据一致性校验 |
+| `protocols/report-pipeline-protocol.md` | 报告流水线：`events.ndjson` + `harness_archive.py execute/replay` + 数据一致性校验 |
 
 每个 skill 的 SKILL.md 关键规则章节都通过相对路径引用这些 protocol（`../protocols/powershell-protocol.md` 等）。
 
@@ -159,9 +159,9 @@
 - **Bash 拒绝、PowerShell 重试、降级、跳过、用户确认都必须记录**
 - 日志状态统一使用 `✅OK / 🟡WARN(原因) / ❌FAIL(原因)`
 - harness-archive 归档时从日志汇总：时间线、总用时、Skill 调用统计
-- `harness_archive.py finalize/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
+- `harness_archive.py execute/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
 - sync 默认不关联具体变更目录，仅在已有变更目录时追加日志和 events
-- archive 是例外：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加阶段边界
+- archive 是例外：`execute` 负责一次准备记录和一次正式 `phase.start` / `phase.end`，调用者不得重复追加阶段边界，也不得串行运行 `auto-gate`、`status`、`finalize`
 
 ## Skill 目录结构
 
@@ -278,7 +278,7 @@ harness-skills/
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
 | **archive 阶段 1** | 归档前确认实际计划阶段的证据与结局；有 Git 时核对最终提交身份，无 Git、无 upstream 或跳过 submit 时使用内容清单身份。发布候选资格与本地封存分开判断；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
-| **archive 最终报告** | 必须运行 `harness_archive.py finalize` 生成权威 `summary-data.json` 并完成 validate。平台直接读取该 JSON；本地不生成重复的 HTML 报告。无测试或无 review 时必须标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。状态演进须真实展示（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
+| **archive 最终报告** | 必须运行 `harness_archive.py execute`，由内部 finalize 生成权威 `summary-data.json` 并完成 validate。平台直接读取该 JSON；本地不生成重复的 HTML 报告。无测试或无 review 时必须标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。状态演进须真实展示（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 
 ### 敏感信息脱敏
 
@@ -424,7 +424,7 @@ npx hunter-harness   # 初始化阶段检查环境/CodeGraph/基础状态（非
 /harness-test         # 运行测试（30条避坑规则）
 /harness-review       # 代码审查
 /harness-submit       # 提交代码（worktree 模式含合并；/harness-merge 为别名）
-/harness-archive      # 归档产出（harness_archive.py finalize），释放工作区
+/harness-archive      # 归档产出（harness_archive.py execute），释放工作区
 ```
 
 ## 避坑知识来源
@@ -454,7 +454,7 @@ npx hunter-harness   # 初始化阶段检查环境/CodeGraph/基础状态（非
 - `protocols/evidence-based-reporting-protocol.md`：证据化报告（✅/🟡/❌ 三态，已取代原 `harness-plan/evidence-based-reporting.md`，各 skill 引用此版本）。
 - `protocols/submit-protocol.md`：固定提交交互、中文 commit 文件、禁止 AI footer。
 - `protocols/archive-report-protocol.md`：summary-data、manifest/checksum 与平台归档展示合同。
-- `protocols/report-pipeline-protocol.md`：events.ndjson + `harness_archive.py finalize/replay` + summary-data 一致性校验。
+- `protocols/report-pipeline-protocol.md`：events.ndjson + `harness_archive.py execute/replay` + summary-data 一致性校验。
 - `protocols/state-layout-protocol.md`：`.harness/changes/<cn>/` 子目录分层（meta/logs/evidence/reports/scripts/backups），读取先新后旧。
 
 各 skill 的 `SKILL.md` 只保留阶段目标和硬门禁，细节优先引用这些协议，避免在多个 skill 中复制并产生冲突。
@@ -475,4 +475,4 @@ backups/    未提交但用于验证的测试文件等备份
 
 读取时先读新路径，再兼容旧路径。详见 `protocols/state-layout-protocol.md`。
 
-Archive 最终报告由 `harness_archive.py finalize` 生成 `summary-data.json`。Hunter Platform 直接读取该文件，避免本地重复渲染和两份报告数据不一致。
+Archive 常规入口为 `harness_archive.py execute`，内部 finalize 生成 `summary-data.json`。Hunter Platform 直接读取该文件，避免本地重复渲染和两份报告数据不一致。

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

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=4e6d08edd1bed76d; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=a18ab1857e283a92; overlay=java; agent=cursor; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -25,7 +25,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/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol