@hunter-harness/workflow-harness 0.2.72 → 0.2.74

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

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d0ad43fe132b6817; overlay=none; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -18,7 +18,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## 前置条件
 
-- `spec/*-design.md`、`plans/*-plan.md`（含 frontmatter）存在且已审批
+- 设计文档（`plans/*-design.md` 优先，回退 `spec/*-design.md`）与 `plans/*-plan.md`（含 frontmatter）存在且已审批
 - 读 `meta/worktree.json`：`requested=true` 时 worktree 须存在或 run 负责创建
 
 ## Worktree 门禁
@@ -41,9 +41,9 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 ## 统一读取协议
 
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **spec** — 设计真相源：`spec/<change>-design.md`
+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`
@@ -59,10 +59,10 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## Workflow 概要
 
-0. 加载上下文：普通 Run 先 `harness_context.py prepare --phase run --executor <tool> [--change <id>] --json`，再 **`harness_context.py begin --phase run --change <id> --executor <tool> --json`** 校验交接，最后运行 **`harness_gate.py begin --phase run --change <id>`**。`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. 加载上下文：普通 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、规范命令和输入闭包；不得再手填另一套身份。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
+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` 原样重试，已完成步骤幂等复用。
 

package/harness/bundles/general/codebuddy/harness-run/checklist.md

@@ -29,7 +29,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 读取并执行 `meta/worktree.json`：如果 `requested=true` 必须创建/切换 worktree，创建失败则停止或询问用户改为主目录；禁止静默降级
 - [ ] **读取计划文件（主任务源）**：`.harness/changes/<change>/plans/<change>-plan.md` — 获取任务列表和依赖关系
 - [ ] **读取详细计划（补充参考）**：`.harness/changes/<change>/plans/<change>-implementation-detail.md`（新版必需；legacy 缺失时 🟡WARN）
-- [ ] **读取设计文档**：`.harness/changes/<change>/spec/<change>-design.md` — 获取核心设计决策和不变项
+- [ ] **读取设计文档**：`.harness/changes/<change>/plans/<change>-design.md`（v2）；不存在时回退 `spec/<change>-design.md`（legacy）— 获取核心设计决策和不变项
 - [ ] **读取测试场景表**：`.harness/changes/<change>/plans/<change>-test-scenarios.md` — 获取与当前任务相关的测试场景
 - [ ] **读取验证账本**：通过 context 返回的 `executionRoot` 读取 `evidence/verification-ledger.json`（如存在）— 复用已有 compile/unitTest 结果
 - [ ] **读取任务状态**：`.harness/changes/<change>/evidence/run-task-status.md`（如存在）— 恢复上次运行状态
@@ -39,7 +39,10 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 检查构建配置完整性（worktree 中确认构建配置文件存在，如 Java 的 `.mvn/maven.config`、`settings.xml`，前端的 `package.json`/lockfile 等）
 - [ ] 依赖模块预安装（worktree 中检查上游依赖是否已安装，如 Java 的 `mvn install`、前端的 `npm install`/lockfile 等）
 - [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
+- [ ] `harness_context.py prepare/begin` 均带 `--project .` 与 `--change <id>`（缺 `--project` 会被 argparse 直接拒）
+- [ ] 交接凭证缺失时**不自行拼造**：v2 计划由 `prepare` 依据 committed 发布 journal 自动补录；仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 即代表发布证据不存在，回 plan 阶段查，不得用 `classify + configure-plan + close` 现编凭证
 - [ ] `harness_gate.py begin --phase run` 已返回 Plan handoff 校验通过并自动 append `phase.start`；不得手工写事件绕过
+- [ ] 门禁报 `SCENARIO_MANIFEST_V2_UNSUPPORTED` 时按 `missingFields` 回规划阶段补齐场景字段后重新发布；**不得**手改 `meta/scenario-manifest.json`（派生产物，手改必致哈希漂移）
 
 ### 步骤 0.1：执行模式（无询问）
 

package/harness/bundles/general/codebuddy/harness-run/reference.md

@@ -19,7 +19,7 @@ description: harness-run 的编译失败策略表、TDD循环详细步骤和编
 
 ## 前置条件
 
-- `.harness/changes/<change-name>/spec/<change-name>-design.md` 存在（含完整 frontmatter）
+- 设计文档存在：`plans/<change-name>-design.md`（v2）或 `spec/<change-name>-design.md`（legacy，含完整 frontmatter），按 `shared/read-protocol.md` 的顺序取第一个
 - `.harness/changes/<change-name>/plans/<change-name>-plan.md` 存在（含完整 frontmatter）
 - `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` 存在
 - `.harness/changes/<change-name>/plans/<change-name>-implementation-detail.md`（新版必需，legacy 缺失时 🟡WARN）
@@ -90,7 +90,7 @@ requested=true + path missing
 2. **读取并执行 worktree 决策**：读取 `.harness/changes/<change-name>/meta/worktree.json`。如果 `requested=false`，在主目录执行；如果 `requested=true` 且 worktree 存在，必须 cd 到该 worktree；如果 `requested=true` 且 worktree 不存在，必须创建 worktree，创建失败则停止或询问用户是否改为主目录执行。禁止静默降级。
 3. **读取计划文件（主任务源）**：`.harness/changes/<change-name>/plans/<change-name>-plan.md` → 获取任务列表和依赖关系
 4. **读取详细计划（补充参考）**：`.harness/changes/<change-name>/plans/<change-name>-implementation-detail.md`（新版必需，legacy 缺失时 🟡WARN）→ 获取自适应执行参考
-5. **读取设计文档**：`.harness/changes/<change-name>/spec/<change-name>-design.md` → 获取核心设计决策和不变项
+5. **读取设计文档**：`.harness/changes/<change-name>/plans/<change-name>-design.md`（v2 发布产物）→ 不存在时回退 `spec/<change-name>-design.md`（legacy）→ 获取核心设计决策和不变项
 6. **读取测试场景表**：`.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` → 获取测试真相源
 7. **读取验证账本**：通过 state layout resolver 定位 `evidence/verification-ledger.json`（如存在）→ 复用已有 compile/unitTest 结果
 8. **读取任务状态**：`.harness/changes/<change-name>/evidence/run-task-status.md`（如存在）→ 恢复上次运行状态
@@ -113,7 +113,7 @@ requested=true + path missing
 
 ```
 检查逻辑：
-1. 读取 .harness/changes/<change-name>/spec/<change-name>-design.md
+1. 读取 .harness/changes/<change-name>/plans/<change-name>-design.md（不存在则回退 spec/<change-name>-design.md）
 2. 读取 .harness/changes/<change-name>/plans/<change-name>-plan.md
 3. 读取 .harness/changes/<change-name>/plans/<change-name>-implementation-detail.md（legacy 缺失时 🟡WARN）
 4. 读取 .harness/changes/<change-name>/plans/<change-name>-test-scenarios.md

package/harness/bundles/general/codebuddy/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d0ad43fe132b6817; overlay=none; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -30,9 +30,9 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 ## 统一读取协议
 
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **spec** — 设计真相源：`spec/<change>-design.md`
+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`
@@ -54,10 +54,11 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 
 ### 提交流程（步骤 0–7）
 
-0. **启动准备** — `harness_context.py prepare --phase submit --executor <tool> [--change <id>] --json` 确定唯一变更与 executionRoot；`harness_context.py begin --phase submit --change <id> --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
+0. **启动准备** — `harness_context.py prepare --project . --change <id> --phase submit --executor <tool> --json`（`--project` 必填）确定唯一变更与 executionRoot；`harness_context.py begin --project . --change <id> --phase submit --executor <tool> --json` 校验 review→submit receipt；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo <executionRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（`executionRoot` 必须直接取准备回执；禁止手写 ledger / 手工 phase.end）
 1. **合并最新代码** — 主目录与 worktree 均**不在业务工作区 stash/pull**；远端同步由合并段 integration transaction 在隔离 integration worktree 内完成（见「worktree 合并流程」）；**正常路径禁止 `git stash` / `stash pop`**
 2. **最终验证** — ledger 复用优先；提交前只调用 `can-reuse --project . --profile-input unitTestFull --command <profile 规范命令>`。不得传入另一套 `--files`，不得把 runner 包装说明写进 `command`。`reuse=true` 时禁止重跑；只有真实输入、依赖、工具链或环境身份变化时才执行一次同一 profile 验证，并只登记一条结果。不要读取 ledger/archive 实现源码或临时编写散列脚本排查参数。
    - 无远端 CI 且 gate-policy 未强制 remote provider 时，验证通过/复用后运行 `harness_archive.py certify-local --change-dir ... --project . --json`，从同一 ledger 生成 `local-reproducible` 产品候选收据；该命令不执行测试。
+   - **被与本变更无关的预存失败卡住时的正规出路**：用 `harness_preflight.py record-quirk --project . --action skip-not-block --pattern "<具体错误签名，≥8 字符>" --reason "<为什么与本变更无关>"` 把它声明进 build-profile 的 `knownPreexistingErrors`，certify-local 会在**该失败的 ledger 证据里确实出现该签名**时放行，并把 `{validation, pattern, reason}` 写进收据的 `verification.preexistingExemptions` 留痕。**不得**改 gate-policy 的 `candidateVerification.requiredValidations` 来绕过——那是把门禁本身拆掉。声明了但证据对不上、或签名短到能匹配一切，仍然阻断。
    - gate-policy 要求 `remote-attested` 时不得降级成本地收据，等待远端 attestation。
 3. **.gitignore + 精确暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**。若存在 `evidence/test-tracking.json`，先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；失败即硬停止。无 manifest 时不使用 `-f`。manifest 之外的文件按精确业务路径正常暂存，**禁止全局 force-add**。
 4. **提交方式** — 主目录：blocking user confirmation 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**

package/harness/bundles/general/codebuddy/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d0ad43fe132b6817; overlay=none; agent=codebuddy; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d0ad43fe132b6817; overlay=none; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -32,9 +32,9 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 ## 统一读取协议
 
 1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
 3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **spec** — 设计真相源：`spec/<change>-design.md`
+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`
@@ -85,7 +85,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-先 `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_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 只失效与改动文件相交的验证目标。
 

package/harness/bundles/general/codebuddy/harness-test/checklist.md

@@ -273,6 +273,8 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] 复用 → 跳过重跑，标记"✅ 复用 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` 记录精确路径

package/harness/bundles/general/codebuddy/scripts/harness_archive.py

@@ -991,6 +991,62 @@ def migrate_legacy_candidate_evidence(
     return receipt
 
 
+# 声明必须是具体的错误签名，不能是能匹配一切的短串。这个下限不是"安全边界"
+# ——审计线索才是——但它挡住最省事的滥用写法。
+_PREEXISTING_MIN_PATTERN = 8
+
+
+def _known_preexisting_patterns(
+    project_root: Path,
+) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    """build-profile 里声明的预存失败签名，按"是否足够具体"分成两组。
+
+    `knownPreexistingErrors` 由 `harness_preflight.py record-quirk --action
+    skip-not-block` 写入，此前没有任何消费方——于是预存失败在 certify-local 处
+    成为死结：要么去 gate-policy 降门禁，要么顺手改范围外的产品 bug。
+    """
+    path = project_root / ".harness" / "config" / "build-profile.json"
+    if not path.is_file():
+        return [], []
+    try:
+        profile = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, ValueError):
+        return [], []
+    declared = profile.get("knownPreexistingErrors") if isinstance(profile, dict) else None
+    if not isinstance(declared, list):
+        return [], []
+    usable: list[dict[str, str]] = []
+    vague: list[dict[str, str]] = []
+    for item in declared:
+        if not isinstance(item, dict) or item.get("action") != "skip-not-block":
+            continue
+        pattern = str(item.get("pattern") or "").strip()
+        reason = str(item.get("reason") or "").strip()
+        if not pattern or not reason:
+            continue
+        record = {"pattern": pattern, "reason": reason}
+        (usable if len(pattern) >= _PREEXISTING_MIN_PATTERN else vague).append(record)
+    return usable, vague
+
+
+def _match_preexisting(
+    entry: dict[str, Any], patterns: list[dict[str, str]]
+) -> dict[str, str] | None:
+    """失败证据里是否确实出现了某个已声明签名。
+
+    只看"声明过"是不够的——那等于声明一次豁免一切。必须是这一条失败的证据里
+    真的带着该签名，声明与现场才对得上。
+    """
+    evidence = entry.get("evidence")
+    haystack = evidence if isinstance(evidence, str) else json.dumps(
+        evidence, ensure_ascii=False, sort_keys=True
+    )
+    for record in patterns:
+        if record["pattern"] in haystack:
+            return record
+    return None
+
+
 def certify_local_candidate(
     change_dir: Path,
     *,
@@ -1029,14 +1085,28 @@ def certify_local_candidate(
         required = ["unitTestFull"]
     required = [str(item).strip() for item in required if str(item).strip()]
 
+    usable_patterns, vague_patterns = _known_preexisting_patterns(project_root)
+
     selected: list[dict[str, Any]] = []
+    exemptions: list[dict[str, Any]] = []
     for name in required:
         entry = validations.get(name)
         if not isinstance(entry, dict):
             raise ValueError(f"required validation missing: {name}")
         missing: list[str] = []
+        exempted = None
         if str(entry.get("status") or "").upper() != "OK":
-            missing.append("status=OK")
+            exempted = _match_preexisting(entry, usable_patterns)
+            if exempted is None:
+                vague = _match_preexisting(entry, vague_patterns)
+                if vague is not None:
+                    raise ValueError(
+                        f"required validation {name} failed and the declared "
+                        f"knownPreexistingErrors pattern {vague['pattern']!r} is too "
+                        "generic to identify it; declare the specific error signature "
+                        f"(at least {_PREEXISTING_MIN_PATTERN} characters)"
+                    )
+                missing.append("status=OK")
         for field in (
             "command",
             "evidence",
@@ -1048,6 +1118,15 @@ def certify_local_candidate(
             raise ValueError(
                 f"required validation {name} is incomplete: {', '.join(missing)}"
             )
+        if exempted is not None:
+            exemptions.append(
+                {
+                    "validation": name,
+                    "status": str(entry.get("status") or "").upper(),
+                    "pattern": exempted["pattern"],
+                    "reason": exempted["reason"],
+                }
+            )
         selected.append(
             {
                 "name": name,
@@ -1160,6 +1239,8 @@ def certify_local_candidate(
                 {str(item["inputsHash"]) for item in selected}
             ),
             "logHashes": sorted({str(item["logHash"]) for item in selected}),
+            # 豁免必须随收据一起留痕，否则事后无法把它与干净通过区分开
+            "preexistingExemptions": exemptions,
         },
     }
     if rebound_from_commit is not None:

package/harness/bundles/general/codebuddy/scripts/harness_context.py

@@ -732,6 +732,16 @@ def prepare_context(
         )
         if not reselection.get("ok"):
             return reselection
+    # v2 计划的交接凭证由此补录：finalize 不写 context 事务，缺它 run 阶段进不去
+    if phase != "plan":
+        _bootstrap_v2_plan_transition(
+            project,
+            change,
+            contract_root=contract_root,
+            state_root=state_root,
+            to_phase=phase,
+            executor=executor,
+        )
     claim = _claim_prepared_context(
         project,
         change,
@@ -779,6 +789,150 @@ def prepare_context(
     }
 
 
+def _plan_run_identity(change_dir: Path) -> tuple[str, int] | None:
+    """已存在的 plan `phase.start` 身份（run-id, attempt）。
+
+    finalize 按生命周期身份 fail-closed：重跑引导时换一个 run-id，整条链路就对不上。
+    因此引导必须复用已有身份，而不是每次新生成。
+    """
+    for item in reversed(_read_ndjson(change_dir / "events.ndjson")):
+        if item.get("phase") != "plan" or item.get("type") != "phase.start":
+            continue
+        run_id = item.get("run_id")
+        if isinstance(run_id, str) and run_id:
+            attempt = item.get("attempt")
+            return run_id, attempt if isinstance(attempt, int) and attempt > 0 else 1
+    return None
+
+
+def bootstrap_plan(
+    project: Path,
+    *,
+    change: str,
+    executor: str,
+    display_title: str | None = None,
+    stage: str = "plan",
+    ttl_seconds: int = 3600,
+) -> dict[str, Any]:
+    """阶段 0 一次性引导：doctor + prepare + capture + classify + phase.start。
+
+    拆成五条子进程调用时，每条的完整 argv 都要调用方记住（少 `--project` 或
+    `--change-dir` 就白跑一轮），run-id 还要调用方自己保证小写字母开头。这些都是
+    确定性工作，交给脚本做；调用方只需要一次调用和一份紧凑摘要。
+
+    重跑安全：已有 plan `phase.start` 时复用同一 run-id / attempt，不追加第二条。
+    """
+    import uuid
+
+    import harness_change as hchg
+    import harness_events as he
+    import harness_gate as hg
+    import harness_runtime as hr
+    import harness_state as hs
+
+    project = Path(project).resolve()
+    changes_root = project / ".harness" / "changes"
+    if not changes_root.is_dir():
+        return {
+            "ok": False,
+            "code": "PROJECT_ROOT_INVALID",
+            "error": f"{changes_root} 不存在——先在该项目运行 hunter-harness init",
+        }
+
+    # 新 change 的目录此前没有任何脚本负责创建，靠的是后续 Write 的副作用；
+    # 引导阶段显式建立骨架，prepare 才有 contract 可读
+    change_dir = changes_root / change
+    created_change = not change_dir.is_dir()
+    if created_change:
+        (change_dir / "meta").mkdir(parents=True, exist_ok=True)
+    hchg.migrate_change(project, change)
+
+    prepared = prepare_context(
+        project,
+        phase="plan",
+        executor=executor,
+        change=change,
+        display_title=display_title,
+        ttl_seconds=ttl_seconds,
+    )
+    if not prepared.get("ok"):
+        return prepared
+
+    change_name = str(prepared["changeName"])
+    # executionRoot 是代码执行根（无 worktree 时等于项目根），change_dir 才是状态目录。
+    # 计划产物一律落 change_dir，混用会把 gate-policy/events 写到项目根去。
+    change_dir = (changes_root / change_name).resolve()
+    execution_root = Path(prepared["executionRoot"])
+
+    # doctor 失败不阻断引导：它是环境体检，结论随摘要返回给调用方判断
+    try:
+        health = hr.doctor(project, change_dir, agent=executor)
+    except Exception as exc:  # noqa: BLE001 - 体检失败要报告而不是中断引导
+        health = {"ok": False, "code": "DOCTOR_FAILED", "error": str(exc)}
+
+    # 首次 capture 把当时的 HEAD 固定为不可变 changeBase（design §3.6）
+    snapshot, changed_segments = hs.capture_current_state(
+        project=project,
+        change_dir=change_dir,
+        change_name=change_name,
+        worktree_root=project,
+    )
+    git_state = snapshot.get("git") or {}
+
+    workflow = hg._load_workflow_policy(project=project)
+    classification = hg.classify_risk(change_dir, stage, workflow=workflow)
+    classification.setdefault("tierOverride", None)
+    classification["classifiedAt"] = _now().isoformat().replace("+00:00", "Z")
+    policy_path = change_dir / "meta" / "gate-policy.json"
+    hg._write_json(policy_path, hg.gate_policy_document(classification))
+
+    identity = _plan_run_identity(change_dir)
+    reused = identity is not None
+    if identity is None:
+        # v2 identity：必须小写字母开头，裸 UUID 有 10/16 概率数字开头被拒
+        run_id = f"plan_{uuid.uuid4()}"
+        attempt = 1
+        appended = he.append_event(
+            change_dir,
+            phase="plan",
+            type_="phase.start",
+            run_id=run_id,
+            attempt=attempt,
+            executor_tool=executor,
+            note=f"/harness-plan 引导：{change_name}",
+        )
+        if not appended.get("ok", True):
+            return appended
+    else:
+        run_id, attempt = identity
+
+    return {
+        "ok": True,
+        "code": "PLAN_BOOTSTRAPPED",
+        "changeName": change_name,
+        "displayTitle": prepared.get("displayTitle"),
+        "changeCreated": created_change,
+        "changeDir": str(change_dir),
+        "executionRoot": str(execution_root),
+        "runId": run_id,
+        "attempt": attempt,
+        "reused": reused,
+        "tier": classification.get("tier"),
+        "tierSource": classification.get("source"),
+        "defaultPhases": list(classification.get("defaultPhases") or []),
+        "conditionalPhases": list(classification.get("conditionalPhases") or []),
+        "requiredValidations": list(classification.get("requiredValidations") or []),
+        "gatePolicyPath": str(policy_path),
+        "plannedPhases": prepared.get("plannedPhases"),
+        "changeBase": git_state.get("base"),
+        "head": git_state.get("head"),
+        "changedSegments": sorted(changed_segments),
+        "legacyBootstrap": prepared.get("legacyBootstrap"),
+        "doctorOk": bool(health.get("ok", True)),
+        "doctor": health,
+    }
+
+
 def _invalidate_for_fixback(
     state_root: Path,
     *,
@@ -808,6 +962,90 @@ def _invalidate_for_fixback(
     return record
 
 
+def _committed_publication_journal(contract_root: Path) -> Path | None:
+    """已 committed 的 v2 发布 journal —— plan 确实完成的机器证据。"""
+    journal_dir = contract_root / "meta" / "publication-journals"
+    if not journal_dir.is_dir():
+        return None
+    for path in sorted(journal_dir.glob("*.json")):
+        try:
+            payload = _read_json(path)
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+        if isinstance(payload, dict) and payload.get("state") == "committed":
+            return path
+    return None
+
+
+def _published_plan_artifacts(project: Path, contract_root: Path, change: str) -> list[dict[str, Any]]:
+    """交接携带的 v2 发布产物（存在者入账，缺失者跳过）。"""
+    entries: list[dict[str, Any]] = []
+    for rel in (
+        f"plans/{change}-design.md",
+        f"plans/{change}-plan.md",
+        f"plans/{change}-implementation-detail.md",
+        f"plans/{change}-test-scenarios.md",
+        "meta/scenario-manifest.json",
+    ):
+        candidate = contract_root / rel
+        if candidate.is_file():
+            entries.append(
+                {
+                    "path": candidate.resolve().relative_to(project).as_posix(),
+                    "sha256": _sha256(candidate),
+                }
+            )
+    return entries
+
+
+def _bootstrap_v2_plan_transition(
+    project: Path,
+    change: str,
+    *,
+    contract_root: Path,
+    state_root: Path,
+    to_phase: str,
+    executor: str,
+) -> dict[str, Any] | None:
+    """v2 发布已 committed 却没有交接凭证时，补录 plan → to_phase 凭证。
+
+    v2 plan finalize 只写 plan-events.ndjson 与发布 journal，不碰 context 事务
+    存储，于是 run 阶段 prepare 必报 HANDOFF_REQUIRED、begin 必报
+    LEGACY_BOOTSTRAP_REQUIRED——两个错误都不给恢复路径，调用方只能读脚本源码
+    自己拼出 classify + configure-plan + close，参数全靠现编，可审计性更差。
+
+    committed 的发布 journal 是比人工 close 更强的完成证据：据此补录，并在凭证上
+    留 bootstrapSource/bootstrapEvidence，事后能与人工 close 区分。没有该证据时
+    返回 None，交接继续 fail-closed。
+    """
+    paths = _paths(state_root)
+    if _read_ndjson(paths["transitions"]):
+        return None
+    if to_phase not in _allowed_next_phases(contract_root, "plan"):
+        return None
+    journal = _committed_publication_journal(contract_root)
+    if journal is None:
+        return None
+    receipt: dict[str, Any] = {
+        "schemaVersion": 1,
+        "changeName": change,
+        "fromPhase": "plan",
+        "toPhase": to_phase,
+        "status": "OK",
+        "executor": executor,
+        "productCommit": _head(project),
+        "artifacts": _published_plan_artifacts(project, contract_root, change),
+        "attempt": 1,
+        "closedAt": _now().isoformat(),
+        "previousReceiptHash": None,
+        "bootstrapSource": "plan_publication_journal",
+        "bootstrapEvidence": journal.resolve().relative_to(project).as_posix(),
+    }
+    receipt["receiptHash"] = _payload_hash(receipt)
+    _append_ndjson(paths["transitions"], receipt)
+    return receipt
+
+
 def close_transition(
     project: Path,
     change: str,
@@ -1007,11 +1245,26 @@ def _begin_transition_unlocked(
                 "message": "本次修复准备凭证与当前上下文不一致，未启动新阶段。",
             }
     transitions = _read_ndjson(paths["transitions"])
+    if not transitions and phase != "plan":
+        # prepare 之外的入口（或跳过了 prepare）同样要能从发布证据恢复
+        _bootstrap_v2_plan_transition(
+            project,
+            change,
+            contract_root=contract_root,
+            state_root=state_root,
+            to_phase=phase,
+            executor=executor,
+        )
+        transitions = _read_ndjson(paths["transitions"])
     if not transitions:
         return {
             "ok": False,
             "code": "LEGACY_BOOTSTRAP_REQUIRED",
             "legacyBootstrap": True,
+            "message": (
+                "没有交接凭证。v2 计划应有 committed 的 meta/publication-journals/*.json "
+                "作为补录证据；legacy 计划需先完成 plan 阶段的 close"
+            ),
         }
     receipt = transitions[-1]
     if receipt.get("toPhase") != phase:
@@ -1256,6 +1509,14 @@ def build_parser() -> argparse.ArgumentParser:
     prepare.add_argument("--title")
     prepare.add_argument("--ttl-seconds", type=int, default=3600)
     prepare.add_argument("--trigger", choices=["review-fixback"])
+    bootstrap = sub.add_parser("bootstrap-plan")
+    bootstrap.add_argument("--json", action="store_true")
+    bootstrap.add_argument("--project", required=True, type=Path)
+    bootstrap.add_argument("--change", required=True)
+    bootstrap.add_argument("--executor", required=True)
+    bootstrap.add_argument("--title")
+    bootstrap.add_argument("--stage", default="plan", choices=["plan", "post-run"])
+    bootstrap.add_argument("--ttl-seconds", type=int, default=3600)
     close = sub.add_parser("close")
     close.add_argument("--json", action="store_true")
     close.add_argument("--project", required=True, type=Path)
@@ -1297,6 +1558,15 @@ def main(argv: list[str] | None = None) -> int:
             ttl_seconds=args.ttl_seconds,
             trigger=args.trigger,
         )
+    elif args.command == "bootstrap-plan":
+        result = bootstrap_plan(
+            args.project,
+            change=args.change,
+            executor=args.executor,
+            display_title=args.title,
+            stage=args.stage,
+            ttl_seconds=args.ttl_seconds,
+        )
     elif args.command == "close":
         result = close_transition(
             args.project,