@hunter-harness/workflow-harness 0.2.72 → 0.2.74

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

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

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

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=a4f07759d60ce2c9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d0ad43fe132b6817; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

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=d0ad43fe132b6817; 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`
@@ -105,7 +105,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+先 `harness_context.py prepare --project . --change <id> --phase test --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 `harness_context.py begin --project . --change <id> --phase test --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
 
 验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close`。`--to-phase` 取实际阶段计划的后继；Fixback 返回 run，普通流程可直接进入 Review、Submit 或 Archive。Fixback 只失效与改动文件相交的验证目标。
 

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

@@ -273,6 +273,8 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-run 单元测试结果"
 - [ ] 不复用 → 按 profile key resolve 重跑测试命令（`harness_profile.py resolve --key unitTest`，不复制示例 `-pl` 命令），结果写回 ledger 的 `unitTest` 项
 - [ ] HTTP/API 契约结果写入 `apiTest`；真实浏览器/真实栈 Playwright 结果写入 `browserTest`，两者不得互相覆盖
+- [ ] **本变更没有该维度场景时**（如全部为单元场景 → 无 API 场景）：用 `harness_ledger.py record --verification apiTest --status NOT_RUN --applicability NOT_APPLICABLE --applicability-reason "<为什么不适用>"` 登记，**不传 `--files`**。门禁 close 要求 requiredValidations 每项都有 entry，但**绝不能拿无关文件（比如单元测试文件）凑 `--files`**——那会让 ledger 声称该维度的输入是那些文件，是假证据
+- [ ] `can-reuse` 返回 `reuse:false` 时直接读默认输出里的 `reason`/`executionNeed`/`detail` 定位原因，不必再补跑 `--verbose`
 - [ ] 复用判断前以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 重算指纹；test-tracking manifest 无效或 hash 漂移即停止
 - [ ] 测试失败若明确为陈旧测试，仅在当前代码/批准计划/可验证历史唯一确定新契约且只改测试时自动修复；否则记录 `BLOCKED_PREEXISTING`
 - [ ] 自动修复后立即重跑该测试与目标测试，并以 `harness_test_guard.py record ... --reason stale-test-repair` 记录精确路径

package/harness/bundles/general/claude-code/scripts/harness_archive.py

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

package/harness/bundles/general/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)