@hunter-harness/workflow-harness 0.2.10 → 0.2.12

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "43088896a4556b69"
+  "coreHash": "8dd8ce9aa1ac47f5"
 }

package/harness/bundles/general/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/general/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/general/codebuddy/harness-archive/SKILL.md

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

package/harness/bundles/general/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=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/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=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/general/codebuddy/harness-knowledge-ingest/scripts/harness_knowledge.py

@@ -1823,6 +1823,19 @@ def compute_inputs_hash(
     versions + preserved entries (active / manually demoted), so promote/demote
     correctly invalidate the no-op fast path.
     """
+    return compute_inputs_hash_from_preserved(
+        records,
+        config,
+        load_preserved_entries(knowledge),
+    )
+
+
+def compute_inputs_hash_from_preserved(
+    records: list[dict[str, Any]],
+    config: dict[str, Any],
+    preserved_entries: list[dict[str, Any]],
+) -> str:
+    """Hash knowledge inputs using an already-resolved preserved closure."""
     archive_fingerprint = json.dumps(
         sorted(
             (
@@ -1843,7 +1856,6 @@ def compute_inputs_hash(
         },
         sort_keys=True,
     )
-    preserved = load_preserved_entries(knowledge)
     preserved_fingerprint = json.dumps(
         sorted(
             (
@@ -1852,7 +1864,7 @@ def compute_inputs_hash(
                     "status": e.get("status"),
                     "lifecycle": e.get("lifecycle", {}),
                 }
-                for e in preserved
+                for e in preserved_entries
             ),
             key=lambda item: item["id"] or "",
         ),
@@ -2120,6 +2132,16 @@ def build_index(
     ingest_mode["confidenceScored"] = len(indexed_entries)
     ingest_mode["entriesPruned"] = prune_generated_entries(knowledge, indexed_entries)
 
+    # Lifecycle policies above may relocate or mutate preserved entries. The
+    # pre-build hash remains useful for the no-op gate, but the persisted index
+    # must describe the final preserved closure or an immediate sync will mark
+    # the freshly rebuilt index stale.
+    ingest_mode["inputsHash"] = compute_inputs_hash_from_preserved(
+        archive_records,
+        config,
+        load_preserved_entries(knowledge),
+    )
+
     sqlite_stats = write_sqlite(knowledge / "index.sqlite", indexed_entries)
     ingest_mode.update(sqlite_stats)
     index = make_manifest(

package/harness/bundles/general/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=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; 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/general/codebuddy/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; 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/general/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/general/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/general/codebuddy/harness-review/SKILL.md

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

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

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

package/harness/bundles/general/codebuddy/harness-run/checklist.md

@@ -10,13 +10,14 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 
 ### 步骤 0.0：Worktree 决策执行 ⚠️
 
+- [ ] 运行 `harness_runtime.py doctor` 并读取 `meta/runtime.json`；后续使用绝对 executable 与 argv 数组
 - [ ] 读取 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）
 - [ ] 如果文件缺失：🟡WARN，按 legacy 逻辑询问用户是否主目录执行或创建 worktree
 - [ ] `requested=false` → 主目录执行，记录原因
 - [ ] `requested=true` 且 worktree 存在 → 切换到 worktree 执行
 - [ ] `requested=true` 且 worktree 不存在 → 必须创建 worktree
 - [ ] worktree 创建命令必须使用 PowerShell：`git worktree add ...`
-- [ ] 创建后验证 `.claude/worktrees/<change-name>/.git` 存在
+- [ ] 创建后验证 `<adapter-worktree-root>/<change-name>/.git` 存在；Codex 必须是 `.codex/worktrees/<change-name>`
 - [ ] 创建成功后更新 `meta/worktree.json` 的 `created=true/createdAt/createdBy`
 - [ ] 创建失败 → 停止，或 AskUserQuestion 询问是否改为主目录执行
 - [ ] 禁止 `requested=true && worktree 不存在` 时直接主目录执行
@@ -219,7 +220,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 
 > 仅在 worktree 中执行时触发此步骤。在主目录执行时跳过（标记 ⏭️主目录跳过）。
 
-- [ ] 确认当前 cwd 在 `.claude/worktrees/<change-name>/` 下
+- [ ] 确认当前 cwd 在 `<adapter-worktree-root>/<change-name>/` 下，且 branch 使用 adapter 的 prefix
 - [ ] 生成变更摘要：`git diff --stat` + `git diff --stat --cached`
 - [ ] 构建 commit message：`wip(<scope>): <change-name> 编码完成 — N任务/M文件变更`
 - [ ] **⚠️ 强制阻断**：用 AskUserQuestion 展示变更列表 + commit message，等待用户确认

package/harness/bundles/general/codebuddy/harness-run/reference.md

@@ -49,20 +49,22 @@ requested=true + path missing
 
 ### PowerShell 命令模板
 
+先执行 runtime doctor，并从 `meta/runtime.json` 读取 adapter 的 `path`、`branch` 以及 PowerShell `argvPrefix`；不要依赖裸 `python`/`powershell.exe`，也不要硬编码 Claude 路径。
+
 ```powershell
-powershell.exe -NoProfile -Command "git worktree add '.claude/worktrees/<change-name>' -b 'worktree/<change-name>'"
+& <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' -b '<adapter-branch>'"
 ```
 
 如果分支已存在：
 
 ```powershell
-powershell.exe -NoProfile -Command "git worktree add '.claude/worktrees/<change-name>' 'worktree/<change-name>'"
+& <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' '<adapter-branch>'"
 ```
 
 验证：
 
 ```powershell
-powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.git'"
+& <powershell-argv-prefix> -Command "Test-Path -LiteralPath '<adapter-worktree-path>/.git'"
 ```
 
 ### 状态目录写入
@@ -72,7 +74,7 @@ powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.
 ```json
 {
   "projectRoot": ".../udp",
-  "worktreeRoot": ".../udp/.claude/worktrees/<change-name>",
+  "worktreeRoot": ".../udp/<adapter-worktree-root>/<change-name>",
   "stateDir": ".../udp/.harness/changes/<change-name>"
 }
 ```

package/harness/bundles/general/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=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/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=43088896a4556b69; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose