@hunter-harness/workflow-harness 0.2.73 → 0.2.75

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

@@ -1101,6 +1101,43 @@ def _derive_verification_graph(profile: dict[str, Any]) -> None:
     }
 
 
+def manual_profile_template(
+    excluded: tuple[str, ...] | list[str], components: list[str]
+) -> dict[str, Any]:
+    """歧义时交给调用方的可填骨架。
+
+    骨架本身就是 `empty_profile_skeleton`——defaultsFingerprint、excludedRoots
+    默认集、commands/verificationInputs/verificationGraph 的键都已就位；这里只是
+    补上 commands 的条目形状与 requiredCoverage 取值，省掉调用方去源码里翻。
+    占位值用 `<...>` 包裹，便于替换后 grep 自检。
+    """
+    template = empty_profile_skeleton(excluded)
+    template["projectType"] = (
+        f"<从 detectedComponents 选定：{'|'.join(components)}>" if components else "<项目类型>"
+    )
+    template["commands"] = {
+        "unitTest": {
+            "command": "<在项目根可直接执行的增量测试命令>",
+            "scope": "incremental",
+            "inputs": ["<相对项目根的 glob，如 <component>/test/**>"],
+            "coverage": "unitTest",
+            "requiredCoverage": "incremental",
+            "dependsOn": [],
+            "source": "user",
+        },
+        "unitTestFull": {
+            "command": "<在项目根可直接执行的全量测试命令>",
+            "scope": "full",
+            "inputs": ["<相对项目根的 glob，如 <component>/**>"],
+            "coverage": "unitTestFull",
+            "requiredCoverage": "module",
+            "dependsOn": [],
+            "source": "user",
+        },
+    }
+    return template
+
+
 def detect(project: Path) -> dict[str, Any]:
     project = project.resolve()
     existing = load_profile(project)
@@ -1120,6 +1157,14 @@ def detect(project: Path) -> dict[str, Any]:
             "applied": False,
             "detectedComponents": components,
             "message": "multiple or nested project components require an explicit profile",
+            # 拒绝生成可以，但不能连结构都不给：调用方否则只能反读本文件源码去凑
+            # v3 形状。骨架不落盘——一份占位 profile 看起来"已配好"比没有更糟。
+            "profileTemplate": manual_profile_template(excluded, components),
+            "hint": (
+                "手工声明一份 profile：以 profileTemplate 为骨架，按 detectedComponents "
+                "选定产品包，commands 里的 inputs 用相对项目根的 glob（如 "
+                f"'<component>/test/**'），填好后写入 {project / PROFILE_REL}"
+            ),
         }
     if project_type == "unknown" and existing:
         return {

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

@@ -157,6 +157,35 @@ def _private_evidence_root(explicit: Path | None = None) -> Path:
             Path.home() / ".harness" / "private-evidence").expanduser().resolve()
 
 
+def private_evidence_root_for(source: Path, explicit: Path | None = None) -> Path:
+    """私有隔离根：必须与源同一驱动器。
+
+    `os.replace` 跨驱动器会直接失败（Windows 上是 WinError 17）。默认根
+    `~/.harness/private-evidence` 在 Windows 落 C 盘，项目在别的盘时隔离必然失败
+    ——而隔离是归档的硬前置，等于整条归档路被堵死。同盘时沿用配置/默认值；不同盘
+    时退到源所在驱动器根下的 `.harness-private-evidence`（天然在任何项目根之外）。
+    POSIX 上 drive 恒为空串，行为不变。
+    """
+    source = source.expanduser().resolve()
+    preferred = _private_evidence_root(explicit)
+    if preferred.drive.lower() == source.drive.lower():
+        return preferred
+    return (Path(source.anchor) / ".harness-private-evidence").resolve()
+
+
+def _infer_project_root(change_root: Path) -> Path | None:
+    """change 目录形如 `<project>/.harness/changes/<name>`：取路径里 `.harness` 段的父目录。
+
+    不做"向上找存在 .harness 的目录"式搜索——用户 HOME 下通常也有 `.harness`，
+    那样会把 HOME 误判成项目根，把合法的临时隔离位置一并拒掉。
+    """
+    parts = change_root.parts
+    for index in range(len(parts) - 1, 0, -1):
+        if parts[index] == ".harness":
+            return Path(*parts[:index])
+    return None
+
+
 def _secure_private_path(path: Path, *, directory: bool) -> str:
     """Best-effort owner-only permissions, with an explicit ACL result on Windows."""
     mode = 0o700 if directory else 0o600
@@ -288,11 +317,12 @@ def quarantine_sensitive_evidence(
     change_root: Path,
     reason: str = "sensitive evidence",
     private_root: Path | None = None,
+    project_root: Path | None = None,
 ) -> dict[str, Any]:
     """Atomically move legacy plaintext evidence outside any publishable tree."""
     source = source.expanduser().resolve()
     change_root = change_root.expanduser().resolve()
-    private = _private_evidence_root(private_root)
+    private = private_evidence_root_for(source, private_root)
     if not source.is_file():
         return {"ok": False, "reasonCode": "SENSITIVE_EVIDENCE_SOURCE_MISSING", "sourcePath": str(source)}
     if private == change_root or private.is_relative_to(change_root):
@@ -301,6 +331,25 @@ def quarantine_sensitive_evidence(
             "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
             "error": "private quarantine root must be outside the publishable change root",
         }
+    # 归档的密钥扫描门禁按**项目根**判定（SECRET_SCAN_PRIVATE_PATH_IN_COPY_ROOT）。
+    # 这里此前只看 change_root，比门禁宽——于是隔离"成功"了，门禁再拒一次，调用方
+    # 得多试一轮才找到合法位置。对齐到同一条边界，错就错在当场。
+    resolved_project = (
+        project_root.expanduser().resolve()
+        if project_root is not None
+        else _infer_project_root(change_root)
+    )
+    if resolved_project is not None and (
+        private == resolved_project or private.is_relative_to(resolved_project)
+    ):
+        return {
+            "ok": False,
+            "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+            "error": (
+                "private quarantine root must be outside the project root "
+                f"({resolved_project}); archive's secret scan rejects paths inside it"
+            ),
+        }
     try:
         raw_digest = "sha256:" + hashlib.sha256(source.read_bytes()).hexdigest()
         quarantine_dir = private / uuid.uuid4().hex
@@ -1850,6 +1899,37 @@ def doctor(project: Path, change_dir: Path, *, agent: str) -> dict[str, Any]:
     return {"ok": True, "action": "doctor", **payload}
 
 
+def cmd_quarantine_evidence(args: argparse.Namespace) -> dict[str, Any]:
+    """隔离命令：把明文敏感证据原子移出可发布树，逐条返回结果。
+
+    单条失败不吞掉其余条目——归档阻断项常常一次报多个文件，逐条报告才能一轮修完。
+    """
+    project = Path(args.project).expanduser().resolve()
+    change_root = Path(args.change_dir).expanduser().resolve()
+    private_root = Path(args.private_root) if args.private_root else None
+    entries: list[dict[str, Any]] = []
+    for raw in args.file:
+        candidate = Path(raw)
+        source = candidate if candidate.is_absolute() else change_root / candidate
+        outcome = quarantine_sensitive_evidence(
+            source,
+            change_root=change_root,
+            reason=args.reason,
+            private_root=private_root,
+            project_root=project,
+        )
+        entries.append({"file": raw, **outcome})
+    failed = [item for item in entries if not item.get("ok")]
+    return {
+        "ok": not failed,
+        "action": "quarantine-evidence",
+        "code": "SENSITIVE_EVIDENCE_QUARANTINED" if not failed else "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+        "quarantined": len(entries) - len(failed),
+        "failed": len(failed),
+        "entries": entries,
+    }
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_runtime.py")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -1858,6 +1938,24 @@ def build_parser() -> argparse.ArgumentParser:
     p_doctor.add_argument("--change-dir", required=True)
     p_doctor.add_argument("--agent", choices=sorted(_ADAPTERS), required=True)
     p_doctor.add_argument("--json", action="store_true")
+    # 归档的 SENSITIVE_EVIDENCE_UNQUARANTINED 是硬阻断，此前却没有任何命令行入口
+    # ——调用方只能写 python -c + sys.path hack 去调内部函数。
+    p_quarantine = sub.add_parser(
+        "quarantine-evidence",
+        help="move plaintext sensitive evidence outside the publishable tree",
+    )
+    p_quarantine.add_argument("--project", required=True)
+    p_quarantine.add_argument("--change-dir", required=True)
+    p_quarantine.add_argument(
+        "--file", required=True, action="append",
+        help="path to quarantine, relative to --change-dir or absolute; repeatable",
+    )
+    p_quarantine.add_argument("--reason", default="sensitive evidence")
+    p_quarantine.add_argument(
+        "--private-root", default=None,
+        help="override the private root; must be outside the project root and on its drive",
+    )
+    p_quarantine.add_argument("--json", action="store_true")
     p_adapter = sub.add_parser("adapter")
     p_adapter.add_argument("--agent", choices=sorted(_ADAPTERS), required=True)
     p_adapter.add_argument("--change", required=True)
@@ -1899,6 +1997,8 @@ def main(argv: list[str] | None = None) -> int:
     try:
         if args.command == "doctor":
             result = doctor(Path(args.project), Path(args.change_dir), agent=args.agent)
+        elif args.command == "quarantine-evidence":
+            result = cmd_quarantine_evidence(args)
         elif args.command == "adapter":
             result = {"ok": True, "action": "adapter", **adapter_worktree(args.agent, args.change)}
         elif args.command == "_worker":

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "d79ae315e929446c"
+  "coreHash": "24b43afeb4dc4c52"
 }

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -38,6 +38,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
@@ -125,6 +126,13 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 `execute` 内部运行自动门禁。实际计划最后阶段已终态、边界快照存在且 `status.archivable=true` 时直接执行；未满足时返回阻断且不移动原目录。用户取消后不得重跑。
 
+### 二·A、两个常见阻断的正规出路（不要自己拼 python -c）
+
+| 阻断 | 出路 |
+|------|------|
+| `SENSITIVE_EVIDENCE_UNQUARANTINED` | `python <skills-root>/scripts/harness_runtime.py quarantine-evidence --project . --change-dir ".harness/changes/<cn>" --file "<相对 change-dir 的路径>" --reason "<为什么是敏感证据>" --json`（`--file` 可重复）。私有根默认已与项目同盘、且在项目根之外——**不要**手工指定项目内的路径，归档的密钥扫描会以 `SECRET_SCAN_PRIVATE_PATH_IN_COPY_ROOT` 拒绝 |
+| `DIFF_ZERO_WITH_NONEMPTY_COMMIT`（提交范围非空但 filesChanged=0） | 契约缺 `ownership.productPaths`，全部改动被判为 `foreignPaths`。用 `python <skills-root>/scripts/harness_change.py declare-ownership --change <cn> --product-path "<目录前缀或精确文件>" --json` 按计划的实际改动范围声明（可重复；只收精确路径，不支持通配）。**不要**手改 `change-context.json` |
+
 ### 三、文件移动只用内置工具或 PowerShell
 
 移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
@@ -186,6 +194,23 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 su
 - `.harness/archive/YYYY-MM-DD-<change-name>/events.ndjson` — 结构化事件层（新流程推荐；旧 archive 可缺失）
 - `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` — 最终报告数据源
 - `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
+- `.harness/state/local/archive-packages/<change-name>.remote.json` — 远端上传回执（`archiveId`/`archiveStatus`/`knowledgeStatus`/`uploadStatus`/`fileCount`）
+
+### 结束报告必须回显两条上传结果 ⚠️
+
+归档会做**两次**独立上传，二者成败无关，必须分别如实回显：
+
+| 上传 | 载什么 | 结果在哪 |
+|------|--------|---------|
+| `steps.archive_push` | 归档 ZIP（核心产物） | `archiveId`/`archiveStatus`/`uploadStatus`/`knowledgeStatus`，同时落盘 `state/local/archive-packages/<cn>.remote.json` |
+| `steps.managed_snapshot_push` | **plan/spec 文档、`.harness/codebase` 架构地图、`.harness/rules`**（push 会 walk 每个归档目录的 `spec/` 与 `plans/`） | `ok`/`reasonCode`/`exitCode`/`cliCode`/`detail` |
+
+```
+远端归档：arc_3ff325bb…（archiveStatus=durable，uploadStatus=ready，knowledgeStatus=ready，8 文件）
+受管快照：❌ MANAGED_SNAPSHOT_UPLOAD_FAILED（exitCode=1，detail=…）→ plan/spec 与规则/架构地图未上平台，需 npx hunter-harness push --yes --non-interactive 重试
+```
+
+**第二条尤其不能省**：它是 best-effort，失败不阻断归档，于是最容易被淹没成一句警告——而平台上"分支文件里没有 plan/spec"正是它失败的后果。成功时也要写明 `submitted` 数量；`ok=false` 时必须带上 `reasonCode` 与 `detail`，不得省略或写成"已完成"。
 
 ## 渐进披露
 

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=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

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

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

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

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -20,6 +20,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

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

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

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

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -30,6 +30,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败

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

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -40,6 +40,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
@@ -62,7 +63,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 0. 加载上下文：普通 Run 先 `harness_context.py prepare --project . --change <id> --phase run --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 **`harness_context.py begin --project . --change <id> --phase run --executor <tool> --json`** 校验交接，最后运行 **`harness_gate.py begin --phase run --change <id>`**。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → run` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。`harness_gate.py` 会从当前已安装适配器自动识别 skills root；只有执行复制到别处的脚本时才显式传 `--skills-root`。`--fixback` 不得拼装这些底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`：该命令会先筛选结构化评审项，再原子选择 Fixback 分支、确认上下文、取得 Run 门禁并创建已填充批次。返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告“本轮评审没有需要执行的代码修复”并停止；返回阻塞码时按 `recoveryAction` 停止，不搜索实现、不试探其他参数、不创建空批次。禁止手写 `events.ndjson` / `phase.end`。已连接平台时 begin 会 best-effort 补传事件，失败只告警。
 0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；测试基线已由上一步 gate begin 内部建立，不得再次执行 guard begin
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
+2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。detect 在嵌套/多组件仓库返回 `DETECTION_AMBIGUOUS` 时，响应里的 `profileTemplate` 就是可填骨架（已含 defaultsFingerprint、excludedRoots 默认集与 commands 条目形状），按 `hint` 填好写入 `.harness/config/build-profile.json` 即可，**不要去反读 `harness_profile.py` 源码凑结构**。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
 4. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 必须取返回的 `nextPhases` 或 `plannedPhases` 中 run 的真实后继，禁止写死 test。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
 

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

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -29,6 +29,7 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
@@ -54,10 +55,11 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 
 ### 提交流程（步骤 0–7）
 
-0. **启动准备** — `harness_context.py prepare --phase submit --executor <tool> [--change <id>] --json` 确定唯一变更与 executionRoot；`harness_context.py begin --phase submit --change <id> --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
+0. **启动准备** — `harness_context.py prepare --project . --change <id> --phase submit --executor <tool> --json`（`--project` 必填）确定唯一变更与 executionRoot；`harness_context.py begin --project . --change <id> --phase submit --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
 1. **合并最新代码** — 主目录与 worktree 均**不在业务工作区 stash/pull**；远端同步由合并段 integration transaction 在隔离 integration worktree 内完成（见「worktree 合并流程」）；**正常路径禁止 `git stash` / `stash pop`**
 2. **最终验证** — ledger 复用优先；提交前只调用 `can-reuse --project . --profile-input unitTestFull --command <profile 规范命令>`。不得传入另一套 `--files`，不得把 runner 包装说明写进 `command`。`reuse=true` 时禁止重跑；只有真实输入、依赖、工具链或环境身份变化时才执行一次同一 profile 验证，并只登记一条结果。不要读取 ledger/archive 实现源码或临时编写散列脚本排查参数。
    - 无远端 CI 且 gate-policy 未强制 remote provider 时，验证通过/复用后运行 `harness_archive.py certify-local --change-dir ... --project . --json`，从同一 ledger 生成 `local-reproducible` 产品候选收据；该命令不执行测试。
+   - **被与本变更无关的预存失败卡住时的正规出路**：用 `harness_preflight.py record-quirk --project . --action skip-not-block --pattern "<具体错误签名，≥8 字符>" --reason "<为什么与本变更无关>"` 把它声明进 build-profile 的 `knownPreexistingErrors`，certify-local 会在**该失败的 ledger 证据里确实出现该签名**时放行，并把 `{validation, pattern, reason}` 写进收据的 `verification.preexistingExemptions` 留痕。**不得**改 gate-policy 的 `candidateVerification.requiredValidations` 来绕过——那是把门禁本身拆掉。声明了但证据对不上、或签名短到能匹配一切，仍然阻断。
    - gate-policy 要求 `remote-attested` 时不得降级成本地收据，等待远端 attestation。
 3. **.gitignore + 精确暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**。若存在 `evidence/test-tracking.json`，先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；失败即硬停止。无 manifest 时不使用 `-f`。manifest 之外的文件按精确业务路径正常暂存，**禁止全局 force-add**。
 4. **提交方式** — 主目录：blocking user confirmation 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**

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

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=24b43afeb4dc4c52; overlay=none; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -31,6 +31,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 
 ## 统一读取协议
 
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
 2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
@@ -85,7 +86,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+先 `harness_context.py prepare --project . --change <id> --phase test --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 `harness_context.py begin --project . --change <id> --phase test --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
 
 验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close`。`--to-phase` 取实际阶段计划的后继；Fixback 返回 run，普通流程可直接进入 Review、Submit 或 Archive。Fixback 只失效与改动文件相交的验证目标。
 

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

@@ -273,6 +273,8 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-run 单元测试结果"
 - [ ] 不复用 → 按 profile key resolve 重跑测试命令（`harness_profile.py resolve --key unitTest`，不复制示例 `-pl` 命令），结果写回 ledger 的 `unitTest` 项
 - [ ] HTTP/API 契约结果写入 `apiTest`；真实浏览器/真实栈 Playwright 结果写入 `browserTest`，两者不得互相覆盖
+- [ ] **本变更没有该维度场景时**（如全部为单元场景 → 无 API 场景）：用 `harness_ledger.py record --verification apiTest --status NOT_RUN --applicability NOT_APPLICABLE --applicability-reason "<为什么不适用>"` 登记，**不传 `--files`**。门禁 close 要求 requiredValidations 每项都有 entry，但**绝不能拿无关文件（比如单元测试文件）凑 `--files`**——那会让 ledger 声称该维度的输入是那些文件，是假证据
+- [ ] `can-reuse` 返回 `reuse:false` 时直接读默认输出里的 `reason`/`executionNeed`/`detail` 定位原因，不必再补跑 `--verbose`
 - [ ] 复用判断前以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 重算指纹；test-tracking manifest 无效或 hash 漂移即停止
 - [ ] 测试失败若明确为陈旧测试，仅在当前代码/批准计划/可验证历史唯一确定新契约且只改测试时自动修复；否则记录 `BLOCKED_PREEXISTING`
 - [ ] 自动修复后立即重跑该测试与目标测试，并以 `harness_test_guard.py record ... --reason stale-test-repair` 记录精确路径