@hunter-harness/workflow-harness 0.2.11 → 0.2.13

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "61a84d6f204a76ae"
+  "coreHash": "8dd8ce9aa1ac47f5"
 }

package/harness/bundles/general/claude-code/contracts/ci-metrics.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hunter-harness.dev/contracts/ci-metrics.schema.json",
+  "title": "Hunter Harness CI Metrics",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runner",
+    "source",
+    "suites",
+    "passed",
+    "failed",
+    "skipped",
+    "setupErrors",
+    "durationMs",
+    "headSha"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runner": { "enum": ["junit", "vitest", "playwright"] },
+    "source": { "type": ["string", "null"] },
+    "suites": { "type": ["integer", "null"], "minimum": 0 },
+    "passed": { "type": ["integer", "null"], "minimum": 0 },
+    "failed": { "type": ["integer", "null"], "minimum": 0 },
+    "skipped": { "type": ["integer", "null"], "minimum": 0 },
+    "setupErrors": { "type": ["integer", "null"], "minimum": 0 },
+    "durationMs": { "type": ["integer", "null"], "minimum": 0 },
+    "headSha": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }
+      ]
+    }
+  }
+}

package/harness/bundles/general/claude-code/contracts/workflow-policy.json

@@ -138,6 +138,36 @@
     "submit": [],
     "package": ["package"]
   },
+  "validationPhases": {
+    "compile": "run",
+    "unitTest": "run",
+    "unitTestFull": "test",
+    "apiTest": "test",
+    "dbCompatibility": "test",
+    "package": "package"
+  },
+  "capabilityGates": {
+    "deployment": {
+      "signals": ["deploy-required"],
+      "requiredStages": ["package"],
+      "requiredValidations": ["package"]
+    },
+    "container": {
+      "signals": ["install-verification"],
+      "requiredStages": ["package"],
+      "requiredValidations": ["package"]
+    },
+    "api": {
+      "signals": ["api-diff-present"],
+      "requiredStages": ["apidoc"],
+      "requiredValidations": ["apiTest"]
+    },
+    "database": {
+      "signals": ["migration"],
+      "requiredStages": [],
+      "requiredValidations": ["dbCompatibility"]
+    }
+  },
   "conditionalStages": {
     "review": {
       "tiers": ["standard", "full"],

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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; 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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; 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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; 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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -76,7 +76,7 @@ disallowed-tools:
 
 | 阶段 | 动作 |
 |------|------|
-| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
+| 0 | 用当前解释器运行 `harness_runtime.py doctor`，后续消费绝对 argv；git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
 | 0.5 | 先初始化 change-name + `phase.start`，从第一条知识查询起保留事件证据 |
 | 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
@@ -84,7 +84,7 @@ disallowed-tools:
 | 4 | **设计审批包** AskUserQuestion；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 产物完整性必检 → `checklist.md` |
+| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`；原子发布、唯一 `phase.end`、render → `checklist.md` |
 
 change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
 
@@ -100,7 +100,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
 | 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
-| 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
+| 阶段 8 | spec/plan/detail/scenarios/worktree.json 先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，失败不得手工补终态 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
 | 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |

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

@@ -213,6 +213,12 @@ source: harness-plan
 
 > **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
 
+- [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
+- [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id ... --attempt ... --json`
+- [ ] finalizer 返回 `ok=true` 与 `artifactsHash`；重复执行返回 `idempotent=true`
+- [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
+- [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
+
 | 文件 | 必须存在 | 检查结果 |
 |------|:---:|:---:|
 | `.harness/changes/<change>/spec/<change>-design.md` | ✅ | □ |

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

@@ -14,8 +14,11 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 {
   "requested": true,
   "created": false,
-  "path": ".claude/worktrees/<change-name>",
-  "branch": "worktree/<change-name>",
+  "agent": "<active-adapter>",
+  "worktreeRoot": "<adapter-worktree-root>",
+  "branchPrefix": "<adapter-branch-prefix>",
+  "path": "<adapter-worktree-root>/<change-name>",
+  "branch": "<adapter-branch-prefix><change-name>",
   "decisionBy": "user",
   "decisionAt": "YYYY-MM-DD HH:mm",
   "ownerSkill": "harness-run"
@@ -38,6 +41,8 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 
 ### 决策事件 note 示例
 
+`path` 与 `branch` 必须来自 `harness_runtime.py adapter`/`meta/runtime.json`，不得复制其他 agent 的历史路径。Codex 的合同固定为 `.codex/worktrees/<change-name>` 与 `codex/<change-name>`。
+
 `用户选择使用 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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

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

@@ -10,13 +10,14 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 
 ### 步骤 0.0：Worktree 决策执行 ⚠️
 
+- [ ] 运行 `harness_runtime.py doctor` 并读取 `meta/runtime.json`；后续使用绝对 executable 与 argv 数组
 - [ ] 读取 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）
 - [ ] 如果文件缺失：🟡WARN，按 legacy 逻辑询问用户是否主目录执行或创建 worktree
 - [ ] `requested=false` → 主目录执行，记录原因
 - [ ] `requested=true` 且 worktree 存在 → 切换到 worktree 执行
 - [ ] `requested=true` 且 worktree 不存在 → 必须创建 worktree
 - [ ] worktree 创建命令必须使用 PowerShell：`git worktree add ...`
-- [ ] 创建后验证 `.claude/worktrees/<change-name>/.git` 存在
+- [ ] 创建后验证 `<adapter-worktree-root>/<change-name>/.git` 存在；Codex 必须是 `.codex/worktrees/<change-name>`
 - [ ] 创建成功后更新 `meta/worktree.json` 的 `created=true/createdAt/createdBy`
 - [ ] 创建失败 → 停止，或 AskUserQuestion 询问是否改为主目录执行
 - [ ] 禁止 `requested=true && worktree 不存在` 时直接主目录执行
@@ -219,7 +220,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 
 > 仅在 worktree 中执行时触发此步骤。在主目录执行时跳过（标记 ⏭️主目录跳过）。
 
-- [ ] 确认当前 cwd 在 `.claude/worktrees/<change-name>/` 下
+- [ ] 确认当前 cwd 在 `<adapter-worktree-root>/<change-name>/` 下，且 branch 使用 adapter 的 prefix
 - [ ] 生成变更摘要：`git diff --stat` + `git diff --stat --cached`
 - [ ] 构建 commit message：`wip(<scope>): <change-name> 编码完成 — N任务/M文件变更`
 - [ ] **⚠️ 强制阻断**：用 AskUserQuestion 展示变更列表 + commit message，等待用户确认

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

@@ -49,20 +49,22 @@ requested=true + path missing
 
 ### PowerShell 命令模板
 
+先执行 runtime doctor，并从 `meta/runtime.json` 读取 adapter 的 `path`、`branch` 以及 PowerShell `argvPrefix`；不要依赖裸 `python`/`powershell.exe`，也不要硬编码 Claude 路径。
+
 ```powershell
-powershell.exe -NoProfile -Command "git worktree add '.claude/worktrees/<change-name>' -b 'worktree/<change-name>'"
+& <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' -b '<adapter-branch>'"
 ```
 
 如果分支已存在：
 
 ```powershell
-powershell.exe -NoProfile -Command "git worktree add '.claude/worktrees/<change-name>' 'worktree/<change-name>'"
+& <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' '<adapter-branch>'"
 ```
 
 验证：
 
 ```powershell
-powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.git'"
+& <powershell-argv-prefix> -Command "Test-Path -LiteralPath '<adapter-worktree-path>/.git'"
 ```
 
 ### 状态目录写入
@@ -72,7 +74,7 @@ powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.
 ```json
 {
   "projectRoot": ".../udp",
-  "worktreeRoot": ".../udp/.claude/worktrees/<change-name>",
+  "worktreeRoot": ".../udp/<adapter-worktree-root>/<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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -56,7 +56,7 @@ python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-
 | 3.5 | `harness_knowledge.py sync`；可 `sync --update`；失败不得假装可用。**知识闭环主入口**是 `/harness-knowledge-ingest auto`（含 Agent judge），sync 不重复列人工知识待办 |
 | 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 一致 |
+| 5 | AGENTS.md 与各 Agent 指令入口一致；Claude Code 启用时验证 CLAUDE.md 引用 AGENTS.md，禁止反向循环引用 |
 | 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
 | 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
 

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

@@ -19,16 +19,17 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 
 ### 2. CodeGraph 索引
 
-检查索引状态，**优先使用 MCP 工具**（若当前环境提供 `mcp__codegraph__codegraph_status` 则调用）；该工具不可用时**降级**为用 Glob 比对 `.codegraph/` 目录修改时间与最近提交时间。不允许通过普通 Bash 调 codegraph 命令：
+检查索引状态，**优先使用 MCP 工具**：若当前环境提供 `mcp__codegraph__codegraph_status` 则调用；没有 status 工具但提供 `codegraph_explore` 时，执行一次只读查询验证索引确实可响应，再用 Glob 比对 `.codegraph/` 目录修改时间与最近提交时间。两种 MCP 工具都不可用时才仅按时间戳降级。不允许通过普通 Bash 调 codegraph 命令：
 
 | 判断条件 | 状态 | 操作 |
 |----------|:----:|------|
 | 覆盖率 > 0% 且索引时间在最近提交之后 | ✅OK | 无需操作 |
+| `codegraph_explore` 查询成功且索引时间在最近提交之后 | ✅OK（功能已验证，覆盖率数值未暴露） | 报告真实证据，不虚构覆盖率百分比 |
 | 覆盖率 = 0% | ❌FAIL(未初始化) | 通过 PowerShell 执行 `npx @colbymchenry/codegraph && codegraph init --index` |
 | 索引时间在最近提交之前 | 🟡WARN(过期) | 同上 |
 
 > 前提：项目构建命令必须已成功。构建失败时先执行 `npx hunter-harness` 初始化检查。
-> 若 MCP 工具与 codegraph CLI 均不可用，标记 🟡WARN(CodeGraph 状态无法验证) 并在报告中说明"CodeGraph 状态无法验证，需用户手动确认"。
+> 若 status/explore MCP 工具均不可用，且时间戳证据也不足，标记 🟡WARN(CodeGraph 状态无法验证) 并在报告中说明具体缺失证据。成功的 explore 只能证明索引可用，不得伪造覆盖率数值。
 
 ### 3. harness-codebase-map 分析文档
 
@@ -61,7 +62,7 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 
 ### 5. AGENTS.md 一致性
 
-检查 `AGENTS.md` 是否引用最新版 CLAUDE.md，是否包含项目概述和规则索引。如果 CLAUDE.md 刚刚更新过，同步更新 AGENTS.md 中的引用描述。
+检查 `AGENTS.md` 是否包含项目概述和规则索引。Claude Code adapter 启用时，检查 `CLAUDE.md` 引用 `AGENTS.md`（canonical managed block 使用 `@AGENTS.md`），让共享约束保持单一来源；不得要求 `AGENTS.md` 反向引用 `CLAUDE.md`，否则会形成循环，且会破坏未启用 Claude Code 的项目。
 
 ### 6. .harness/ 完整性
 
@@ -133,7 +134,7 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 | CodeGraph | 🟡WARN(索引过期) | 索引已过期（上次: 3天前，最近提交: 今天），已重新索引 |
 | harness-codebase-map (.harness/codebase/map/) | ✅OK | 2 天前更新，变更量 5 个文件，无需更新 |
 | CLAUDE.md | ✅OK | 180 行，6 个必要章节完整 |
-| AGENTS.md | ✅OK | 已正确引用 CLAUDE.md |
+| AGENTS.md | ✅OK | 共享规则索引完整；CLAUDE.md 已单向引用 AGENTS.md |
 | .harness/ | ✅OK | config 目录存在，1 个变更目录（contribution-module） |
 
 ### 自动更新

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=61a84d6f204a76ae; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose