@hunter-harness/workflow-harness 0.2.8 → 0.2.10

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

@@ -353,6 +353,95 @@ def changed_file_paths(summary: dict[str, Any]) -> list[str]:
     return files
 
 
+def archive_publication_status(project: Path, archive_rel: str) -> dict[str, Any]:
+    """Knowledge publication gate for one archive (API-006/RET-40).
+
+    Blocks judge/apply/promote when: source consistency never ran or failed,
+    the authoritative version is missing or hash-mismatched, or the archive
+    is DEGRADED/UNVERIFIED. Ordinary ingest may still build quarantined
+    candidates, but nothing from a blocked archive becomes active.
+    """
+    result: dict[str, Any] = {"status": "missing", "allowed": False, "reasons": []}
+    archive_dir = (Path(project) / archive_rel).resolve()
+    summary_path = archive_dir / "reports" / "final" / "summary-data.json"
+    if not summary_path.is_file():
+        result["reasons"].append("summary-data.json missing")
+        return result
+    try:
+        summary = json.loads(summary_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        result["reasons"].append("summary-data.json unreadable")
+        return result
+    if not isinstance(summary, dict):
+        result["reasons"].append("summary-data.json must be an object")
+        return result
+
+    # A versioned repair becomes authoritative only after its pointer and
+    # repair-record hashes are verified. Gate the authoritative summary, not
+    # the known-bad original that caused the repair.
+    pointer_path = archive_dir / "derived" / "authoritative.json"
+    if pointer_path.is_file():
+        try:
+            pointer = json.loads(pointer_path.read_text(encoding="utf-8"))
+            version = str(pointer.get("version") or "")
+            if re.fullmatch(r"v[0-9]+", version) is None:
+                raise ValueError("invalid authoritative version")
+            version_dir = (archive_dir / "derived" / version).resolve()
+            if not version_dir.is_relative_to((archive_dir / "derived").resolve()):
+                raise ValueError("authoritative version escapes derived root")
+            record = json.loads(
+                (version_dir / "repair-record.json").read_text(encoding="utf-8")
+            )
+            derived_path = version_dir / "summary-data.json"
+            summary_bytes = derived_path.read_bytes()
+            actual = "sha256:" + hashlib.sha256(summary_bytes).hexdigest()
+            if record.get("summarySha256") != actual:
+                result["status"] = "degraded"
+                result["reasons"].append("repair record summary hash mismatch")
+                return result
+            if pointer.get("summarySha256") not in {None, actual}:
+                result["status"] = "degraded"
+                result["reasons"].append("authoritative pointer hash mismatch")
+                return result
+            summary = json.loads(summary_bytes.decode("utf-8"))
+            if not isinstance(summary, dict):
+                raise ValueError("authoritative summary must be an object")
+            result["authoritativeVersion"] = version
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError, ValueError):
+            result["status"] = "degraded"
+            result["reasons"].append("authoritative version unreadable")
+            return result
+
+    consistency = (summary.get("reportPipeline") or {}).get("sourceConsistency")
+    if consistency is None:
+        result["status"] = "unverified"
+        result["reasons"].append("source consistency never ran")
+        return result
+    if not consistency.get("ok"):
+        result["status"] = "failed"
+        codes = [
+            str(i.get("code"))
+            for i in (consistency.get("issues") or [])
+            if isinstance(i, dict) and i.get("code")
+        ]
+        result["reasons"].append(
+            "source consistency failed" + (f": {', '.join(codes)}" if codes else "")
+        )
+        return result
+
+    final_status = str(summary.get("finalStatus") or "").upper()
+    if final_status not in {"OK", "CONDITIONAL_OK"}:
+        result["status"] = "degraded" if final_status == "DEGRADED" else "unverified"
+        result["reasons"].append(
+            f"authoritative finalStatus is not publishable: {final_status or 'missing'}"
+        )
+        return result
+
+    result["status"] = "ok"
+    result["allowed"] = True
+    return result
+
+
 def archive_summary_records(project: Path, summary_paths: list[Path]) -> list[dict[str, Any]]:
     records = []
     for summary_path in summary_paths:
@@ -939,6 +1028,9 @@ def apply_confidence_scores(entries: list[dict[str, Any]], config: dict[str, Any
 def should_auto_promote(entry: dict[str, Any], policy: dict[str, Any]) -> bool:
     if not policy["enabled"]:
         return False
+    # API-006/RET-40: entries from blocked archives stay quarantined.
+    if entry.get("lifecycle", {}).get("publishBlocked"):
+        return False
     if entry.get("type") not in set(policy["allowedTypes"]):
         return False
     if entry.get("status") == "stale" and not policy["allowStale"]:
@@ -1946,6 +2038,17 @@ def build_index(
                     ingest_mode["cacheWrites"] += 1
             else:
                 ingest_mode["archivesReused"] += 1
+            # API-006/RET-40: entries from archives failing the publication
+            # gate stay quarantined (candidate only, never active/promoted).
+            archive_rel = rel_to_project(project, archive_dir_from_summary(summary_path))
+            publication = archive_publication_status(project, archive_rel)
+            if not publication.get("allowed"):
+                for entry in archive_entries:
+                    lifecycle = entry.setdefault("lifecycle", {})
+                    lifecycle["publishBlocked"] = list(publication.get("reasons") or [])
+                    if entry.get("status") == "active":
+                        entry["status"] = "candidate"
+                        ingest_mode["activeAutoDemoted"] += 1
             entries.extend(archive_entries)
         except Exception as exc:  # keep one bad archive from blocking the index
             failures.append({"path": rel_to_project(project, summary_path), "error": str(exc)})
@@ -2064,6 +2167,20 @@ def promote_entry(project: Path, entry_id: str, note: str, allow_stale: bool = F
         raise ValueError(f"entry not found in promotable statuses: {entry_id}")
 
     source_path, entry = found
+    # API-006/RET-40: refuse promotion of entries from blocked archives.
+    blocked = (entry.get("lifecycle") or {}).get("publishBlocked")
+    if blocked:
+        raise ValueError(
+            "publication blocked: " + "; ".join(str(r) for r in blocked)
+        )
+    archive_rel = (entry.get("source") or {}).get("archive")
+    if archive_rel:
+        publication = archive_publication_status(project, archive_rel)
+        if not publication.get("allowed"):
+            raise ValueError(
+                "publication blocked: "
+                + "; ".join(str(r) for r in (publication.get("reasons") or []))
+            )
     entry["status"] = "active"
     lifecycle = entry.setdefault("lifecycle", {})
     lifecycle["promotedAt"] = now_iso()

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

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=5b2756a71712c9d3; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ca4e4b55f29590dc; overlay=none; agent=codex; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

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

@@ -57,6 +57,12 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 > - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
 > - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
 
+## 影响面检查（远程客户端路径）
+
+变更涉及 HTTP/RPC 客户端时，在设计/任务拆分前完成路径静态比对：
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+
 ## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
 
 > 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。

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

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

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

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

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

@@ -120,6 +120,11 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 纯 Mock 数据访问层测试 → 标记为 🟡静态验证，交给 harness-test 真实 DB 验证
 - [ ] 如果必须自动化 → 使用真实数据访问层（非 mock）或可检查查询条件的测试方式
 
+### 编码前检查（远程客户端 / stub 同源错误）
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+- [ ] 修 stub/null 返回时，顺带核对同文件相邻声明（注解、常量、同类方法路径）是否同源错误，一并列出核对结果
+
 ### GREEN（最简实现 — 按变更簇批量实现）
 
 - [ ] 写最少代码让变更簇测试全部通过

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

@@ -522,12 +522,14 @@ powershell.exe -Command "<测试命令> <模块定位参数>"
 
 ```powershell
 python <skills-root>/scripts/harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json
-python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/changes/<change-name>" --verification compile --status PASS --command "<cmd>" --exit-code 0 --json
+python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/changes/<change-name>" --verification compile --status ok --command "<cmd>" --exit-code 0 --json
 ```
 
 > `content-changeset-2` 同时读取 tracked diff、标准 untracked 文件和 manifest 的精确测试路径。manifest 缺失时保持普通行为；manifest 存在但路径越界、内容 hash 漂移或结构非法时命令失败，ledger 不可复用。checkpoint commit 不改变各路径的工作树内容，因此提交前后 hash 保持一致。
 
 > 这样 harness-test 的 Phase 1 可读取 ledger 判断是否复用 run 的 unitTest（diffHash commit-invariant + reuse 规则 #2 允许 HEAD 前移 → run 的 checkpoint commit 不破坏复用），submit 也可复用 compile 结果。详见 `../protocols/ledger-protocol.md`。
+>
+> **Ledger v3（v2 契约 / split-v1 布局起）**：`record` 自动解析并强制顶层身份（`schemaVersion=3/repositoryId/changeName/baseCommit/currentHead/diffHash/ownershipHash`），缺字段非零退出、不写账本；`--metrics-json` 必须通过 typed schema（unit=`total/passed/failed`，apiContract=`scenariosTotal/passed/failed`，browserE2E=`total/passed/failed`，dbCompatibility=`applicability(+reason)`）；新增 `--base-commit/--diff-hash/--applicability/--applicability-reason`。legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
 
 阶段边界：`harness_gate.py begin/close`；测试跟踪：`harness_test_guard.py begin/close`。close 失败不得用自然语言覆盖。
 
@@ -789,6 +791,36 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 在 harness-test 通过前，不建议也不应进入 `/harness-submit`。
 ```
 
+## CLI 速查（gate / ledger）
+
+> 可直接复制；替换 `<skills-root>` / `<cn>` / `<dir>` / `<project>`。`--task` **仅在该 change 启用 checkpoint 时必需**（checkpoints 文件缺失或不含 pending foundation-gate 时不要传）。
+> `ledger record` 必需：`--duration-ms`、`--evidence`，以及 `--files`（逗号分隔源文件）或 `--profile-input <verificationKey> --project <project>`（从 build-profile 展开）。`status` 枚举: `ok|fail|not_run`（没有 PASS）。
+> `--skills-root` 仅用于 `begin`（及 `lint-skills`）：必须是 adapter 根（如 `.cursor/skills`），不是 `scripts/` 子目录。**`close` 不需要 `--skills-root`**（该子命令不接受此参数）。
+
+```powershell
+# gate begin/close（--task 仅在该 change 启用 checkpoint 时必需；close 不需要 --skills-root）
+python <skills-root>/scripts/harness_gate.py begin --change <cn> --phase run --skills-root <skills-root> [--task N]
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase run --status OK [--task N]
+
+# ledger 记录（status: ok|fail|not_run —— 没有 PASS）
+python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification unitTestFull --status ok --command "<完整命令>" --exit-code 0 --duration-ms 120000 --evidence "Tests run: 155, Failures: 0, Errors: 0, Skipped: 0" --coverage full --files "packages/core/src/index.ts"
+
+# 复用检查（--profile-input 取 verification key，不是文件路径；配合 --project）
+python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --verification unitTestFull --profile-input unitTestFull --project <project>
+```
+
+### 常见报错对照
+
+| 报错 | 原因 | 处理 |
+|------|------|------|
+| `unsupported status: PASS` | ledger status 无 PASS | 改用 `ok` / `fail` / `not_run` |
+| `TASK_NUMBER_REQUIRED` | 该 change 启用了 checkpoint（如 foundation-gate pending） | 补 `--task N` |
+| skills-root / BUNDLE_IDENTITY_* | `begin` 未传或传了 `.../scripts` 子目录（`close` 不接受该参数） | 仅对 `begin` 显式传 adapter 根：`.cursor/skills` / `.claude/skills`（含 `.harness-build.json`） |
+| `--profile-input` 指向文件路径 | 参数语义是 verification key | 传 `compile` / `unitTestFull` 等 key，不是 JSON 路径 |
+| `record requires --files or a non-empty --profile-input file set` | 缺少输入文件集 | 补 `--files` 或 `--profile-input <key> --project <project>` |
+| `--profile-input requires --project` | can-reuse/record 展开 profile 需要项目根 | 补 `--project <project>` |
+| `record` 缺 `--duration-ms` / `--evidence` | 参数为必填 | 按模板补齐 |
+
 ## 关键原则
 
 - 增量构建优先：`powershell.exe -Command "<构建命令> <模块定位参数>"`（Java 示例：`mvn compile -pl <module> -o -q`，不用 clean，用离线模式加速）

package/harness/bundles/general/codex/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=5b2756a71712c9d3; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ca4e4b55f29590dc; overlay=none; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -57,7 +57,7 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 ### 提交流程（步骤 0–7）
 
 0. **启动准备** — `harness_change.py resolve` 确定变更名；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（禁止手写 ledger / 手工 phase.end）
-1. **合并最新代码** — 主目录：`stash` → `pull --rebase` → `stash pop`；**worktree：N/A**（远端同步在合并段主分支完成）
+1. **合并最新代码** — 主目录与 worktree 均**不在业务工作区 stash/pull**；远端同步由合并段 integration transaction 在隔离 integration worktree 内完成（见「worktree 合并流程」）；**正常路径禁止 `git stash` / `stash pop`**
 2. **最终验证** — ledger 复用优先；**提交前最终门禁只调 `can-reuse`**（删除与 coverage 冲突的二次全量门禁）：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <resolved commands.unitTestFull.command>`。`--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command，**不复制示例模块名**（文档示例只展示 key）。`--profile-input unitTestFull` 从 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开依赖闭包，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包。`reuse=true` → 不再执行二次全量测试；仅 `reuse=false` 时执行**同一 resolved verification**（profile `unitTestFull` 命令），成功后用同一文件集、command、`scope=module` 经 **`harness_ledger.py record`** 写回 ledger `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
 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. **提交方式** — 主目录：AskUserQuestion 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**
@@ -69,15 +69,20 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 
 ### worktree 合并流程（requested=true，commit 后自动执行）
 
+合并由 `harness_integration.py` transaction 执行：隔离 integration worktree + journal + 保护 ref + 精确清理。skill 只负责确认提交信息、调用子命令、展示结构化结果；**禁止手工 `checkout --ours/--theirs`**。
+
 M0. append `phase.start`（phase=merge，若从 `/harness-merge` 重入则 note 标注重入）
-M1. **切回主目录主分支** — `symbolic-ref origin/HEAD` 读主分支名；必要时 stash；确认 checkout 主分支
-M2. **fetch + pull --rebase** — 记录是否引入他人提交（决定 M4 是否重跑验证）
-M3. **`git merge --no-ff worktree/<change-name>`** — 合并消息可让用户改文案，**方式固定 --no-ff**
-M4. **冲突处理** — 若 `CONFLICT` → **停下**，列出冲突文件，提示用户手动解决后重跑；**禁止 `checkout --theirs/--ours`**；状态 🟡WARN，不得宣称合并成功
-M5. **合并后验证** — 他人提交引入 → 必须重跑构建+测试；否则 ledger 复用 🔁REUSED
-M6. **push 主分支** — fetch 后 `log HEAD..@{u}` 非空则回 M2；否则 push，记录 `mergeFinalHash`
-M7. **清理 worktree** — `worktree remove` + `branch -D`（Windows 兜底见 `reference.md`）；更新 `worktree.json`（`created=false` + removedAt 等）
-M8. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
+M1. **preflight** — `harness_integration.py preflight --change <id> --run-id <run> --feature-branch worktree/<id> --target-branch <主分支> --temp-root <task temp>`；获取 integration lock、写 journal 与保护 ref；锁被持有即停止
+M2. **prepare** — fetch 后从已提交 target 创建临时 integration worktree；primary 的 dirty 状态不被触碰
+M3. **merge** — `--no-ff` 合并 feature 分支；merge diff 出现其他 Change 的 contract/runtime 路径 → 结构化拒绝；冲突 → step FAILED，**停下**列出冲突文件，人工解决后以 `recover` 续跑（已完成步骤返回 REUSED，不重复 merge/push）
+M4. **verify** — 在 integration worktree 内执行组合态验证；他人提交引入或 ledger 不可复用时必跑
+M5. **push** — 仅在验证身份与远端基线仍匹配时 push；远端漂移 → `TARGET_MOVED` 结构化失败，不继续
+M6. **cleanup** — `git worktree remove --force` 精确路径 + 临时分支 + （push 成功后）保护 ref；释放 integration lock；失败保留 journal 与诊断证据；更新 `worktree.json`（`created=false` + removedAt）
+M7. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`（= journal `pushedHead`）；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
+
+> Ledger v3（v2 契约 / split-v1 布局起）：`record` 强制顶层身份（`schemaVersion=3/repositoryId/baseCommit/currentHead/diffHash/ownershipHash`，缺失非零退出、不写账本）与 typed metrics；legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
+
+正常路径**禁止创建、应用或删除仓库级 stash**。中断恢复：`harness_integration.py status` 读 journal，`recover` 从首个未完成步骤续跑；protection refs 只在 push 成功后的 cleanup 删除。
 
 ## P0 执行可信度规则
 

package/harness/bundles/general/codex/harness-submit/checklist.md

@@ -36,25 +36,24 @@ description: harness-submit 的8 步工作流详细步骤和执行日志记录
 
 > **分支名自动读取**：不硬编码 `master` 或 `main`，使用 `git rev-parse --abbrev-ref @{u}` 自动读取 upstream 分支。
 
+**正常路径禁止 `git stash` / `stash pop`**。远端同步不在业务工作区执行；主目录与 worktree 模式统一由合并段的 `harness_integration.py` transaction 在隔离 integration worktree 内 fetch + merge：
+
 ```powershell
-# 0. 自动读取 upstream
+# 0. 自动读取 upstream 与目标分支（只读操作）
 powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref @{u}"
 
-# 1. 暂存当前变更
-powershell.exe -Command "git -C '<项目路径>' stash"
-
-# 2. 拉取并合并远程
-powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+# 1. preflight：获取 integration lock + 写 journal/保护 ref
+python harness/scripts/harness_integration.py preflight --change <change-name> --run-id <run-id> --feature-branch <feature> --target-branch <target> --temp-root <task-temp>
 
-# 3. 恢复暂存的变更
-powershell.exe -Command "git -C '<项目路径>' stash pop"
+# 2. prepare：fetch + 从已提交 target 创建临时 integration worktree
+python harness/scripts/harness_integration.py prepare --change <change-name> --run-id <run-id> --feature-branch <feature> --target-branch <target> --temp-root <task-temp>
 ```
 
 **Shell 安全规则（强制）**：
 - 任何 git 命令被 hook 拒绝（`Denied` / `PreToolUse:Bash hook error`）→ 停止流程，不得宣称"拉取成功"
-- 拉取成功的判断证据：git 输出包含 `Already up to date.` 或 `Fast-forward`、`Updating <hash>..<hash>`，且 exit code 为 0
+- transaction 各步骤状态以 journal 为唯一事实源；FAILED 步骤用 `recover` 续跑，不重复已完成副作用
 
-如果 stash pop 冲突或 merge 冲突，参考 `reference.md` 的常见问题处理。
+merge 冲突或 `TARGET_MOVED` 时，参考 `reference.md` 的恢复清单；**禁止 `checkout --ours/--theirs`**。
 
 ## 步骤 2：最终验证（ledger 复用优先）
 
@@ -311,122 +310,87 @@ powershell.exe -Command "git -C '<项目路径>' rev-parse HEAD"
 
 ---
 
-## worktree 合并流程（步骤 M0–M8）
+## worktree 合并流程（integration transaction，M0–M7）
 
-> worktree 模式 commit 成功后自动执行；用户仅说「合并分支」/`/harness-merge` 且已有本地 commit 时从 M0 重入。合并方式固定 `--no-ff`；冲突 → 停下 → 用户手动解 → 确认后继续；**禁止 `checkout --theirs/--ours`**。
+> worktree 模式 commit 成功后自动执行；用户仅说「合并分支」/`/harness-merge` 且已有本地 commit 时从 M0 重入。合并由 `harness_integration.py` transaction 执行：隔离 integration worktree + journal + 保护 ref + 精确清理。**禁止 `checkout --theirs/--ours`；正常路径禁止仓库级 stash。**
 
 ### P0 合并稳定性门禁
 
 - 主分支名不硬编码，用 `git symbolic-ref --short refs/remotes/origin/HEAD` 读取
 - push 只在主分支；worktree 分支不 push
-- 所有 git 命令通过 `powershell.exe -Command "..."` 执行
+- 所有 git 命令通过 `powershell.exe -Command "..."` 执行（transaction 脚本内部 git 调用除外）
+- transaction 步骤状态以 `.harness/state/integration/<transaction-id>/journal.json` 为唯一事实源
 
 ### 步骤 M0：启动合并段
 
 append `phase.start`（`--phase merge`；`note` 含 worktree 分支、主分支、ledger diffHash、验证策略；重入时 note 标注「重入 merge」）。
 
-### 步骤 M1：切回主目录主分支
-
-```powershell
-powershell.exe -Command "git -C '<项目路径>' symbolic-ref --short refs/remotes/origin/HEAD"
-powershell.exe -Command "git -C '<项目路径>' stash"   # 主目录有未提交变更时
-powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref HEAD"
-```
-
-不在主分支则 `git checkout <主分支>`。
-
-### 步骤 M2：fetch + 同步主分支
+### 步骤 M1：preflight
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' fetch origin"
-powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+python harness/scripts/harness_integration.py preflight --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-pull 输出非 `Already up to date.` → 引入他人提交 → M4 必须重跑验证。
+获取 integration lock、解析 base/feature head、写 journal 与保护 refs（`refs/harness/integration/<txn>/base|head`）。锁被其他 run 持有 → **停止**，不改动工作区与状态文件。
 
-**CRLF 预检**（pull 后强制）：旧 working copy 的 `.gitattributes eol=lf` 文件可能是 CRLF（.gitattributes 后加未重新检出），曾导致 `core_content_hash` 跨工作树不一致 → sync 产生 dirty → M5 失败重跑。检测并修复：
+### 步骤 M2：prepare
 
 ```powershell
-# 1. renormalize 暴露 CRLF 漂移（仅规范化行尾，不改内容语义）
-powershell.exe -Command "git -C '<项目路径>' add --renormalize ."
-# 2. 若 git status --porcelain 非空 → working copy 存在 CRLF 漂移
-powershell.exe -Command "git -C '<项目路径>' status --porcelain"
-# 3. 有漂移 → 弃 staging + 强制 LF 重检（worktree 合并段 M2 在主仓库 main，应 clean，安全）
-powershell.exe -Command "git -C '<项目路径>' reset -q; git -C '<项目路径>' checkout -- ."
-# 4. 重新 renormalize 确认 clean（git status --porcelain 应空）
-powershell.exe -Command "git -C '<项目路径>' add --renormalize .; git status --porcelain"
+python harness/scripts/harness_integration.py prepare --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-> cluster 1 的 `core_content_hash` 改用 git blob sha 后，CRLF 不再影响 core hash，但 working copy CRLF 仍可能影响 workflow-data 包内容 hash，预检仍有价值。
+fetch 后从**已提交** target 创建临时 integration worktree；primary 的 staged/unstaged/untracked/ignored 与 mtime 均不被触碰。
 
-### 步骤 M3：合并 worktree 分支
+### 步骤 M3：merge
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' merge --no-ff worktree/<change-name>"
+python harness/scripts/harness_integration.py merge --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-合并消息默认 `Merge branch 'worktree/<change-name>'`，用户可改文案，**方式固定 --no-ff**。
+- 方式固定 `--no-ff`；merge diff 出现其他 Change 的 contract/runtime 路径 → 结构化 `FOREIGN_CHANGE_PATHS` 拒绝
+- 冲突 → step FAILED：**停下**，`git -C <integration-worktree> diff --name-only --diff-filter=U` 列冲突文件，提示用户手动解决；保护 refs 与 journal 保留
+- 人工解决后以 `recover` 续跑；已完成步骤返回 REUSED，不重复 merge
 
-### 步骤 M4：冲突处理
+### 步骤 M4：verify（组合态验证）
 
-若输出 `CONFLICT`：
+在 integration worktree 内执行验证命令；远端引入他人提交或 ledger 不可复用时必跑：
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=U"
+python harness/scripts/harness_integration.py verify --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp> --command "<resolved command>"
 ```
 
-- 列出冲突文件，**停下**，提示用户手动解决（编辑 → `git add` → `git commit`）
-- 状态 `🟡WARN(merge 冲突，待手动解决：<文件列表>)`
-- 用户确认解决后重跑 submit（从 M0 重入）
-- **禁止自动 `git checkout --theirs/--ours`**
-
-### 步骤 M5：合并后验证（ledger 复用优先）
-
-- 步骤 M2 引入他人提交 → **必须重跑** 构建+测试
-- 否则 diffHash 一致且 post-test 非行为性 → 🔁REUSED
-
-重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
+任一命令非零退出 → step FAILED，不进入 push。
 
-**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check。三重校验（marker ts<10min + command + commit tree），任一不满足照跑。marker 写入时记录 `git write-tree`，因此验证后创建 commit 不会仅因 HEAD 前移而使缓存失效。
+**写 check-ok marker**（npm run check exit 0 后强制）：
 
 ```powershell
-# npm run check exit 0 后立即写 marker（M5 或 REUSED 后均可）
 powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
 ```
 
-> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 比较 `HEAD^{tree}` 与 marker 的 `treeHash`，再校验 ts<10min + command；commit tree 未变化即可跳过，任何内容变化都照跑（安全默认）。
-
-### 步骤 M6：push 主分支
+### 步骤 M5：push
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' fetch"
-powershell.exe -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+python harness/scripts/harness_integration.py push --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-远端有新提交 → 回 M2；无则：
-
-```powershell
-powershell.exe -Command "git -C '<项目路径>' push"
-```
-
-记录 `mergeFinalHash`：`git rev-parse HEAD`。
-
-### 步骤 M7：清理 worktree
+远端基线漂移 → `TARGET_MOVED` 结构化失败，不继续。成功后 journal `pushedHead` 即 `mergeFinalHash`。
 
-若存在 test-tracking manifest，删除 worktree 前必须逐一确认 manifest 路径已包含在 worktree commit 中，且合并后的主分支可用 `git ls-files --error-unmatch -- <exact-path>` 找到；任一路径缺失即停止清理并报告，防止 ignored test 随 worktree 被永久删除。
+### 步骤 M6：cleanup
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' worktree remove '<worktree-path>' --force"
-powershell.exe -Command "git -C '<项目路径>' branch -D worktree/<change-name>"
+python harness/scripts/harness_integration.py cleanup --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-> Windows 兜底见 `reference.md`「Worktree 清理兜底（Windows）」。
+- `git worktree remove --force` 精确路径 → 验证注销 → 临时分支 `branch -D` → （push 成功后）删除保护 refs → 释放 integration lock
+- 清理只接受 journal 登记的精确 integrationRoot；仓库根、父目录、空路径、逃逸路径与其他 transaction 路径一律拒绝
+- 失败保留 journal 与诊断证据，状态 🟡WARN，不得宣称清理完成
+- 若存在 test-tracking manifest，确认其路径已由合并后的目标分支跟踪（`git ls-files --error-unmatch -- <exact-path>`），缺失即停止
 
 更新 `meta/worktree.json`：`created=false` + `removedAt`/`removedBy`/`removalNote`。
 
-### 步骤 M8：更新 ledger + 收尾
+### 步骤 M7：更新 ledger + 收尾
 
-ledger 顶层写入 `"mergeFinalHash": "<hash>"`；append `phase.end`（merge 段）。
+ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。
 
 ```markdown
 ## 合并完成 — <change-name>

package/harness/bundles/general/codex/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=5b2756a71712c9d3; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ca4e4b55f29590dc; overlay=none; agent=codex; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -15,6 +15,21 @@ description: 检查并更新项目AI元数据（CodeGraph索引、harness-codeba
 
 ## Workflow（薄编排）
 
+运行开始先执行受管 runtime 生命周期：
+
+```powershell
+python <skills-root>/scripts/harness_sync.py reap --project . --json
+python <skills-root>/scripts/harness_sync.py begin --project . --run-id <run-id> --agent <agent> --purpose harness-sync --json
+```
+
+所有 deploy 临时产物只能写入 `begin` 返回的 `workspace`。无论正常完成、命令失败还是异常退出，都必须在 `finally` 中执行：
+
+```powershell
+python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-id> --json
+```
+
+禁止重新使用固定 `sync-deploy-*` 目录；`--keep-temp` 仅供显式诊断。
+
 | Phase | 检查 → 动作 |
 |-------|-------------|
 | 0 | 读 SKILL + `reference.md` + protocols |
@@ -25,7 +40,7 @@ description: 检查并更新项目AI元数据（CodeGraph索引、harness-codeba
 | 3.6 | 单次运行 `harness_knowledge.py maintain --project . --drain --json`，有界推进全部 `.harness/knowledge/maintenance-outbox/{pending,failed}`；不得为每个条目重复启动 Python/重建索引（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/pending-judge） |
 | 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
 | 5 | AGENTS.md 与 CLAUDE.md 一致 |
-| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；可选 `harness_deploy.py diff` 检查已装 skill 是否过期 |
+| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
 | 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
 
 状态判断表格、修复动作、输出示例 → `reference.md`

package/harness/bundles/general/codex/harness-sync/reference.md

@@ -75,8 +75,8 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 | state 目录 | `.harness/state/baseline/` 存在（internal_state） | ✅OK | 无需操作 |
 | codebase map | `.harness/codebase/map/` 状态 | — | 见第 3 步 |
 | 整体缺失 | `project.yaml` 与 `context-index.json` 均不存在 | ❌FAIL(未初始化) | 执行 `hunter-harness init`（见下方风险规程） |
-| .gitignore 选择性跟踪 | 未整条忽略 `.harness/`：user_editable（project.yaml/knowledge/）、generated_reviewable（codebase/map）多需跟踪；internal_state（state/）、generated_cache（cache/、generated/、reports/）不跟踪 | ✅OK | 无需操作 |
-| .gitignore 整体忽略 | `.gitignore` 含整条 `.harness/` | 🟡WARN(过度忽略) | 提示按 file-policy 拆分跟踪策略，而非整体忽略 |
+
+> sync 不读取、不修改也不建议修改项目 `.gitignore` 策略（RET-34/35）：三种跟踪策略（整体忽略 / 选择性跟踪 / 完全跟踪）下完整性结论相同，新鲜度由 post-adaptation projection 判定，与 Git 策略无关。
 
 > ⚠️ **`hunter-harness init` 风险规程**（`.harness/` 未初始化时触发）：
 > 1. **预览**：`node packages/cli/dist/bin.js --non-interactive --dry-run --adapter claude-code --profile general --json`，确认将写入的路径清单与 `project_id`（`null` = 未绑服务器，本地自治理）。

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

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

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

@@ -293,6 +293,15 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] durationMs > 10000 → 🟡SLOW，说明原因
 - [ ] durationMs > 30000 → ❌TIMEOUT_RISK，说明原因
 
+### 覆盖标注诚实性（✅ 实测 vs 🟡 推断）
+
+场景状态标注规则：
+
+- [ ] ✅ 仅当断言实际执行**且**场景声明的前置条件/数据真实构造
+- [ ] 🟡（推断）：未构造场景条件、以相邻场景或同接口行为推断时使用，必须注明推断依据
+- [ ] 用同一请求重复调用来"覆盖"不同异常场景 → 一律 🟡
+- [ ] 报告汇总行的通过数只统计 ✅（不含 🟡 推断）
+
 ## 关门检查（⚠️ 结束前强制执行）
 
 - [ ] `powershell.exe -NoProfile -Command "git status --porcelain"`

package/harness/bundles/general/codex/harness-test/pitfalls-java.md

@@ -0,0 +1,14 @@
+---
+description: Java/Feign 相关测试踩坑（harness-test）。API 实测前通读；发现客户端路径缺陷时回写 plan 外修复记录。
+---
+
+# Java 测试踩坑补充（Feign / 远程客户端）
+
+> 与 `pitfalls.md`（通用）及 `overlays/java/pitfalls-java.md`（overlay 速查表）互补；本文件收录路径拼接类缺陷的症状与流程要求。
+
+## Feign/客户端路径前缀缺失
+
+**症状**：服务正常、接口 200，但客户端拿到 404 / 空数据 / fallback 生效。
+**根因模式**：`@FeignClient` 方法上只写了 `@GetMapping("/type")`，漏掉服务端类级前缀（如 `/system/dict-data`）。
+**定位**：对照服务端 controller 完整映射（类级 `@RequestMapping` + 方法级注解），或看服务端访问日志中的实际 404 路径。
+**流程要求**：此类缺陷若在 test 阶段被 API 实测发现，属于"计划外修复"——必须记 decision 事件（含根因与修复文件），并检查同客户端文件的其余方法是否同源错误。