@hunter-harness/workflow-harness 0.2.17 → 0.2.19

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "d5b51ad56d4d4535"
+  "coreHash": "71f31413c45ca599"
 }

package/harness/bundles/general/claude-code/harness-archive/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -50,6 +50,12 @@ disallowed-tools:
 - commit 已 push（`git log @{u}..HEAD` 输出为空）
 - **最终 hash 来源**：worktree 模式（`meta/worktree.json` requested=true）下读 ledger 的 `mergeFinalHash`（由 `/harness-submit` 合并段写入）；主目录模式读 submit 的 `final pushed hash`。当前 `git rev-parse HEAD` 须一致
 - test 报告存在或标记"跳过"；review 报告存在或标记"未运行 review"（review 不阻塞归档）
+- **最小必备集（H-4 / `harness_archive.py status` blockers）**：
+  - `plans/*-plan.md`
+  - 非空 `events.ndjson`
+  - `evidence/verification-ledger.json`
+  - 至少一个 test 或 review 报告/证据
+  - 缺失任一项 → `archivable=false`；可从 `.harness/cache/change-snapshots/<change>/` 恢复正式层后再重试
 
 ## Inputs
 

package/harness/bundles/general/claude-code/harness-archive/checklist.md

@@ -20,6 +20,12 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 - [ ] 未在调用 finalize 前手工追加 archive 阶段边界
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
+- [ ] **最小必备集 blockers**（`harness_archive.py status`）：
+  - [ ] `plans/*-plan.md` 存在
+  - [ ] `events.ndjson` 存在且非空
+  - [ ] `evidence/verification-ledger.json` 存在
+  - [ ] 至少一个 test 或 review 报告/证据
+  - [ ] 若缺失：优先从 `.harness/cache/change-snapshots/<change>/` 恢复，禁止空壳归档
 - [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
 - [ ] `events.ndjson` 存在；执行日志允许由 finalize 从事件流重新渲染（旧 archive 才兼容根目录 `execution-log.md`）
 - [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; 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/claude-code/harness-plan/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-plan/reference.md

@@ -15,10 +15,10 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
   "requested": true,
   "created": false,
   "agent": "<active-adapter>",
-  "worktreeRoot": "<adapter-worktree-root>",
-  "branchPrefix": "<adapter-branch-prefix>",
-  "path": "<adapter-worktree-root>/<change-name>",
-  "branch": "<adapter-branch-prefix><change-name>",
+  "worktreeRoot": ".worktrees",
+  "branchPrefix": "harness/",
+  "path": ".worktrees/<change-name>",
+  "branch": "harness/<change-name>",
   "decisionBy": "user",
   "decisionAt": "YYYY-MM-DD HH:mm",
   "ownerSkill": "harness-run"
@@ -41,7 +41,7 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 
 ### 决策事件 note 示例
 
-`path` 与 `branch` 必须来自 `harness_runtime.py adapter`/`meta/runtime.json`，不得复制其他 agent 的历史路径。Codex 的合同固定为 `.codex/worktrees/<change-name>` 与 `codex/<change-name>`。
+`path` 与 `branch` 必须来自 `harness_runtime.py adapter`/`meta/runtime.json`。所有 agent 共享统一路径 `.worktrees/<change-name>` 与统一分支前缀 `harness/`；`agent` 字段仅作创建者元数据，不再决定路径。
 
 `用户选择使用 Worktree；决策文件为 meta/worktree.json；requested=true, created=false；创建责任为 harness-run。`
 

package/harness/bundles/general/claude-code/harness-review/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-review/checklist.md

@@ -8,7 +8,7 @@ description: harness-review 的6维度审查检查项详细列表。仅在执行
 
 用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或询问用户。后续所有路径基于此变更名。
 
-**读取 worktree 状态**：读 `.harness/changes/<change-name>/meta/worktree.json`。`requested=true` 且 worktree 已创建 → 后续 `git diff` 的 `<项目路径>` 用 worktree 路径（`.claude/worktrees/<change-name>`）；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录。
+**读取 worktree 状态**：读 `.harness/changes/<change-name>/meta/worktree.json`。`requested=true` 且 worktree 已创建 → 后续 `git diff` 的 `<项目路径>` 用 worktree 路径（`.worktrees/<change-name>`）；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录。
 
 ## 审查流程
 

package/harness/bundles/general/claude-code/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/checklist.md

@@ -17,7 +17,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] `requested=true` 且 worktree 存在 → 切换到 worktree 执行
 - [ ] `requested=true` 且 worktree 不存在 → 必须创建 worktree
 - [ ] worktree 创建命令必须使用 PowerShell：`git worktree add ...`
-- [ ] 创建后验证 `<adapter-worktree-root>/<change-name>/.git` 存在；Codex 必须是 `.codex/worktrees/<change-name>`
+- [ ] 创建后验证 `.worktrees/<change-name>/.git` 存在
 - [ ] 创建成功后更新 `meta/worktree.json` 的 `created=true/createdAt/createdBy`
 - [ ] 创建失败 → 停止，或 blocking user confirmation 询问是否改为主目录执行
 - [ ] 禁止 `requested=true && worktree 不存在` 时直接主目录执行

package/harness/bundles/general/claude-code/harness-run/reference.md

@@ -76,7 +76,7 @@ requested=true + path missing
 ```json
 {
   "projectRoot": ".../udp",
-  "worktreeRoot": ".../udp/<adapter-worktree-root>/<change-name>",
+  "worktreeRoot": ".../udp/.worktrees/<change-name>",
   "stateDir": ".../udp/.harness/changes/<change-name>"
 }
 ```

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -96,12 +96,17 @@ M3. **merge** — `--no-ff` 合并 feature 分支；merge diff 出现其他 Chan
 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）
+M6.5. **formal snapshot** — mergeFinalHash 写入后调用 `harness_paths.snapshot_change_formal_layer(projectRoot, changeId)`，备份到主仓 `.harness/cache/change-snapshots/<change>/`（不得写在 feature worktree 内）
 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` 第十节。
+> Ledger v3（v2 契约 / split-v1 布局起）：`record` 强制顶层身份（`schemaVersion=3/repositoryId/baseCommit/currentHead/diffHash/ownershipHash`，缺失非零退出、`LEDGER_IDENTITY_INVALID`，不写账本）与 typed metrics；legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
 
 正常路径**禁止创建、应用或删除仓库级 stash**。中断恢复：`harness_integration.py status` 读 journal，`recover` 从首个未完成步骤续跑；protection refs 只在 push 成功后的 cleanup 删除。
 
+**失败 txn 回收（abandon）**：verify/push 未成功且 remote 不含 mergeCommit 时，运行 `harness_integration.py abandon --change … --run-id …`：清理 integrationRoot / temp branch / protection refs / lock；**绝不删除 feature worktree**。push 已成功或 remote 已含 merge → `ABANDON_REFUSED`，改走 cleanup。
+
+**清 feature worktree 迁根硬门槛（H-1/H-2）**：删除 feature worktree 前，若 Agent root / cwd 落在待删路径内，必须先 `move_agent_to_root(projectRoot)`（目标为主仓已存在的 `main`/`master`；**禁止**为迁根去 fetch 已删除的 feature 分支）。迁根失败 → **拒绝删除**。清理前调用 `harness_paths.assert_cleanup_safe(cleanupRoot, stateRoots, archiveRoots)`；state/archive（含 junction/symlink 解析后）落在 cleanup 内 → `CLEANUP_TOPOLOGY_REFUSED`。
+
 ## P0 执行可信度规则
 
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
@@ -133,6 +138,10 @@ test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许
 - **`git merge --no-ff` 固定**；禁止 fast-forward
 - **冲突不自动解** → 停下 → 用户手动解 → 确认后继续
 - **`mergeFinalHash`** = 主分支 push 后 HEAD；archive 优先读此字段
+- **迁根后再删 feature WT**：Agent 仍在待删 root 内则拒绝删除；目标分支已删时切主仓 `main`/`master`，禁止强行 fetch
+- **snapshot 后再清**：正式层已写入 `.harness/cache/change-snapshots/<change>/`
+- **拓扑安全**：`assert_cleanup_safe` 拒绝 state/archive ⊆ cleanup（含 junction）
+- **abandon ≠ cleanup**：仅失败 txn；永不删 feature worktree
 
 ### 五、Shell 安全 / 敏感信息 / 证据化
 

package/harness/bundles/general/claude-code/harness-submit/checklist.md

@@ -328,7 +328,7 @@ append `phase.start`（`--phase merge`；`note` 含 worktree 分支、主分支
 ### 步骤 M1：preflight
 
 ```powershell
-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>
+python harness/scripts/harness_integration.py preflight --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
 获取 integration lock、解析 base/feature head、写 journal 与保护 refs（`refs/harness/integration/<txn>/base|head`）。锁被其他 run 持有 → **停止**，不改动工作区与状态文件。
@@ -336,7 +336,7 @@ python harness/scripts/harness_integration.py preflight --change <change-name> -
 ### 步骤 M2：prepare
 
 ```powershell
-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>
+python harness/scripts/harness_integration.py prepare --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
 fetch 后从**已提交** target 创建临时 integration worktree；primary 的 staged/unstaged/untracked/ignored 与 mtime 均不被触碰。
@@ -344,7 +344,7 @@ fetch 后从**已提交** target 创建临时 integration worktree；primary 的
 ### 步骤 M3：merge
 
 ```powershell
-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>
+python harness/scripts/harness_integration.py merge --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
 - 方式固定 `--no-ff`；merge diff 出现其他 Change 的 contract/runtime 路径 → 结构化 `FOREIGN_CHANGE_PATHS` 拒绝
@@ -356,7 +356,7 @@ python harness/scripts/harness_integration.py merge --change <change-name> --run
 在 integration worktree 内执行验证命令；远端引入他人提交或 ledger 不可复用时必跑：
 
 ```powershell
-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>"
+python harness/scripts/harness_integration.py verify --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp> --command "<resolved command>"
 ```
 
 任一命令非零退出 → step FAILED，不进入 push。
@@ -370,7 +370,7 @@ powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
 ### 步骤 M5：push
 
 ```powershell
-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>
+python harness/scripts/harness_integration.py push --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
 远端基线漂移 → `TARGET_MOVED` 结构化失败，不继续。成功后 journal `pushedHead` 即 `mergeFinalHash`。
@@ -378,7 +378,7 @@ python harness/scripts/harness_integration.py push --change <change-name> --run-
 ### 步骤 M6：cleanup
 
 ```powershell
-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>
+python harness/scripts/harness_integration.py cleanup --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
 - `git worktree remove --force` 精确路径 → 验证注销 → 临时分支 `branch -D` → （push 成功后）删除保护 refs → 释放 integration lock
@@ -386,11 +386,26 @@ python harness/scripts/harness_integration.py cleanup --change <change-name> --r
 - 失败保留 journal 与诊断证据，状态 🟡WARN，不得宣称清理完成
 - 若存在 test-tracking manifest，确认其路径已由合并后的目标分支跟踪（`git ls-files --error-unmatch -- <exact-path>`），缺失即停止
 
+**失败 txn 改走 abandon（勿强行 cleanup）**：
+
+```powershell
+python harness/scripts/harness_integration.py abandon --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
+```
+
+仅当 push ≠ DONE 且 remote 不含 mergeCommit；清理 integration 产物后可换新 run-id 重开。push 成功 → `ABANDON_REFUSED`。
+
 更新 `meta/worktree.json`：`created=false` + `removedAt`/`removedBy`/`removalNote`。
 
+**删除 feature worktree 前（硬门槛）**：
+
+1. 若 Agent root / cwd 落在待删 worktree → 先 `move_agent_to_root(<projectRoot>)`；目标为主仓，feature 分支已删则切 `main`/`master`，禁止 fetch 已不存在分支
+2. 迁根失败 → **停止删除**
+3. `assert_cleanup_safe(cleanupRoot, [.harness/changes/<id>, .harness/state/...], [.harness/archive])`；`CLEANUP_TOPOLOGY_REFUSED` → 停止
+4. mergeFinalHash 已写后先 `snapshot_change_formal_layer`，再清 feature WT
+
 ### 步骤 M7：更新 ledger + 收尾
 
-ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。
+ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。正式层快照确认存在于 `.harness/cache/change-snapshots/<change-name>/`。
 
 ```markdown
 ## 合并完成 — <change-name>
@@ -399,6 +414,7 @@ ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_ga
 - 主分支 push: ✅（<old>..<new> → origin/<主分支>）
 - mergeFinalHash: `<merge-final-hash>`
 - 验证策略: 🔁REUSED / 🔄已重跑
-- worktree: 已清理
+- snapshot: `.harness/cache/change-snapshots/<change-name>/`
+- worktree: 已清理（迁根后）
 - 下一步: `/harness-archive`
 ```

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/general/claude-code/protocols/report-pipeline-protocol.md

@@ -43,6 +43,8 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 
 `append` 写入契约（Task 4 §6.1）：普通 append = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex`）；仅 `--type phase.end` append 成功后渲染一次 `logs/execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。人类可读摘要（触发指令、降级原因、阶段结论）写入事件的 `note` 字段；阶段开始/结束、命令、验证、artifact、问题、决策各写对应 `type` 事件。旧 archive 缺少 events 可回放兼容；新变更不得以 execution-log 已存在为理由跳过 events。
 
+**artifact 硬门禁（H-8）**：`--type artifact` **必须**带非空 `--path`（change 相对路径）。知识探索/预览类说明改用 `--type issue` 或 `--type decision`，禁止再用 `--kind informational` 伪装无 path 的 artifact。
+
 基础事件结构（schema_version 3；兼容读取 v1/v2）：
 
 ```json