@hunter-harness/workflow-harness 0.2.72 → 0.2.74

package/harness/bundles/java/claude-code/scripts/harness_ledger.py

@@ -304,12 +304,23 @@ def _compact_record_payload(payload: dict[str, Any]) -> dict[str, Any]:
 
 
 def _compact_can_reuse_payload(payload: dict[str, Any]) -> dict[str, Any]:
-    """C5: can-reuse compact — ok/reuse/code only."""
-    return {
+    """C5: can-reuse compact — ok/reuse/code；拒绝复用时附带可执行的原因。
+
+    只回 ok/reuse/code 时，调用方拿到裸 `{"reuse": false}` 无从判断该怎么办，
+    只能再跑一次 `--verbose`——原因（profile 缺 verificationInputs、证据不完整等）
+    是单行短文本，值得留在默认输出里。允许复用时保持原样精简。
+    """
+    compact = {
         "ok": payload.get("ok", True),
         "reuse": payload.get("reuse"),
         "code": payload.get("code"),
     }
+    if payload.get("reuse") is not True:
+        for key in ("reason", "executionNeed", "detail"):
+            value = payload.get(key)
+            if value not in (None, "", [], {}):
+                compact[key] = value
+    return compact
 
 
 def emit_compact_or_verbose(
@@ -2581,9 +2592,19 @@ def cmd_record(args: argparse.Namespace) -> int:
                     error_code="PROFILE_INPUT_FILES_CONFLICT",
                 )
         files = profile_files
-    if not files:
+    # NOT_APPLICABLE 的 validation 没有输入文件可言。门禁 close 又要求
+    # requiredValidations 每项都有 entry——两条规则叠加会逼调用方拿无关文件凑数，
+    # ledger 从此声称该 validation 的输入是那些文件，是假证据。
+    not_applicable = str(getattr(args, "applicability", "") or "") == "NOT_APPLICABLE"
+    if not files and not not_applicable:
+        return emit_error(
+            "record requires --files or a non-empty --profile-input file set; "
+            "unless --applicability NOT_APPLICABLE (then --applicability-reason is required)",
+            as_json=as_json,
+        )
+    if not_applicable and not _nonempty_str(getattr(args, "applicability_reason", None)):
         return emit_error(
-            "record requires --files or a non-empty --profile-input file set",
+            "NOT_APPLICABLE requires --applicability-reason",
             as_json=as_json,
         )
 

package/harness/bundles/java/claude-code/scripts/harness_profile.py

@@ -1101,6 +1101,43 @@ def _derive_verification_graph(profile: dict[str, Any]) -> None:
     }
 
 
+def manual_profile_template(
+    excluded: tuple[str, ...] | list[str], components: list[str]
+) -> dict[str, Any]:
+    """歧义时交给调用方的可填骨架。
+
+    骨架本身就是 `empty_profile_skeleton`——defaultsFingerprint、excludedRoots
+    默认集、commands/verificationInputs/verificationGraph 的键都已就位；这里只是
+    补上 commands 的条目形状与 requiredCoverage 取值，省掉调用方去源码里翻。
+    占位值用 `<...>` 包裹，便于替换后 grep 自检。
+    """
+    template = empty_profile_skeleton(excluded)
+    template["projectType"] = (
+        f"<从 detectedComponents 选定：{'|'.join(components)}>" if components else "<项目类型>"
+    )
+    template["commands"] = {
+        "unitTest": {
+            "command": "<在项目根可直接执行的增量测试命令>",
+            "scope": "incremental",
+            "inputs": ["<相对项目根的 glob，如 <component>/test/**>"],
+            "coverage": "unitTest",
+            "requiredCoverage": "incremental",
+            "dependsOn": [],
+            "source": "user",
+        },
+        "unitTestFull": {
+            "command": "<在项目根可直接执行的全量测试命令>",
+            "scope": "full",
+            "inputs": ["<相对项目根的 glob，如 <component>/**>"],
+            "coverage": "unitTestFull",
+            "requiredCoverage": "module",
+            "dependsOn": [],
+            "source": "user",
+        },
+    }
+    return template
+
+
 def detect(project: Path) -> dict[str, Any]:
     project = project.resolve()
     existing = load_profile(project)
@@ -1120,6 +1157,14 @@ def detect(project: Path) -> dict[str, Any]:
             "applied": False,
             "detectedComponents": components,
             "message": "multiple or nested project components require an explicit profile",
+            # 拒绝生成可以，但不能连结构都不给：调用方否则只能反读本文件源码去凑
+            # v3 形状。骨架不落盘——一份占位 profile 看起来"已配好"比没有更糟。
+            "profileTemplate": manual_profile_template(excluded, components),
+            "hint": (
+                "手工声明一份 profile：以 profileTemplate 为骨架，按 detectedComponents "
+                "选定产品包，commands 里的 inputs 用相对项目根的 glob（如 "
+                f"'<component>/test/**'），填好后写入 {project / PROFILE_REL}"
+            ),
         }
     if project_type == "unknown" and existing:
         return {

package/harness/bundles/java/claude-code/scripts/harness_test_guard.py

@@ -332,12 +332,15 @@ def _matches_pattern(rel: str, pattern: str) -> bool:
 
 
 def _standard_test_path(rel: str) -> bool:
+    """路径中出现 test/tests 目录段即视为标准测试路径。
+
+    此前只认 parts[0]，于是 monorepo（packages/cli/tests/…）与"仓库根 + 同名
+    子包"（kld-sdd/test/…）这类常见布局全被拒，调用方被迫先补 build-profile
+    才能记录一次 stale-test-repair。段级匹配不放宽语义：testing/ 与
+    tests-helper/ 仍然不算，目录本身（末段）也不算文件。
+    """
     parts = rel.split("/")
-    if len(parts) >= 2 and parts[0] in ("test", "tests"):
-        return True
-    if any(parts[index:index + 2] == ["src", "test"] for index in range(len(parts) - 1)):
-        return True
-    return False
+    return any(part in ("test", "tests") for part in parts[:-1])
 
 
 def _allowed_test_path(project: Path, rel: str) -> bool:

package/harness/bundles/java/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "49a4943b301fe1fd"
+  "coreHash": "f432924cb623923d"
 }

package/harness/bundles/java/codebuddy/harness-apidoc/SKILL.md

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -18,9 +18,9 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 ## 统一读取协议
 
 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`

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -39,9 +39,9 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/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`

package/harness/bundles/java/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/java/codebuddy/harness-knowledge-query/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/java/codebuddy/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose
@@ -24,9 +24,9 @@ description: 增量模块打包：拉取最新→编译验证→mvn package→
 ## 统一读取协议
 
 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`

package/harness/bundles/java/codebuddy/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -21,9 +21,9 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 ## 统一读取协议
 
 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`
@@ -66,14 +66,15 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 | 阶段 | 动作 |
 |------|------|
-| 0 | 用当前解释器运行 `harness_runtime.py doctor`，后续消费绝对 argv；git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
-| 0.5 | 确定英文 `change-name` 后，根据需求生成一次简洁的中文展示标题（建议 6～24 个可见字符，保留必要产品名），执行 `harness_context.py prepare --phase plan --executor <tool> [--change <id>] --title "<中文标题>" --json`；英文名继续作为目录与稳定标识。立即运行一次 `harness_state.py capture --project . --change-dir "<executionRoot>" --json`，把此时 HEAD 固定为不可变 `changeBase`。以其唯一 change/executionRoot 初始化 plan-run-id 与 attempt（首次为 1）；run-id 必须小写字母开头（v2 identity 规则，裸 UUID 有 10/16 概率数字开头被拒）——统一用 `plan_<uuid>` 形状（contracts `createPlanRunId()`），用同一身份追加 `phase.start`；从第一条知识查询起保留事件证据，并在 finalizer 中复用该身份 |
-| 0.6 | 使用 `classify` 返回的默认阶段和项目能力生成 `plannedPhases`，向用户用中文说明可选阶段；确认后运行 `harness_context.py configure-plan --project . --change <id> --phases "plan,run,...,archive" --operator <tool> --reason "<中文原因>" --json`。无 Git 或不需要提交时不得加入 `submit`；快速迭代默认 `plan,run,archive`。省略项由脚本写入 `skippedPhases`，不得伪造阶段事件 |
+| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问。环境体检并入 0.5 的引导命令，不再单独跑 doctor |
+| 0.5 | 先定英文 `change-name`（kebab-case，`^[a-z0-9]+(-[a-z0-9]+)*$`）与一次性中文展示标题（建议 6～24 个可见字符，保留必要产品名），然后**一条命令完成引导**：<br>`python <skills-root>/scripts/harness_context.py bootstrap-plan --project . --change <cn> --executor <tool> --title "<中文标题>" --json`<br>它按序做完 doctor → 建 change 骨架 → prepare → state capture（首次把当时 HEAD 固定为不可变 `changeBase`）→ classify（落 `meta/gate-policy.json`）→ 生成合规 `plan_<uuid>` run-id 并追加 `phase.start`，返回紧凑摘要：`runId`/`attempt`/`tier`/`defaultPhases`/`conditionalPhases`/`requiredValidations`/`changeBase`/`head`/`executionRoot`。**重跑复用同一 run-id、不重复写 `phase.start`**（换 run-id 会让 finalize 按生命周期身份 fail-closed）。finalizer 必须复用该 `runId`/`attempt` |
+| 0.5b | 仅在引导失败需要单步排查时用等价分解——**每条的参数都是必填，少一个就是白跑一轮**：<br>`harness_runtime.py doctor --project . --change-dir ".harness/changes/<cn>" --agent <claude-code\|codebuddy\|codex\|cursor> --json`<br>`harness_context.py prepare --project . --change <cn> --phase plan --executor <tool> --title "<中文标题>" --json`<br>`harness_state.py capture --project . --change-dir ".harness/changes/<cn>" --json`<br>`harness_gate.py classify --change <cn> --stage plan --json`<br>`harness_events.py append --change-dir ".harness/changes/<cn>" --phase plan --type phase.start --run-id plan_<uuid> --attempt 1`<br>⚠️ `--change-dir` 一律是 `.harness/changes/<cn>`（状态目录），**不是** prepare 返回的 `executionRoot`（代码执行根，无 worktree 时等于项目根）——填错会把 gate-policy/events 写到项目根 |
+| 0.6 | 用引导返回的 `tier`/`defaultPhases`/`requiredValidations` 生成 `plannedPhases`，向用户用中文说明可选阶段；确认后运行 `harness_context.py configure-plan --project . --change <cn> --phases "plan,run,...,archive" --operator <tool> --reason "<中文原因>" --json`。无 Git 或不需要提交时不得加入 `submit`；快速迭代默认 `plan,run,archive`。省略项由脚本写入 `skippedPhases`，不得伪造阶段事件 |
 | 1 | 直接执行一次 `npx hunter-harness knowledge query "<用户需求原文>" --limit 10 --json`。这是唯一执行入口，不扫描技能目录、不查找其他脚本；失败记 `issue` 并继续，不建立本地索引或离线回退 |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
 | 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
-| 5–6 | plan + implementation-detail + test-scenarios → `plans/`；v2 路径时同步沉淀 `meta/plan-evidence-input.json`（自然输入，字段定稿时点见 `reference.md` 阶段 8 v2 表） |
+| 5–6 | **v2（默认）**：任务与场景只沉淀进 `meta/plan-evidence-input.json`（自然输入，字段定稿时点见 `reference.md` 阶段 8 v2 表）；`plans/*.md` 四份由 finalize 派生，**不得手写**——手写的会被派生渲染覆盖，只是白写。**legacy**：才手写 plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
 | 8 | **v2 路径（新 change 优先）**：`npx hunter-harness plan evidence-pack --input <meta/plan-evidence-input.json> --output <meta/plan-evidence.json>`，再 `npx hunter-harness plan finalize --input <meta/plan-evidence.json>`；exit 0 且 `code:"PLAN_FINALIZED"` 即发布完成（契约见 `reference.md` 阶段 8 v2 路径）。**legacy 路径**：自然输入不完整（如缺真实审批记录）时才在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；成功后把 finalizer 返回的绝对 `receiptPath` 原样传给 `harness_context.py close`，`--to-phase` 必须取 `plannedPhases` 中 plan 的真实后继，不得写死。写 append-only handoff receipt；不得手写占位路径；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
 
@@ -96,16 +97,19 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 规则 | 要点 |
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
+| 设计真相源 | **v2** = `plans/<cn>-design.md`（finalize 派生、哈希绑定、八 target 之一）；**legacy** = `spec/<cn>-design.md`。同一 change 只有一份设计权威，禁止两处并存导致漂移；下游读取顺序见 `shared/read-protocol.md` |
 | Change 标题 | 首次 Plan 同时确定英文 `change-name` 与中文展示标题；英文名保持目录和机器标识不变，中文标题由 `prepare --title` 持久化，后续阶段只复用、不重新生成 |
 | 阶段计划 | Plan 必须持久化 `plannedPhases`；固定从 plan 开始、以 archive 结束。Test、Review、Submit、Package、API 文档可按项目策略省略；高风险必需项只能转为“提前结束且不可发布”，不得伪装通过 |
 | 产品边界 | `ownership.productPaths` 必须覆盖计划会修改的源文件、测试文件和构建入口；只写目录前缀或精确文件，禁止 `**` 通配。finalize 前对照任务表补齐，避免归档阶段才发现边界缺口 |
 | 空目录 | 不得为“预留目录”生成 `.gitkeep`；只有产品明确需要跟踪空目录时才能创建，并在计划中说明业务原因 |
-| 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`） |
+| 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`）。必须同时展示 **in_scope 与 out_of_scope 两个列表**——只展示"做什么"会让范围误判活到发布之后，代价是整份计划 republish |
+| 引用即追问 | 需求引用了外部设计文档章节（贴段落、指 `### Bn`、说"之前设计的时候如…"）时，阶段 2 必须确认该章节是否纳入本次范围，落到 in_scope 或 out_of_scope；引用 ≠ 纳入，也 ≠ 排除 |
 | 阶段 8 | 二选一且不得混用：**v2** = `hunter-harness plan finalize`（证据包 → 八 target + journal committed + plan-events.ndjson）；**legacy** = 六项标准产物先进入 staging，仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，随后 `verify` 确认 start/end、收据完整覆盖六项标准产物、哈希、全部任务表和非空场景清单一致。失败均不得手工补终态 |
 | 发布后改产物 | 用 `harness_plan_finalize.py republish --run-id <全新> --reason "<why>"` 一次完成（新 attempt + 换收据 + 重新派生 manifest）。重跑 `finalize` 会报 `PLAN_FINALIZATION_HASH_CONFLICT`；**绝不手改 `meta/scenario-manifest.json`**（派生物，手改必致 `ARTIFACT_HASH_DRIFT`）→ `reference.md`「发布后修订计划」 |
-| v2 输入骨架 | 不要猜 `plan-evidence-input.json` 结构，也不要去翻 TS 接口/npx 缓存：`npx hunter-harness plan evidence-pack --print-template` 直接给带占位符的完整骨架 |
+| v2 输入骨架 | 不要猜 `plan-evidence-input.json` 结构：`npx hunter-harness plan evidence-pack --print-template` 给出**一个字不改就能通过 evidence-pack** 的骨架（结构合法；`change_key`/`run_id` 仍须换成真实身份才能 finalize），逐项替换即可。结构不符时命令返回 `PLAN_EVIDENCE_INPUT_INVALID`，带 `field_path` 与 `problems[]`（缺失/多余键、枚举取值）——按 problems 改完重跑；**不得**为找契约去反编译 `dist/bin.js` 或翻 npx 缓存。带不了 `<>` 的占位字段与硬约束清单 → `reference.md` 阶段 8 v2 路径 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 阶段 1 失败不得假装已读历史，也不得改用本地索引或其他执行入口 |
+| 读命令输出 | `--json` 输出是完整结构，**不得**接 `\| tail -N` / `\| head -N` 后据此判断——截断的 JSON 解析不了，只会逼出一次补读。输出太长时读命令写下的文件（classify → `meta/gate-policy.json`），或用 `bootstrap-plan` 的紧凑摘要 |
 | 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |
 | 简单修复探索预算 | 预计不超过 2 个代码文件、且不涉及认证/安全/迁移/并发/API 契约重设时，最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个用户澄清问题；无关发现只记非阻断说明 |
 | 精简产物 | 简单修复只保留实现所需的设计、任务、边界和测试；禁止在 spec/plan/detail/scenarios 中重复同一背景和结论 |
@@ -123,7 +127,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 
 ## 交互白名单
 
-1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
+1. **设计审批包**（阶段 4）：设计 + **范围（做什么/不做什么）** + 场景表 + worktree + change-name
 2. **decision-grilling**（阶段 2/3 澄清）：语义歧义或高风险业务裁决（一次一问）
 
 ## 执行日志

package/harness/bundles/java/codebuddy/harness-plan/checklist.md

@@ -12,9 +12,12 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 **判定**：stdout 为空 → ✅ 继续；stdout 非空 → baseline 隔离 + `decision`（note 含变更文件列表）；Bash 被拒 → PowerShell 重试。
 
-## 阶段 0.5：事件初始化与知识查询
+## 阶段 0.5：一次性引导与知识查询
 
-- [ ] 先确定 change-name、稳定的 plan-run-id 与 attempt（首次为 1），立即用 `harness_events.py append ... --phase plan --type phase.start --run-id <plan-run-id> --attempt <attempt>` 追加开始事件
+- [ ] 定好 change-name（kebab-case）与中文展示标题后，运行一次 `harness_context.py bootstrap-plan --project . --change <cn> --executor <tool> --title "<中文标题>" --json`
+- [ ] 引导返回 `code:"PLAN_BOOTSTRAPPED"`，记下 `runId`/`attempt`/`tier`/`defaultPhases`/`changeBase`；后续 finalize 必须复用同一 `runId`/`attempt`
+- [ ] 不再手工生成 run-id、不再单独跑 doctor/prepare/capture/classify/append；需要单步排查时才用 SKILL.md 阶段 0.5b 的等价分解
+- [ ] 引导失败时按返回的 `code` 处理（`PROJECT_ROOT_INVALID` → 该项目未 init），**不得**跳过引导直接写产物
 - [ ] 项目已绑定平台时执行一次远端 knowledge `query`；不另跑前置 sync，不创建本地索引
 - [ ] 查询失败追加 `issue`，不得回退本地 archive/SQLite、重跑“sync + query”循环或假装已读取历史
 
@@ -22,6 +25,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 - [ ] 否定、对比、动作对象、范围或保留/删除关系不存在未确认的多义解释
 - [ ] 若存在歧义，仅完成最小取证后一次一问，并给出推荐理解
+- [ ] **需求里引用了外部设计文档/章节（贴了段落、给了 `xxx.md` 的 `### Bn` 小节、说"之前设计的时候如…"）时，必须确认该章节本次是否纳入**——引用不等于纳入，也不等于排除。把它列进 `in_scope` 或 `out_of_scope` 后再进入阶段 4；漏判会导致计划发布后整体作废重来（republish），是本流程最贵的返工
 - [ ] 简单修复探索预算：最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个澄清问题
 - [ ] 无关发现只记非阻断 `issue`，未扩展当前方案或问题列表
 
@@ -65,16 +69,21 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 **展示内容**：
 
 1. 设计摘要 + 关键证据 + 风险 + 变更清单
-2. 测试场景表摘要 + 8 维度覆盖检查
-3. worktree 选项（是/否，含推荐理由）
-4. change-name（自动生成，可修改）
-5. 确认进入任务拆分
+2. **本次做什么（in_scope）/ 本次不做什么（out_of_scope）** — 两个列表都必须显式列出，不得只展示"做什么"。用户看到"不做"清单才有机会当场纠正范围误判；`out_of_scope` 为空时写"无"，不得省略该行。这两个列表随后原样进入 `plan-evidence-input.json` 的 `intent` 与 `approval.content`（两处必须集合相等）
+3. 测试场景表摘要 + 8 维度覆盖检查
+4. worktree 选项（是/否，含推荐理由）
+5. change-name（自动生成，可修改）
+6. 确认进入任务拆分
 
-确认后写入 `spec/<change>-design.md`（含 frontmatter）和 `meta/worktree.json`。
+确认后立即追加 decision 事件，并写入 `meta/worktree.json`。设计文档按路径分流：
+
+- **v2**：审批内容写进 `meta/plan-evidence-input.json` 的 `approval.content`（含 `approver_id`），
+  `plans/<change>-design.md` 由 finalize 从审批内容派生——**不要**手写它，手写的会被覆盖
+- **legacy**：写 `spec/<change>-design.md`（含下方 frontmatter）
 
 - [ ] 确认事件早于 approved 设计文档；未获确认时不得先落盘 `status: approved`
 
-设计文档必须包含 frontmatter：
+legacy 设计文档必须包含 frontmatter：
 ```yaml
 ---
 change-name: <change-name>
@@ -209,6 +218,37 @@ source: harness-plan
 
 > **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
 
+> **先认路径再对表**：v2 与 legacy 的完整性口径不同，混用会得出错误结论。
+
+### v2 路径（新 change 默认）
+
+- [ ] 只手写 `meta/plan-evidence-input.json`；`plans/*.md` 由 finalize 派生，**不得**手写后再被覆盖
+- [ ] `evidence-pack` 返回 `code:"PLAN_EVIDENCE_PACK_BUILT"`；结构报错按 `field_path`/`problems[]` 修正后重跑
+- [ ] `finalize` exit 0 且 `code:"PLAN_FINALIZED"`
+- [ ] 八 target 齐全：`plans/` ×4（design / implementation-detail / plan / test-scenarios）+ `meta/` ×4（gate-policy / implementation-checkpoints / scenario-manifest / worktree）
+- [ ] `meta/publication-journals/<op>.json` 的 `state === "committed"`
+- [ ] `meta/plan-events.ndjson` 含 `artifact_published` 与 `phase_ended` 两类终态事件
+- [ ] 以上任一缺失都不得手工补写；回到对应阶段改自然输入后重跑
+
+| 文件（v2） | 必须存在 | 检查结果 |
+|------|:---:|:---:|
+| `.harness/changes/<change>/meta/plan-evidence-input.json` | ✅ | □ |
+| `.harness/changes/<change>/plans/<change>-design.md` | ✅ | □ |
+| `.harness/changes/<change>/plans/<change>-plan.md` | ✅ | □ |
+| `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅ | □ |
+| `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅ | □ |
+| `.harness/changes/<change>/meta/gate-policy.json` | ✅ | □ |
+| `.harness/changes/<change>/meta/worktree.json` | ✅ | □ |
+| `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ | □ |
+| `.harness/changes/<change>/meta/scenario-manifest.json`（非空且计数一致） | ✅ | □ |
+| `.harness/changes/<change>/meta/publication-journals/<op>.json`（committed） | ✅ | □ |
+| `.harness/changes/<change>/meta/plan-events.ndjson` | ✅ | □ |
+| `.harness/changes/<change>/events.ndjson` | ✅ | □ |
+
+> v2 过渡期**不写** `meta/plan-finalization.json` 与 `logs/execution-log.md`；缺这两项不算失败，不得为凑表手工补。
+
+### legacy 路径（自然输入不完整时的回退）
+
 - [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
 - [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id <plan-run-id> --attempt <attempt> --json`；身份必须与本次 `phase.start` 完全相同
 - [ ] finalizer 返回 `ok=true`、`artifactsHash`、绝对 `receiptPath` 与稳定 `artifactRef=meta/plan-finalization.json`；重复执行返回 `idempotent=true`
@@ -220,7 +260,7 @@ source: harness-plan
 - [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
 - [ ] context close 的 `--artifact` 只传 finalizer 原样返回的 `receiptPath` 或 `artifactRef`，不得猜测、拼接或使用 `<plan-finalization>` 占位文本
 
-| 文件 | 必须存在 | 检查结果 |
+| 文件（legacy） | 必须存在 | 检查结果 |
 |------|:---:|:---:|
 | `.harness/changes/<change>/spec/<change>-design.md` | ✅ | □ |
 | `.harness/changes/<change>/plans/<change>-plan.md` | ✅ | □ |

package/harness/bundles/java/codebuddy/harness-plan/reference.md

@@ -104,11 +104,16 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 
 > **本阶段是强制检查点。** 先展示设计审批包，收到确认并追加 decision 事件后，才能落盘 `status: approved` 的设计文档并进入阶段 6（任务拆分）。设计方向正确后再细化任务，避免基于错误理解拆分无效任务。
 
-**用户确认后必须立即写入** `.harness/changes/<change-name>/spec/<change-name>-design.md`。如果此文件不存在，harness-plan 不得进入阶段 6。
+**用户确认后必须立即追加 decision 事件**，然后按路径分流落盘：
 
-**设计文档路径规则**：设计文档必须保存到 `.harness/changes/<change-name>/spec/<change-name>-design.md`。禁止保存到 `docs/superpowers/specs/` 作为正式产物；`/harness-plan` 不运行时调用 Superpowers。
+| 路径 | 审批内容去哪 | 设计文档 |
+|------|------------|---------|
+| **v2**（默认） | `meta/plan-evidence-input.json` 的 `approval.content` + `approver_id` | `plans/<change-name>-design.md`，由 finalize 从审批内容派生——**不要手写**，手写的会被派生渲染覆盖 |
+| **legacy** | 直接写文档 | `.harness/changes/<change-name>/spec/<change-name>-design.md`（不存在则不得进入阶段 6） |
 
-### 设计文档模板
+**设计文档路径规则**：禁止保存到 `docs/superpowers/specs/` 作为正式产物；`/harness-plan` 不运行时调用 Superpowers。同一 change 不得同时存在 `plans/` 与 `spec/` 两份设计——v2 发布的那份才受完整性门禁保护。
+
+### 设计文档模板（legacy 路径手写时使用；v2 由 finalize 派生，此模板仅作内容清单参考）
 
 ```markdown
 ---
@@ -181,15 +186,19 @@ source: harness-plan
 
 ### 产物结构
 
-推荐结构：
-
 ```
 .harness/changes/<change-name>/plans/
+├── <change-name>-design.md                  # 设计（v2 由 finalize 派生）
 ├── <change-name>-plan.md                    # harness 简洁任务表，run 默认读取
 ├── <change-name>-implementation-detail.md   # 原生自适应详细执行参考，run 补充读取
 └── <change-name>-test-scenarios.md          # 测试场景表
 ```
 
+> **v2 路径下这四份都是派生产物**：唯一手写的是 `meta/plan-evidence-input.json`。
+> 阶段 6 的任务拆分结果直接填进它的 `structured_input.tasks`，阶段 7 的场景填 `structured_input.scenarios`——
+> 同一份内容不要先写成 Markdown 再誊进 JSON，finalize 会用派生渲染覆盖手写的 Markdown。
+> 下面的 Markdown 格式说明用于**理解字段语义**与 legacy 路径手写。
+
 ### 计划文件 frontmatter（必须）
 
 ```yaml
@@ -284,10 +293,12 @@ status: approved
    .harness/changes/<change-name>/backups/
    ```
 
-3. **保存设计文档**：将阶段 4 已确认的设计文档保存到：
-   - `.harness/changes/<change-name>/spec/<change-name>-design.md`
+3. **保存设计文档**：
+   - **v2**：不手写文档；把审批内容填进 `meta/plan-evidence-input.json` 的 `approval.content`，
+     `plans/<change-name>-design.md` 由 finalize 派生（frontmatter 也由渲染器写）
+   - **legacy**：保存到 `.harness/changes/<change-name>/spec/<change-name>-design.md`
 
-   设计文档 frontmatter 格式：
+   legacy 设计文档 frontmatter 格式：
    ```yaml
    ---
    change-name: <change-name>
@@ -299,14 +310,17 @@ status: approved
 
    > 如果 frontmatter 缺失，后续 run/test/review/submit/archive 不得依赖模型猜测 change-name。
 
-4. **初始化结构化事件**：确定 change-name 后，立即生成稳定的 `<plan-run-id>`（必须小写字母开头：v2 identity 规则，裸 UUID 有 10/16 概率数字开头被拒——统一用 `plan_<uuid>` 形状，contracts `createPlanRunId()`；同一次 plan 尝试内不得改变；首次 `<attempt>` 为 `1`），运行 `harness_events.py append --change-dir ... --phase plan --type phase.start --run-id <plan-run-id> --attempt <attempt>`。finalizer 必须复用完全相同的 `--run-id` / `--attempt`，否则 verify 会按生命周期身份 fail-closed。脚本负责建立父目录和 `events.ndjson`；执行日志在 `phase.end` 时由完整事件流渲染，任何阶段都不得直接用 Write/Edit 维护该投影。
+4. **初始化结构化事件**：由阶段 0.5 的 `harness_context.py bootstrap-plan` 一次完成——它生成合规的 `<plan-run-id>`（`plan_<uuid>` 形状，必须小写字母开头：v2 identity 规则，裸 UUID 有 10/16 概率数字开头被拒）、`<attempt>`（首次为 `1`）并追加 `phase.start`，重跑复用同一身份不重复写事件。finalizer 必须复用引导返回的 `runId`/`attempt`，否则 verify 会按生命周期身份 fail-closed。同一次 plan 尝试内不得改变身份。执行日志在 `phase.end` 时由完整事件流渲染，任何阶段都不得直接用 Write/Edit 维护该投影。
 
-5. **保存计划文件**：计划文件包含 YAML frontmatter（含 change-name），保存到：
-   - `.harness/changes/<change-name>/plans/<change-name>-plan.md`（简洁任务表）
-   - `.harness/changes/<change-name>/plans/<change-name>-implementation-detail.md`（自适应详细执行参考）
-   - `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md`（测试场景表）
+5. **保存计划文件**：
+   - **v2**：不手写；任务填 `structured_input.tasks`、场景填 `structured_input.scenarios`，
+     `plans/` 下四份 Markdown 全部由 finalize 派生
+   - **legacy**：手写并保存到（含 YAML frontmatter，含 change-name）
+     - `.harness/changes/<change-name>/plans/<change-name>-plan.md`（简洁任务表）
+     - `.harness/changes/<change-name>/plans/<change-name>-implementation-detail.md`（自适应详细执行参考）
+     - `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md`（测试场景表）
 
-   计划文件 frontmatter 格式：
+   legacy 计划文件 frontmatter 格式：
    ```yaml
    ---
    change-name: <change-name>
@@ -327,23 +341,27 @@ status: approved
 
 ## 阶段 8：结束前产物完整性检查 ⚠️ 强制
 
-> **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
-
-| 文件 | 必须存在 |
-|------|:---:|
-| `.harness/changes/<change>/spec/<change>-design.md` | ✅ |
-| `.harness/changes/<change>/plans/<change>-plan.md` | ✅ |
-| `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅ |
-| `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅ |
-| `.harness/changes/<change>/meta/gate-policy.json` | ✅ |
-| `.harness/changes/<change>/meta/worktree.json` | ✅ |
-| `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ |
-| `.harness/changes/<change>/meta/scenario-manifest.json` | ✅ |
-| `.harness/changes/<change>/meta/plan-finalization.json` | ✅ |
-| `.harness/changes/<change>/logs/execution-log.md` | ✅ |
-| `.harness/changes/<change>/events.ndjson` | ✅ |
-
-`plan-finalization.json.files` 必须完整列出 design、plan、implementation-detail、test-scenarios、gate-policy、worktree 六项标准输入。`verify` 对缺项、重复项、越界路径以及 symlink/junction/reparse point 一律 fail-closed；不得通过删减收据文件集后重算哈希来绕过完整性检查。
+> **缺任一文件 → ❌FAIL，不得宣称 plan 完成。先认清走的是 v2 还是 legacy——两条路径的必需文件集不同，拿 legacy 的表去查 v2 会得出假失败。**
+
+| 文件 | v2 | legacy |
+|------|:---:|:---:|
+| `.harness/changes/<change>/meta/plan-evidence-input.json` | ✅ | — |
+| `.harness/changes/<change>/plans/<change>-design.md` | ✅（派生） | — |
+| `.harness/changes/<change>/spec/<change>-design.md` | — | ✅ |
+| `.harness/changes/<change>/plans/<change>-plan.md` | ✅（派生） | ✅ |
+| `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅（派生） | ✅ |
+| `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅（派生） | ✅ |
+| `.harness/changes/<change>/meta/gate-policy.json` | ✅ | ✅ |
+| `.harness/changes/<change>/meta/worktree.json` | ✅ | ✅ |
+| `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ | ✅ |
+| `.harness/changes/<change>/meta/scenario-manifest.json` | ✅ | ✅ |
+| `.harness/changes/<change>/meta/publication-journals/<op>.json`（committed） | ✅ | — |
+| `.harness/changes/<change>/meta/plan-events.ndjson` | ✅ | — |
+| `.harness/changes/<change>/meta/plan-finalization.json` | — | ✅ |
+| `.harness/changes/<change>/logs/execution-log.md` | — | ✅ |
+| `.harness/changes/<change>/events.ndjson` | ✅ | ✅ |
+
+legacy 的 `plan-finalization.json.files` 必须完整列出 design、plan、implementation-detail、test-scenarios、gate-policy、worktree 六项标准输入。`verify` 对缺项、重复项、越界路径以及 symlink/junction/reparse point 一律 fail-closed；不得通过删减收据文件集后重算哈希来绕过完整性检查。
 
 ### 阶段 8 v2 路径（结构化证据包流程，新 change 优先）
 
@@ -363,8 +381,32 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 > ```bash
 > npx hunter-harness plan evidence-pack --print-template > .harness/changes/<cn>/meta/plan-evidence-input.json
 > ```
-> 输出是带 `<...>` 占位符的完整骨架，逐项替换即可；替换完 grep 一次 `<` 自检有无遗漏。
-> `--print-template` 不读写任何文件，只打到 stdout。
+> **骨架一个字不改就能通过 `evidence-pack`**（回归测试冻结这条不变量），所以可以先跑一次确认链路通，再逐项替换。
+> 注意这只保证结构合法：`finalize` 还要求 `change_key` 与 `run_id` 是本次真实身份，占位值过不了发布。
+> 自由文本字段用 `<...>` 占位，替换完 grep 一次 `<` 自检有无遗漏。`--print-template` 不读写任何文件，只打到 stdout。
+
+**带不了 `<>` 的占位字段**（受枚举/哈希/命名约束，grep `<` 查不出来，必须逐个确认）：
+
+| 字段 | 模板占位值 | 换成什么 |
+|------|-----------|---------|
+| `change_key` | `replace-with-change-name` | 真实 change-name（kebab-case：`^[a-z0-9]+(-[a-z0-9]+)*$`） |
+| `context.run_id` | `plan_replace-with-your-plan-run-id` | 阶段 0.5 生成、`phase.start` 已用的**同一个** plan-run-id |
+| `evidence_sources[].content_hash` | `sha256:deadbeef…` | 证据源内容的真实 sha256（校验器显式拒绝全 0） |
+| `risk_signals` | `["production_code"]` | classify 实际返回的信号 |
+
+**容易踩的硬约束**（违反时命令会给 `field_path`，不必再猜）：
+
+- `structured_input.scenarios` **至少 3 条**——八维度缺项由命令补 `not_applicable`，但场景总数不能少于 3
+- `intent.acceptance_examples` 2~5 条，`approval.content.acceptance_examples` 3~7 条 → 取 3 条同时满足
+- `key_alternatives` / `invariants` / `failure_behaviors` / `compatibility_boundaries` 各至少 1 条
+- `intent.in_scope`/`out_of_scope` 与 `approval.content` 同名字段必须**集合相等**
+- tasks 只写 `task_id/objective/affected_paths/owner_phase`，六个 refs 数组由命令接线；多写 `cluster`/`title` 这类键会因精确键集被拒
+- scenarios 只写 `scenario_id/title/acceptance/coverage_dimension/execution_level/evidence_requirements/risk_level`（+可选 `verification_command`）；`priority`/`test_file` 这类计划表列不属于本输入
+- `machine.worktree_policy` ∈ `project_default | required | forbidden`（没有 `none`）
+
+> **结构错了怎么读报错**：命令在边界返回 `code:"PLAN_EVIDENCE_INPUT_INVALID"`（`stage:"boundary"`），
+> `field_path` 指向第一处问题，`problems[]` 逐条给 `missing_keys`/`unexpected_keys`/`message`。
+> 按 `problems` 改完重跑即可——**不需要**去反编译 `dist/bin.js` 或翻 npx 缓存找校验器。
 
 | 字段 | 内容 | 定稿阶段 |
 |------|------|:---:|
@@ -380,6 +422,14 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 | `context` | project_id/run_id/branch_name/attempt（复用 plan-run-id 与 attempt） | 0.5 |
 | `expected_baseline` | 首次发布 `{state:"absent", manifest_hash:null, generation:0}` | 8 |
 
+> ⚠️ **已知缺口：v2 派生的 `meta/scenario-manifest.json` 目前喂不了 run/test 门禁。**
+> 它是 artifact 包装体，每条场景只有 `scenario_id/coverage_dimension/execution_level/
+> evidence_requirements/risk_level/task_refs/requirement_refs`；而门禁按
+> `id/priority/requiredEvidenceKind/ownerPhase/executableTestId/testFile/testTitle`
+> 判定哪些场景需要 ledger 证据。缺 `priority` 与 `requiredEvidenceKind` 时"必需场景"会算成空集，
+> 所以门禁**明确报 `SCENARIO_MANIFEST_V2_UNSUPPORTED` 并列出 `missingFields`，绝不静默放行**。
+> 需要 ledger 证据闭环的变更，在 v2 场景契约补齐这些字段前请走 legacy 路径。
+
 - **证据包**（`plan-evidence.json`）是命令推导的产物（trusted/publication/context/baseline），不得手改；任何字段变化必须改自然输入后重跑 evidence-pack。
 - **成功语义**：finalize exit 0 且 `code:"PLAN_FINALIZED"`。落盘事实 = 八 target（plans/*.md ×4 + meta/*.json ×4）+ `meta/publication-journals/<op>.json`（状态 committed）+ `meta/plan-events.ndjson`（artifact_published/phase_ended）。确定性门失败 exit 1 且 `code:"PLAN_FINALIZE_DETERMINISTIC_FAILED"` 附 findings——此时必须回到对应阶段修正规划内容，**不得**手改证据包或 staged 内容绕过。
 - **验证**：journal `state==="committed"` + 八 target 存在 + plan-events.ndjson 含两类终态事件；不得手工补写任何一项。

package/harness/bundles/java/codebuddy/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=49a4943b301fe1fd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=f432924cb623923d; overlay=java; agent=codebuddy; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose