@hunter-harness/workflow-harness 0.2.72 → 0.2.73

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -52,9 +52,9 @@ disallowed-tools:
 ## 统一读取协议
 
 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/claude-code/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,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "a4f07759d60ce2c9"
+  "coreHash": "d79ae315e929446c"
 }

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

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

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

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

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

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

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d79ae315e929446c; overlay=none; 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 澄清）：语义歧义或高风险业务裁决（一次一问）
 
 ## 执行日志