@hunter-harness/workflow-harness 0.2.72 → 0.2.74

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

@@ -2024,6 +2024,70 @@ def _deferred_hint(deferred_ids: list[str], phase: str | None) -> str:
     )
 
 
+_PROJECT_ROOT_HELP = (
+    "project root PATH (defaults to resolving from CWD). Takes a path, not a project name."
+)
+
+
+def _resolve_project(args: argparse.Namespace) -> Path:
+    """--project 优先，未给时按 CWD 解析主项目根。
+
+    其他 harness 脚本都把 --project 当项目根且列为必填，只有 gate 例外——调用方
+    按惯例传过来会被 argparse 拒掉。注意 begin/close 的 --project 是另一层语义
+    （本阶段执行根/worktree），本函数只服务 classify/checkpoint。
+    """
+    raw = getattr(args, "project", None)
+    if raw:
+        return Path(raw).expanduser().resolve()
+    return hc.resolve_main_project_root()
+
+
+# 门禁消费的场景字段。v2 plan finalize 派生的 scenario_manifest 一个都没有：
+# 它只带 scenario_id/coverage_dimension/execution_level/evidence_requirements/
+# risk_level/task_refs/requirement_refs。
+_V2_MANIFEST_REQUIRED_FIELDS = (
+    "id",
+    "priority",
+    "requiredEvidenceKind",
+    "ownerPhase",
+    "executableTestId",
+    "testFile",
+    "testTitle",
+)
+
+
+def _v2_artifact_manifest_gap(manifest: Any) -> dict[str, Any] | None:
+    """v2 plan artifact 包装的 scenario-manifest → 明确的不可消费错误。
+
+    不能"解包 + 字段改名"了事：包装体里既没有 priority 也没有
+    requiredEvidenceKind，`required_ids` 会算成空集，C9 随即返回
+    NO_LEDGER_REQUIRED_SCENARIOS——那是把证据门禁对所有 v2 计划静默关掉，
+    比直接失败危险得多。所以这里点名缺口，让调用方回规划阶段补齐后重新发布。
+
+    v2 场景契约补齐这些字段后，解包逻辑加在这里。
+    """
+    if not isinstance(manifest, dict) or manifest.get("artifact_type") != "scenario_manifest":
+        return None
+    content = manifest.get("content")
+    present: set[str] = set()
+    if isinstance(content, dict) and isinstance(content.get("scenarios"), list):
+        for scenario in content["scenarios"]:
+            if isinstance(scenario, dict):
+                present.update(scenario.keys())
+    return {
+        "ok": False,
+        "code": "SCENARIO_MANIFEST_V2_UNSUPPORTED",
+        "message": (
+            "meta/scenario-manifest.json 是 v2 plan artifact 包装体，缺少门禁消费的场景字段；"
+            "请在规划阶段补齐后重新发布，不要手改派生产物"
+        ),
+        "missingFields": [
+            field for field in _V2_MANIFEST_REQUIRED_FIELDS if field not in present
+        ],
+        "artifactType": "scenario_manifest",
+    }
+
+
 def _validate_scenario_coverage(
     change_dir: Path, phase: str | None = None
 ) -> dict[str, Any]:
@@ -2050,6 +2114,9 @@ def _validate_scenario_coverage(
             "code": "SCENARIO_MANIFEST_INVALID",
             "message": f"scenario-manifest.json unreadable: {exc}",
         }
+    v2_gap = _v2_artifact_manifest_gap(manifest)
+    if v2_gap is not None:
+        return v2_gap
     scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
     if not isinstance(scenarios, list):
         return {
@@ -3218,7 +3285,7 @@ def cmd_close(args: argparse.Namespace) -> int:
 
 def cmd_classify(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
-    project = hc.resolve_main_project_root()
+    project = _resolve_project(args)
     try:
         workflow = _load_workflow_policy(project=project)
     except (OSError, ValueError, hwp.PolicyValidationError) as exc:
@@ -3271,7 +3338,7 @@ def cmd_classify(args: argparse.Namespace) -> int:
 
 def cmd_checkpoint(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
-    project = hc.resolve_main_project_root()
+    project = _resolve_project(args)
     resolved = hc.resolve_change(project, args.change)
     if not resolved.get("ok"):
         return emit_error(
@@ -3425,6 +3492,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_close.set_defaults(func=cmd_close)
 
     p_classify = sub.add_parser("classify", parents=[shared])
+    p_classify.add_argument("--project", default=None, type=Path, help=_PROJECT_ROOT_HELP)
     p_classify.add_argument("--change", default=None)
     p_classify.add_argument("--stage", required=True, choices=["plan", "post-run"])
     p_classify.add_argument(
@@ -3436,6 +3504,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_classify.set_defaults(func=cmd_classify)
 
     p_checkpoint = sub.add_parser("checkpoint", parents=[shared])
+    p_checkpoint.add_argument("--project", default=None, type=Path, help=_PROJECT_ROOT_HELP)
     p_checkpoint.add_argument("checkpoint_action", choices=["status", "approve"])
     p_checkpoint.add_argument("--id", required=True)
     p_checkpoint.add_argument("--change", default=None)

package/harness/bundles/general/codebuddy/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/general/codebuddy/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/general/codebuddy/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/general/codex/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "4239bfb29d5056eb"
+  "coreHash": "ecbe1a870731d9da"
 }

package/harness/bundles/general/codex/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=4239bfb29d5056eb; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ecbe1a870731d9da; overlay=none; agent=codex; 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/general/codex/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=4239bfb29d5056eb; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ecbe1a870731d9da; overlay=none; agent=codex; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/codex/harness-knowledge-ingest/SKILL.md

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

package/harness/bundles/general/codex/harness-knowledge-query/SKILL.md

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

package/harness/bundles/general/codex/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=4239bfb29d5056eb; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ecbe1a870731d9da; overlay=none; agent=codex; 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`
@@ -65,14 +65,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` |
 
@@ -95,16 +96,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 中重复同一背景和结论 |
@@ -122,7 +126,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 
 ## 交互白名单
 
-1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
+1. **设计审批包**（阶段 4）：设计 + **范围（做什么/不做什么）** + 场景表 + worktree + change-name
 2. **decision-grilling**（阶段 2/3 澄清）：语义歧义或高风险业务裁决（一次一问）
 
 ## 执行日志

package/harness/bundles/general/codex/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` | ✅ | □ |