@hunter-harness/workflow-harness 0.2.85 → 0.2.86

package/harness/bundles/general/cursor/scripts/harness_ledger.py

@@ -28,6 +28,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_paths  # noqa: E402
+import harness_plan_finalize as hpf  # noqa: E402
 import harness_profile  # noqa: E402
 
 
@@ -1629,6 +1630,24 @@ def _scenario_receipt_error(code: str, message: str) -> dict[str, Any]:
     return {"ok": False, "code": code, "error": message}
 
 
+def resolve_scenario_manifest(manifest: Any) -> dict[str, Any]:
+    """把 v2 artifact 包装体解成 legacy 形状；legacy 输入原样返回。
+
+    解包规则住在 harness_plan_finalize（它定义了 legacy manifest 的 schema），
+    门禁与本模块共用同一份，两边不会各推一套。
+
+    此前这里只判包装体、一律 fail-closed；更早的时候连判都不判——cmd_record
+    的版本探测初值是 0，包装体探测不出 schemaVersion 就停在 0，
+    `manifest_schema >= 2` 判假，--scenario-receipt-file 的强制要求被静默跳过。
+
+    返回 ``{"ok": True, "manifest": ...}`` 或 ``{"ok": False, "code": ...}``。
+    """
+    unpacked = hpf.unpack_v2_scenario_manifest(manifest)
+    if unpacked is None:
+        return {"ok": True, "manifest": manifest}
+    return unpacked
+
+
 def _resolve_receipt_path(
     raw: str, change_dir: Path
 ) -> tuple[Path | None, list[Path]]:
@@ -1694,6 +1713,12 @@ def validate_scenario_execution_receipt(
         )
     except (OSError, json.JSONDecodeError) as exc:
         return _scenario_receipt_error("SCENARIO_MANIFEST_INVALID", str(exc))
+    resolved = resolve_scenario_manifest(manifest)
+    if not resolved["ok"]:
+        return _scenario_receipt_error(
+            str(resolved["code"]), str(resolved.get("message") or "")
+        )
+    manifest = resolved["manifest"]
     if not isinstance(manifest, dict) or not isinstance(manifest.get("scenarios"), list):
         return _scenario_receipt_error(
             "SCENARIO_MANIFEST_INVALID",
@@ -2827,6 +2852,15 @@ def cmd_record(args: argparse.Namespace) -> int:
                             as_json=as_json,
                             error_code="SCENARIO_MANIFEST_INVALID",
                         )
+                    resolved_probe = resolve_scenario_manifest(manifest_probe)
+                    if not resolved_probe["ok"]:
+                        return emit_error(
+                            str(resolved_probe.get("message") or ""),
+                            as_json=as_json,
+                            error_code=str(resolved_probe["code"]),
+                            extra={"artifactType": "scenario_manifest"},
+                        )
+                    manifest_probe = resolved_probe["manifest"]
                     raw_schema = (
                         manifest_probe.get("schemaVersion")
                         if isinstance(manifest_probe, dict)
@@ -3064,6 +3098,15 @@ def cmd_scenario_receipt_template(args: argparse.Namespace) -> int:
             as_json=as_json,
             error_code="SCENARIO_MANIFEST_INVALID",
         )
+    resolved = resolve_scenario_manifest(manifest)
+    if not resolved["ok"]:
+        return emit_error(
+            str(resolved.get("message") or ""),
+            as_json=as_json,
+            error_code=str(resolved["code"]),
+            extra={"artifactType": "scenario_manifest"},
+        )
+    manifest = resolved["manifest"]
     scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
     if not isinstance(scenarios, list):
         return emit_error(

package/harness/bundles/general/cursor/scripts/harness_paths.py

@@ -34,6 +34,66 @@ if hasattr(sys.stderr, "reconfigure"):
 LIFECYCLE_STATUSES = {"draft", "active", "superseded", "archived", "cancelled"}
 CHANGE_CONTEXT_REL = Path("meta") / "change-context.json"
 
+# 工作流阶段的唯一权威清单。这里是叶子模块（不 import 任何 harness_*），所以
+# harness_context 与 harness_phase 都能引它而不成环。
+#
+# 此前这份清单在两个模块各写一遍，靠约定保持同步——直到 harness_phase 少了一个
+# merge，worktree 变更走到 merge 阶段就在 target_required_dag 里直接 raise
+# "unsupported reconcile target phase"。同一份事实不该有两个副本。
+WORKFLOW_PHASES = (
+    "plan",
+    "run",
+    "test",
+    "review",
+    "package",
+    "apidoc",
+    "submit",
+    "merge",
+    "archive",
+)
+
+# 出现在阶段位置、但不是工作流阶段的名字。它们是真实存在的：
+# workflow-policy.json 的 skills.*.phase 用 sync/codebase-map/knowledge-query 标注
+# 技能归属，harness_gate.GATE_RELEASE_PHASES 含 release/deploy。把它们与"拼错的
+# 阶段名"区分开，调用方才能既不误判也不硬崩。
+KNOWN_NON_WORKFLOW_PHASES = frozenset({
+    "release",
+    "deploy",
+    "sync",
+    "codebase-map",
+    "knowledge-query",
+    "knowledge-ingest",
+    "push",
+    "pull",
+})
+
+# 旧阶段名 → 现阶段名。阶段合并/改名时在这里登记，读时映射即可让历史
+# gate-policy.json 与 plannedPhases 继续可读，不必迁移已落盘的 change。
+# 目前为空：还没有发生过阶段改名。
+LEGACY_PHASE_ALIASES: dict[str, str] = {}
+
+
+def resolve_phase_name(phase: Any) -> str | None:
+    """把可能是旧名的阶段解析成当前的工作流阶段名；不是工作流阶段则返回 None。"""
+    name = str(phase or "").strip()
+    if name in WORKFLOW_PHASES:
+        return name
+    mapped = LEGACY_PHASE_ALIASES.get(name)
+    return mapped if mapped in WORKFLOW_PHASES else None
+
+
+def classify_phase_name(phase: Any) -> str:
+    """三态判定：``workflow`` | ``non_workflow`` | ``unknown``。
+
+    调用方需要区分这三者：``workflow`` 照常处理；``non_workflow`` 是别的子系统
+    的标注，跳过而不是报错；只有 ``unknown`` 才是真的有问题，值得让人看见。
+    """
+    if resolve_phase_name(phase) is not None:
+        return "workflow"
+    if str(phase or "").strip() in KNOWN_NON_WORKFLOW_PHASES:
+        return "non_workflow"
+    return "unknown"
+
 
 def _git_text(cwd: Path, *args: str) -> str | None:
     proc = subprocess.run(

package/harness/bundles/general/cursor/scripts/harness_phase.py

@@ -33,7 +33,9 @@ import harness_paths as hpaths  # noqa: E402
 
 SCHEMA_VERSION = 1
 CI_METRICS_SCHEMA_VERSION = 1
-PHASE_ORDER = ("plan", "run", "test", "review", "package", "apidoc", "submit", "archive")
+# 唯一权威清单在 harness_paths，harness_context 引的是同一个对象。此前这里另有
+# 一份拷贝，少了 merge，worktree 变更走到 merge 就在 target_required_dag 里硬 raise。
+PHASE_ORDER = hpaths.WORKFLOW_PHASES
 VALIDATION_PHASES = {
     "compile": "run",
     "unitTest": "run",
@@ -700,8 +702,18 @@ def target_required_dag(policy: dict[str, Any], target_phase: str) -> dict[str,
     stage nodes for the target itself are deliberately excluded because their
     ``phase.end`` is the result of close, not evidence required before close.
     """
-    if target_phase not in PHASE_ORDER:
-        raise ValueError(f"unsupported reconcile target phase: {target_phase}")
+    # 未知阶段名先过读时映射：阶段改名后，历史 change 的 gate-policy.json 与
+    # plannedPhases 里仍然是旧名，靠 LEGACY_PHASE_ALIASES 继续可读，不必迁移已落盘
+    # 的 change（本仓库没有 change 级 schema 迁移机制，硬 raise 等于让在途变更报废）。
+    resolved_target = hpaths.resolve_phase_name(target_phase)
+    if resolved_target is None:
+        raise ValueError(
+            f"unsupported reconcile target phase: {target_phase}; "
+            f"已知阶段 {', '.join(PHASE_ORDER)}。"
+            "若这是改名前的旧阶段，在 harness_paths.LEGACY_PHASE_ALIASES 登记映射；"
+            "若这份 gate-policy.json 本身过期，重跑 harness_gate.py classify 重建"
+        )
+    target_phase = resolved_target
     dag = policy.get("requiredGateDag")
     if not isinstance(dag, dict) or not isinstance(dag.get("nodes"), list):
         raise ValueError("gate policy missing requiredGateDag; run harness_gate.py classify")
@@ -718,9 +730,15 @@ def target_required_dag(policy: dict[str, Any], target_phase: str) -> dict[str,
             if node_kind == "validation"
             else node_name
         )
-        node_phase = str(node.get("phase") or inferred_phase or "")
-        if node_phase not in PHASE_ORDER:
-            raise ValueError(f"requiredGateDag node has unsupported phase: {node_id}")
+        raw_phase = str(node.get("phase") or inferred_phase or "")
+        node_phase = hpaths.resolve_phase_name(raw_phase)
+        if node_phase is None:
+            raise ValueError(
+                f"requiredGateDag node has unsupported phase: {node_id} (phase={raw_phase!r})；"
+                "旧阶段名在 harness_paths.LEGACY_PHASE_ALIASES 登记映射，"
+                "或重跑 harness_gate.py classify 重建这份 gate-policy.json"
+            )
+        node["phase"] = node_phase
         node_rank = PHASE_ORDER.index(node_phase)
         is_validation = node.get("kind") == "validation" or node_id.startswith(
             "validation:"

package/harness/bundles/general/cursor/scripts/harness_plan_finalize.py

@@ -261,6 +261,127 @@ def scenario_manifest_schema_version(scenarios: list[dict[str, Any]]) -> int:
     return 1
 
 
+# v2 场景键 → 门禁与 ledger 消费的 legacy 键。可执行三元是可选的：缺了只是把
+# manifest 降到 schemaVersion 1（绑不上结构化执行收据），不算缺口。
+_V2_SCENARIO_FIELD_MAP = (
+    ("scenario_id", "id"),
+    ("priority", "priority"),
+    ("required_evidence_kind", "requiredEvidenceKind"),
+    ("owner_phase", "ownerPhase"),
+)
+_V2_SCENARIO_OPTIONAL_FIELD_MAP = (
+    ("executable_test_id", "executableTestId"),
+    ("test_file", "testFile"),
+    ("test_title", "testTitle"),
+)
+V2_MANIFEST_UNSUPPORTED = "SCENARIO_MANIFEST_V2_UNSUPPORTED"
+
+
+def is_v2_scenario_manifest(manifest: Any) -> bool:
+    """v2 plan finalize 派生的 scenario_manifest artifact 包装体。
+
+    它没有顶层 schemaVersion，场景字段全在 content.scenarios 下且改了名。
+    """
+    return (
+        isinstance(manifest, dict)
+        and manifest.get("artifact_type") == "scenario_manifest"
+    )
+
+
+def unpack_v2_scenario_manifest(manifest: Any) -> dict[str, Any] | None:
+    """v2 artifact 包装体 → 消费端的 legacy 形状；字段不齐时 fail-closed。
+
+    返回 None 表示"这不是 v2 包装体"，调用方按 legacy 原样处理。否则返回
+    ``{"ok": True, "manifest": {...}}``（已是 legacy 形状，后续判定逻辑对
+    v2 与 legacy 完全一致）或 ``{"ok": False, "code": V2_MANIFEST_UNSUPPORTED}``。
+
+    这个函数住在 finalizer 里，是因为 legacy manifest 的 schema 本来就由本模块
+    定义（``scenario_manifest_schema_version`` / ``PRIORITY_EVIDENCE_KIND``）。
+    门禁与 ledger 都 import 它，两边不会各推一套解包规则。
+
+    为什么必须逐场景校验、不能取键的并集：并集只要有**一条**场景带了
+    priority 就算"present"，其余缺 priority 的场景会静默落进非必需集，
+    ``required_ids`` 随之缩水——那正是把证据门禁悄悄关掉的老路子。
+    """
+    if not is_v2_scenario_manifest(manifest):
+        return None
+    content = manifest.get("content")
+    raw = content.get("scenarios") if isinstance(content, dict) else None
+    if not isinstance(raw, list):
+        return {
+            "ok": False,
+            "code": V2_MANIFEST_UNSUPPORTED,
+            "message": "v2 scenario-manifest 的 content.scenarios 必须是数组",
+            "missingFields": [legacy for _, legacy in _V2_SCENARIO_FIELD_MAP],
+            "artifactType": "scenario_manifest",
+        }
+    scenarios: list[dict[str, Any]] = []
+    missing: set[str] = set()
+    for item in raw:
+        if not isinstance(item, dict):
+            missing.update(legacy for _, legacy in _V2_SCENARIO_FIELD_MAP)
+            continue
+        mapped: dict[str, Any] = {}
+        for source, legacy in _V2_SCENARIO_FIELD_MAP:
+            value = item.get(source)
+            if not str(value or "").strip():
+                missing.add(legacy)
+                continue
+            mapped[legacy] = value
+        for source, legacy in _V2_SCENARIO_OPTIONAL_FIELD_MAP:
+            value = item.get(source)
+            if str(value or "").strip():
+                mapped[legacy] = value
+        scenarios.append(mapped)
+    if missing:
+        return {
+            "ok": False,
+            "code": V2_MANIFEST_UNSUPPORTED,
+            "message": (
+                "meta/scenario-manifest.json 是 v2 plan artifact 包装体，"
+                "部分场景缺少消费端需要的字段；请在规划阶段补齐后重新发布，"
+                "不要手改派生产物"
+            ),
+            "missingFields": sorted(missing),
+            "artifactType": "scenario_manifest",
+        }
+    return {
+        "ok": True,
+        "manifest": {
+            # 与 legacy 同一条规则判版本，不另立一套。
+            "schemaVersion": scenario_manifest_schema_version(scenarios),
+            "scenarios": scenarios,
+        },
+    }
+
+
+def unpack_v2_implementation_checkpoints(document: Any) -> dict[str, Any] | None:
+    """v2 的 implementation_checkpoints artifact 包装体 → 门禁消费的形状。
+
+    返回 None 表示"这不是 v2 包装体"，调用方按原样处理。
+
+    v2 的 content 是 ``{tasks, foundation_gate}``，而 ``checkpoint_status`` 找的是
+    ``checkpoints: [{id, status}]``——找不到就返回 "missing"，``foundation_gate_blocks``
+    随即放行。也就是说 foundation-gate 对**所有 v2 计划**是静默关闭的。信息本身是够
+    的（``foundation_gate`` 就是那个状态），只是形状不同，所以这里解包而不是改文件名
+    ——与 scenario-manifest 同一模式。
+    """
+    if (
+        not isinstance(document, dict)
+        or document.get("artifact_type") != "implementation_checkpoints"
+    ):
+        return None
+    content = document.get("content")
+    content = content if isinstance(content, dict) else {}
+    status = str(content.get("foundation_gate") or "").strip() or "pending"
+    tasks = content.get("tasks")
+    return {
+        "schemaVersion": 1,
+        "checkpoints": [{"id": "foundation-gate", "status": status, "blocking": True}],
+        "tasks": tasks if isinstance(tasks, list) else [],
+    }
+
+
 def parse_plan_tasks(plan_path: Path) -> list[dict[str, str]]:
     """C8: parse plan.md task table rows, extracting optional ownerPhase/implementationDoneWhen/verificationPhase columns.
 
@@ -877,7 +998,9 @@ def _verify_plan_v2(change_dir: Path) -> dict[str, Any] | None:
         f"plans/{change_dir.name}-plan.md",
         f"plans/{change_dir.name}-implementation-detail.md",
         f"plans/{change_dir.name}-test-scenarios.md",
-        "meta/gate-policy.json",
+        # v2 发布的是派生视图 meta/plan-profile.json，不是 Python classify 写的
+        # meta/gate-policy.json——后者是 run/test 门禁的权威输入，不能被发布覆盖。
+        "meta/plan-profile.json",
         "meta/worktree.json",
     }
     missing_required = sorted(required - set(ownership_paths))

package/harness/bundles/general/cursor/scripts/harness_review.py

@@ -194,14 +194,30 @@ def _load_findings(change_dir: Path) -> dict[str, Any] | None:
 
 
 def validate_dispositions(
-    doc: Any, known_ids: set[str]
+    doc: Any, known_ids: set[str], findings_run_id: str | None = None
 ) -> list[str]:
+    """校验处置文档。``findings_run_id`` 给出时，还要求两份 sidecar 同属一轮。
+
+    runId 以前完全不校验——``write_dispositions`` 直接透传 ``doc.get("runId")``，
+    写 ``None`` 都能落盘，整条 sidecar 的强制力全压在 gate 关门时的一行断言上。
+    而这条断言防的是 fixback 循环里的跨轮重放：sidecar 是 per-change 单文件、不带
+    runId 后缀，第二轮 review 关门时磁盘上躺着第一轮那份（finding 全已 FIXED）。
+    在写入端就挡住，比等到关门再拒绝早一整轮。
+    """
     problems: list[str] = []
     if not isinstance(doc, dict):
         return ["dispositions document must be an object"]
+    run_id = doc.get("runId")
+    if not isinstance(run_id, str) or not run_id.strip():
+        problems.append("runId is required")
+    elif findings_run_id is not None and run_id != findings_run_id:
+        problems.append(
+            f"runId {run_id} does not match review findings runId {findings_run_id}"
+        )
     dispositions = doc.get("dispositions")
     if not isinstance(dispositions, list):
-        return ["dispositions must be a list"]
+        problems.append("dispositions must be a list")
+        return problems
     for index, item in enumerate(dispositions):
         if not isinstance(item, dict):
             problems.append(f"dispositions[{index}] must be an object")
@@ -226,12 +242,17 @@ def write_dispositions(change_dir: Path, doc: dict[str, Any]) -> dict[str, Any]:
         f.get("id") for f in (findings_doc or {}).get("findings", [])
         if isinstance(f, dict)
     }
-    problems = validate_dispositions(doc, known_ids)
+    findings_run_id = (findings_doc or {}).get("runId")
+    problems = validate_dispositions(
+        doc,
+        known_ids,
+        findings_run_id if isinstance(findings_run_id, str) else None,
+    )
     if problems:
         return {"ok": False, "code": "DISPOSITIONS_INVALID", "problems": problems}
     payload = {
         "schemaVersion": 1,
-        "runId": doc.get("runId"),
+        "runId": doc["runId"],
         "dispositions": doc["dispositions"],
     }
     out = dispositions_path(change_dir)

package/harness/bundles/java/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "123134be5333129c"
+  "coreHash": "0130f72da1a50434"
 }

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-archive/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/java/claude-code/harness-knowledge-query/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/claude-code/harness-plan/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=123134be5333129c; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=0130f72da1a50434; overlay=java; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -88,7 +88,7 @@ disallowed-tools:
 | 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`，不得伪造阶段事件 |
+| 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`，不得伪造阶段事件。<br>⚠️ 无风险信号时 classify 默认 `standard`（`plan,run,test,submit,archive` + compile/unitTest/unitTestFull），**不再默认 full**。需要 review 阶段与 apiTest 的高风险变更，在计划文档里写「风险等级: full」或用 `classify --tier-override full` 显式升档 |
 | 1 | 直接执行一次 `npx hunter-harness knowledge query "<用户需求原文>" --limit 10 --json`。这是唯一执行入口，不扫描技能目录、不查找其他脚本；失败记 `issue` 并继续，不建立本地索引或离线回退 |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
@@ -124,6 +124,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 设计审批包 | 一次 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、收据完整覆盖六项标准产物、哈希、全部任务表和非空场景清单一致。失败均不得手工补终态 |
+| 选 v2 还是 legacy | **默认 v2**；legacy 已 deprecated，将在 workflow-harness 0.3.0 移除，只用于自然输入不完整（例如缺真实审批记录）的回退。v2 的场景契约已补齐 `priority`/`owner_phase` 与可执行测试三元，派生的 `meta/scenario-manifest.json` 能被 run/test 门禁与 `harness_ledger.py record` 解包消费，证据闭环走得通。P0/P1 场景必须给全可执行三元（要么整组给全、要么整组省略；省略则 manifest 降为 schemaVersion 1，关门绑不上结构化执行收据） |
 | 发布后改产物 | 用 `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` 结构：`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` |

package/harness/bundles/java/claude-code/harness-plan/checklist.md

@@ -184,8 +184,8 @@ source: harness-plan
 □ 已用 decision / issue 事件 note 记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
 □ 已叠加项目架构约束（分层规范、数据模型、接口规范）
 □ 需求澄清结论已追加到 events.ndjson，阶段结束后执行日志由渲染器生成
-□ 用户问题未超预算：简单修复 0-1 问，普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
-□ 提问遵循"一次一问、等答再继续"；能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
+□ 提问方式与问题预算符合 protocols.md 的 decision-grilling-protocol（预算数值以那份为准，此处不复述）
+□ 能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
 □ 每个需要用户决策的问题，AI 先给出了推荐答案、理由和取舍，用户仅确认或修正
 □ 高风险/业务语义决策（范围、权限、安全、支付、迁移、删除、API契约、用户可见行为）已显式等待用户确认
 ```
@@ -199,97 +199,34 @@ source: harness-plan
 ```
 □ 已读取 protocols.md，并按 implementation-planning-protocol 执行
 □ 输入为阶段4已审核设计文档
-□ 已生成基础任务列表，并用 artifact 事件 note 记录任务拆分摘要
+□ 已用 artifact 事件 note 记录任务拆分摘要
 □ 已叠加项目层序依赖（数据/契约→业务层→接口层）
 □ 已生成 4 维度场景表（单元/接口/数据兼容/集成）
 □ 每个自动化场景均标注执行层级、预计时长、资源预算、超时、可复用证据；快速反馈不默认扫描全仓库
 □ 已确定变更名（kebab-case）
-□ 产物已写入 .harness/changes/<change-name>/plans/：
-  - <change-name>-plan.md（简洁任务表）
-  - <change-name>-implementation-detail.md（自适应详细执行参考）
-  - <change-name>-test-scenarios.md（测试场景表）
 □ implementation-detail.md 按复杂度自适应：简单任务不过度展开，复杂任务写清接口/数据/顺序/风险/测试策略
 □ plan / implementation-detail / test-scenarios 三件套互相引用一致，无 TBD/TODO/空泛占位
 ```
 
+> 产物是否齐全、任务表与场景表是否非空、优先级与 ownerPhase 取值是否合法，由 finalizer
+> fail-closed 判定（`PLAN_ARTIFACT_MISSING` / `PLAN_TASKS_EMPTY` / `PLAN_SCENARIOS_EMPTY` /
+> `PLAN_SCENARIO_PRIORITY_INVALID`），此处不重复勾选。上面留下的都是机器判不了的：
+> 层序依赖是否合理、维度是否真被覆盖、详略是否配得上复杂度、三件套是否自洽。
+
 > 不再检查 Superpowers writing-plans 是否安装或调用；阶段 6 是 harness 原生协议，不存在 `docs/superpowers/` 同步分支。
 
 ## 阶段 8：结束前产物完整性检查 ⚠️ 强制
 
-> **缺任一文件 → ❌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`
-- [ ] 紧接着执行 `harness_plan_finalize.py verify --change-dir ... --json`
-- [ ] verify 返回 `phaseStartCount=1`、`phaseEndCount=1`、`phaseEndStatus=OK`、`receiptConsistent=true`
-- [ ] 收据 `files` 完整包含 design / plan / implementation-detail / test-scenarios / gate-policy / worktree 六项标准产物；不得省略、重复或经 symlink/junction/reparse point 引用
-- [ ] verify 的 `taskCount` 等于全部任务表行数，`scenarioCount` 等于 Markdown 中全部唯一场景 ID 数；任一为 0 或不一致即 ❌FAIL
-- [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
-- [ ] 禁止在 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` | ✅ | □ |
-| `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅ | □ |
-| `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅ | □ |
-| `.harness/changes/<change>/meta/gate-policy.json` | ✅ | □ |
-| `.harness/changes/<change>/meta/worktree.json` | ✅ | □ |
-| `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ | □ |
-| `.harness/changes/<change>/meta/scenario-manifest.json`（非空且计数一致） | ✅ | □ |
-| `.harness/changes/<change>/meta/plan-finalization.json`（finalized） | ✅ | □ |
-| `.harness/changes/<change>/logs/execution-log.md` | ✅ | □ |
-| `.harness/changes/<change>/events.ndjson` | ✅ | □ |
-
-### Plan 结束行为检查
+> **先认路径**：v2 与 legacy 的完整性口径不同，混用会得出错误结论。两条路径各自的必需文件清单 → `reference.md`「阶段 8」。
 
-```
-□ 未询问 Subagent-Driven / Inline Execution 等执行模式
-□ 最终输出只提示了产出物路径和下一步 /harness-run
-□ 未将 docs/superpowers/ 列为最终产物路径
-```
+文件是否齐全、哈希是否一致、身份是否匹配、计数是否对得上——这些 **finalizer 与 verify 已经 fail-closed 判定**，逐条复述不产生新结论，只会把一份事实变成两份。命令失败时按返回的 `code` 查 `reference.md`，不要对着清单猜。
 
-### Legacy Frontmatter 兼容
+下面三条不在机器判定范围内，必须自己守：
+
+- [ ] **v2**：只手写 `meta/plan-evidence-input.json`。`plans/*.md` 由 finalize 派生，手写的会被渲染覆盖，只是白写
+- [ ] 任何缺失**都不得手工补写**（包括 `phase.end`）；回到对应阶段改自然输入/staging 后重跑
+- [ ] v2 过渡期**不写** `meta/plan-finalization.json` 与 `logs/execution-log.md`；缺这两项不算失败，不得为凑表手工补
 
-```
-□ 已确认 plan 文件 frontmatter 存在
-□ 如不存在 → 已从路径推断 change-name 和 plan-name
-□ 如不存在 → 执行日志中已标记 🟡 legacy-plan
-□ 旧 plan 不因 frontmatter 缺失而 FAIL
-```
 
 ## 关键原则
 
@@ -300,7 +237,9 @@ source: harness-plan
 - 场景表是后续所有步骤的真相源——宁可多花时间打磨，不要草草了事
 - 如果需求不明确，优先提问而不是猜测后继续设计
 - 任务拆分粒度按复杂度调整——plan 简表保持可追踪，implementation-detail 按风险和复杂度自适应展开
-- **Plan 结束禁止询问执行模式**：Subagent-Driven / Inline Execution 属于 /harness-run 阶段
+
+> Plan 的结束行为（禁止询问执行模式、只提示 `/harness-run`）由 `SKILL.md` 的关键规则表定义，
+> 详细规则见 `reference.md`「Plan 结束行为规则」。此处不再复述。
 
 ## 事件记录（前置规则）
 

package/harness/bundles/java/claude-code/harness-plan/protocols.md

@@ -128,4 +128,6 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 - implementation-planning-protocol：plan 简表、implementation-detail、test-scenarios 三件套一致，无占位符
 ```
 
-该自检作为 `verification` 事件的 `note` 追加；关键结论分别追加 `decision` / `issue` 事件。渲染器在 `phase.end` 后生成执行日志。
+自检结论直接展示给用户即可，**不要**再追加一条 `verification` 事件——「协议自检通过」不改变
+任何结论，只增加监控噪声（roadmap 12 号「事件规则」）。真正影响行为的东西照常留痕：关键决策
+追加 `decision`，发现的冲突与阻塞追加 `issue`。渲染器在 `phase.end` 后生成执行日志。