@hunter-harness/workflow-harness 0.2.72 → 0.2.74

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "0ab8c8fcd63fec9b"
+  "coreHash": "2c27498e1b85cfca"
 }

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

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

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

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

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