@hunter-harness/workflow-harness 0.2.19 → 0.2.21

package/harness/bundles/general/cursor/scripts/harness_migration_head.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Migration head single-source consistency check (Wave-2 H-7).
+
+Canonical file (default ``.harness/config/migration-head.json``)::
+
+    {
+      "schemaVersion": 1,
+      "head": "005_example",
+      "sources": [
+        {"path": "backend/app/config.py", "pattern": "EXPECTED_ALEMBIC_HEAD\\s*=\\s*[\\\"']([^\\\"']+)[\\\"']"},
+        {"path": "integration/manifest.json", "jsonPointer": "/migrationHead"}
+      ]
+    }
+
+Each source must resolve to the same ``head`` value. This harness repo may not
+ship alembic; consumer projects declare the canonical file and run::
+
+    python harness_migration_head.py check --project . --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REL = ".harness/config/migration-head.json"
+
+
+def emit_json(payload: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    else:
+        code = payload.get("code") or ("OK" if payload.get("ok") else "FAIL")
+        sys.stdout.write(f"{code}\n")
+
+
+def emit_error(code: str, message: str, *, as_json: bool, extra: dict[str, Any] | None = None) -> int:
+    payload: dict[str, Any] = {"ok": False, "code": code, "message": message}
+    if extra:
+        payload.update(extra)
+    stream = sys.stdout if as_json else sys.stderr
+    if as_json:
+        stream.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    else:
+        stream.write(f"{code}: {message}\n")
+    return 1
+
+
+def _read_json_pointer(data: Any, pointer: str) -> Any:
+    if not pointer.startswith("/"):
+        raise ValueError(f"jsonPointer must start with /: {pointer}")
+    cur = data
+    for part in pointer.lstrip("/").split("/"):
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            raise KeyError(pointer)
+    return cur
+
+
+def _extract_source(project: Path, source: dict[str, Any]) -> str:
+    rel = str(source.get("path") or "").strip().replace("\\", "/")
+    if not rel or rel.startswith("/") or ".." in rel.split("/"):
+        raise ValueError(f"invalid source path: {rel}")
+    target = (project / rel).resolve()
+    try:
+        target.relative_to(project.resolve())
+    except ValueError as exc:
+        raise ValueError(f"source escapes project: {rel}") from exc
+    if not target.is_file():
+        raise FileNotFoundError(rel)
+    text = target.read_text(encoding="utf-8-sig")
+    if "jsonPointer" in source and source["jsonPointer"]:
+        data = json.loads(text)
+        value = _read_json_pointer(data, str(source["jsonPointer"]))
+        if value is None or (isinstance(value, str) and not value.strip()):
+            raise ValueError(f"empty value at {source['jsonPointer']} in {rel}")
+        return str(value).strip()
+    pattern = str(source.get("pattern") or "").strip()
+    if not pattern:
+        raise ValueError(f"source {rel} requires pattern or jsonPointer")
+    match = re.search(pattern, text, flags=re.MULTILINE)
+    if not match:
+        raise ValueError(f"pattern did not match in {rel}")
+    return str(match.group(1) if match.lastindex else match.group(0)).strip()
+
+
+def check_migration_head(
+    project: Path,
+    *,
+    config_rel: str = DEFAULT_REL,
+) -> dict[str, Any]:
+    project = project.resolve()
+    config_path = (project / config_rel).resolve()
+    try:
+        config_path.relative_to(project)
+    except ValueError:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_CONFIG_ESCAPE",
+            "message": f"config path escapes project: {config_rel}",
+        }
+    if not config_path.is_file():
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_MISSING",
+            "message": f"canonical migration-head file missing: {config_rel}",
+            "configPath": str(config_path),
+        }
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_UNREADABLE",
+            "message": str(exc),
+            "configPath": str(config_path),
+        }
+    if not isinstance(data, dict) or data.get("schemaVersion") != 1:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_SCHEMA_INVALID",
+            "message": "migration-head.json must be schemaVersion 1 object",
+            "configPath": str(config_path),
+        }
+    head = str(data.get("head") or "").strip()
+    sources = data.get("sources")
+    if not head:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_EMPTY",
+            "message": "head must be a non-empty string",
+            "configPath": str(config_path),
+        }
+    if not isinstance(sources, list) or not sources:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_SOURCES_EMPTY",
+            "message": "sources must be a non-empty array",
+            "configPath": str(config_path),
+        }
+
+    observed: list[dict[str, Any]] = []
+    drifts: list[dict[str, Any]] = []
+    for index, source in enumerate(sources):
+        if not isinstance(source, dict):
+            return {
+                "ok": False,
+                "code": "MIGRATION_HEAD_SOURCE_INVALID",
+                "message": f"sources[{index}] must be an object",
+            }
+        try:
+            value = _extract_source(project, source)
+        except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
+            return {
+                "ok": False,
+                "code": "MIGRATION_HEAD_SOURCE_UNREADABLE",
+                "message": str(exc),
+                "index": index,
+                "path": source.get("path"),
+            }
+        item = {"path": source.get("path"), "value": value}
+        observed.append(item)
+        if value != head:
+            drifts.append({**item, "expected": head})
+
+    if drifts:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_DRIFT",
+            "message": "one or more sources disagree with canonical head",
+            "head": head,
+            "drifts": drifts,
+            "observed": observed,
+            "configPath": str(config_path),
+        }
+    return {
+        "ok": True,
+        "code": "MIGRATION_HEAD_OK",
+        "head": head,
+        "observed": observed,
+        "configPath": str(config_path),
+        "sourceCount": len(observed),
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness_migration_head.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="verify sources match canonical head")
+    check.add_argument("--project", required=True)
+    check.add_argument("--config", default=DEFAULT_REL)
+    check.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    as_json = bool(getattr(args, "json", False))
+    if args.command == "check":
+        result = check_migration_head(Path(args.project), config_rel=str(args.config))
+        if not result.get("ok"):
+            return emit_error(
+                str(result.get("code") or "MIGRATION_HEAD_FAIL"),
+                str(result.get("message") or "check failed"),
+                as_json=as_json,
+                extra={k: v for k, v in result.items() if k not in {"ok", "code", "message"}},
+            )
+        emit_json(result, as_json=as_json)
+        return 0
+    return emit_error("UNKNOWN_COMMAND", f"unknown command: {args.command}", as_json=as_json)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/java/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "f01595d3142d34b7"
+  "coreHash": "a9c096220b88ca56"
 }

package/harness/bundles/java/claude-code/CONTEXT.md

@@ -48,6 +48,26 @@ _Avoid_: 每次重新探测, skill 内硬编码项目参数
 一项验证（compile/install/unitTest/apiTest）所依赖源文件集合的内容哈希。指纹一致且证据完整才允许 🔁REUSED；无法证明即保守重跑。
 _Avoid_: 仅凭 diffHash 复用, 无证据跳过
 
+**验证图（verification graph）**:
+`evidence/verification-graph.json` 按 canonical identity 持久化验证节点；`can-reuse` 返回 `invalidationCode`（如 `INPUT_CHANGED`）；profile `mergeVerification.requiredOnMerge` 进入 integration verify。详见 ledger / integration 脚本。
+_Avoid_: 冻结后无因重跑全量
+
+**Migration head 单源**:
+消费项目用 `.harness/config/migration-head.json` 声明 canonical head 与联动 sources；`harness_migration_head.py check` 做静态一致性门禁。
+_Avoid_: config/CI/manifest 多处手写 head
+
+**事件批处理**:
+同阶段多事件用 `harness_events.py batch-append`（单锁多行）；`phase.end` 仍走单次 append。
+_Avoid_: 机械事件逐条起进程
+
+**能力级模型路由**:
+任务用 `economy` / `balanced` / `frontier` 表述；禁止在通用 harness 规则硬编码供应商模型名。详见 `protocols/model-routing-protocol.md`。
+_Avoid_: skill 内写死 claude-/gpt- 模型 id
+
+**Overlay 所有权**:
+Bundle 安装目标由安装器管理；项目自有配置放 `.harness/project-overlay/`（或 project.yaml 侧）。`--force-managed` 必须配合 `--yes`/`--confirmed`，冲突 fail closed。
+_Avoid_: 静默 force-managed
+
 **服务会话**:
 `runtime/service-session.json` 记录的 AI 启动服务生命周期。指纹匹配静默复用、不匹配自动重启、归档收尾统一停止；只有用户自启服务占端口才询问。
 _Avoid_: 每轮测试后必杀服务

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-archive/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-knowledge-ingest/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/java/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-plan/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-review/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-submit/checklist.md

@@ -369,6 +369,8 @@ powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
 
 ### 步骤 M5：push
 
+**硬门槛（eslint × feature worktree）**：integration / 主仓 `pre-push` 跑 `npm run check` 时，eslint 不得把 sibling `.worktrees/<change>/` 当成第二工程根（双 `tsconfigRootDir`）。本仓以 `eslint.config.mjs` 的 `.worktrees/**` ignore 为准；若自定义 eslint 未 ignore，须先 `move_agent_to_root(<projectRoot>)` 再清 feature worktree，再 push。
+
 ```powershell
 python harness/scripts/harness_integration.py push --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
@@ -418,3 +420,9 @@ ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_ga
 - worktree: 已清理（迁根后）
 - 下一步: `/harness-archive`
 ```
+
+
+## Wave-2 — 验证复用与 merge 面（H-9）
+
+- [ ] 代码冻结后，同 identity 的 unitTestFull 须 can-reuse；禁止无 invalidationCode 整套重跑
+- [ ] integration verify 会合并 profile mergeVerification.requiredOnMerge（若配置）

package/harness/bundles/java/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f01595d3142d34b7; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=a9c096220b88ca56; overlay=java; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/java/claude-code/protocols/model-routing-protocol.md

@@ -0,0 +1,22 @@
+# model-routing-protocol — 能力级模型路由（Wave-2 H-16）
+
+> 本协议定义 **economy / balanced / frontier** 三档能力级。通用 Harness 规则与 skill **禁止**硬编码供应商模型名（如 `claude-*`、`gpt-*`、`gemini-*`）。宿主把能力级映射到具体模型；映射表属于项目/宿主配置，不属于本协议正文。
+
+## 能力级
+
+| 级别 | 适用任务 | 示例 |
+|------|----------|------|
+| `economy` | 机械提取、日志压缩、等待监控、格式化摘要 | 解析测试输出行、压缩长日志、轮询服务就绪 |
+| `balanced` | 常规实现、常规修复、常规文档修订 | 按 plan 实现 CRUD、修 YELLOW、补 checklist |
+| `frontier` | 架构取舍、安全/并发/迁移、最终审查、高风险判断 | 设计审批、RED 安全项、schema 迁移方案、merge 前终审 |
+
+## 路由规则
+
+1. Skill/任务描述用能力级（`--capability economy|balanced|frontier` 或文案「本任务=frontier」），不写供应商模型 id。  
+2. 宿主或 `HUNTER_HARNESS_MODEL` 仅作**遥测**（`executor_model`），不得反过来驱动通用规则分支。  
+3. **降级**（frontier→balanced→economy）必须由确定性命令结果或更高能力审查验收；不得用更低能力级的模型输出替代测试/门禁证据。  
+4. 无法映射某能力级时：fail closed，列出可用级别，禁止静默落到未知模型。
+
+## 与验证的关系
+
+能力级不改变 ledger / can-reuse / verification graph 合同。模型便宜不能成为跳过 `unitTestFull` 或忽略 `requiredOnMerge` 的理由。

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

@@ -24,7 +24,7 @@ import tempfile
 import time
 import uuid
 from pathlib import Path
-from typing import Any
+from typing import Any, Sequence
 
 SCRIPTS_DIR = Path(__file__).resolve().parent
 if str(SCRIPTS_DIR) not in sys.path:
@@ -595,6 +595,132 @@ def append_event(
     return {"ok": True, "event": event, "events_path": str(events_path_obj), "rendered": False}
 
 
+def batch_append_events(
+    change_dir: Path,
+    events: Sequence[dict[str, Any]],
+) -> dict[str, Any]:
+    """Validate then append many events under one lock (Wave-2 H-15).
+
+    Any invalid item aborts the whole batch before mutation. ``phase.end`` items
+    are rejected here — use single ``append`` so render semantics stay explicit.
+    """
+    if not isinstance(events, (list, tuple)) or not events:
+        return {
+            "ok": False,
+            "code": "BATCH_EMPTY",
+            "message": "batch-append requires a non-empty events array",
+        }
+    archived = archived_change_dir(change_dir)
+    if archived is not None:
+        return {
+            "ok": False,
+            "code": "ARCHIVED_CHANGE_IMMUTABLE",
+            "message": str(archived),
+        }
+
+    built: list[dict[str, Any]] = []
+    for index, raw in enumerate(events):
+        if not isinstance(raw, dict):
+            return {
+                "ok": False,
+                "code": "BATCH_ITEM_INVALID",
+                "message": f"events[{index}] must be an object",
+                "index": index,
+            }
+        type_ = str(raw.get("type") or "").strip()
+        phase = str(raw.get("phase") or "").strip()
+        if not type_ or type_ not in EVENT_TYPES:
+            return {
+                "ok": False,
+                "code": "EVENT_TYPE_INVALID",
+                "message": f"events[{index}]: unsupported type: {type_}",
+                "index": index,
+            }
+        if not phase:
+            return {
+                "ok": False,
+                "code": "EVENT_REQUIRED_FIELD",
+                "message": f"events[{index}]: phase required",
+                "index": index,
+            }
+        if type_ == "phase.end":
+            return {
+                "ok": False,
+                "code": "BATCH_PHASE_END_FORBIDDEN",
+                "message": f"events[{index}]: phase.end must use single append",
+                "index": index,
+            }
+        args = argparse.Namespace(
+            change_dir=str(change_dir),
+            phase=phase,
+            type=type_,
+            note=raw.get("note"),
+            kind=raw.get("kind"),
+            path=raw.get("path"),
+            run_id=raw.get("run_id"),
+            executor_tool=raw.get("executor_tool"),
+            command=raw.get("command"),
+            exit_code=raw.get("exit_code"),
+            duration_ms=raw.get("duration_ms"),
+            status=raw.get("status"),
+            name=raw.get("name"),
+            code=raw.get("code"),
+            severity=raw.get("severity"),
+            message=raw.get("message"),
+            decision=raw.get("decision"),
+            reason=raw.get("reason"),
+            issue_id=raw.get("issue_id"),
+            scope=raw.get("scope"),
+            target_event_id=raw.get("target_event_id"),
+            target_field=raw.get("target_field"),
+            old_value_hash=raw.get("old_value_hash"),
+            new_value_json=raw.get("new_value_json"),
+            renamed_from=raw.get("renamed_from"),
+            renamed_to=raw.get("renamed_to"),
+            change_uuid=raw.get("change_uuid"),
+            attempt=raw.get("attempt"),
+            executor_agent=raw.get("executor_agent"),
+            executor_model=raw.get("executor_model"),
+            handoff_from_tool=raw.get("handoff_from_tool"),
+            handoff_reason=raw.get("handoff_reason"),
+            trace_id=raw.get("trace_id"),
+            span_id=raw.get("span_id"),
+            parent_span_id=raw.get("parent_span_id"),
+            runner_ms=raw.get("runner_ms"),
+            orchestration_active_ms=raw.get("orchestration_active_ms"),
+            wall_clock_ms=raw.get("wall_clock_ms"),
+            user_wait_ms=raw.get("user_wait_ms"),
+            legacy_lenient=False,
+            json=True,
+        )
+        validation = validate_append_event(args)
+        if validation:
+            error_code, message = validation
+            return {
+                "ok": False,
+                "code": error_code,
+                "message": f"events[{index}]: {message}",
+                "index": index,
+            }
+        built.append(build_event(args, []))
+
+    events_path_obj = events_path(change_dir)
+    lock_path = events_path_obj.with_name(events_path_obj.name + ".lock")
+    with event_file_lock(lock_path):
+        for event in built:
+            atomic_append_line(
+                events_path_obj, json.dumps(event, ensure_ascii=False, separators=(",", ":"))
+            )
+    return {
+        "ok": True,
+        "action": "batch-append",
+        "count": len(built),
+        "events": built,
+        "events_path": str(events_path_obj),
+        "rendered": False,
+    }
+
+
 def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dict[str, Any]:
     event: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
@@ -1295,6 +1421,25 @@ def cmd_append(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_batch_append(args: argparse.Namespace) -> int:
+    as_json = bool(args.json)
+    change_dir = resolve_change_dir(args.change_dir)
+    batch_path = Path(str(args.file)).expanduser()
+    try:
+        raw = json.loads(batch_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return emit_error(f"batch-append failed to read --file: {exc}", as_json=as_json)
+    result = batch_append_events(change_dir, raw if isinstance(raw, list) else [])
+    if not result.get("ok"):
+        return emit_error(
+            str(result.get("message") or "batch-append failed"),
+            as_json=as_json,
+            error_code=str(result.get("code") or "BATCH_APPEND_FAILED"),
+        )
+    emit_json(result, as_json=as_json)
+    return 0
+
+
 def cmd_render(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     change_dir = resolve_change_dir(args.change_dir)
@@ -1395,6 +1540,19 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_append.set_defaults(func=cmd_append)
 
+    p_batch = sub.add_parser(
+        "batch-append",
+        parents=[common],
+        help="validate and append many events under one lock (H-15)",
+    )
+    p_batch.add_argument("--change-dir", required=True)
+    p_batch.add_argument(
+        "--file",
+        required=True,
+        help="JSON file containing a non-empty array of event objects",
+    )
+    p_batch.set_defaults(func=cmd_batch_append)
+
     p_render = sub.add_parser(
         "render",
         parents=[common],

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

@@ -862,8 +862,42 @@ class IntegrationTransaction:
 
         return self._run_step("merge", action)
 
+    def _required_on_merge_commands(self) -> list[list[str]]:
+        """Load build-profile mergeVerification.requiredOnMerge (Wave-2 H-9)."""
+        import harness_profile
+
+        profile = harness_profile.load_profile(self.project_root)
+        if not isinstance(profile, dict):
+            return []
+        merge = profile.get("mergeVerification")
+        if not isinstance(merge, dict):
+            return []
+        required = merge.get("requiredOnMerge")
+        if not isinstance(required, list):
+            return []
+        commands: list[list[str]] = []
+        for index, item in enumerate(required):
+            if isinstance(item, str) and item.strip():
+                commands.append(shlex.split(item.strip()))
+                continue
+            if not isinstance(item, dict):
+                raise ValueError(f"requiredOnMerge[{index}] must be string or object")
+            raw = item.get("command")
+            if isinstance(raw, list) and raw and all(isinstance(x, str) and x for x in raw):
+                commands.append([str(x) for x in raw])
+            elif isinstance(raw, str) and raw.strip():
+                commands.append(shlex.split(raw.strip()))
+            else:
+                raise ValueError(f"requiredOnMerge[{index}].command missing")
+        return commands
+
     def verify(self, commands: Sequence[Sequence[str]] | None = None) -> dict[str, Any]:
         commands = list(commands or [])
+        # Wave-2 H-9: append profile mergeVerification.requiredOnMerge commands.
+        try:
+            commands.extend(self._required_on_merge_commands())
+        except Exception as exc:  # noqa: BLE001 — surface as verify plan error
+            raise VerifyPlanMissingError(f"mergeVerification load failed: {exc}") from exc
 
         def action(journal: dict[str, Any]) -> None:
             if not commands or any(