@hunter-harness/workflow-harness 0.2.84 → 0.2.86

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

@@ -157,6 +157,47 @@ GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
 # phase close. Must stay a superset-ordering of hpf.VALID_OWNER_PHASES.
 SCENARIO_OWNER_PHASE_ORDER = ("plan", "run", "test", "review", "submit")
 
+# ---------------------------------------------------------------------------
+# 阶段能力表：每个阶段在 begin/close 里额外做什么，集中在这里声明。
+#
+# 这些开关以前是 cmd_begin / cmd_close 里散落的 `if args.phase == ...` —— 两个
+# 五百行的函数，想知道"test 阶段关门时到底跑哪几项"要通读全文。更要紧的是
+# run/test/review 的差异被摊平在控制流里，看不出它们其实共用同一套生命周期。
+#
+# 键的含义：
+#   plan_handoff      begin 时校验 plan 已 finalize（只有进入实现的第一个阶段需要）
+#   test_guard        begin 建测试基线快照、close 比对（改测试的阶段才需要）
+#   scenario_coverage close 时跑 C9 场景覆盖
+#   ledger_blocking   close 时 ledger 校验失败是否阻断（否则只进 payload）
+#   review_outputs    close 时校验 review sidecar 与 runId 绑定
+#   head_may_advance  capsule 校验允许 HEAD 前移（会产生 commit 的阶段）
+#   projection_drift  close 时 projection receipt 变化即硬失败（外发边界）
+PHASE_GATE_RULES: dict[str, frozenset[str]] = {
+    "plan": frozenset(),
+    "run": frozenset({
+        "plan_handoff", "test_guard", "scenario_coverage",
+        "ledger_blocking", "head_may_advance",
+    }),
+    "test": frozenset({"test_guard", "scenario_coverage", "ledger_blocking"}),
+    "review": frozenset({"review_outputs"}),
+    "package": frozenset({"ledger_blocking"}),
+    "apidoc": frozenset(),
+    "submit": frozenset({"head_may_advance", "projection_drift"}),
+    "merge": frozenset({"head_may_advance"}),
+    "archive": frozenset({"projection_drift"}),
+}
+# 不在 WORKFLOW_PHASES 里、但 projection 门禁按发布阶段对待的名字。
+_EXTRA_PROJECTION_DRIFT_PHASES = frozenset({"release", "deploy"})
+
+
+def phase_gate_rule(phase: str | None, rule: str) -> bool:
+    """这个阶段是否启用某项门禁能力。未知阶段一律不启用（fail-safe）。"""
+    name = str(phase or "")
+    if rule == "projection_drift" and name in _EXTRA_PROJECTION_DRIFT_PHASES:
+        return True
+    resolved = hp.resolve_phase_name(name) or name
+    return rule in PHASE_GATE_RULES.get(resolved, frozenset())
+
 
 def gate_severity_mode(project: Path, change_dir: Path | None = None) -> str:
     """Resolve gate severity mode: env > change gate-policy > project config.
@@ -554,19 +595,39 @@ def load_checkpoints(change_dir: Path) -> dict[str, Any] | None:
         data = _read_json(path)
     except (OSError, json.JSONDecodeError):
         return None
+    # 刻意返回**原样**文档：cmd_checkpoint approve 会把这里的返回值写回盘，
+    # 返回归一化结构会用合成内容覆盖 v2 的哈希绑定产物（ARTIFACT_HASH_DRIFT）。
+    # 形状差异在只读的 checkpoint_status 里消化。
     return data if isinstance(data, dict) else None
 
 
 def checkpoint_status(checkpoints: dict[str, Any] | None, checkpoint_id: str) -> str:
+    """Read a checkpoint's status across the three shapes this file is written in.
+
+    `meta/implementation-checkpoints.json` 有三个写入者，形状各不相同：
+    `harness_change.migrate` 写 ``checkpoints[{id,status}]``；legacy plan finalize 写
+    顶层 ``foundationGate``；v2 plan finalize 写 artifact 包装体，状态在
+    ``content.foundation_gate``。以前只认第一种，另外两种一律返回 "missing"
+    ——checkpoint 的状态对整条 v2 路径和 legacy finalize 之后都是读不出来的。
+
+    只读归一化：调用方拿到的是状态，不是文档。写回路径（cmd_checkpoint approve）
+    仍然操作原始文档，不能用归一化结构覆盖哈希绑定的 v2 产物。
+    """
     if not checkpoints:
         return "missing"
     items = checkpoints.get("checkpoints")
-    if not isinstance(items, list):
+    if isinstance(items, list):
+        for item in items:
+            if isinstance(item, dict) and item.get("id") == checkpoint_id:
+                return str(item.get("status") or "pending")
         return "missing"
-    for item in items:
-        if isinstance(item, dict) and item.get("id") == checkpoint_id:
-            return str(item.get("status") or "pending")
-    return "missing"
+    if checkpoint_id != "foundation-gate":
+        return "missing"
+    unpacked = hpf.unpack_v2_implementation_checkpoints(checkpoints)
+    if unpacked is not None:
+        return str(unpacked["checkpoints"][0]["status"])
+    legacy = checkpoints.get("foundationGate")
+    return str(legacy).strip() if str(legacy or "").strip() else "missing"
 
 
 def foundation_gate_blocks(task_number: int | None, change_dir: Path) -> dict[str, Any] | None:
@@ -901,8 +962,13 @@ def validate_identity(
     core_hash = str(build.get("coreHash") or "").strip()
     if not agent or not core_hash:
         raise ValueError("BUNDLE_IDENTITY_INVALID: agent/coreHash is required")
-    if executor_tool and executor_tool != agent:
-        raise ValueError(f"BUNDLE_IDENTITY_MISMATCH: executor {executor_tool} uses {agent} bundle")
+
+    # 「这个 bundle 是否可信」和「现在是哪个工具在跑」是两件事。以前
+    # executor_tool != agent 直接 BUNDLE_IDENTITY_MISMATCH，于是 Codex 换
+    # CodeBuddy 接手同一个 change 会被当成 bundle 身份不符挡下来。下面每一项
+    # 校验用的都是 bundle 自称的 agent，与当前工具无关；工具名降级为审计字段，
+    # 随 phase.start 事件留痕。
+    executor_matches_bundle = not executor_tool or executor_tool == agent
 
     context = _read_json(project / ".harness" / "context-index.json")
     installed = _read_json(
@@ -953,6 +1019,8 @@ def validate_identity(
         "adapter": agent,
         "buildMarkerHash": actual_hash,
         "contextIndexPresent": True,
+        "executorTool": executor_tool or None,
+        "executorMatchesBundle": executor_matches_bundle,
     }
 
 
@@ -1295,8 +1363,13 @@ def classify_risk(
     stage: str,
     workflow: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    tier = "full"
-    source = "default-full"
+    # 无风险信号时的起步档。曾经是 full，于是每个普通变更都默认背上
+    # plan→run→test→review→submit→archive 六阶段和 apiTest；风险信号推断只在
+    # --stage post-run 下跑，而生产流程没有任何地方调用它，起步值实际就是终值。
+    # standard 保留 compile/unitTest/unitTestFull 的证据闭环，只去掉默认的
+    # review 阶段与 apiTest。下面的单调升级逻辑不变，有信号照样升到 full。
+    tier = "standard"
+    source = "default-standard"
     capabilities = _design_capabilities(change_dir)
     plan_path = change_dir / "plans"
     for candidate in sorted(plan_path.glob("*.md")) if plan_path.is_dir() else []:
@@ -1551,8 +1624,9 @@ def classify_defaults(
     change_id: str,
     stage: str,
 ) -> dict[str, Any]:
-    tier = "full"
-    source = "default-full"
+    # change 目录不存在时的兜底，与 classify_risk 的起步档保持一致。
+    tier = "standard"
+    source = "default-standard"
     tier_policy = workflow["riskTiers"][tier]
     payload = {
         "ok": True,
@@ -1668,6 +1742,7 @@ def append_phase_event(
     executor_agent: str | None = None,
     executor_model: str | None = None,
     code: str | None = None,
+    fixback: bool = False,
 ) -> dict[str, Any]:
     """Skill-facing phase lifecycle append (begin/close use this directly).
 
@@ -1720,8 +1795,17 @@ def append_phase_event(
             execution_mode=None,
             decision_reason_code=None,
             fallback_reason_code=None,
-            trigger=("fixback" if "fixback" in note.lower() else None),
-            from_phase=("review" if phase == "run" and "fixback" in note.lower() else None),
+            # 显式信号优先。以前只嗅探 note 文本，而真正的 fixback 启动路径
+            # （harness_fixback._default_gate_begin）写的 note 是
+            # "开始处理评审中确认需要修改的代码问题。"，一个 "fixback" 字都没有
+            # ——于是 fixback 的 run 事件从来没被打上 trigger/from_phase。
+            # note 嗅探保留为兼容回退：手工传 --note 带 fixback 的老用法仍然有效。
+            trigger=("fixback" if fixback or "fixback" in note.lower() else None),
+            from_phase=(
+                "review"
+                if phase == "run" and (fixback or "fixback" in note.lower())
+                else None
+            ),
             result_status=None,
         )
         event = he.build_event(args, existing)
@@ -2068,52 +2152,6 @@ def _resolve_project(args: argparse.Namespace) -> Path:
     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]:
@@ -2140,9 +2178,12 @@ 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
+    unpacked = hpf.unpack_v2_scenario_manifest(manifest)
+    if unpacked is not None:
+        if not unpacked.get("ok"):
+            return unpacked
+        # 解包成 legacy 形状后，下面的判定逻辑对 v2 与 legacy 完全一致。
+        manifest = unpacked["manifest"]
     scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
     if not isinstance(scenarios, list):
         return {
@@ -2514,7 +2555,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
     severity_mode = gate_severity_mode(project, change_dir)
     gate_warnings: list[dict[str, Any]] = []
     plan_verification: dict[str, Any] | None = None
-    if args.phase == "run":
+    if phase_gate_rule(args.phase, "plan_handoff"):
         plan_verification = validate_plan_handoff(change_dir)
         if not plan_verification.get("ok"):
             code = str(
@@ -2700,7 +2741,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
         if capsule is not None:
             guard_result = {"ok": True, "code": "SNAPSHOT_REUSED"}
         else:
-            if args.phase in {"run", "test"}:
+            if phase_gate_rule(args.phase, "test_guard"):
                 guard_result = htg.begin(execution_root, change_dir)
                 if not guard_result.get("ok"):
                     if gate_soft_allowed(severity_mode, args.phase, "test-guard"):
@@ -2767,6 +2808,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 phase=args.phase,
                 type_="phase.start",
                 note=args.note or "",
+                fixback=bool(getattr(args, "fixback", False)),
                 identity=identity,
                 run_id=run_id,
                 executor_tool=executor_tool,
@@ -2857,6 +2899,83 @@ def cmd_close(args: argparse.Namespace) -> int:
 
     explicit_run_id = args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID")
     current_lease = hc.inspect_lease(project, resolved["changeId"])
+    lease_lapsed: dict[str, Any] | None = None
+    # 只有在"没有活跃租约"时才需要区分不存在/已过期/已损坏——三者要给的答案
+    # 完全不同，而 inspect_lease 把它们一律压成 None。
+    lease_state = (
+        {"state": "active", "lease": current_lease}
+        if current_lease is not None
+        else hc.inspect_lease_state(project, resolved["changeId"])
+    )
+
+    if lease_state["state"] == "corrupt":
+        # 损坏的租约证明不了"没人抢占过"，所以不自动恢复——那正是自动重取唯一
+        # 的安全前提。
+        return emit_error(
+            "LEASE_INVALID",
+            "phase lease file is unreadable; it cannot prove the phase was not taken over",
+            as_json=as_json,
+            extra={
+                "phase": args.phase,
+                "changeId": resolved["changeId"],
+                "recoveryAction": (
+                    "租约文件已损坏，无法自动恢复。确认没有其他进程在跑同一个 change 后，"
+                    "用本阶段原 run-id 重新取得租约再重试 close："
+                    "python <skills-root>/scripts/harness_change.py claim "
+                    f"--change {resolved['changeId']} --phase {args.phase} "
+                    "--run-id <原 run-id> --ttl-seconds 3600 --json"
+                ),
+            },
+        )
+
+    if lease_state["state"] == "expired":
+        expired_lease = lease_state["lease"] or {}
+        expired_run_id = str(expired_lease.get("runId") or "")
+        expected_run_id = explicit_run_id or expired_run_id
+        # 租约过期、runId 还是本轮的，恰好证明没有第三方抢占过：抢占会重写
+        # 租约文件把 runId 换掉。所以过期只说明这个阶段跑得比 TTL 久，不说明
+        # 所有权变了——harness_context.close_transition 早就是这么推理的
+        # （只记 leaseLapsed 照常收尾），这里把 Gate 侧对齐过去，不再要求
+        # 用户手工 claim 一遍再原样重试。
+        if (
+            expired_run_id
+            and expired_run_id == expected_run_id
+            and str(expired_lease.get("phase") or "") == args.phase
+        ):
+            reacquired = hc.claim_lease(
+                project,
+                change_id=str(resolved["changeId"]),
+                phase=args.phase,
+                run_id=expired_run_id,
+                ttl_seconds=int(getattr(args, "ttl_seconds", 0) or 3600),
+            )
+            if not reacquired.get("ok"):
+                return emit_error(
+                    str(reacquired.get("code") or "LEASE_CONFLICT"),
+                    "expired phase lease could not be reacquired for close",
+                    as_json=as_json,
+                    extra={
+                        "phase": args.phase,
+                        "changeId": resolved["changeId"],
+                        "holder": reacquired.get("holder"),
+                    },
+                )
+            current_lease = reacquired.get("lease")
+            lease_lapsed = {
+                "acquiredAt": expired_lease.get("acquiredAt"),
+                "expiresAt": expired_lease.get("expiresAt"),
+                "reacquiredAt": (current_lease or {}).get("refreshedAt")
+                or (current_lease or {}).get("acquiredAt"),
+                "runId": expired_run_id,
+            }
+        else:
+            return emit_error(
+                "LEASE_OWNER_MISMATCH",
+                "expired lease belongs to a different run or phase",
+                as_json=as_json,
+                extra={"holder": expired_lease},
+            )
+
     if current_lease is None:
         terminal = _latest_phase_end(change_dir, args.phase, explicit_run_id)
         if (
@@ -2911,8 +3030,10 @@ def cmd_close(args: argparse.Namespace) -> int:
                 "changeId": resolved["changeId"],
                 "resumeRunId": resume_run_id,
                 "recoveryAction": (
-                    "阶段租约已过期（TTL 由 begin 的 --ttl-seconds 决定，默认 3600 秒）或已被释放。"
-                    "用本阶段原 run-id 重新取得租约后原样重试 close："
+                    "本阶段没有任何租约记录——过期租约现在由 close 自动重取，所以这里说明的是"
+                    "租约从未建立或已被释放。先确认 gate begin 是否真的跑过（events.ndjson 里"
+                    f"应有 phase={args.phase} 的 phase.start）。确有本轮 run-id 时用它重新取得"
+                    "租约再原样重试 close："
                     "python <skills-root>/scripts/harness_change.py claim "
                     f"--change {resolved['changeId']} --phase {args.phase} "
                     f"--run-id {resume_run_id or '<原 run-id>'} --ttl-seconds 3600 --json"
@@ -2994,7 +3115,7 @@ def cmd_close(args: argparse.Namespace) -> int:
                 run_id=run_id,
                 project=project,
                 execution_root=execution_root,
-                allow_head_advance=args.phase in {"run", "submit", "merge"},
+                allow_head_advance=phase_gate_rule(args.phase, "head_may_advance"),
             )
         except ValueError as exc:
             if gate_soft_allowed(severity_mode, args.phase, "capsule"):
@@ -3049,7 +3170,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         and captured_projection.get("receiptHash")
         and captured_projection.get("receiptHash")
         != projection.get("receiptHash")
-        and args.phase in {"submit", "archive", "release", "deploy"}
+        and phase_gate_rule(args.phase, "projection_drift")
     ):
         mismatch = {
             "code": "PROJECTION_CHANGED_DURING_PHASE",
@@ -3076,7 +3197,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         change_dir, args.phase, policy, execution_root=execution_root,
         phase_status=args.status,
     )
-    if not ledger_result.get("ok") and args.phase in {"run", "test", "package"}:
+    if not ledger_result.get("ok") and phase_gate_rule(args.phase, "ledger_blocking"):
         persist_close_failure(
             change_dir,
             args.phase,
@@ -3102,7 +3223,7 @@ def cmd_close(args: argparse.Namespace) -> int:
             extra={k: v for k, v in ledger_result.items() if k not in {"ok", "message", "code"}},
         )
 
-    if args.phase == "review":
+    if phase_gate_rule(args.phase, "review_outputs"):
         review_outputs = validate_review_outputs_for_close(change_dir, run_id)
         if not review_outputs.get("ok"):
             persist_close_failure(
@@ -3134,7 +3255,7 @@ def cmd_close(args: argparse.Namespace) -> int:
     # C9: scenario coverage check — every P0/ledger scenario *due by this phase*
     # must have a ledger entry. Scenarios with a later ownerPhase are deferred,
     # not missing (see _validate_scenario_coverage).
-    if args.phase in {"run", "test"}:
+    if phase_gate_rule(args.phase, "scenario_coverage"):
         coverage = _validate_scenario_coverage(change_dir, args.phase)
         if not coverage.get("ok"):
             if gate_soft_allowed(severity_mode, args.phase, "scenario-coverage"):
@@ -3192,7 +3313,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         write_phase_capsule(change_dir, args.phase, run_id, capsule)
 
     guard_result = None
-    if args.phase in {"run", "test"}:
+    if phase_gate_rule(args.phase, "test_guard"):
         if close_transaction.get("guardClosed"):
             guard_result = {"ok": True, "code": "ALREADY_CLOSED", "reused": True}
         else:
@@ -3247,6 +3368,7 @@ def cmd_close(args: argparse.Namespace) -> int:
                 type_="phase.end",
                 status=close_status,
                 note=args.note or "",
+                fixback=bool(getattr(args, "fixback", False)),
                 run_id=run_id,
             )
         except BaseException as exc:
@@ -3364,6 +3486,10 @@ def cmd_close(args: argparse.Namespace) -> int:
         "gateRecovery": recovery_result,
         "scratchSwept": scratch_swept,
     }
+    if lease_lapsed is not None:
+        # 与 context transition receipt 的 leaseLapsed 同名同义：记录这个阶段
+        # 跑过了 TTL 且租约是自动重取的，不隐藏。
+        payload["leaseLapsed"] = lease_lapsed
     emit(payload, as_json=as_json)
     return 0
 
@@ -3551,6 +3677,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_begin.add_argument("--ttl-seconds", type=int, default=3600)
     p_begin.add_argument("--task", type=int, default=None)
     p_begin.add_argument("--note", default="")
+    p_begin.add_argument(
+        "--fixback",
+        action="store_true",
+        help="This phase is a review fixback round (tags the lifecycle event).",
+    )
     p_begin.add_argument("--executor-tool", default=None)
     p_begin.add_argument("--executor-agent", default=None)
     p_begin.add_argument("--executor-model", default=None)
@@ -3571,6 +3702,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)
     p_close.add_argument("--note", default="")
+    p_close.add_argument(
+        "--fixback",
+        action="store_true",
+        help="This phase is a review fixback round (tags the lifecycle event).",
+    )
     p_close.add_argument("--to-phase", default=None)
     p_close.add_argument("--executor", default=None)
     p_close.add_argument("--artifact", action="append", default=[])

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:"