@hunter-harness/workflow-harness 0.2.15 → 0.2.17

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

@@ -27,6 +27,12 @@ import sys
 from pathlib import Path
 from typing import Any
 
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+import harness_paths  # noqa: E402
+
 
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8")
@@ -358,14 +364,53 @@ def empty_profile_skeleton(excluded: tuple[str, ...] | list[str]) -> dict[str, A
 
 
 def load_profile(project: Path) -> dict[str, Any] | None:
-    path = project / PROFILE_REL
-    if not path.is_file():
-        return None
-    try:
-        data = read_json(path)
-    except (OSError, json.JSONDecodeError):
+    """C7: 分层读取 — 先读 common_root 的 build-profile.json，再叠加 execution root 的 override。
+
+    common_root 是 worktree 共享的主项目根（git common dir 的父目录）；
+    execution root 是当前工作目录（可能是 linked worktree）。
+    override 合并策略：execution 的 buildCommands 覆盖 common 的同名 key；
+    common 独有的 key 保留。
+    """
+    project = Path(project).resolve()
+    common = harness_paths.common_root(project)
+    common_path = common / PROFILE_REL
+    exec_path = project / PROFILE_REL
+
+    common_data: dict[str, Any] | None = None
+    if common_path.is_file():
+        try:
+            data = read_json(common_path)
+            if isinstance(data, dict):
+                common_data = data
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    exec_data: dict[str, Any] | None = None
+    if exec_path.is_file():
+        try:
+            data = read_json(exec_path)
+            if isinstance(data, dict):
+                exec_data = data
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    if common_data is None and exec_data is None:
         return None
-    return data if isinstance(data, dict) else None
+    if common_data is None:
+        return exec_data
+    if exec_data is None:
+        return common_data
+
+    # Merge: start from common, overlay execution's buildCommands.
+    merged = dict(common_data)
+    common_cmds = common_data.get("buildCommands") or {}
+    exec_cmds = exec_data.get("buildCommands") or {}
+    if common_cmds or exec_cmds:
+        merged_cmds = dict(common_cmds) if isinstance(common_cmds, dict) else {}
+        if isinstance(exec_cmds, dict):
+            merged_cmds.update(exec_cmds)
+        merged["buildCommands"] = merged_cmds
+    return merged
 
 
 def _merge_user_overrides(
@@ -616,6 +661,8 @@ def resolve_command(
     *,
     test_classes: list[str] | None = None,
     modules: list[str] | None = None,
+    common_root: Path | None = None,
+    execution_root: Path | None = None,
 ) -> dict[str, Any]:
     cmd = (profile.get("commands") or {}).get(key)
     if not isinstance(cmd, dict):
@@ -625,6 +672,10 @@ def resolve_command(
         replacements["{testClasses}"] = ",".join(test_classes)
     if modules is not None:
         replacements["{modules}"] = ",".join(modules)
+    if common_root is not None:
+        replacements["{commonRoot}"] = str(common_root)
+    if execution_root is not None:
+        replacements["{executionRoot}"] = str(execution_root)
 
     command = cmd.get("command", "")
     for placeholder, val in replacements.items():

package/harness/bundles/general/codex/scripts/harness_review.py

@@ -14,6 +14,7 @@ Python 3.10+, stdlib only.
 from __future__ import annotations
 
 import argparse
+import datetime as dt
 import hashlib
 import json
 import os
@@ -270,6 +271,112 @@ def _emit(payload: Any, *, as_json: bool) -> int:
     return 0 if payload.get("ok") else 1
 
 
+def dispatch_review(
+    *,
+    change_dir: Path,
+    run_id: str,
+    budget_seconds: int = 300,
+) -> dict[str, Any]:
+    """C11: dispatch a bounded review task.
+
+    Returns reviewTaskId / deadline / heartbeatAt. The caller is expected to
+    poll the review subagent and collect partial findings on timeout.
+    """
+    now = dt.datetime.now(dt.timezone.utc).astimezone()
+    task_id = f"review-{uuid.uuid4().hex}"
+    deadline = now + dt.timedelta(seconds=budget_seconds)
+    # heartbeat at midpoint of the budget
+    heartbeat = now + dt.timedelta(seconds=budget_seconds // 2)
+    return {
+        "ok": True,
+        "code": "DISPATCHED",
+        "reviewTaskId": task_id,
+        "runId": run_id,
+        "deadline": deadline.isoformat(timespec="milliseconds"),
+        "heartbeatAt": heartbeat.isoformat(timespec="milliseconds"),
+        "budgetSeconds": budget_seconds,
+    }
+
+
+def collect_partial_findings(
+    *,
+    change_dir: Path,
+    run_id: str,
+    completed_dimensions: list[str],
+    pending_dimensions: list[str],
+) -> dict[str, Any]:
+    """C11: collect partial findings after timeout — completed dimensions only.
+
+    Applies the degradation matrix to decide the fallback path.
+    """
+    matrix = degradation_matrix(
+        subagent_timed_out=bool(pending_dimensions),
+        main_session_available=True,
+    )
+    return {
+        "ok": True,
+        "code": "PARTIAL_FINDINGS",
+        "runId": run_id,
+        "completedDimensions": list(completed_dimensions),
+        "pendingDimensions": list(pending_dimensions),
+        "degradationMatrix": matrix,
+    }
+
+
+def degradation_matrix(
+    *,
+    subagent_timed_out: bool,
+    main_session_available: bool,
+) -> dict[str, Any]:
+    """C11: degradation matrix — subagent timeout → main session; main fail → ADVISORY."""
+    if not subagent_timed_out:
+        return {"fallback": "none", "status": "OK"}
+    if main_session_available:
+        return {"fallback": "main-session", "status": "DEGRADED"}
+    return {"fallback": "advisory", "status": "ADVISORY"}
+
+
+def validate_codegraph_identity(
+    *,
+    response: dict[str, Any],
+    expected_repository_id: str,
+    expected_head: str,
+) -> dict[str, Any]:
+    """C12: validate CodeGraph identity — repositoryId/indexedHead must match.
+
+    On mismatch, signal CODEGRAPH_IDENTITY_MISMATCH with fallback to Grep/Glob + Read.
+    """
+    repo_id = response.get("repositoryId")
+    indexed_head = response.get("indexedHead")
+    indexed_at = response.get("indexedAt")
+    if (
+        repo_id == expected_repository_id
+        and indexed_head == expected_head
+        and indexed_at
+    ):
+        return {
+            "ok": True,
+            "code": "IDENTITY_OK",
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        }
+    return {
+        "ok": False,
+        "code": "CODEGRAPH_IDENTITY_MISMATCH",
+        "expected": {
+            "repositoryId": expected_repository_id,
+            "indexedHead": expected_head,
+        },
+        "actual": {
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        },
+        "fallback": "grep-glob-read",
+    }
+
+
 def cmd_validate_findings(args: argparse.Namespace) -> int:
     doc = _read_json(Path(args.input))
     problems = validate_findings(doc)

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "7fd91be625bd5963"
+  "coreHash": "d2eb65d744fddce3"
 }

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

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

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