@hunter-harness/workflow-harness 0.4.0 → 0.4.2

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

@@ -0,0 +1,250 @@
+---
+name: harness-test
+description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
+  时使用；不得在 run 结束后自动接续执行。
+---
+<!-- generated by harness_deploy.py; core=3719b9e9d98df0f9; overlay=none; agent=pi; 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/pi/harness-test/checklist.md

@@ -0,0 +1,359 @@
+---
+description: harness-test 的 Phase 0 环境准备 + Playwright 探测 + 关门检查清单。仅在执行测试前的环境准备阶段读取。
+---
+
+# harness-test 检查清单 — Phase 0 环境准备 + 关门检查
+
+以下检查项确认完了再开始测试。每一项背后都有踩坑经历。
+
+### Wave-A 环境合同（IA-3）
+
+- [ ] 需要可写 DB/栈时：先 `harness_environment.py fingerprint` → `acquire` lease → 再跑测试 → `release`
+- [ ] 无 lease 不得占用可写栈（`ENVIRONMENT_LEASE_REQUIRED`）；跨 change 默认可写共享拒绝（`ENVIRONMENT_LEASE_CROSS_CHANGE`）
+- [ ] 租约目录：主仓 `.harness/runtime/env-leases/`（与 change 状态目录分离）
+
+#### 0.0 加载项目配置（如存在）与确定变更名
+
+先检查当前项目的测试配置文件（按优先级查找）：
+
+1. **优先**：`.harness/config/harness-test-config.md`（集中配置目录）
+2. **兼容**：`harness-test/harness-test-config.md（兼容旧路径）`（旧路径，过渡期仍支持）
+
+如果任一文件存在，**必须先读取并应用其中的配置**。配置文件通常包含：
+
+- **登录端点**：本地无法直接登录时，远程认证服务（如 SSO/Gateway）的登录 URL
+- **测试账号**：各权限级别的用户名密码（如 admin、一层组织管理员等）
+- **真实测试数据**：有效的部门编码和名称、项目 ID、规则 ID 等
+- **环境调整**：需要使用的 profile、需要临时放行的 URL 路径、需要跳过的模块
+- **避坑补充**：本项目特有的已知问题和解决方案
+
+**Profile 选择**（从配置文件读取，如无配置则询问用户；按技术栈，Java Spring Boot 为例）：
+
+| Profile | 适用场景 | 配置文件（按技术栈） |
+|---------|---------|---------|
+| `local` | 连接远程数据库/缓存 | 应用本地配置（如 `application-local.yml`） |
+| `local-dev` | 完全本地隔离 | 应用本地隔离配置（如 `application-local-dev.yml`） |
+
+> **关键**：不指定 profile 时默认使用主应用配置文件（如 `application.yml`）中的配置（可能指向生产环境），必须显式指定。启动命令必须包含对应技术栈的 profile 指定参数（如 Spring Boot 的 `--spring.profiles.active=<profile>`）。
+
+然后确定变更名：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。
+
+#### 0.0-A 资源安全档位（所有测试的硬前置）
+
+- [ ] 默认选择 `safe`，测试命令由 `harness/scripts/harness_test_runner.py` 托管；禁止裸跑整库 discovery 或工具默认无限并发
+- [ ] Python `unittest` 使用逐模块隔离模式；每个 `test_*.py` 在独立解释器中串行执行，失败默认立即停止
+- [ ] 同项目单实例锁已获得；出现 `TEST_RUN_ALREADY_ACTIVE` 时停止，不得启动第二套测试
+- [ ] `HARNESS_TEST_MAX_WORKERS` 为 `1` 或 `2`，且技术栈自身 worker 参数不高于该值
+- [ ] 每个模块/命令设置明确超时；超时返回 `TEST_COMMAND_TIMEOUT` 并清理整棵进程树
+- [ ] Windows 普通模块使用 kill-on-close Job Object；显式测试 detached service 的模块改用精确 PID 血缘跟踪；其他平台使用独立进程组
+- [ ] Windows detached-service 模块执行前 nested-breakaway preflight 已通过；`DETACHED_PROCESS_CAPABILITY_UNAVAILABLE` 时立即停止并切换到允许该能力的执行环境，不逐用例等待超时
+- [ ] 任一隔离模式返回 `PROCESS_TREE_ISOLATION_UNAVAILABLE` 时停止资源密集型测试
+- [ ] `system` / `full` 属于资源密集型档位：用户明确授权后才传 `--confirm-resource-intensive`；受控 CI 可用 `CI=true`
+- [ ] `safe` 不包含服务生命周期和集成模块；`full` 仍按“普通模块 → 资源密集型模块”顺序串行，不得恢复单进程全量 discovery
+- [ ] 测试前记录已有工作区状态；测试后状态只允许包含本轮预期变化，不要求删除用户原有变更
+
+#### 0.1 命令执行模式 preflight（⚠️ 必须在编译/启动服务/生成执行器之前执行）
+
+- [ ] 检查 PowerShell 基础命令：`powershell.exe -NoProfile -Command "$PSVersionTable.PSVersion"` 返回 exitCode=0
+- [ ] 检查执行器运行时可用性（如 Node 绝对路径）：`powershell.exe -NoProfile -Command "& 'C:\nvm4w\nodejs\node.exe' --version"` 返回 exitCode=0
+- [ ] 检查构建工具可用性（如 Maven）：`powershell.exe -NoProfile -Command "mvn -version"` 返回 exitCode=0
+- [ ] 检查安全分类器：上述任一命令是否返回"安全分类器暂时不可用" / Auto mode 拦截 → **不应出现**
+- [ ] 将通过的 `executorPath` / `powershellVersion` / `buildToolVersion` 写入 `.harness/changes/<change-name>/runtime/preflight.json`
+- [ ] **任一情况触发硬停**：原文输出"❌ 命令执行模式不可用：PowerShell/接口测试执行器无法稳定执行..."，**不得继续编译/启动服务/生成执行器，不得长时间等待，不得盲目降级到 Playwright MCP**
+- [ ] 用户确认切换权限模式后，**重新执行 0.1**；重试 ≤ 1 次
+
+#### 0.2 fallback 执行器探测（仅在首选执行器不可用时执行）
+
+- [ ] 如果 0.1 已确认首选接口测试执行器可用：标记 `NOT_NEEDED`，**跳过本阶段**，直接使用接口测试执行器
+- [ ] 仅当首选执行器不可用时，检查 PowerShell batch runner (`.ps1`) 是否可用
+- [ ] 仅当 PowerShell batch 也不可用时，检查 Claude Code 是否暴露 Playwright MCP 工具（`mcp__plugin_playwright_playwright__*` 存在）
+- [ ] 检查 `claude mcp list` 中是否有 playwright（如果可以执行命令）
+- [ ] 检查 `@playwright/mcp` 是否可启动
+- [ ] 检查当前 skill 的 `allowed-tools` 是否允许 Playwright 相关工具
+- [ ] 输出 fallback 执行器可用性表格（见 reference.md）
+- [ ] 记录决策：接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl fallback
+- [ ] 如果 fallback 不可用，必须写明原因，不得静默改用 curl
+
+#### 0.3 依赖模块预安装检查
+
+> **强制检查，不可跳过。** 即使服务已运行，worktree 中的编译仍可能缺少依赖（服务可能从主目录启动）。
+
+**在编译前检查上游依赖模块是否已安装到本地仓库**（按技术栈，Java/Maven 为例）：
+
+```powershell
+powershell.exe -Command "Test-Path '$env:USERPROFILE\.m2\repository\<group-path>\<module>\*\*.jar'"
+```
+
+如果缺失，先安装上游依赖：
+```powershell
+powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"
+```
+
+#### 0.4 编译确认（按技术栈，Java/Maven 为例）
+
+```powershell
+powershell.exe -Command "Test-Path 'target/classes/<package>/<ChangedClass>.class'"
+```
+编译产物时间戳早于源文件 → 重新编译：
+```powershell
+powershell.exe -Command "mvn compile -pl <module> -o -q"
+```
+
+**编译成功必须有证据**：
+- 构建工具输出包含成功标志（如 Maven 的 `BUILD SUCCESS`）才能继续测试
+- 如果命令被 hook 拒绝（`Denied` / `PreToolUse:Bash hook error`），停止流程
+- 不得在编译失败时继续宣称"准备进入测试阶段"
+
+#### 0.5 认证方案确认
+
+| 方案 | 适用场景 | 操作 |
+|------|----------|------|
+| A. 配置放行 | 纯本地开发 | 应用配置文件中放行测试接口（如 `permit-all-urls`） |
+| B. 本地凭证 | 有本地认证服务 | 通过本地登录接口获取认证凭证 |
+| C. 权限降级 | 临时测试 | 无认证上下文时降级为高权限账号 |
+
+> ⚠️ 方案 A 或 C 时，测试完成后确认还原配置。
+
+#### 0.6 请求头确认
+
+所有 HTTP 请求必须带：`Content-Type: application/json; charset=UTF-8` 和租户标识（如项目适用，如 `tenant-id: <从配置读取>`）。
+
+#### 0.7 编码确认
+
+Windows 环境特别注意：
+- 不要用 `curl` 发送含中文的请求体（curl 在 Windows 默认用 GBK 编码）
+- 优先用接口测试执行器；单次临时请求可用 PowerShell `Invoke-RestMethod`
+- curl 仅作为最后兜底，且必须用 UTF-8 JSON body file
+
+#### 0.8 配置文件完整性检查
+
+**如果使用 worktree**，检查配置文件是否完整（按技术栈，Java Spring Boot 为例）：
+
+```powershell
+powershell.exe -Command "Test-Path '<worktree-path>/<module>/src/main/resources/application-<profile>.yml'"
+```
+
+如果缺失，从主目录复制：
+```powershell
+powershell.exe -Command "Copy-Item '<main-dir>/<module>/src/main/resources/application-<profile>.yml' '<worktree-path>/<module>/src/main/resources/' -Force"
+```
+
+**检查关键配置项**（读取配置文件内容确认，按项目）：
+- 外部服务地址（如 `workflow.baseUrl` 或类似属性）— 缺失会导致组件初始化失败
+- 服务注册开关（如 `spring.cloud.nacos.discovery.register-enabled: false`）— 缺失会导致线上流量路由到本地
+- 接口放行配置（如 `udp.security.permit-all-urls`）— 需包含本次测试的接口路径
+
+#### 0.9 Playwright 远程访问确认
+
+如果接口测试需要通过 Playwright 访问远程服务（如远程认证服务获取凭证），确认 Playwright MCP 配置允许目标地址。
+
+检查 `.mcp.json` 或全局 MCP 配置中 Playwright 的 `allowedOrigins`：
+```json
+{
+  "playwright": {
+    "allowedOrigins": ["http://localhost:*", "http://<remote-ip>:*"]
+  }
+}
+```
+
+> 如果 Playwright 无法访问远程地址，降级为 PowerShell Invoke-RestMethod 获取认证凭证。
+
+#### 0.10 服务确认、服务决策门与启动等待
+
+检查服务是否运行（优先使用已知接口，不依赖通用健康端点如 `/actuator/health`）：
+
+```powershell
+powershell.exe -NoProfile -Command "Test-NetConnection -ComputerName localhost -Port <port>"
+powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.0.1:<port>/<context-path>/meta' -UseBasicParsing -TimeoutSec 3).StatusCode } catch { $_.Exception.Message }"
+```
+
+**如果端口已有应用服务进程，必须先进入服务决策门（Service Decision Gate），禁止先跑业务接口。**
+
+需要展示：pid、profile、startTime、commandLine、healthResult、serviceFingerprint(match/missing/mismatch)、当前源码是否晚于服务启动时间。
+
+询问用户：
+
+```text
+1. 直接复用当前服务
+2. 重启服务，使用已知良好测试配置
+3. 跳过接口测试，只执行单元测试
+4. 停止测试
+```
+
+只有 `runtime/service-session.json` 与当前**同时**满足 `moduleInputsHash`/`startCommandHash`/`profile`/`overlayPath` 一致且进程身份（pid 存活 + create time）可确认时，才允许自动复用（§5.3）。任一变化 -> restart；身份无法确认 -> `needs-user-decision`；非 AI 用户进程不自动 kill。否则必须询问。`moduleInputsHash` 来自 CLI `--files` ∪ `serviceStart.inputFiles`，**空输入被拒绝**（不生成空指纹）。
+
+**如果服务未运行**，询问用户：
+
+```text
+服务未启动（端口 <port> 无响应）。请选择：
+1. AI 启动 — 使用已知良好测试配置，serviceState=AI_STARTED
+2. 用户手动启动 — 启动后告诉我继续，serviceState=USER_STARTED
+3. 跳过接口测试 — 只运行单元测试，serviceState=NOT_STARTED
+4. 停止测试
+```
+
+**如果用户选择 AI 启动或 AI 重启**：
+1. 从已知良好测试配置读取 module/profile/port/healthUrl/sdkUrl（按项目配置）。
+2. 生成 ASCII 运行时配置叠加：`C:/temp/harness-test-overlay/<change-name>/application-harness-test.yml`（按技术栈；Java Spring Boot 的 application.yml 为例）。
+3. 禁止默认直接 Edit tracked 应用配置文件（如 `application-local-dev.yml`）。
+4. 默认启动命令（按技术栈，Java Spring Boot 为例）：
+   ```powershell
+   powershell.exe -NoProfile -Command "mvn spring-boot:run -pl <module> -Dspring-boot.run.profiles=<profile> -Dspring-boot.run.jvmArguments='-Dspring.config.additional-location=file:C:/temp/harness-test-overlay/<change-name>/application-harness-test.yml'"
+   ```
+5. 写入 `service.pid`、`service-start-command.txt`、`service-start.log`、`runtime/service-session.json`（含 `moduleInputsHash`/`moduleInputsFiles`/`startCommandHash`/`profile`/`overlayPath`/`pid`/`startedBy=AI`/`startedAt`）。`moduleInputsHash` 来自 CLI `--files` ∪ `serviceStart.inputFiles`，空输入拒绝。
+6. 服务启动等待：0–30s 每 2s 探测；30–120s 每 5s 探测；>10s 必须输出状态行；>120s 读取最近 200 行日志。
+7. 发现启动失败特征（按技术栈识别，如 Java Spring Boot 的 `BindException` / `Could not resolve placeholder` / `Connection refused during bean init` / `BeanCreationException` / `Failed to start bean` / `BUILD FAILURE`）立即失败。
+
+#### 0.10.x 重入沿用（同一变更 harness-test 再次执行时）
+
+满足以下**全部**条件时，可沿用上次服务决策，不重复询问：
+
+1. 重入：同一 change-name 的 harness-test 再次执行（非首次）
+2. 环境未变：PG 可用性、目标端口、执行器可用性与上次一致
+3. 上次已确认执行器方案（如"内存 HTTP 执行器，PG 不可用"）
+4. 当前源码未改服务启动逻辑（如未改 main.ts 启动路径、未改服务端口/profile 配置）
+
+沿用时执行日志记录：`重入沿用上次服务决策 + 环境未变（PG=<同上次>、执行器=<同上次>）`。
+
+**不适用重入沿用**（仍须询问/重启）：
+- 真实二进制服务需重启（service-fingerprint 不匹配）
+- 环境已变（PG 从不可用变可用、端口被占、执行器丢失）
+- 上次 serviceState=USER_STARTED（用户手动启动，状态未知）
+- 源码改动影响服务启动逻辑
+
+> in-process 内存执行器（无持久服务进程）的重入沿用最常见：PG 不可用→内存 HTTP 执行器方案在环境未变时可沿用，不重复询问服务决策门。
+
+#### 0.11 服务生命周期收尾（即使测试失败也要进入 finally 清理）
+
+测试结束前必须按 serviceState 分支处理：
+
+- `AI_STARTED` → 默认 `Stop-Process -Id <pid> -Force`，删除 `service.pid`，记录 `testServiceStopped=✅`。
+- `AI_RESTARTED_FROM_USER_SERVICE` → 默认停止新服务，报告中明确 `restoredOriginalService=❌ not supported`。
+- `USER_STARTED` → 保留进程，报告中提示用户可手动停止。
+- `REUSED_EXISTING` → 保留进程，除非用户明确要求关闭。
+
+测试报告与 `summary-data.json` 的服务生命周期投影必须包含：
+
+```md
+## 服务生命周期
+| 项 | 值 |
+|---|---|
+| originalServicePid | ... / N/A |
+| originalServiceStopped | ✅ / ❌ / N/A |
+| testServicePid | ... / N/A |
+| testServiceStopped | ✅ / ❌ / N/A |
+| restoredOriginalService | ❌ not supported / N/A |
+| finalPortState | no service / service running |
+```
+
+> 不要使用 Monitor 工具等待健康检查，直接用 PowerShell 检查已知接口。通用健康端点（如 Spring Boot 的 `/actuator/health`）可能返回 404。
+
+#### 0.12 服务注册风险确认（如项目适用）
+
+确认应用配置文件中服务注册开关关闭（如 Spring Cloud Nacos 的 `spring.cloud.nacos.discovery.register-enabled: false`），避免线上流量被路由到本地。
+
+## 接口测试执行检查
+
+### 认证凭证缓存与复用
+
+- [ ] 检查 `.harness/changes/<change-name>/runtime/credential-cache.json` 是否存在
+- [ ] 如果存在 → 读取已有认证凭证，用**本地轻量接口**（直连本地 baseURL）验证有效性
+- [ ] 验证通过 → 复用，不重新登录、不访问远程认证服务
+- [ ] 验证失败（401/expired） → 才访问远程认证服务（如 SSO）重新获取后写回 cache
+- [ ] 同一上下文中，前面已获取过凭证时必须优先复用
+- [ ] **同一次测试流程内只允许因凭证失效重新获取 1 次**；超过 1 次 → 🟡 WARN，记录原因
+- [ ] 接口测试执行器用 request context / 原生 HTTP 客户端直连本地 baseURL，**不依赖浏览器当前页面 origin**
+- [ ] **不得因浏览器 origin 在远程认证服务就重新获取凭证**；禁止"远程取凭证→导航 localhost→重新取凭证"
+- [ ] **不得在报告、execution-log、对话总结中输出明文凭证**
+
+### 单元测试复用（ledger 驱动）
+
+- [ ] Phase 1 前通过 state layout resolver 定位并检查 `evidence/verification-ledger.json`
+- [ ] 判断是否复用 run 的 unitTest：diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 实际跑了全量测试
+- [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-run 单元测试结果"
+- [ ] 不复用 → 按 profile key resolve 重跑测试命令（`harness_profile.py resolve --key unitTest`，不复制示例 `-pl` 命令），结果写回 ledger 的 `unitTest` 项
+- [ ] HTTP/API 契约结果写入 `apiTest`；真实浏览器/真实栈 Playwright 结果写入 `browserTest`，两者不得互相覆盖
+- [ ] **本变更没有该维度场景时**（如全部为单元场景 → 无 API 场景）：用 `harness_ledger.py record --verification apiTest --status NOT_RUN --applicability NOT_APPLICABLE --applicability-reason "<为什么不适用>"` 登记，**不传 `--files`**。门禁 close 要求 requiredValidations 每项都有 entry，但**绝不能拿无关文件（比如单元测试文件）凑 `--files`**——那会让 ledger 声称该维度的输入是那些文件，是假证据
+- [ ] `can-reuse` 返回 `reuse:false` 时直接读默认输出里的 `reason`/`executionNeed`/`detail` 定位原因，不必再补跑 `--verbose`
+- [ ] 复用判断前以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 重算指纹；test-tracking manifest 无效或 hash 漂移即停止
+- [ ] 测试失败若明确为陈旧测试，仅在当前代码/批准计划/可验证历史唯一确定新契约且只改测试时自动修复；否则记录 `BLOCKED_PREEXISTING`
+- [ ] 自动修复后立即重跑该测试与目标测试，并以 `harness_test_guard.py record ... --reason stale-test-repair` 记录精确路径
+- [ ] **禁止临时排除测试**：未使用 `.bak`/改名/移目录/删除/禁用注解/build exclude/skip-tests 制造通过；服务启动的 `maven.test.skip` 不作为测试证据
+
+### 批量执行器（强制单次 PowerShell + 执行器绝对路径执行）
+
+- [ ] 0.1 preflight 已通过，`preflight.json` 包含 `executorPath`
+- [ ] 生成 `.harness/changes/<change-name>/runtime/api-test-runner.mjs`（按技术栈选择实现，Node runner 为一种实现），**按 setup / test / cleanup 三阶段结构**编写
+- [ ] payload 来自数据契约 / 接口定义 / 真实样例，执行器注释/JSON 中标注字段来源；**禁止临场猜字段、禁止先跑失败接口再补**
+- [ ] 唯一前缀 `TEST_<change-name>_<timestamp>_<random>`，唯一约束字段用随机或避让策略，避免冲突导致 BLOCKED
+- [ ] 通过**一次命令**执行（PowerShell + 执行器绝对路径）：
+   ```powershell
+   powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<executorPath>' '.harness/changes/<change-name>/runtime/api-test-runner.mjs'"
+   ```
+- [ ] **禁止**裸 `node ...`、禁止用 Bash 执行 node
+- [ ] 执行器失败 ≤ 1 次重试；仍失败 → 提示用户切换权限模式或手动执行，**不得继续盲目重试或长时间等待**
+- [ ] 执行器输出 `.harness/changes/<change-name>/runtime/api-test-results.json`，包含
+      `passed/failed/blocked/skipped/setupErrors/cleanupResult/credentialRefreshCount`
+- [ ] **setup 失败时依赖该数据的场景必须标 🟡 BLOCKED，不得用 null ID 继续请求**
+- [ ] 主会话只 Read JSON 生成摘要，不再调用 MCP
+- [ ] **只有首选执行器不可执行才降级**：PowerShell batch (.ps1) → 多次 MCP `browser_evaluate` → curl
+- [ ] **如果执行器在 PowerShell 可用，禁止使用 Playwright MCP 逐条执行接口测试**
+- [ ] 执行器直连本地 baseURL，复用认证凭证，不依赖浏览器 origin
+- [ ] 记录每个请求的 requestDurationMs、status、code、message、assertionResult
+- [ ] 支持失败时继续执行后续非依赖场景
+- [ ] 报告区分四种执行器：**接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl**（不得与"Playwright"混写）
+
+### 测试数据命名
+
+- [ ] 所有测试数据使用前缀 `TEST_<change-name>_<timestamp>_<random>`
+- [ ] 测试报告记录测试数据表（ID、Code、用途、是否需要清理）
+- [ ] 测试结束后清理可清理的数据
+- [ ] 不能清理的记录遗留数据和原因
+
+### 请求耗时（§5.22 分层耗时）
+
+- [ ] 每个请求记录 requestDurationMs（单 HTTP 请求耗时）
+- [ ] 整个批次记录 batchDurationMs（runner wall-clock）
+- [ ] requestDurationMs > 10000 → 🟡SLOW，说明原因
+- [ ] requestDurationMs > 30000 → ❌TIMEOUT_RISK，说明原因
+- [ ] batchDurationMs > 180000 → 🟡BATCH_SLOW
+- [ ] 聚合合同套件场景只记录 batch reference + coveredTests，**禁止均摊生成伪 requestDurationMs**
+
+### 覆盖标注诚实性（✅ 实测 vs 🟡 推断）
+
+场景状态标注规则：
+
+- [ ] ✅ 仅当断言实际执行**且**场景声明的前置条件/数据真实构造
+- [ ] 🟡（推断）：未构造场景条件、以相邻场景或同接口行为推断时使用，必须注明推断依据
+- [ ] 用同一请求重复调用来"覆盖"不同异常场景 → 一律 🟡
+- [ ] 报告汇总行的通过数只统计 ✅（不含 🟡 推断）
+
+## 关门检查（⚠️ 结束前强制执行）
+
+- [ ] `powershell.exe -NoProfile -Command "git status --porcelain"`
+- [ ] `powershell.exe -NoProfile -Command "git diff --stat"`
+- [ ] `powershell.exe -NoProfile -Command "git diff --check"`（如果失败 → 最终结果 ❌FAIL）
+- [ ] 检查报告和日志是否包含明文凭证/password/secret/access-key/client-secret
+- [ ] 检查 `.harness/changes/<change>/runtime/` 是否不会被提交（.gitignore 确认）
+- [ ] **服务生命周期收尾**：AI_STARTED→Stop-Process / USER_STARTED→提示 / REUSED_EXISTING→保留或确认 / NOT_STARTED→N/A
+- [ ] **资源生命周期收尾**：Runner 单实例锁已释放，测试进程树无新增残留，未对用户原有 Python/Node 进程做宽泛清理
+- [ ] 检查测试数据是否需要清理
+- [ ] 检查请求执行器结果是否完整（4 种执行器，未与接口测试执行器混写）
+- [ ] 检查是否存在慢请求或超时风险
+- [ ] **API 维度状态正确**：5 PASS + 9 BLOCKED + 1 FAIL → `apiTest=PARTIAL`，不得写成 `NOT_RUN`
+- [ ] 如果存在未清理测试数据、fallback 请求执行器、慢请求或环境变更 → 至少 🟡WARN
+
+## 关键原则
+
+- 如果有项目配置文件，优先从 `.harness/config/harness-test-config.md` 读取并应用（含已知良好测试配置）
+- 环境准备（阶段 0）的 **命令执行模式 preflight + 各项环境检查 + fallback 执行器探测** 必须在测试之前全部通过
+- 单元测试优先于接口测试（先跑测试命令，通过后再跑接口）
+- 接口测试优先级：**接口测试执行器 > PowerShell batch > Playwright MCP browser_evaluate > curl**
+- 单用例失败不阻塞后续用例；setup 失败时依赖场景必须标 🟡 BLOCKED，**不得用 null ID 继续请求**
+- 失败类型必须区分：代码 Bug vs 测试脚本问题 vs 预存问题
+- 测试数据使用唯一前缀命名 + 唯一约束字段随机或避让，测试后确认清理或记录遗留
+- 测试报告持久化到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行）
+- 请求执行器必须在报告中明确记录（四种执行器，含降级原因）
+- 请求耗时统计必须包含在报告中
+- 服务由 AI 启动的情况，测试结束默认 Stop-Process；**即使测试失败也要进入 finally 清理**
+- `summary-data.json` 与平台监控中的 `apiTest` 状态必须使用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）