@hunter-harness/workflow-harness 0.2.11 → 0.2.13

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

@@ -266,6 +266,8 @@ def capture_current_state(
         segment_files=files,
     )
     changed: list[str] = []
+    baseline_created = previous is None
+    unresolved: list[str] = []
     if previous:
         old_segments = previous.get("segments") or {}
         for name, segment in fresh["segments"].items():
@@ -275,7 +277,12 @@ def capture_current_state(
             else:
                 changed.append(name)
     else:
-        changed = list(fresh["segments"])
+        # A first observation establishes the baseline; it is not evidence
+        # that every segment changed during the current phase.
+        unresolved = sorted(fresh["segments"])
+    fresh["baselineCreated"] = baseline_created
+    fresh["changedSegments"] = sorted(changed)
+    fresh["unresolvedSegments"] = unresolved
     write_snapshot(change_dir, fresh)
     return fresh, changed
 
@@ -312,7 +319,13 @@ def main(argv: list[str] | None = None) -> int:
         "ok": True,
         "path": str(snapshot_path(change_dir)),
         "changedSegments": changed,
-        "reusedSegments": sorted(set(snapshot["segments"]) - set(changed)),
+        "reusedSegments": sorted(
+            set(snapshot["segments"])
+            - set(changed)
+            - set(snapshot.get("unresolvedSegments") or [])
+        ),
+        "baselineCreated": bool(snapshot.get("baselineCreated")),
+        "unresolvedSegments": list(snapshot.get("unresolvedSegments") or []),
         "git": snapshot["git"],
     }
     if args.json:

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

@@ -564,6 +564,159 @@ def record(
     return _result(True, action, "RECORDED", [rel for _, rel in validated], manifestPath=str(manifest_path))
 
 
+def rehome(
+    from_project: Path | str,
+    to_project: Path | str,
+    change_dir: Path | str,
+    expected_head: str,
+) -> dict[str, Any]:
+    """Atomically hand test ownership from a merged feature worktree to target."""
+    action = "rehome"
+    from_root = Path(from_project).resolve()
+    to_root = Path(to_project).resolve()
+    if not from_root.is_dir() or not to_root.is_dir():
+        return _result(False, action, "PROJECT_ROOT_MISSING", [])
+    if harness_paths.repository_identity(from_root) != harness_paths.repository_identity(to_root):
+        return _result(False, action, "REPOSITORY_MISMATCH", [])
+    to_head_result = _git(to_root, "rev-parse", "--verify", "HEAD")
+    to_head = to_head_result.stdout.strip() if to_head_result.returncode == 0 else ""
+    if not expected_head or to_head != expected_head:
+        return _result(
+            False, action, "EXPECTED_HEAD_MISMATCH", [],
+            expectedHead=expected_head, actualHead=to_head,
+        )
+    from_head_result = _git(from_root, "rev-parse", "--verify", "HEAD")
+    from_head = from_head_result.stdout.strip() if from_head_result.returncode == 0 else ""
+    from_tree_result = _git(from_root, "rev-parse", "HEAD^{tree}")
+    to_tree_result = _git(to_root, "rev-parse", f"{expected_head}^{{tree}}")
+    from_tree = from_tree_result.stdout.strip() if from_tree_result.returncode == 0 else ""
+    to_tree = to_tree_result.stdout.strip() if to_tree_result.returncode == 0 else ""
+    if not from_tree or from_tree != to_tree:
+        return _result(
+            False, action, "TREE_MISMATCH", [],
+            fromHead=from_head, toHead=to_head, fromTree=from_tree, toTree=to_tree,
+        )
+
+    change_root = _change_dir(from_root, change_dir)
+    if change_root is None:
+        return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
+    manifest_path = _manifest_path(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):
+            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))
+            is_v2 = isinstance(manifest, dict) and manifest.get("schemaVersion") == 2
+            entries = manifest.get("files") if isinstance(manifest, dict) else None
+            if not isinstance(entries, list):
+                return _result(False, action, "MANIFEST_INVALID", [])
+            if not is_v2 and (
+                manifest.get("schemaVersion") != SCHEMA_VERSION
+                or manifest.get("mode") != MODE
+                or manifest.get("projectRoot") != str(from_root)
+            ):
+                return _result(False, action, "MANIFEST_PROJECT_MISMATCH", [])
+            if is_v2:
+                error, validated = _validate_existing_manifest_v2(
+                    from_root, manifest, require_files=False
+                )
+                if error:
+                    return _result(False, action, error, [])
+            else:
+                validated: dict[str, dict[str, Any]] = {}
+                for item in entries:
+                    if not _entry_shape_valid(item):
+                        return _result(False, action, "MANIFEST_INVALID", [])
+                    rel = item["path"]
+                    source, normalized, error = _validate_file(from_root, rel)
+                    if error or normalized != rel or source is None:
+                        return _result(False, action, error or "MANIFEST_INVALID", [rel])
+                    if item["sha256"] != _sha256(source):
+                        return _result(False, action, "HASH_DRIFT", [rel])
+                    validated[rel] = dict(item)
+
+            updated = json.loads(json.dumps(manifest))
+            updated_entries: list[dict[str, Any]] = []
+            for rel, item in sorted(validated.items()):
+                target, normalized, error = _validate_file(to_root, rel)
+                if error or normalized != rel or target is None:
+                    return _result(False, action, "TARGET_CONTENT_MISMATCH", [rel])
+                replacement = dict(item)
+                if is_v2:
+                    digest = logical_file_hash(to_root, rel)
+                    source_digest = item.get("logicalHash") or item.get("binaryHash")
+                    if digest != source_digest:
+                        return _result(False, action, "TARGET_CONTENT_MISMATCH", [rel])
+                    replacement["logicalHash"] = digest
+                    replacement["binaryHash"] = (
+                        None if digest.startswith("gitblob:") else digest
+                    )
+                    replacement["ignored"] = _is_ignored(to_root, rel)
+                else:
+                    digest = _sha256(target)
+                    if digest != item["sha256"]:
+                        return _result(False, action, "TARGET_CONTENT_MISMATCH", [rel])
+                    replacement["sha256"] = digest
+                    replacement["ignored"] = _is_ignored(to_root, rel)
+                    replacement["trackedBefore"] = (
+                        _git(to_root, "ls-files", "--error-unmatch", "--", rel).returncode == 0
+                    )
+                updated_entries.append(replacement)
+
+            before_hash = _sha256(manifest_path)
+            handoff_at = time.strftime("%Y-%m-%dT%H:%M:%S")
+            handoff_id = "handoff-" + hashlib.sha256(
+                f"{from_root}\0{to_root}\0{from_head}\0{to_head}".encode("utf-8")
+            ).hexdigest()[:20]
+            handoffs = updated.get("handoffs")
+            if handoffs is None:
+                handoffs = []
+            if not isinstance(handoffs, list):
+                return _result(False, action, "MANIFEST_INVALID", [])
+            handoff = {
+                "id": handoff_id,
+                "fromRoot": str(from_root),
+                "toRoot": str(to_root),
+                "fromHead": from_head,
+                "toHead": to_head,
+                "expectedHead": expected_head,
+                "treeHash": to_tree,
+                "at": handoff_at,
+                "manifestHashBefore": before_hash,
+            }
+            if not any(isinstance(item, dict) and item.get("id") == handoff_id for item in handoffs):
+                handoffs.append(handoff)
+            updated["files"] = updated_entries
+            updated["projectRoot"] = str(to_root)
+            updated["head"] = to_head
+            updated["handoffs"] = handoffs
+            _write_json(manifest_path, updated)
+            after_hash = _sha256(manifest_path)
+    except LockUnavailable:
+        return _result(False, action, "MANIFEST_LOCKED", [])
+    return _result(
+        True,
+        action,
+        "REHOMED",
+        sorted(validated),
+        fromRoot=str(from_root),
+        toRoot=str(to_root),
+        fromHead=from_head,
+        toHead=to_head,
+        treeHash=to_tree,
+        handoffId=handoff_id,
+        manifestHashBefore=before_hash,
+        manifestHashAfter=after_hash,
+        manifestPath=str(manifest_path),
+    )
+
+
 def _stage_locked(
     project_root: Path, change_root: Path, manifest_path: Path, index_path: Path
 ) -> dict[str, Any]:
@@ -709,6 +862,31 @@ def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     if not _manifest_target_inside(change_root, snapshot_path):
         return _result(False, action, "SNAPSHOT_PATH_OUTSIDE_PROJECT", [])
 
+    if snapshot_path.is_file():
+        try:
+            snapshot = _read_json(snapshot_path)
+        except (OSError, json.JSONDecodeError) as exc:
+            return _result(False, action, "SNAPSHOT_INVALID", [], error=str(exc))
+        entries = snapshot.get("files") if isinstance(snapshot, dict) else None
+        if (
+            not isinstance(snapshot, dict)
+            or snapshot.get("schemaVersion") != SCHEMA_VERSION
+            or snapshot.get("mode") != MODE
+            or snapshot.get("projectRoot") != str(project_root)
+            or not isinstance(entries, list)
+            or any(not isinstance(item, dict) or not isinstance(item.get("path"), str)
+                   for item in entries)
+        ):
+            return _result(False, action, "SNAPSHOT_INVALID", [])
+        return _result(
+            True,
+            action,
+            "SNAPSHOT_REUSED",
+            [item["path"] for item in entries],
+            snapshotPath=str(snapshot_path),
+            fileCount=len(entries),
+        )
+
     files = _enumerate_allowed_test_files(project_root)
     snapshot = {
         "schemaVersion": SCHEMA_VERSION,
@@ -867,6 +1045,12 @@ def main(argv: list[str] | None = None) -> int:
     close_parser.add_argument("--project", required=True)
     close_parser.add_argument("--change-dir", required=True)
     close_parser.add_argument("--json", action="store_true")
+    rehome_parser = sub.add_parser("rehome")
+    rehome_parser.add_argument("--from", dest="from_project", required=True)
+    rehome_parser.add_argument("--to", dest="to_project", required=True)
+    rehome_parser.add_argument("--change-dir", required=True)
+    rehome_parser.add_argument("--expected-head", required=True)
+    rehome_parser.add_argument("--json", action="store_true")
     mark_parser = sub.add_parser("mark")
     mark_parser.add_argument("--project", required=True)
     mark_parser.add_argument("--change-dir", required=True)
@@ -883,6 +1067,10 @@ def main(argv: list[str] | None = None) -> int:
     elif args.action == "mark":
         files = [item.strip() for item in args.files.split(",") if item.strip()]
         result = mark(args.project, args.change_dir, files)
+    elif args.action == "rehome":
+        result = rehome(
+            args.from_project, args.to_project, args.change_dir, args.expected_head
+        )
     else:
         result = stage(args.project, args.change_dir)
     print(json.dumps(result, ensure_ascii=False, indent=2 if args.json else None))

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

@@ -19,6 +19,8 @@ TOP_LEVEL_KEYS = frozenset(
         "skills",
         "requiredArtifacts",
         "requiredValidations",
+        "validationPhases",
+        "capabilityGates",
         "conditionalStages",
         "interactionWhitelist",
         "checkpointRules",
@@ -48,6 +50,9 @@ SKILL_KEYS = frozenset(
 )
 
 CONDITIONAL_STAGE_KEYS = frozenset({"tiers", "signals"})
+CAPABILITY_GATE_KEYS = frozenset(
+    {"signals", "requiredStages", "requiredValidations"}
+)
 CHECKPOINT_RULE_KEYS = frozenset(
     {
         "afterTasks",
@@ -121,6 +126,20 @@ def validate_policy(data: Any) -> dict[str, Any]:
         for phase, items in section_data.items():
             _require_type(items, list, f"{section}.{phase}")
 
+    validation_phases = data["validationPhases"]
+    _require_type(validation_phases, dict, "validationPhases")
+    for verification, phase in validation_phases.items():
+        _require_type(phase, str, f"validationPhases.{verification}")
+
+    capability_gates = data["capabilityGates"]
+    _require_type(capability_gates, dict, "capabilityGates")
+    for capability, gate in capability_gates.items():
+        path = f"capabilityGates.{capability}"
+        _require_type(gate, dict, path)
+        _reject_unknown(gate, CAPABILITY_GATE_KEYS, path)
+        for key in CAPABILITY_GATE_KEYS:
+            _require_type(gate[key], list, f"{path}.{key}")
+
     conditional = data["conditionalStages"]
     _require_type(conditional, dict, "conditionalStages")
     for stage_name, stage in conditional.items():

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "4f5b31d96f5a002c"
+  "coreHash": "14a6b9abc6a451bd"
 }

package/harness/bundles/java/codebuddy/contracts/ci-metrics.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hunter-harness.dev/contracts/ci-metrics.schema.json",
+  "title": "Hunter Harness CI Metrics",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runner",
+    "source",
+    "suites",
+    "passed",
+    "failed",
+    "skipped",
+    "setupErrors",
+    "durationMs",
+    "headSha"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runner": { "enum": ["junit", "vitest", "playwright"] },
+    "source": { "type": ["string", "null"] },
+    "suites": { "type": ["integer", "null"], "minimum": 0 },
+    "passed": { "type": ["integer", "null"], "minimum": 0 },
+    "failed": { "type": ["integer", "null"], "minimum": 0 },
+    "skipped": { "type": ["integer", "null"], "minimum": 0 },
+    "setupErrors": { "type": ["integer", "null"], "minimum": 0 },
+    "durationMs": { "type": ["integer", "null"], "minimum": 0 },
+    "headSha": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }
+      ]
+    }
+  }
+}

package/harness/bundles/java/codebuddy/contracts/workflow-policy.json

@@ -138,6 +138,36 @@
     "submit": [],
     "package": ["package"]
   },
+  "validationPhases": {
+    "compile": "run",
+    "unitTest": "run",
+    "unitTestFull": "test",
+    "apiTest": "test",
+    "dbCompatibility": "test",
+    "package": "package"
+  },
+  "capabilityGates": {
+    "deployment": {
+      "signals": ["deploy-required"],
+      "requiredStages": ["package"],
+      "requiredValidations": ["package"]
+    },
+    "container": {
+      "signals": ["install-verification"],
+      "requiredStages": ["package"],
+      "requiredValidations": ["package"]
+    },
+    "api": {
+      "signals": ["api-diff-present"],
+      "requiredStages": ["apidoc"],
+      "requiredValidations": ["apiTest"]
+    },
+    "database": {
+      "signals": ["migration"],
+      "requiredStages": [],
+      "requiredValidations": ["dbCompatibility"]
+    }
+  },
   "conditionalStages": {
     "review": {
       "tiers": ["standard", "full"],

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

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

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

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

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

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

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

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; 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/codebuddy/harness-package/SKILL.md

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

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -58,7 +58,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 | 阶段 | 动作 |
 |------|------|
-| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
+| 0 | 用当前解释器运行 `harness_runtime.py doctor`，后续消费绝对 argv；git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
 | 0.5 | 先初始化 change-name + `phase.start`，从第一条知识查询起保留事件证据 |
 | 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
@@ -66,7 +66,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | 4 | **设计审批包** AskUserQuestion；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 产物完整性必检 → `checklist.md` |
+| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`；原子发布、唯一 `phase.end`、render → `checklist.md` |
 
 change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
 
@@ -82,7 +82,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
 | 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
-| 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
+| 阶段 8 | spec/plan/detail/scenarios/worktree.json 先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，失败不得手工补终态 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
 | 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |

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

@@ -213,6 +213,12 @@ source: harness-plan
 
 > **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
 
+- [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
+- [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id ... --attempt ... --json`
+- [ ] finalizer 返回 `ok=true` 与 `artifactsHash`；重复执行返回 `idempotent=true`
+- [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
+- [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
+
 | 文件 | 必须存在 | 检查结果 |
 |------|:---:|:---:|
 | `.harness/changes/<change>/spec/<change>-design.md` | ✅ | □ |

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

@@ -14,8 +14,11 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 {
   "requested": true,
   "created": false,
-  "path": ".claude/worktrees/<change-name>",
-  "branch": "worktree/<change-name>",
+  "agent": "<active-adapter>",
+  "worktreeRoot": "<adapter-worktree-root>",
+  "branchPrefix": "<adapter-branch-prefix>",
+  "path": "<adapter-worktree-root>/<change-name>",
+  "branch": "<adapter-branch-prefix><change-name>",
   "decisionBy": "user",
   "decisionAt": "YYYY-MM-DD HH:mm",
   "ownerSkill": "harness-run"
@@ -38,6 +41,8 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 
 ### 决策事件 note 示例
 
+`path` 与 `branch` 必须来自 `harness_runtime.py adapter`/`meta/runtime.json`，不得复制其他 agent 的历史路径。Codex 的合同固定为 `.codex/worktrees/<change-name>` 与 `codex/<change-name>`。
+
 `用户选择使用 Worktree；决策文件为 meta/worktree.json；requested=true, created=false；创建责任为 harness-run。`
 
 ## 参考 — 详细格式

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

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

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

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-sync
 description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -39,7 +39,7 @@ python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-
 | 3.5 | `harness_knowledge.py sync`；可 `sync --update`；失败不得假装可用。**知识闭环主入口**是 `/harness-knowledge-ingest auto`（含 Agent judge），sync 不重复列人工知识待办 |
 | 3.6 | 单次运行 `harness_knowledge.py maintain --project . --drain --json`，有界推进全部 `.harness/knowledge/maintenance-outbox/{pending,failed}`；不得为每个条目重复启动 Python/重建索引（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/pending-judge） |
 | 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
-| 5 | AGENTS.md 与 CLAUDE.md 一致 |
+| 5 | AGENTS.md 与各 Agent 指令入口一致；Claude Code 启用时验证 CLAUDE.md 引用 AGENTS.md，禁止反向循环引用 |
 | 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
 | 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
 

package/harness/bundles/java/codebuddy/harness-sync/reference.md

@@ -19,16 +19,17 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 
 ### 2. CodeGraph 索引
 
-检查索引状态，**优先使用 MCP 工具**（若当前环境提供 `mcp__codegraph__codegraph_status` 则调用）；该工具不可用时**降级**为用 Glob 比对 `.codegraph/` 目录修改时间与最近提交时间。不允许通过普通 Bash 调 codegraph 命令：
+检查索引状态，**优先使用 MCP 工具**：若当前环境提供 `mcp__codegraph__codegraph_status` 则调用；没有 status 工具但提供 `codegraph_explore` 时，执行一次只读查询验证索引确实可响应，再用 Glob 比对 `.codegraph/` 目录修改时间与最近提交时间。两种 MCP 工具都不可用时才仅按时间戳降级。不允许通过普通 Bash 调 codegraph 命令：
 
 | 判断条件 | 状态 | 操作 |
 |----------|:----:|------|
 | 覆盖率 > 0% 且索引时间在最近提交之后 | ✅OK | 无需操作 |
+| `codegraph_explore` 查询成功且索引时间在最近提交之后 | ✅OK（功能已验证，覆盖率数值未暴露） | 报告真实证据，不虚构覆盖率百分比 |
 | 覆盖率 = 0% | ❌FAIL(未初始化) | 通过 PowerShell 执行 `npx @colbymchenry/codegraph && codegraph init --index` |
 | 索引时间在最近提交之前 | 🟡WARN(过期) | 同上 |
 
 > 前提：项目构建命令必须已成功。构建失败时先执行 `npx hunter-harness` 初始化检查。
-> 若 MCP 工具与 codegraph CLI 均不可用，标记 🟡WARN(CodeGraph 状态无法验证) 并在报告中说明"CodeGraph 状态无法验证，需用户手动确认"。
+> 若 status/explore MCP 工具均不可用，且时间戳证据也不足，标记 🟡WARN(CodeGraph 状态无法验证) 并在报告中说明具体缺失证据。成功的 explore 只能证明索引可用，不得伪造覆盖率数值。
 
 ### 3. harness-codebase-map 分析文档
 
@@ -61,7 +62,7 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 
 ### 5. AGENTS.md 一致性
 
-检查 `AGENTS.md` 是否引用最新版 CLAUDE.md，是否包含项目概述和规则索引。如果 CLAUDE.md 刚刚更新过，同步更新 AGENTS.md 中的引用描述。
+检查 `AGENTS.md` 是否包含项目概述和规则索引。Claude Code adapter 启用时，检查 `CLAUDE.md` 引用 `AGENTS.md`（canonical managed block 使用 `@AGENTS.md`），让共享约束保持单一来源；不得要求 `AGENTS.md` 反向引用 `CLAUDE.md`，否则会形成循环，且会破坏未启用 Claude Code 的项目。
 
 ### 6. .harness/ 完整性
 
@@ -133,7 +134,7 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 | CodeGraph | 🟡WARN(索引过期) | 索引已过期（上次: 3天前，最近提交: 今天），已重新索引 |
 | harness-codebase-map (.harness/codebase/map/) | ✅OK | 2 天前更新，变更量 5 个文件，无需更新 |
 | CLAUDE.md | ✅OK | 180 行，6 个必要章节完整 |
-| AGENTS.md | ✅OK | 已正确引用 CLAUDE.md |
+| AGENTS.md | ✅OK | 共享规则索引完整；CLAUDE.md 已单向引用 AGENTS.md |
 | .harness/ | ✅OK | config 目录存在，1 个变更目录（contribution-module） |
 
 ### 自动更新

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

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=4f5b31d96f5a002c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=14a6b9abc6a451bd; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose