@hunter-harness/workflow-harness 0.2.15 → 0.2.17

package/harness/bundles/general/claude-code/scripts/harness_test_cleanup.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Controlled cleanup helper for test fixtures (retro §5.23).
+
+Provides a host-policy-friendly entry point for removing gitignored test
+fixtures (e.g. .pytest_data) within an execution root. Performs realpath
+containment, rejects symlink/reparse escapes, lists exact counts before
+deletion, and outputs a structured receipt.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+def _resolve_within(execution_root: Path, rel: str) -> Path | None:
+    """Resolve rel under execution_root, rejecting escapes and symlinks."""
+    if not rel or rel.startswith("/"):
+        return None
+    # Reject absolute paths (Windows drive letter or POSIX).
+    if len(rel) >= 2 and rel[1] == ":":
+        return None
+    parts = rel.replace("\\", "/").split("/")
+    if ".." in parts:
+        return None
+    candidate = (execution_root / rel).resolve(strict=False)
+    # Containment check: candidate must be under execution_root.
+    try:
+        candidate.relative_to(execution_root.resolve(strict=False))
+    except ValueError:
+        return None
+    # Reject symlink/reparse escape: if the path is a symlink, check its target.
+    if candidate.is_symlink():
+        target = Path(os.readlink(candidate)).resolve(strict=False)
+        try:
+            target.relative_to(execution_root.resolve(strict=False))
+        except ValueError:
+            return None
+        # Even if target is inside, a symlinked cleanup root is suspicious;
+        # reject to avoid following links into unexpected locations.
+        return None
+    return candidate
+
+
+def _count_files(root: Path) -> tuple[int, int]:
+    """Count files and total bytes under root."""
+    count = 0
+    total = 0
+    for dirpath, _dirs, files in os.walk(root):
+        for name in files:
+            fp = Path(dirpath) / name
+            try:
+                total += fp.stat().st_size
+                count += 1
+            except OSError:
+                continue
+    return count, total
+
+
+def cleanup(execution_root: Path, cleanup_roots: list[str]) -> dict[str, Any]:
+    """Remove allowlisted cleanup roots within execution_root.
+
+    Returns a structured receipt. Any path escape, symlink escape, or
+    unallowed root results in ok=false with zero files removed.
+    """
+    execution_root = Path(execution_root).resolve(strict=False)
+    if not execution_root.is_dir():
+        return {
+            "ok": False,
+            "code": "EXECUTION_ROOT_MISSING",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+        }
+
+    rejected: list[dict[str, str]] = []
+    removed_files = 0
+    removed_bytes = 0
+    cleaned: list[str] = []
+
+    for rel in cleanup_roots:
+        target = _resolve_within(execution_root, rel)
+        if target is None:
+            rejected.append({"path": rel, "reason": "PATH_ESCAPE_REJECTED"})
+            continue
+        if not target.exists():
+            # Already absent — idempotent reentry.
+            continue
+        # Re-check symlink after resolution (the parent might be a symlink).
+        if target.is_symlink():
+            rejected.append({"path": rel, "reason": "SYMLINK_ESCAPE_REJECTED"})
+            continue
+        # Count before deletion for the receipt.
+        try:
+            count, total = _count_files(target)
+        except OSError:
+            count, total = 0, 0
+        # Delete.
+        try:
+            shutil.rmtree(target)
+        except OSError as exc:
+            rejected.append({"path": rel, "reason": f"DELETE_FAILED: {exc}"})
+            continue
+        removed_files += count
+        removed_bytes += total
+        cleaned.append(rel)
+
+    if rejected:
+        return {
+            "ok": False,
+            "code": rejected[0]["reason"],
+            "executionRoot": str(execution_root),
+            "removedFiles": removed_files,
+            "removedBytes": removed_bytes,
+            "rejectedEscapes": rejected,
+            "cleaned": cleaned,
+        }
+
+    if removed_files == 0 and not cleaned:
+        return {
+            "ok": True,
+            "code": "ALREADY_ABSENT",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+            "cleaned": [],
+        }
+
+    return {
+        "ok": True,
+        "code": "CLEANUP_COMPLETE",
+        "executionRoot": str(execution_root),
+        "removedFiles": removed_files,
+        "removedBytes": removed_bytes,
+        "rejectedEscapes": [],
+        "cleaned": cleaned,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    clean_parser = sub.add_parser("cleanup")
+    clean_parser.add_argument("--execution-root", required=True)
+    clean_parser.add_argument("--cleanup-roots", required=True, help="JSON array of relative paths")
+    clean_parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    try:
+        roots = json.loads(args.cleanup_roots)
+        if not isinstance(roots, list):
+            raise ValueError("cleanup-roots must be a JSON array")
+    except (json.JSONDecodeError, ValueError) as exc:
+        result = {"ok": False, "code": "INVALID_CLEANUP_ROOTS", "error": str(exc)}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 1
+
+    result = cleanup(Path(args.execution_root), roots)
+    print(json.dumps(result, ensure_ascii=False, indent=2 if args.json else None))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "6232f66fbf691292"
+  "coreHash": "d5b51ad56d4d4535"
 }

package/harness/bundles/general/codebuddy/CONTEXT.md

@@ -53,9 +53,22 @@ _Avoid_: 仅凭 diffHash 复用, 无证据跳过
 _Avoid_: 每轮测试后必杀服务
 
 **交互白名单**:
-每个 skill 显式声明的允许 AskUserQuestion 场景清单。白名单外一律取默认值并记 decision 事件。
+每个 skill 显式声明的允许 `blocking user confirmation` 场景清单。白名单外一律取默认值并记 decision 事件。
 _Avoid_: 逐决策点询问
 
+**阻断式用户确认（blocking user confirmation）**:
+宿主无关的审批原语。canonical skill 使用此术语表达"展示完整审批包并等待明确答复"的语义，不绑定具体宿主工具。adapter 按下表映射到宿主具体工具：
+
+| Adapter | 工具 |
+|---------|------|
+| claude-code | AskUserQuestion |
+| codebuddy | AskUserQuestion |
+| codex | request_user_input 或普通对话 |
+| cursor | 普通对话 |
+
+finalizer 只校验 approval receipt/decision 的顺序和内容，不校验交互工具品牌。
+_Avoid_: 硬编码宿主工具名, 跨宿主不可移植
+
 **部署合成**:
 `harness_deploy.py build` 把通用核心 + shared 片段 + overlay 合成为自包含 SKILL.md 后部署。Vault 源头 DRY，运行时单文件。
 _Avoid_: 运行时跨文件拼规则, fork 维护

package/harness/bundles/general/codebuddy/README.md

@@ -59,7 +59,7 @@
 | harness-knowledge-query | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
 | harness-knowledge-ingest | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
 
-> **AskUserQuestion 不预批准**：各 skill 需要向用户确认时通过普通权限提示调用 `AskUserQuestion`，不在 `allowed-tools` 中预批准（遵循 skill-optimizer 规则）。`harness-codebase-map` 额外预批准 `Agent` 用于派发并行 mapper。
+> **blocking user confirmation 不预批准**：各 skill 需要向用户确认时通过普通权限提示调用 `blocking user confirmation`（adapter 映射到 `AskUserQuestion`/`request_user_input`/普通对话），不在 `allowed-tools` 中预批准（遵循 skill-optimizer 规则）。`harness-codebase-map` 额外预批准 `Agent` 用于派发并行 mapper。
 
 > **codegraph 命令**：原 `Bash(codegraph *)` 改为 MCP 工具调用（`mcp__codegraph__codegraph_explore` 等），不再通过 Bash。
 >

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -52,6 +52,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol
 
 ## Workflow
 
@@ -79,7 +80,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ### Phase 2：确认归档 ⚠️ 强制阻断
 
-AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
+blocking user confirmation 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
 
 - **Read `reference.md`** — 确认对话框的内容格式
 
@@ -104,6 +105,7 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust
 
 ## 关键规则（硬门禁速查）
 
@@ -115,7 +117,7 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 
 ### 二、归档前确认是强制阻断检查点
 
-AskUserQuestion 确认；用户拒绝 → 终止，不执行任何操作。
+blocking user confirmation 确认；用户拒绝 → 终止，不执行任何操作。
 
 ### 三、文件移动只用内置工具或 PowerShell
 
@@ -184,7 +186,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 交互白名单
 
-**仅允许**归档确认（Phase 2 AskUserQuestion）；拒绝 → 终止，不执行任何移动。
+**仅允许**归档确认（Phase 2 blocking user confirmation）；拒绝 → 终止，不执行任何移动。
 
 ## 执行日志
 
@@ -199,3 +201,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`archive`

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

@@ -8,7 +8,7 @@ description: harness-archive 的归档流程、manifest、summary-data、final-s
 
 - **Phase 0 读取上下文**：读 SKILL.md / 本文件 / 共用协议（`../protocols/archive-report-protocol.md`、`../protocols/report-pipeline-protocol.md`、`../protocols/state-layout-protocol.md`、`../protocols/powershell-protocol.md`、`../protocols/sensitive-info-protocol.md`、`../protocols/evidence-based-reporting-protocol.md`）/ 解析 `$ARGUMENTS`。
 - **Phase 1 确认归档对象**：Glob `.harness/changes/*/plans/*-plan.md`（排除 archive），展示概要；多变更让用户选择或终止。
-- **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
+- **Phase 2 确认归档（强制阻断）**：blocking user confirmation 确认，拒绝即终止。
 - **Phase 3 执行归档**：
   1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
   2. `meta/archive-meta.md` 由 finalize 生成（与 summary `finalStatus` 同源）；禁止手写。维护者结论写入 events 即可。finalize 在 before-manifest 前执行 cleanup（删除 lock/pid/launcher/credential，截断超大日志）。

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -56,6 +56,7 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust · map 额外：文件存在/行数/hash 为证据
 
 ## 关键规则
 
@@ -81,7 +82,7 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 
 ## 交互白名单
 
-**无** AskUserQuestion；参数/默认值 + `decision` 事件
+**无** blocking user confirmation；参数/默认值 + `decision` 事件
 
 ## 执行日志
 
@@ -96,3 +97,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`codebase-map`；默认写 reports，有未归档变更时另写 change events

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -211,6 +211,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust · ingest/sync 须绑定 `upToDate`/产物路径证据
 
 ## Output Format
 
@@ -230,7 +231,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 
 ## 交互白名单
 
-**仅当** `.harness/config/harness.json` 中 `knowledge.manualReview=true` 时，promote/demote 高价值条目需 AskUserQuestion；否则按 skill 默认策略 + `decision` 事件。
+**仅当** `.harness/config/harness.json` 中 `knowledge.manualReview=true` 时，promote/demote 高价值条目需 blocking user confirmation；否则按 skill 默认策略 + `decision` 事件。
 
 ## 执行日志
 
@@ -245,3 +246,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`knowledge-ingest` · 默认控制台报告；变更上下文写 phase/decision/issue/artifact

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

@@ -4552,6 +4552,11 @@ def main(argv: list[str] | None = None) -> int:
     query.add_argument("--status", action="append", dest="statuses", default=[], help="Only return entries with this lifecycle status")
     query.add_argument("--type", action="append", dest="types", default=[], help="Only return entries of this knowledge type")
     query.add_argument("--change", default=None, help="Write a change-scoped knowledge-context pointer")
+    query.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Emit full payload including matches array (default: compact output for host decisioning)",
+    )
 
     promote = sub.add_parser("promote", help="Promote a candidate knowledge entry to active")
     promote.add_argument("--project", default=".", help="Project root containing .harness/knowledge")
@@ -4652,7 +4657,17 @@ def main(argv: list[str] | None = None) -> int:
             Path(args.project), args.query, args.limit, args.files, args.statuses,
             args.types, args.change,
         )
-        print(json.dumps(result, ensure_ascii=False, indent=2))
+        if getattr(args, "verbose", False):
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            # C5: compact output — omit matches array; host reads context pack for details.
+            compact = {
+                "query": result["query"],
+                "matchCount": result["matchCount"],
+                "contextPack": result["contextPack"],
+                "planInput": result["planInput"],
+            }
+            print(json.dumps(compact, ensure_ascii=False, indent=2))
         return 0
     if args.command == "promote":
         try:

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; 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 的上下文归属。
@@ -111,6 +111,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust · query 成功须含 `contextPack`/`planInput.kind` 与 `latest.json` 写入
 
 ## Output Format
 
@@ -128,7 +129,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 
 ## 交互白名单
 
-**无** AskUserQuestion；`stale`/`conflicted` 命中记 `issue`，不阻断 query。
+**无** blocking user confirmation；`stale`/`conflicted` 命中记 `issue`，不阻断 query。
 
 ## 执行日志
 
@@ -143,3 +144,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`knowledge-query` · 独立运行时控制台报告；变更上下文写 decision/issue/artifact

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -28,6 +28,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol · plan 额外写 `meta/worktree.json`、`meta/change-context.json`
 
 ## Worktree 门禁
 
@@ -39,11 +40,12 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | `requested=true` + path 存在 | 切换 worktree 执行 |
 | `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
 
-**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
 
 **状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
 
 创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+> 片段：worktree-gate · plan 在**设计审批包**写入 `worktree.json`（模板 → `reference.md`）
 
 ## 原生规划协议
 
@@ -63,7 +65,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
-| 4 | **设计审批包** AskUserQuestion；确认事件早于 approved 设计文档和 `meta/worktree.json` |
+| 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
 | 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`；原子发布、唯一 `phase.end`、render → `checklist.md` |
@@ -75,13 +77,14 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust
 
 ## 关键规则
 
 | 规则 | 要点 |
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
-| 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
+| 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`） |
 | 阶段 8 | spec/plan/detail/scenarios/worktree.json 先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，失败不得手工补终态 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
@@ -117,3 +120,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`plan`

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

@@ -6,7 +6,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 ## 阶段 0：工作区变更检查 ⚠️ 强制检查
 
-> 有未提交业务变更（排除 `.harness/`）→ **默认 baseline 隔离**，append `decision` 事件，**不 AskUserQuestion**，继续规划。PowerShell 失败 → ❌ 停止。
+> 有未提交业务变更（排除 `.harness/`）→ **默认 baseline 隔离**，append `decision` 事件，**不 blocking user confirmation**，继续规划。PowerShell 失败 → ❌ 停止。
 
 **固定命令**：`powershell.exe -Command "git -C '<项目路径>' status --porcelain"`
 
@@ -27,7 +27,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 ## 设计审批包字段：Worktree
 
-> worktree 不再单独询问。阶段 4 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
+> worktree 不再单独询问。阶段 4 **设计审批包** 一次 blocking user confirmation 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
 
 - [ ] 审批包确认后写入 worktree.json（`requested` true/false）
 - [ ] 阶段 8 检查 worktree.json 存在
@@ -63,7 +63,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 - [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
 
-## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
+## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 blocking user confirmation）
 
 > 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。
 
@@ -89,7 +89,7 @@ source: harness-plan
 ---
 ```
 
-展示可审核包后，使用 `AskUserQuestion` 询问用户：
+展示可审核包后，使用 `blocking user confirmation` 询问用户：
 - **确认**：设计方向正确，继续任务拆分
 - **修改**：某个部分需要调整，修改后再审核
 - **取消**：方向不对，回到需求澄清阶段
@@ -154,7 +154,7 @@ source: harness-plan
 阶段 7.5 执行完成后，确认以下事项：
 
 ```
-□ 已用 **设计审批包** 一次 AskUserQuestion（设计 + 场景表摘要 + worktree + change-name）
+□ 已用 **设计审批包** 一次 blocking user confirmation（设计 + 场景表摘要 + worktree + change-name）
 □ **未**单独询问 worktree 或对抗评审（对抗评审仅 `--adversarial`）
 □ 用户同意后，已用 Agent 工具委派 harness-evaluator（haiku, context:fork, plan 模式只读, maxTurns:8）
 □ 已用 context:fork 隔离上下文（evaluator 未参与规划，破除确认偏误）

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=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -42,6 +42,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol
 
 ## Workflow
 
@@ -107,6 +108,7 @@ review:
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust
 
 ## 关键规则（硬门禁速查）
 
@@ -134,7 +136,7 @@ review 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol
 
 ## 交互白名单
 
-**无** AskUserQuestion（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。
+**无** blocking user confirmation（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。
 
 ## 执行日志
 
@@ -149,3 +151,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`review` · 事件：phase/decision/verification/issue/artifact

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

@@ -84,3 +84,16 @@ RED 高风险建议: N | YELLOW 中低风险建议: M | 仅供参考，不阻塞
 ```
 
 fixback 是给后续修复循环使用的结构化清单，不替代 review-report；无 RED/YELLOW 时记录跳过原因，不生成空文件。
+
+## CodeGraph Identity 合同（C12）
+
+调用 `codegraph_explore` 后必须校验响应中的 `repositoryId` / `indexedHead` / `indexedAt`：
+
+- `repositoryId` 必须与 `harness_paths.repository_identity(project_root)` 一致
+- `indexedHead` 必须与当前 HEAD 一致
+- `indexedAt` 必须存在
+
+identity 不匹配时记 `CODEGRAPH_IDENTITY_MISMATCH` warning，降级为 Grep/Glob + Read。
+identity 匹配时正常使用 codegraph 结果。
+
+校验函数：`harness_review.validate_codegraph_identity(response, expected_repository_id, expected_head)`。

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

@@ -2,12 +2,12 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=6232f66fbf691292; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
 
-基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 [[shared/worktree-gate.md|worktree-gate]]）。
+基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 worktree-gate）。
 
 ## When to Use
 
@@ -28,11 +28,12 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | `requested=true` + path 存在 | 切换 worktree 执行 |
 | `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
 
-**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
 
 **状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
 
 创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+> 片段：worktree-gate · 创建命令 → `reference.md`
 
 ## 统一读取协议
 
@@ -47,6 +48,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol · run 必读文件优先级 → `reference.md` Step 0
 
 ## 执行模式
 
@@ -70,6 +72,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust
 
 ## 关键规则（硬门禁速查）
 
@@ -129,3 +132,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`run`