@hunter-harness/workflow-harness 0.2.53 → 0.2.55

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "f636ed002f37b71f"
+  "coreHash": "e9b3973b8ba91be9"
 }

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

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

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

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

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

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -85,14 +85,14 @@ disallowed-tools:
 | 阶段 | 动作 |
 |------|------|
 | 0 | 用当前解释器运行 `harness_runtime.py doctor`，后续消费绝对 argv；git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
-| 0.5 | 先执行 `harness_context.py prepare --phase plan --executor <tool> [--change <id>] --json`，以其唯一 change/executionRoot 初始化 plan-run-id 与 attempt（首次为 1），用同一身份追加 `phase.start`；从第一条知识查询起保留事件证据，并在 finalizer 中复用该身份 |
+| 0.5 | 确定英文 `change-name` 后，根据需求生成一次简洁的中文展示标题（建议 6～24 个可见字符，保留必要产品名），执行 `harness_context.py prepare --phase plan --executor <tool> [--change <id>] --title "<中文标题>" --json`；英文名继续作为目录与稳定标识。以其唯一 change/executionRoot 初始化 plan-run-id 与 attempt（首次为 1），用同一身份追加 `phase.start`；从第一条知识查询起保留事件证据，并在 finalizer 中复用该身份 |
 | 1 | `harness-knowledge-query` 单次远端 query（失败记 `issue`，不建立本地索引或离线回退） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
 | 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；成功后执行 `harness_context.py close --from-phase plan --to-phase run --executor <tool> --artifact <plan-finalization> --json` 写 append-only handoff receipt；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
+| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；成功后把 finalizer 返回的绝对 `receiptPath` 原样传给 `harness_context.py close --from-phase plan --to-phase run --executor <tool> --artifact "<receiptPath>" --json`（也可使用返回的稳定 `artifactRef=meta/plan-finalization.json`），写 append-only handoff receipt；不得手写占位路径；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
 
 change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
 
@@ -113,6 +113,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 规则 | 要点 |
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
+| Change 标题 | 首次 Plan 同时确定英文 `change-name` 与中文展示标题；英文名保持目录和机器标识不变，中文标题由 `prepare --title` 持久化，后续阶段只复用、不重新生成 |
 | 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`） |
 | 阶段 8 | spec/plan/detail/scenarios/gate-policy/worktree 六项标准产物先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log；随后 `verify` 必须确认 start/end、收据完整覆盖六项标准产物、哈希、全部任务表和非空场景清单一致，失败不得手工补终态 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |

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

@@ -211,13 +211,14 @@ source: harness-plan
 
 - [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
 - [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id <plan-run-id> --attempt <attempt> --json`；身份必须与本次 `phase.start` 完全相同
-- [ ] finalizer 返回 `ok=true` 与 `artifactsHash`；重复执行返回 `idempotent=true`
+- [ ] finalizer 返回 `ok=true`、`artifactsHash`、绝对 `receiptPath` 与稳定 `artifactRef=meta/plan-finalization.json`；重复执行返回 `idempotent=true`
 - [ ] 紧接着执行 `harness_plan_finalize.py verify --change-dir ... --json`
 - [ ] verify 返回 `phaseStartCount=1`、`phaseEndCount=1`、`phaseEndStatus=OK`、`receiptConsistent=true`
 - [ ] 收据 `files` 完整包含 design / plan / implementation-detail / test-scenarios / gate-policy / worktree 六项标准产物；不得省略、重复或经 symlink/junction/reparse point 引用
 - [ ] verify 的 `taskCount` 等于全部任务表行数，`scenarioCount` 等于 Markdown 中全部唯一场景 ID 数；任一为 0 或不一致即 ❌FAIL
 - [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
 - [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
+- [ ] context close 的 `--artifact` 只传 finalizer 原样返回的 `receiptPath` 或 `artifactRef`，不得猜测、拼接或使用 `<plan-finalization>` 占位文本
 
 | 文件 | 必须存在 | 检查结果 |
 |------|:---:|:---:|

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -63,14 +63,16 @@ disallowed-tools:
 
 ## Workflow
 
-先用 `harness_context.py prepare --phase review --executor <tool> [--change <id>] --json` 与 `harness_context.py begin --phase review --change <id> --executor <tool> --json` 解析唯一 active change 并校验 test→review receipt；多个 active change 未显式选择时返回 `ACTIVE_CHANGE_AMBIGUOUS`，禁止再按 Glob/mtime 猜测。阶段门禁使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json` 和 `harness_gate.py close --phase review --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --json`；之后通过 `harness_context.py close --from-phase review --to-phase submit|run --executor <tool> --json` 交接或 fixback。不得手工追加 `phase.start/phase.end`；任一 close 失败不得宣称审查完成。
+先用 `harness_context.py prepare --phase review --executor <tool> [--change <id>] --json` 与 `harness_context.py begin --phase review --change <id> --executor <tool> --json` 解析唯一 active change 并校验 test→review receipt；多个 active change 未显式选择时返回 `ACTIVE_CHANGE_AMBIGUOUS`，禁止再按 Glob/mtime 猜测。阶段门禁使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json`；结束时只执行一次 `harness_gate.py close --phase review --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --to-phase submit|run --executor <tool> --json`，由 gate 完成阶段事件、租约、上下文交接与远端补传。不得手工追加 `phase.start/phase.end` 或再次调用 context close；任一 close 失败不得宣称审查完成。
 
 0. **启动准备** — 确定变更名（Glob `.harness/changes/*/plans/*-plan.md`，排除 `.harness/archive/*/`，读 frontmatter 提取 change-name）；**append `phase.start` 事件**（不得等审查完成才补）
 1. **读取 worktree 状态（门禁检查）** — 读 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 但 worktree 不存在 → 停止并提示先修复 `harness-run`，不得静默回主目录（否则 git diff 为空）；`requested=true` 且 worktree 已创建 → spawned agent 用该 worktree 路径执行 `git diff`（确保审查 worktree 变更而非主目录）；`requested=false` → 审查主目录变更
 <!-- @section-id review.delegate -->
-### 2. 审查执行（风险分级、inline 优先）
+### 2. 审查执行（隔离 reviewer 优先）
 
-默认由主会话按同一 6 维度检查清单审查。仅发布候选，或变更命中权限/安全、支付、数据迁移、并发幂等、公共契约、跨模块核心路径时，才考虑隔离 reviewer；需要固定 `harness-reviewer` 时执行一次 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`。只有 `executionMode=delegated` 才委派；`executionMode=inline` 静默由主会话审查，不显示缺失告警。定义损坏、spawn 失败、空返回或只有元数据 → 记录一次 issue 后直接主会话审查，`fallbackPolicy=inline-no-retry`。
+review 默认优先在独立上下文执行，避免主会话已形成的实现结论影响审查。阶段开始后只做一次能力判定：固定 reviewer 可用时执行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`；宿主提供通用隔离任务能力时可直接委派一次只读审查。委派只读取 diff、规则和测试证据，主会话负责最终核验与落盘。
+
+无隔离能力、定义损坏、spawn 失败、空返回或只有元数据时，不重试，立即由主会话按同一 6 维度检查清单完成审查。无论是否委派，都必须追加一条 `decision` 事件：`executor_agent=harness-reviewer` 表示已委派；`decision` 写执行方式，`reason` 写选择或回退原因，稳定原因码使用 `REVIEW_DELEGATED`、`REVIEW_INLINE_UNAVAILABLE`、`REVIEW_INLINE_SPAWN_FAILED` 或 `REVIEW_INLINE_INVALID_RESULT`。正常 inline 是可接受结果，不显示成流程故障；`fallbackPolicy=inline-no-retry`。
 
 3. **持久化报告与事实 sidecar（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`，并把同一批发现写成临时 JSON 后调用 `python <skills-root>/scripts/harness_review.py write-findings --change-dir <change-dir> --input <findings.json>`。权威计数来自 `reports/review/review-findings.json`，不是 Markdown。任一写入缺失 → 🟡WARN，不得宣称 review 完成。
 4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`；随后把 disposition 临时 JSON 交给 `python <skills-root>/scripts/harness_review.py write-dispositions --change-dir <change-dir> --input <dispositions.json>`，权威状态写入 `reports/review/fixback-dispositions.json`。若无 RED/YELLOW，也必须写空 findings sidecar，并记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -79,11 +79,11 @@ disallowed-tools:
 ## Workflow 概要
 
 0. 加载上下文：先 `harness_context.py prepare --phase run --executor <tool> [--change <id>] --json`，以返回的唯一 change/executionRoot/transition receipt 为准（多 active 缺参 → `ACTIVE_CHANGE_AMBIGUOUS`，禁止按 mtime 猜测）；再 **`harness_context.py begin --phase run --change <id> --executor <tool> --json`** 校验 Plan artifact/hash/HEAD，读 spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback → **`harness_gate.py begin --phase run --change <id>`**（claim + phase.start + identity；禁止手工 Write `events.ndjson` / 手工 `phase.end`）。**C3 钩子**：`harness_gate.py begin` 在已连接平台时会 best-effort 调用 events-sync（注册 run / `running`）；失败只告警，不阻断 begin。
-0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；进入 TDD 前执行 `harness_test_guard.py begin --project . --change-dir ".harness/changes/<cn>" --json`
+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`）；`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-4. **关门检查**（10 项）→ `harness_test_guard.py close` → **`harness_gate.py close --phase run --change <id> --status <OK|WARN|FAIL>`** → `harness_context.py close --from-phase run --to-phase test --executor <tool> --json`（内部 phase.end + append-only handoff + 释放租约；任一 close 失败不得用自然语言宣称成功）
+4. **关门检查**（10 项）→ 只执行一次 **`harness_gate.py close --phase run --change <id> --status <OK|WARN|FAIL> --to-phase test --executor <tool> --json`**。该命令内部依次关闭 test guard、写 `phase.end`、释放阶段租约、写 append-only handoff，并立即补传远端事件；不得再单独调用 test-guard/context close。若返回 `PHASE_HANDOFF_PENDING`，修正明确指出的输入后原样重试同一命令，已完成步骤会幂等复用。
 
 **Fixback**：`--fixback` 或用户要求时读 `reports/review/fixback-*.md`；RED 优先；未选用则记 `fixback: advisory-not-applied`。
 
@@ -112,7 +112,7 @@ disallowed-tools:
 | **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过；greenfield 大重写豁免见 reference |
 | **Mapper/DB** | 纯 Mock 不得宣称 DB 验证通过；迁移脚本**永不自动执行** |
 | **探测/ledger** | 基础设施先探测；每次构建/测试经 `harness_ledger.py record`；禁止手写 ledger JSON；用 canonical `diff-hash --change-dir` |
-| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin/close`；阶段门禁用 `harness_gate.py begin/close`；测试跟踪用 `harness_test_guard.py begin/close/record/stage` |
+| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin`；阶段门禁与上下文交接统一用 `harness_gate.py begin/close`；gate 内部负责 guard begin/close，模型只在需要记录测试来源或修复时调用 guard 的 `record/stage/mark` |
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
 | **Worktree** | `requested=true` 时代码只写 worktree |

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

@@ -540,7 +540,7 @@ python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/cha
 >
 > **Ledger v3**：`record` 自动解析并强制顶层身份（`schemaVersion=3/repositoryId/changeName/baseCommit/currentHead/diffHash/ownershipHash`），缺字段非零退出、不写账本；已有 v1/v2 ledger 在写前透明迁移，`migrationHistory` 回执记录原/目标 schema 与迁移前后 evidence identity。无法迁移时返回 `LEDGER_MIGRATION_REQUIRED` 和确定性 `rerecordCommand`，不得半升级。v2 契约下 `--metrics-json` 必须通过 typed schema（unit=`total/passed/failed`，apiContract=`scenariosTotal/passed/failed`，browserE2E=`total/passed/failed`，dbCompatibility=`applicability(+reason)`）。详见 `../protocols/ledger-protocol.md` 第十节。
 
-阶段边界：`harness_gate.py begin/close`；测试跟踪：`harness_test_guard.py begin/close`。close 失败不得用自然语言覆盖。
+阶段边界与测试跟踪统一由 `harness_gate.py begin/close` 协调；底层 guard begin/close 不再由模型重复调用。close 失败不得用自然语言覆盖。
 
 ## 步骤 3：场景覆盖检查
 
@@ -800,7 +800,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 ```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]
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase run --status OK --to-phase test --executor <tool> [--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"

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; 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=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=f636ed002f37b71f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -66,7 +66,9 @@ disallowed-tools:
 
 ## Workflow
 
-测试跟踪的确定性边界为 `harness_test_guard.py begin` 和 `harness_test_guard.py close`；任一失败都必须传递给 `harness_gate.py close`，不得以自然语言覆盖失败状态。
+测试跟踪由 `harness_gate.py begin/close` 统一协调 test guard；不得额外手工执行 guard close。任一失败都必须使用 gate 返回的结构化状态，不得以自然语言覆盖失败状态。
+
+兼容实现中的底层命令名是 `harness_test_guard.py begin` 与 `harness_test_guard.py close`，两者只允许由 gate 内部调用；写在这里用于能力审计，不构成模型执行步骤。
 
 并行服务测试先运行 `harness_change.py lease-port --change <id> --run-id <run-id> --range <start-end> --json`，再把返回端口传给 `harness_service.py ensure --leased-port <port> --lease-owner <run-id>`。`serviceStart` 的 command/health/overlay 可用 `{leasedPort}` 占位符；用户自启进程仍只进入 Service Gate，禁止 kill。测试清理的 `finally` 中运行 `harness_change.py release-port --change <id> --run-id <run-id> --json`，避免租约池耗尽。
 
@@ -105,7 +107,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 先 `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_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再 `--to-phase run` 并由 context 失效受影响 target。
+验证写入**仅**允许 `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 --phase test --status ... --to-phase review --executor <tool> --json`。fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再把同一 close 命令的 `--to-phase` 改为 `run`，由 context 失效受影响 target。
 
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续

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

@@ -740,7 +740,7 @@ TEST_<change-name>_<timestamp>_<short-random>
 ```powershell
 # gate begin/close（phase=test；--task 仅 checkpoint 启用时必需；close 不需要 --skills-root）
 python <skills-root>/scripts/harness_gate.py begin --change <cn> --phase test --skills-root <skills-root> [--task N]
-python <skills-root>/scripts/harness_gate.py close --change <cn> --phase test --status OK [--task N]
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase test --status OK --to-phase review --executor <tool> [--task N]
 
 # ledger 记录 / 复用（--profile-input = verification key，不是文件路径）
 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: N, Failures: 0" --coverage full --files "packages/core/src/index.ts"

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

@@ -17,6 +17,7 @@ import argparse
 import datetime as dt
 import hashlib
 import io
+import ipaddress
 import json
 import os
 import re
@@ -31,6 +32,7 @@ import zipfile
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlsplit
 
 
 if hasattr(sys.stdout, "reconfigure"):
@@ -192,9 +194,9 @@ def append_event(
     for key, value in fields.items():
         if value is not None:
             event[key] = value
-    line = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
-    he.atomic_append_line(path, line)
-    all_events = existing + [he.normalize_event(event)]
+    result = he.append_with_auto_seal(path, event, existing_events=existing)
+    event = result["event"]
+    all_events = he.load_events(path)
     he.write_execution_log(change_dir, he.render_execution_log(all_events))
     return event
 
@@ -3053,6 +3055,25 @@ def build_verification_projection(
         "apiTests": _ledger_api_tests(effective_ledger, change_dir=change_dir),
     }
     db_compatibility = _ledger_db_compat(effective_ledger)
+    if db_compatibility["status"] == "NOT_RUN" and change_dir is not None:
+        gate_policy_path = change_dir / "meta" / "gate-policy.json"
+        try:
+            gate_policy = read_json(gate_policy_path) if gate_policy_path.is_file() else None
+        except (OSError, json.JSONDecodeError):
+            gate_policy = None
+        if isinstance(gate_policy, dict):
+            capabilities = gate_policy.get("capabilities")
+            required = gate_policy.get("requiredValidations")
+            if (
+                isinstance(capabilities, list)
+                and "database" not in capabilities
+                and (not isinstance(required, list) or "dbCompatibility" not in required)
+            ):
+                db_compatibility = {
+                    "status": "NOT_APPLICABLE",
+                    "reason": "项目能力画像未声明数据库能力",
+                    "source": "capability-profile",
+                }
     projection["dbCompatibility"] = db_compatibility["status"]
     projection["dbCompatibilityEvidence"] = db_compatibility
     api_contract = validations.get("apiContract")
@@ -8377,6 +8398,27 @@ def _read_optional_text(path: Path) -> str:
         return ""
 
 
+def _archive_server_url_allowed(value: str | None) -> bool:
+    """Require TLS remotely while allowing explicit loopback HTTP for local testing."""
+    if value is None or not value.strip() or re.search(r"\s", value):
+        return False
+    try:
+        parsed = urlsplit(value)
+        host = (parsed.hostname or "").lower()
+    except ValueError:
+        return False
+    if parsed.scheme.lower() == "https":
+        return bool(host)
+    if parsed.scheme.lower() != "http":
+        return False
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
 def _resolve_archive_remote_credentials(
     project_root: Path,
     environment: Mapping[str, str],
@@ -8403,10 +8445,7 @@ def _resolve_archive_remote_credentials(
         else ""
     )
     token_available = bool(env_token or local_token)
-    url_available = bool(
-        server_url
-        and re.fullmatch(r"https://[^\s]+", server_url, flags=re.IGNORECASE)
-    )
+    url_available = _archive_server_url_allowed(server_url)
     return {
         "configured": bool(url_available and token_available),
         "serverUrl": server_url if url_available else None,

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

@@ -23,6 +23,8 @@ PHASE_GRAPH = {
     "submit": (),
 }
 
+DISPLAY_TITLE_MAX_LENGTH = 80
+
 
 def _now() -> dt.datetime:
     return dt.datetime.now(dt.timezone.utc)
@@ -35,6 +37,41 @@ def _read_json(path: Path) -> dict[str, Any]:
     return data
 
 
+def _normalize_display_title(value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError("display title must be text")
+    title = value.strip()
+    if not title:
+        raise ValueError("display title must not be empty")
+    if len(title) > DISPLAY_TITLE_MAX_LENGTH:
+        raise ValueError(
+            f"display title exceeds {DISPLAY_TITLE_MAX_LENGTH} characters"
+        )
+    if any(ord(character) < 32 or ord(character) == 127 for character in title):
+        raise ValueError("display title contains control characters")
+    return title
+
+
+def _ensure_display_title(contract_root: Path, value: Any) -> str | None:
+    path = contract_root / "meta" / "change-title.json"
+    if path.is_file():
+        payload = _read_json(path)
+        return _normalize_display_title(payload.get("displayTitle"))
+    title = _normalize_display_title(value)
+    if title is None:
+        return None
+    _write_json_atomic(
+        path,
+        {
+            "schemaVersion": 1,
+            "displayTitle": title,
+        },
+    )
+    return title
+
+
 def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, raw = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent))
@@ -243,6 +280,7 @@ def prepare_context(
     phase: str,
     executor: str,
     change: str | None = None,
+    display_title: str | None = None,
     ttl_seconds: int = 3600,
 ) -> dict[str, Any]:
     project = Path(project).resolve()
@@ -265,6 +303,16 @@ def prepare_context(
         contract_root, contract, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return {"ok": False, "code": str(exc).split(":", 1)[0], "error": str(exc)}
+    try:
+        resolved_display_title = _ensure_display_title(
+            contract_root, display_title
+        )
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "DISPLAY_TITLE_INVALID",
+            "error": str(exc),
+        }
     lifecycle = contract.get("lifecycle")
     if (
         isinstance(lifecycle, dict)
@@ -343,6 +391,7 @@ def prepare_context(
             "executionRoot": str(execution_root),
             "preparedAt": now.isoformat(),
             "receiptHash": latest.get("receiptHash") if latest else None,
+            "displayTitle": resolved_display_title,
         },
     )
     next_phases = (
@@ -363,6 +412,7 @@ def prepare_context(
         "latestTransition": latest,
         "lease": lease,
         "recovery": recovery,
+        "displayTitle": resolved_display_title,
     }
 
 
@@ -424,7 +474,7 @@ def close_transition(
     *,
     from_phase: str,
     to_phase: str,
-    executor: str,
+    executor: str | None,
     artifacts: list[str] | None = None,
     status: str = "OK",
 ) -> dict[str, Any]:
@@ -441,13 +491,81 @@ def close_transition(
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
     paths = _paths(state_root)
+
+    artifact_entries: list[dict[str, Any]] = []
+    for raw in artifacts or []:
+        requested = Path(raw)
+        candidates = (
+            [requested]
+            if requested.is_absolute()
+            else [project / requested, contract_root / requested]
+        )
+        valid: list[Path] = []
+        for candidate in candidates:
+            try:
+                resolved_candidate = candidate.resolve()
+            except OSError:
+                continue
+            if resolved_candidate in valid:
+                continue
+            if resolved_candidate.is_relative_to(project) and resolved_candidate.is_file():
+                valid.append(resolved_candidate)
+        if len(valid) > 1:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_AMBIGUOUS",
+                "path": raw,
+                "candidates": [item.relative_to(project).as_posix() for item in valid],
+                "message": "relative artifact exists under both project and change roots",
+            }
+        if not valid:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_INVALID",
+                "path": raw,
+                "acceptedBases": [str(project), str(contract_root)],
+                "examples": [
+                    str(contract_root / "meta" / "plan-finalization.json"),
+                    f".harness/changes/{change}/meta/plan-finalization.json",
+                    "meta/plan-finalization.json",
+                ],
+            }
+        resolved_artifact = valid[0]
+        artifact_entries.append(
+            {
+                "path": resolved_artifact.relative_to(project).as_posix(),
+                "sha256": _sha256(resolved_artifact),
+            }
+        )
+
+    transitions = _read_ndjson(paths["transitions"])
     if not paths["lease"].is_file():
+        latest = transitions[-1] if transitions else None
+        if (
+            isinstance(latest, dict)
+            and latest.get("fromPhase") == from_phase
+            and latest.get("toPhase") == to_phase
+            and latest.get("status") == status
+            and latest.get("artifacts") == artifact_entries
+            and (executor is None or latest.get("executor") == executor)
+        ):
+            return {
+                "ok": True,
+                "code": "TRANSITION_ALREADY_CLOSED",
+                "idempotent": True,
+                "receipt": latest,
+                "path": str(paths["transitions"]),
+                "invalidation": None,
+            }
         return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
     try:
         lease = _read_json(paths["lease"])
     except (OSError, ValueError, json.JSONDecodeError):
         return {"ok": False, "code": "CONTEXT_LEASE_INVALID"}
-    if lease.get("owner") != executor or lease.get("phase") != from_phase:
+    effective_executor = executor or str(lease.get("owner") or "")
+    if not effective_executor:
+        return {"ok": False, "code": "CONTEXT_EXECUTOR_REQUIRED"}
+    if lease.get("owner") != effective_executor or lease.get("phase") != from_phase:
         return {
             "ok": False,
             "code": "CONTEXT_LEASE_MISMATCH",
@@ -458,25 +576,6 @@ def close_transition(
     if expiry is None or _now() >= expiry:
         return {"ok": False, "code": "CONTEXT_LEASE_EXPIRED"}
 
-    artifact_entries: list[dict[str, Any]] = []
-    for raw in artifacts or []:
-        path = Path(raw)
-        if not path.is_absolute():
-            path = contract_root / path
-        resolved = path.resolve()
-        if not resolved.is_relative_to(project) or not resolved.is_file():
-            return {
-                "ok": False,
-                "code": "TRANSITION_ARTIFACT_INVALID",
-                "path": str(path),
-            }
-        artifact_entries.append(
-            {
-                "path": resolved.relative_to(project).as_posix(),
-                "sha256": _sha256(resolved),
-            }
-        )
-    transitions = _read_ndjson(paths["transitions"])
     previous_hash = transitions[-1].get("receiptHash") if transitions else None
     attempt = (
         1
@@ -493,7 +592,7 @@ def close_transition(
         "fromPhase": from_phase,
         "toPhase": to_phase,
         "status": status,
-        "executor": executor,
+        "executor": effective_executor,
         "productCommit": _head(project),
         "artifacts": artifact_entries,
         "attempt": attempt,
@@ -657,6 +756,7 @@ def build_parser() -> argparse.ArgumentParser:
     prepare.add_argument("--change")
     prepare.add_argument("--phase", required=True)
     prepare.add_argument("--executor", required=True)
+    prepare.add_argument("--title")
     prepare.add_argument("--ttl-seconds", type=int, default=3600)
     close = sub.add_parser("close")
     close.add_argument("--json", action="store_true")
@@ -688,6 +788,7 @@ def main(argv: list[str] | None = None) -> int:
             phase=args.phase,
             executor=args.executor,
             change=args.change,
+            display_title=args.title,
             ttl_seconds=args.ttl_seconds,
         )
     elif args.command == "close":