@hunter-harness/workflow-harness 0.4.8 → 0.4.10

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

@@ -1,250 +0,0 @@
----
-name: harness-test
-description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
-  时使用；不得在 run 结束后自动接续执行。
----
-<!-- generated by harness_deploy.py; core=f3bbb4e119882451; overlay=none; agent=cursor; do not edit -->
-# harness-test — 测试执行
-
-> **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，
-> 统一入口为 **`/harness-execute`**（`harness/harness-execute/SKILL.md`）。本 skill 作为
-> 别名保留，frontmatter `name` 不变、内容照旧可用；门禁入参 `--phase test` 经
-> `LEGACY_PHASE_ALIASES` 归一为 execute。别名至少保留一个 minor 版本，退役时间见
-> `docs/harness-improvement-roadmap/`。下文出现的阶段名 `run`/`test` 均按别名解析。
->
-> 合并语义注意：execute 关门时 C9 场景覆盖要求全部 `ownerPhase=execute` 场景有通过
-> receipt（包括本属 test 的接口/兼容场景）；`ownerPhase=review`/`submit` 仍按计划顺延。
-
-## Purpose
-
-读取测试场景表，逐条执行单元测试和接口测试，验证代码变更的正确性，输出测试报告。
-
-## When to Use
-
-仅当用户显式调用 `/harness-test` 时执行（已设 `disable-model-invocation`）。run 阶段结束后**不自动**进入本阶段；用户口头提到"跑测试"而未调用本 skill 时，先确认是否走 Harness 测试阶段。
-
-**单阶段原则**：test 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动接续执行。
-
-使用场景：
-- 完成 `/harness-run` 编码后，验证单元测试 + 接口测试 + 数据兼容
-- 修改公共模块 / 数据访问 / sql / 权限认证 / 接口层 / 数据契约 后需要真实接口验证
-- run 阶段 ledger 可复用时，跳过单元测试重跑，只补接口测试
-
-前置依赖：
-- `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` 存在（测试真相源）
-- `/harness-run` 已完成，或 ledger 中有可复用的 unitTest 结果
-- 必须读取 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 且 worktree 已创建 → 在 worktree 目录中执行测试；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回到主目录
-
-跳过场景：
-- 仅改了注释 / 格式化等非行为性清理，且 ledger `postTestClassification=NON_BEHAVIORAL_CLEANUP`，可复用已有 apiTest 结果，不必重跑
-
-## 统一读取协议
-
-0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
-1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
-3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
-5. **plan** — 任务真相源：`plans/<change>-plan.md`
-6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
-7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
-8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
-
-状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
-> 片段：read-protocol
-
-## Workflow
-
-测试跟踪由 `harness_gate.py begin/close` 统一协调 test guard；不得额外手工执行 guard close。任一失败都必须使用 gate 返回的结构化状态，不得以自然语言覆盖失败状态。所有 change/state 路径必须使用 `harness_change.py resolve` 或 context 返回的 `executionRoot`，不得固定拼接 `.harness/changes/**`；split-v1 默认位于 `.harness/state/changes/**`。
-
-兼容实现中的底层命令名是 `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`，避免租约池耗尽。
-
-### Phase -1：资源安全门（任何测试命令之前）
-
-测试默认使用 `safe` 资源档位，禁止直接执行会把整套测试放进同一长生命周期的裸命令。所有本地测试命令必须由 `harness/scripts/harness_test_runner.py` 托管：
-
-```text
-python harness/scripts/harness_test_runner.py exec --profile safe --timeout-seconds <秒> -- <测试命令及参数>
-```
-
-对于 Python `unittest` 测试库，必须使用逐模块隔离模式，不得执行裸 `python -m unittest discover ...`：
-
-```text
-python harness/scripts/harness_test_runner.py unittest --profile safe --tests-dir <测试目录>
-```
-
-资源档位是硬合同：
-
-- `safe`：默认；普通测试模块串行执行，每个模块使用全新进程。
-- `system`：只执行服务生命周期、集成等资源密集型模块。
-- `full`：先执行普通模块，再执行资源密集型模块；仍保持逐模块串行。
-- `system` / `full` 只有在用户明确要求资源密集型测试、传入 `--confirm-resource-intensive`，或受控 CI 设置 `CI=true` / `HARNESS_ALLOW_RESOURCE_INTENSIVE_TESTS=1` 时才允许执行。
-
-Runner 强制同项目单实例、低调度优先级、逐命令超时、正常结束和异常结束的进程树清理。`HARNESS_TEST_MAX_WORKERS` 默认且最高为 `2`，只能调低，不能调高；技术栈自身的并发参数也必须收敛到该值。Windows detached-service 模块在执行前先做 nested-breakaway 能力探测，受限沙箱不支持时立即返回 `DETACHED_PROCESS_CAPABILITY_UNAVAILABLE`，不得让每个服务用例逐一超时。出现该错误、`TEST_RUN_ALREADY_ACTIVE`、`PROCESS_TREE_ISOLATION_UNAVAILABLE` 或 `TEST_COMMAND_TIMEOUT` 必须停止，不得绕过 Runner 重跑裸命令。完整约束见 `checklist.md`「0.0-A 资源安全档位」。
-
-动态数据库/Redis/令牌字段必须先由 `harness_environment.py prepare` 生成 secret-free receipt，再用 `exec --environment-receipt <file> --required-environment-field <NAME>` 闭包注入；缺失或指纹变化在启动测试前返回 `VERIFICATION_ENVIRONMENT_INCOMPLETE`。复杂 JSON、Docker template 或含引号参数不得跨多层 `-Command` 传递，改用 `exec --argv-file <utf8-json> --runtime-receipt <file>`；参数文件记录 PowerShell edition/version，运行回执只存 argv hash。`harness_service.py ensure` 属于正式持久服务模式，禁止从 bounded runner 内启动；命中时返回 `PERSISTENT_SERVICE_MODE_REQUIRED`。
-
-预计超过交互窗口的正式验证使用 `harness_runtime.py run-start`，随后通过
-`run-status` / `run-log --cursor` 重连；不得把调用方存活当作验证存活条件。环境 acquire
-必须显式选择 `change-session`（同 change + 内容指纹复用）或 `ephemeral`（每次重置）。
-验证 DAG 的并行度由 `resourceLocks` 决定，未分类重任务默认串行。完整合同见
-`../protocols/execution-session-protocol.md`。
-
-### Phase 0：环境准备（主会话执行，需要交互确认）
-
-先 `harness_context.py prepare --project . --change <id> --phase test --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 `harness_context.py begin --project . --change <id> --phase test --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
-
-验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close`。`--to-phase` 取实际阶段计划的后继；Fixback 返回 run，普通流程可直接进入 Review、Submit 或 Archive。Fixback 只失效与改动文件相交的验证目标。
-
-- **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
-- **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续
-- 通过后进入 Phase 1
-
-### Phase 0.1：命令执行模式 preflight（⚠️ 必须在编译/启动服务/生成 runner 之前执行）
-
-`/harness-test` 高度依赖 PowerShell 与接口测试执行器。如果当前会话处于 Auto mode / 安全分类器降级 / PowerShell 被拒，会反复失败并错误降级到 Playwright MCP 逐条接口，造成长时间阻塞。**必须先做 4 项执行模式检查**（PowerShell 基础命令、执行器运行时可用性、构建工具可用性、安全分类器），将通过的 `executorPath` 写入 `.harness/changes/<change-name>/runtime/preflight.json`。
-
-任一硬停情况（安全分类器不可用 / Auto mode 拦截 / PowerShell 被拒 / 执行器或构建工具不可执行）→ 原文输出"❌ 命令执行模式不可用..."，不得继续编译/启动服务/生成执行器，不得盲目降级到 Playwright MCP。用户确认切换权限模式后**必须重新执行 0.1**，重试 ≤ 1 次。详见 `reference.md`「命令执行模式 preflight」。
-
-### Phase 0.2：fallback 执行器探测（仅在首选执行器不可用时执行）
-
-只有 0.1 通过但首选接口测试执行器不可用时才执行 0.2。如果 0.1 已确认执行器在 PowerShell 中可用，直接选择 **接口测试执行器**（Node runner 为一种实现，可按项目替换），不得继续探测或使用 Playwright MCP。
-
-严格优先级（不得颠倒）：接口测试执行器（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅当 1+2 都不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底）> 禁止直接用 curl 内联发送含中文 JSON body。
-
-> ⚠️ Playwright MCP `browser_evaluate` 不得替代执行器。执行器在 PowerShell 可用时，**禁止**使用 Playwright MCP 逐条执行接口测试——认证凭证是独立凭证，应读认证凭证缓存，由执行器直连本地 baseURL 发起请求。详见 `reference.md`「fallback 执行器探测」。
-
-### Phase 1-2：测试执行（默认主会话执行）
-
-**Phase 1 前先检查 verification-ledger**：先执行 `harness_preflight.py check --project . --json`；profile 缺失或因清单、锁文件、源码根、技术栈变化而陈旧时立即执行一次 `detect --project . --json`。随后通过 state layout 解析后的路径调用 `harness_ledger.py can-reuse --project . --profile-input <key> --command <profile 解析出的规范命令>`；可复用时不得重跑。不得手工读取实现源码来猜账本参数。按返回的 `executionNeed` 使用中文：`first-run`=“尚未执行，需要首次运行”，`rerun`=“证据已失效，需要重新运行”，`evidence-incomplete`=“已有记录不完整，需要重新验证”，`reuse`=“现有证据可复用”；禁止把首次执行统一描述成“强制重跑”。
-
-**默认在主会话执行**（不委派 subagent）：
-- 单元测试：可复用则跳过重跑；否则按技术栈执行测试命令
-- 接口测试：**强制批量执行器**，一次跑完全部场景，主会话只读 JSON
-
-### Phase 3：覆盖率总结 + 关门检查（主会话执行）
-
-读取测试报告，生成覆盖率总结，**执行关门检查**，包含：单元测试通过/失败/跳过计数、接口测试逐条结果+汇总+耗时、数据兼容验证汇总、败因分类（代码 Bug vs 测试脚本 vs 预存问题）、请求执行器及降级原因、关门检查 10 项（见「关键规则·十」）。
-
-## P0 执行可信度规则
-
-- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
-- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
-- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
-
-## 生成内容语言约定
-
-- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
-- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
-> 片段：p0-trust
-
-## 关键规则（硬门禁速查）
-
-> 每条规则的详细判定、模板、表格见 `reference.md` 对应章节；Shell 执行安全见 `../protocols/powershell-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，ledger 见 `../protocols/ledger-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`，结构化报告事件见 `../protocols/report-pipeline-protocol.md`。
-
-### 一、接口测试工具优先级
-
-强制优先级：**接口测试执行器**（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅 1+2 不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底，须通过 PowerShell 调用）。**禁止裸 `node`、禁止用 Bash 执行 node**（`disallowed-tools` 已禁 `Bash(node *)`）；执行器在 PowerShell 可用时**不得**用 Playwright MCP 逐条执行。详见 `reference.md`「接口测试工具优先级」。
-
-### 二、批量测试执行 + Runner 三阶段
-
-0.1 通过后生成 `.harness/changes/<change-name>/runtime/api-test-runner.mjs`（按技术栈选择实现，Node runner 为一种实现，可按项目替换），通过**一次命令**（PowerShell + 执行器绝对路径）执行全部场景，输出 `api-test-results.json`，主会话只读 JSON。执行器必须按 **setup / test / cleanup** 三阶段：setup 失败时依赖场景标 🟡 BLOCKED，**不得用 null ID 继续请求**。绝对路径从 `runtime/preflight.json` 的 `executorPath` 读取，禁止 hardcode。详见 `reference.md`「批量测试执行器」「执行器三阶段模板」。
-
-### 三、请求体与测试数据
-
-请求体必须从数据契约 / 接口定义 / 真实样例生成，**禁止临场猜字段、禁止先跑失败接口再补**。测试数据用唯一前缀 `TEST_<change-name>_<timestamp>_<random>`；唯一约束字段必须随机或避让，避免冲突导致大面积 BLOCKED。详见 `reference.md`「请求体生成」「测试数据治理」。
-
-### 四、单元测试复用 + 写入 ledger
-
-Phase 1 前用 `harness_ledger.py diff-hash` 和 `can-reuse` 重算真实指纹。验证目标必须使用 profile key 的单一入口：`--project . --profile-input unitTest|unitTestFull --command <规范命令>`；声明 `--profile-input` 后不得同时传入另一套 `--files`。`record` 与 `can-reuse` 必须消费同一 profile target，由 CLI 推导 scope、coverage、规范命令与输入闭包。`npx vitest run` 与 `vitest run` 等包装差异由账本规范化，`safe runner` 等说明只能写 `--runner-command` 元数据。可复用则跳过；否则执行同一 profile 命令并只登记一条结果。增量测试记 `unitTest`，模块全量记 `unitTestFull`，API/浏览器分别记录。详见 `checklist.md` 与 ledger protocol。
-
-报告必须分开呈现“产品测试”与“工具维护”。`ownership.productPaths` 决定产品结论；`.cursor/.agents/.claude/.codebuddy` 的 Harness 投影、context-index 与安装状态变化只进入“工具维护”，不得单独把产品结果降为 WARN。已知升级使用明确文案“Harness 已从 <旧版本> 更新到 <新版本>”，不得写“无关漂移”。场景统计分别列出：已执行、待手工验收、已豁免、说明性、NOT_APPLICABLE；“未验证”必须只等于仍要求执行但尚未完成的场景数。
-
-### 五、命令与请求超时治理
-
-所有命令必须通过资源安全 Runner 设置「预期时长 + 超时上限」，超过预期必须输出一次状态行，**不得静默等待**。测试模块超时或退出时必须清理其进程树；`durationMs > 10000` → 🟡 SLOW，`> 30000` → ❌ TIMEOUT_RISK。详见 `reference.md`「命令与请求超时治理」。
-
-### 五-A、陈旧测试安全修复
-
-若测试编译或执行明确指向已移除/改名 API 的陈旧测试，且当前生产代码、已批准计划或可验证历史能唯一确定新契约，可仅修改测试并立即重跑该测试与目标测试，然后记录：
-
-```text
-python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
-```
-
-普通新增/更新测试使用 `tdd-created` / `test-updated`。存在业务歧义或修复会触及生产代码时，记录 `BLOCKED_PREEXISTING` 并停止复用该验证，不得猜测或绕过。
-
-**禁止临时排除测试**：禁止 `.bak`/改名、移出测试目录、删除、禁用注解、构建 exclude、`skipTests`/`maven.test.skip` 充当测试通过证据；服务启动可在单元测试已独立通过后使用 `-Dmaven.test.skip=true` 避免重复编译测试，但不得据此声明测试通过。所有本轮新增、更新或安全修复且被忽略的测试必须写入 test-tracking manifest；仅执行、未修改的只读 ignored test 不获得 force-track 授权。
-
-### 六、服务启动 + 生命周期管理
-
-启动等待状态机：0–30s 每 2s 探测、30–120s 每 5s 探测、>120s 读日志判定；遇启动失败特征立即停。**Service Gate**：`harness_service.py ensure` 返回 `action=needs-user-decision`（用户自启服务占端口）时 **才** blocking user confirmation；AI 托管服务或端口空闲则自动继续，不询问。服务指纹（`moduleInputsHash`，来自 CLI `--files` ∪ `serviceStart.inputFiles`）+ `startCommandHash` + `profile` + `overlayPath` + 进程身份任一变化即 restart；**空输入被拒绝**，不生成可复用空指纹。测试结束默认清理 AI 启动的服务。详见 `reference.md`「服务决策门」。
-
-### 七、运行时配置叠加（不动 tracked 配置）
-
-禁止默认 Edit tracked 应用配置文件。默认运行时配置叠加（ASCII 绝对路径）；改 tracked 配置 → 默认拒绝，记 `decision` 事件（不 blocking user confirmation，报告 🟡 WARN）。详见 `reference.md`。
-
-### 八、Token 缓存与复用
-
-先读 `.harness/changes/<change-name>/runtime/credential-cache.json`（认证凭证缓存，按项目认证机制；token/SSO 为常见实现），本地轻量接口验证通过则复用，失败才走远程认证。接口测试执行器用 request context / 原生 HTTP 客户端直连本地 baseURL，**不得依赖浏览器当前页面 origin**。同一次流程内凭证刷新计数 > 1 → 🟡 WARN。**不得在报告/日志/对话总结中输出明文凭证**。详见 `reference.md`「认证凭证缓存与复用」。
-
-> ⛔ **验证码 = 硬停，不是待解的技术问题。** 登录响应出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` 等特征时，**禁止**编写或运行任何求解代码（图像匹配、OCR、打码平台、反编译服务端找容差均在禁止之列）。立即记 `apiTest=BLOCKED`，请用户手工把凭证写入 `runtime/credential-cache.json` 或临时关闭测试环境验证码，并提示 `.harness/config/harness-test-config.md` 的认证方式已过期。详见 `pitfalls.md` 规则 31。
-
-### 九、测试报告状态规则
-
-整体 ✅OK / 🟡WARN / ❌FAIL 三态；API 维度使用 `OK` / `PARTIAL` / `BLOCKED` / `NOT_RUN` / `FAIL` 五态。**不得把「5 PASS + 9 BLOCKED + 1 FAIL」写成 `apiTest=NOT_RUN`**，正确为 `apiTest=PARTIAL`。P0 场景 BLOCKED 不得仍 OK。详见 `reference.md`「结果分级规则」。
-
-### 十、关门检查（结束前强制执行）
-
-输出最终总结前必须执行 10 项：`git status --porcelain` / `git diff --stat` / `git diff --check`（失败→❌FAIL，必须 PowerShell-only）/ 明文敏感信息 / runtime 不提交 / 服务生命周期收尾 / 测试数据清理 / 执行器表完整 / 慢请求或超时 / 未清理+fallback+慢请求→至少 🟡WARN。详见 `checklist.md`「关门检查」、`reference.md`「关门检查」。
-
-### 十一、请求执行器 fallback 输出 + 性能统计
-
-报告必须区分四种执行器（接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl），**不得笼统写"Playwright"**，不得把 "Playwright API 执行器" 与 "Playwright MCP browser_evaluate" 混写。报告必须含请求耗时统计表。详见 `reference.md`「请求执行器 fallback 输出」「输出格式」。
-
-## Output Format
-
-> 详细报告格式见 `reference.md` 的「输出格式」模板。
-
-测试报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行），同时在控制台输出摘要。
-
-## 渐进披露
-
-- **Read `checklist.md`** 仅在 Phase 0 环境准备时 — 含 各项强制检查、0.1 命令执行模式 preflight、服务生命周期清单
-- **Read `reference.md`** 仅在执行接口测试时 — 含 API 测试执行方法、已知良好测试配置、运行时配置叠加、setup/test/cleanup 执行器模板、双格式错误码兼容
-- **Read `pitfalls.md`** 仅在遇到测试失败时 — 含所有踩坑规则（30 条，含 Bash 执行执行器 / 运行时配置叠加 / 唯一字段冲突 / 服务生命周期等）
-
-## 交互白名单
-
-本 skill **仅允许**以下 blocking user confirmation；其余默认值 + `decision` 事件：
-
-1. **Service Gate**：仅当 `harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时询问处理方式
-2. **资源密集型测试确认**：仅当发布/验收确实需要 `system` 或 `full` 档位，且用户尚未明确授权时询问；获得授权后传入 `--confirm-resource-intensive`
-
-## 执行日志
-
-`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
-
-**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
-`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
-auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
-（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
-
-```powershell
-# 阶段开始：gate begin 负责，note 在这里给
-python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
-# 阶段中的其他事件才用 append
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
-```
-
-> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
-
-> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
-
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
-
-阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
-> 片段：logging · phase=`test` · 事件：phase/command/verification/decision/issue/artifact

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

@@ -1,14 +0,0 @@
----
-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 事件（含根因与修复文件），并检查同客户端文件的其余方法是否同源错误。

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

@@ -1,188 +0,0 @@
----
-name: harness-run
-description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
-  /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
----
-<!-- generated by harness_deploy.py; core=626fde5b3e847963; overlay=none; agent=pi; do not edit -->
-# harness-run — 需求编码
-
-> **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，
-> 统一入口为 **`/harness-execute`**（`harness/harness-execute/SKILL.md`）。本 skill 作为
-> 别名保留，frontmatter `name` 不变、内容照旧可用；门禁入参 `--phase run` 经
-> `LEGACY_PHASE_ALIASES` 归一为 execute。别名至少保留一个 minor 版本，退役时间见
-> `docs/harness-improvement-roadmap/`。下文出现的阶段名 `run`/`test` 均按别名解析。
-
-## Purpose
-
-基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 worktree-gate）。
-
-## When to Use
-
-仅当用户显式调用 `/harness-run` 时执行；plan 完成后**不自动**进入本阶段。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
-
-**单阶段原则**：run 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动开始其他阶段。
-
-## 前置条件
-
-- 设计文档（`plans/*-design.md` 优先，回退 `spec/*-design.md`）与 `plans/*-plan.md`（含 frontmatter）存在且已审批
-- 读 `meta/worktree.json`：`requested=true` 时 worktree 须存在或 run 负责创建
-
-## Worktree 门禁
-
-读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
-
-| 条件 | 行为 |
-|------|------|
-| `requested=false` | 主目录执行 |
-| `requested=true` + path 存在 | 切换 worktree 执行 |
-| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
-
-**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
-
-**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
-
-创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
-> 片段：worktree-gate · 创建命令 → `reference.md`
-
-## 统一读取协议
-
-0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
-1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
-3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
-5. **plan** — 任务真相源：`plans/<change>-plan.md`
-6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
-7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
-8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
-
-状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
-> 片段：read-protocol · run 必读文件优先级 → `reference.md` Step 0
-
-## 执行模式
-
-默认 **Inline Execution**；仅 `--subagent` 切换 Subagent-Driven。
-
-## Workflow 概要
-
-0. 加载上下文：普通 Run 先 `harness_context.py prepare --project . --change <id> --phase run --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 **`harness_context.py begin --project . --change <id> --phase run --executor <tool> --json`** 校验交接，最后运行 **`harness_gate.py begin --phase run --change <id>`**。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → run` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。`harness_gate.py` 会从当前已安装适配器自动识别 skills root；只有执行复制到别处的脚本时才显式传 `--skills-root`。`--fixback` 不得拼装这些底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`：该命令会先筛选结构化评审项，再原子选择 Fixback 分支、确认上下文、取得 Run 门禁并创建已填充批次。返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告“本轮评审没有需要执行的代码修复”并停止；返回阻塞码时按 `recoveryAction` 停止，不搜索实现、不试探其他参数、不创建空批次。禁止手写 `events.ndjson` / `phase.end`。已连接平台时 begin 会 best-effort 补传事件，失败只告警。
-0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；测试基线已由上一步 gate begin 内部建立，不得再次执行 guard begin
-1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。detect 在嵌套/多组件仓库返回 `DETECTION_AMBIGUOUS` 时，响应里的 `profileTemplate` 就是可填骨架（已含 defaultsFingerprint、excludedRoots 默认集与 commands 条目形状），按 `hint` 填好写入 `.harness/config/build-profile.json` 即可，**不要去反读 `harness_profile.py` 源码凑结构**。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
-3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-4. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 必须取返回的 `nextPhases` 或 `plannedPhases` 中 run 的真实后继，禁止写死 test。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
-
-**阶段归属规则**：只用 `ownerPhase=run` 的任务和场景判定编码阶段结果。`ownerPhase=test` 的任务或场景按计划留给测试阶段属于正常移交，必须记录为“待测试阶段执行”，不得将编码阶段降级为 WARN；只有 run 自身负责的工作未完成、验证降级或证据异常时才使用 WARN。
-
-> 关门脚本与本规则一致：`harness_gate.py close --phase run` 的 C9 场景覆盖只要求 `ownerPhase` 为 `plan`/`run` 的必需场景有通过 receipt，`ownerPhase=test` 的场景出现在返回值的 `deferred` 里，不阻断 run。若 run 关门报 `REQUIRED_SCENARIO_NOT_EXECUTED` 且缺的是接口/端到端场景，那是 `meta/scenario-manifest.json` 里 `ownerPhase` 标错了（或老清单没声明），应当修清单——**不要**为了过门在 run 阶段起服务补跑本属 test 的验证。
-
-**Fixback**：入口只用 `launch-review`，后续问题处理通过 `resolve-issue/close` 驱动，不得把修复说明当成新的普通 Run。只读取返回的受影响问题和文件；验证仅失效与 `changedFiles` 相交的目标，其他 Test/Review 证据继续复用。RED 优先；`manual`、`workflow` 或未选用的建议不进入代码批次，使用中文记录处理结论。
-
-**构建/测试执行入口**：所有构建与测试命令（mvn / gradle / npm test / pytest 等）必须经 `harness_test_runner.py exec` 发起，**禁止**用 `powershell.exe -Command` 直接裸跑：
-
-```text
-python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
-```
-
-该入口持有项目级互斥锁并托管进程树。裸跑构建在宿主工具超时后会被推入后台，多个后台构建同时写同一个 `target/`、`build/` 或 `node_modules/.cache`，表现为编译产物被清空、日志文件被占用、"增量编译抖动"——这些都不是代码缺陷，是并发自相残杀，排查成本极高。`--timeout-seconds` 按最慢的一次全量构建估（默认 300 秒偏短），宁可给足也不要让命令被中途掐断。
-
-返回 `TEST_RUN_ALREADY_ACTIVE`（退出码 3）说明**已有构建在跑**：等它结束或用 `lock-status` 查明持有者，**不得**改用裸跑绕开锁，也不得另起一个并行构建。确认持有进程已消失时才用 `lock-reap` 回收。
-
-**长阶段租约**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，**也不再阻断收尾**：`gate close` 发现租约过期而 run-id 仍是本阶段的，会自动用原 run-id 重取并照常关门，只在返回体的 `leaseLapsed` 里记下这个阶段跑过了 TTL。过期本身不说明所有权变了——抢占会重写租约文件把 run-id 换掉，那时报的是 `LEASE_OWNER_MISMATCH`。
-
-因此**不需要**为了长阶段定期续租。确实想让租约始终有效时，用本阶段原 run-id 刷新即可（同 run-id 重复 claim 即刷新，不会新开 attempt）：
-
-```text
-python <skills-root>/scripts/harness_change.py claim --change <id> --phase run --run-id <本阶段 run-id> --ttl-seconds 3600 --json
-```
-
-仍然报 `LEASE_ABSENT` 说明这个阶段**根本没有租约记录**（从未 begin，或已被释放），不是超时；先确认 `gate begin` 真的跑过。报 `LEASE_INVALID` 说明租约文件损坏，无法证明没被抢占，需人工确认无并发后再用上面的命令重取。两种情况都**不要**重跑 `gate begin`——那会新开 attempt 并丢失本轮 capsule。
-
-**执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。
-
-**Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
-
-## P0 执行可信度规则
-
-- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
-- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
-- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
-
-## 生成内容语言约定
-
-- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
-- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
-> 片段：p0-trust
-
-## 关键规则（硬门禁速查）
-
-> 全文判定、示例、模板 → `reference.md`；ledger → `../protocols/ledger-protocol.md`
-
-| 域 | 要点 |
-|----|------|
-| **文档输入** | 只读 `.harness/changes/<cn>/`；禁止 `docs/superpowers/` |
-| **变更簇 TDD** | 一簇一次 RED/GREEN；低价值项豁免；新分支必须 RED |
-| **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`；阶段门禁与上下文交接统一用 `harness_gate.py begin/close`；gate 内部负责 guard begin/close，模型只在需要记录测试来源或修复时调用 guard 的 `record/stage/mark` |
-| **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
-| **关门/状态** | 10 项关门检查；持久化 run-task-status；仅 run-owned P0 静态-only 导致 WARN；test-owned 待办正常移交 |
-| **Worktree** | `requested=true` 时代码只写 worktree |
-| **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑 mvn/gradle/npm test；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
-| **租约** | 阶段超 TTL 由 close 自动用原 run-id 重取，无需续租；`LEASE_ABSENT`（无记录）/`LEASE_INVALID`（文件损坏）才需人工 `harness_change.py claim`，一律不重跑 begin |
-| **PowerShell** | 所有 git 经 `powershell.exe -NoProfile -Command` |
-
-### 陈旧测试安全修复与精确跟踪
-
-测试编译或 RED/GREEN 失败时，先区分当前实现缺陷、测试基础设施故障与陈旧测试。只有同时满足以下条件才允许自动修复陈旧测试：当前生产代码、已批准计划或可验证的历史变更能唯一确定新契约；修改范围仅限测试文件；修复后会立即重跑该测试及本变更目标测试。符合时以 `stale-test-repair` 记录：
-
-```text
-python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
-```
-
-新建或正常更新测试分别使用 `tdd-created` / `test-updated`。若预期行为存在业务歧义，停止测试修复并记录 `BLOCKED_PREEXISTING`，不得猜测新断言。
-
-**禁止临时排除测试**：不得将测试改名为 `.bak`、移出测试目录、删除、添加 `@Disabled`/`@Ignore`、修改 Surefire/Gradle exclude 或跳过测试来制造绿色结果；也不得仅为满足陈旧测试而修改生产代码。`.gitignore` 中的测试只能通过 manifest 的精确路径闭环处理，禁止全局放宽 ignore。
-
-## Output Format
-
-变更文件表 + 构建/测试证据 + 场景覆盖摘要 + 最终状态（✅OK / 🟡WARN / ❌FAIL）。→ `reference.md`
-
-## 渐进披露
-
-- **Read `protocols.md`** — run-tdd + change-cluster-review
-- **Read `reference.md`** — Step 0–5 细节、TDD/RED/ledger/迁移/安全矩阵
-- **Read `checklist.md`** — 逐步勾选
-
-## 交互白名单
-
-1. **预存变更**：保留 / 暂存 / 终止
-2. **数据库迁移**：展示审查清单并确认（**永不自动执行**）
-3. **worktree 创建失败**：是否改主目录
-
-## 执行日志
-
-`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
-
-**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
-`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
-auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
-（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
-
-```powershell
-# 阶段开始：gate begin 负责，note 在这里给
-python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
-# 阶段中的其他事件才用 append
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
-```
-
-> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
-
-> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
-
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
-
-阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
-> 片段：logging · phase=`run`