@hunter-harness/workflow-harness 0.2.85 → 0.3.0

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

@@ -155,7 +155,47 @@ GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
 # Lifecycle order used to scope C9 scenario coverage by scenario ownerPhase.
 # A scenario owned by a later phase is deferred, not missing, at an earlier
 # phase close. Must stay a superset-ordering of hpf.VALID_OWNER_PHASES.
-SCENARIO_OWNER_PHASE_ORDER = ("plan", "run", "test", "review", "submit")
+SCENARIO_OWNER_PHASE_ORDER = ("plan", "execute", "review", "submit")
+
+# ---------------------------------------------------------------------------
+# 阶段能力表：每个阶段在 begin/close 里额外做什么，集中在这里声明。
+#
+# 这些开关以前是 cmd_begin / cmd_close 里散落的 `if args.phase == ...` —— 两个
+# 五百行的函数，想知道"execute 阶段关门时到底跑哪几项"要通读全文。更要紧的是
+# execute/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(),
+    "execute": frozenset({
+        "plan_handoff", "test_guard", "scenario_coverage",
+        "ledger_blocking", "head_may_advance",
+    }),
+    "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:
@@ -440,8 +480,20 @@ def _phase_capsule_path(change_dir: Path, phase: str, run_id: str) -> Path:
 def load_phase_capsule(
     change_dir: Path, phase: str, run_id: str
 ) -> dict[str, Any] | None:
-    path = _phase_capsule_path(change_dir, phase, run_id)
-    if not path.is_file():
+    # 在途 change 的 capsule 可能按旧名（run/test）写入：先归一入参，canonical
+    # 查不到时对所有解析为该 canonical 的旧名各查一次。新写一律 canonical。
+    phase = hp.resolve_phase_name(phase) or phase
+    candidates = [phase] + [
+        legacy for legacy, canonical in hp.LEGACY_PHASE_ALIASES.items()
+        if canonical == phase
+    ]
+    path: Path | None = None
+    for name in candidates:
+        candidate = _phase_capsule_path(change_dir, name, run_id)
+        if candidate.is_file():
+            path = candidate
+            break
+    if path is None:
         return None
     try:
         data = _read_json(path)
@@ -554,19 +606,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:
@@ -658,7 +730,16 @@ def validate_ledger_for_phase_close(
     individual validation status to be FAIL/NOT_RUN, so a failing phase can
     close honestly without polluting evidence or blocking lease release.
     """
-    required = policy.get("requiredValidations", {}).get(phase, [])
+    resolved_phase = hp.resolve_phase_name(phase) or phase
+    # requiredValidations 的键可能还是合并前的旧名（在途 change 的旧契约），
+    # 入参也可能是旧名（手工 --phase run）——两侧都归一后再匹配；旧契约的
+    # run/test 两个键都映射到 execute，取并集。
+    required: list[str] = []
+    for key, value in (policy.get("requiredValidations") or {}).items():
+        if (hp.resolve_phase_name(key) or str(key)) == resolved_phase:
+            for item in value or []:
+                if item not in required:
+                    required.append(item)
     if not required:
         return {"ok": True, "code": "LEDGER_NOT_REQUIRED", "phase": phase}
 
@@ -852,11 +933,17 @@ def validate_ledger_for_phase_close(
 def effective_workflow_policy(
     workflow: dict[str, Any], change_dir: Path
 ) -> dict[str, Any]:
-    """Overlay a classified change's per-phase gate requirements."""
-    path = change_dir / "meta" / "gate-policy.json"
-    if not path.is_file():
+    """Overlay a classified change's per-phase gate requirements.
+
+    权威切换（2026-08）：经 ``harness_paths.load_change_gate_policy`` 读取——
+    v2 发布快照（meta/plan-profile.json）优先，classify 工作副本回退。
+    返回值保持与历史一致的纯净 workflow 形状；source/drift 由需要记录的
+    调用方另行调用 ``load_change_gate_policy`` 获取（见 gate begin 路径）。
+    """
+    loaded = hp.load_change_gate_policy(change_dir)
+    document = loaded.get("policy")
+    if document is None:
         return workflow
-    document = json.loads(path.read_text(encoding="utf-8"))
     if not isinstance(document, dict) or document.get("schemaVersion") != 1:
         raise ValueError("gate-policy.json must be a schemaVersion 1 object")
     by_phase = document.get("requiredValidationsByPhase")
@@ -901,8 +988,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 +1045,8 @@ def validate_identity(
         "adapter": agent,
         "buildMarkerHash": actual_hash,
         "contextIndexPresent": True,
+        "executorTool": executor_tool or None,
+        "executorMatchesBundle": executor_matches_bundle,
     }
 
 
@@ -1266,7 +1360,7 @@ def _apply_required_gate_contract(
         if stage_name == "package":
             dependencies = [
                 f"validation:{item}" for item in required
-                if validation_phases.get(item) in {"run", "test"}
+                if hp.resolve_phase_name(validation_phases.get(item)) == "execute"
             ]
         elif stage_name == "apidoc" and "apiTest" in required_set:
             dependencies = ["validation:apiTest"]
@@ -1295,8 +1389,13 @@ def classify_risk(
     stage: str,
     workflow: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    tier = "full"
-    source = "default-full"
+    # 无风险信号时的起步档。曾经是 full，于是每个普通变更都默认背上
+    # plan→execute→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 +1650,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 +1768,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 +1821,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 == "execute" and (fixback or "fixback" in note.lower())
+                else None
+            ),
             result_status=None,
         )
         event = he.build_event(args, existing)
@@ -1856,7 +1966,7 @@ def validate_context_for_gate_begin(
     if not isinstance(current, dict):
         return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
     current_phase = str(current.get("phase") or view.get("currentPhase") or "")
-    if current_phase != phase:
+    if hp.resolve_phase_name(current_phase) != phase:
         return {
             "ok": False,
             "code": "CONTEXT_HANDOFF_REQUIRED",
@@ -1870,11 +1980,11 @@ def validate_context_for_gate_begin(
         begin_items = begins if isinstance(begins, list) else []
         acknowledged = any(
             isinstance(item, dict)
-            and item.get("phase") == phase
+            and hp.resolve_phase_name(item.get("phase")) == phase
             and item.get("receiptHash") == receipt_hash
             for item in begin_items
         )
-        if latest.get("toPhase") != phase or not acknowledged:
+        if hp.resolve_phase_name(latest.get("toPhase")) != phase or not acknowledged:
             return {
                 "ok": False,
                 "code": "CONTEXT_BEGIN_REQUIRED",
@@ -1886,7 +1996,7 @@ def validate_context_for_gate_begin(
 
 def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -> bool:
     return any(
-        event.get("phase") == phase
+        hp.resolve_phase_name(event.get("phase")) == phase
         and event.get("type") == type_
         and event.get("run_id") == run_id
         for event in he.load_events(he.events_path(change_dir))
@@ -1899,7 +2009,10 @@ def _latest_phase_end(
     run_id: str | None = None,
 ) -> dict[str, Any] | None:
     for event in reversed(he.load_events(he.events_path(change_dir))):
-        if event.get("phase") != phase or event.get("type") != "phase.end":
+        if (
+            hp.resolve_phase_name(event.get("phase")) != phase
+            or event.get("type") != "phase.end"
+        ):
             continue
         if run_id and event.get("run_id") != run_id:
             continue
@@ -1917,7 +2030,7 @@ def _latest_open_run_id(change_dir: Path, phase: str) -> str | None:
     started: list[str] = []
     ended: set[str] = set()
     for event in he.load_events(he.events_path(change_dir)):
-        if event.get("phase") != phase:
+        if hp.resolve_phase_name(event.get("phase")) != phase:
             continue
         run_id = str(event.get("run_id") or "")
         if not run_id:
@@ -1963,12 +2076,15 @@ def _close_context_handoff(
     to_phase = getattr(args, "to_phase", None)
     if not to_phase:
         return None
+    # 写边界归一：旧名（--to-phase test）落 canonical；未知名交给
+    # close_transition 的 PHASE_UNKNOWN 报错，不在此吞掉。
+    to_phase = hp.resolve_phase_name(to_phase) or str(to_phase)
     try:
         return hctx.close_transition(
             project,
             change_id,
             from_phase=args.phase,
-            to_phase=str(to_phase),
+            to_phase=to_phase,
             executor=getattr(args, "executor", None),
             artifacts=list(getattr(args, "artifact", None) or []),
             status=status,
@@ -1997,6 +2113,10 @@ def _scenario_owner_phase_rank(owner_phase: str | None) -> int | None:
     if not owner_phase:
         return None
     normalized = str(owner_phase).strip().lower()
+    # 旧 manifest 的 ownerPhase=run/test 经别名表归一到 execute 后再定秩。
+    resolved = hp.resolve_phase_name(normalized)
+    if resolved is not None:
+        normalized = resolved
     if normalized not in hpf.VALID_OWNER_PHASES:
         return None
     try:
@@ -2068,52 +2188,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 +2214,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 {
@@ -2473,8 +2550,32 @@ def validate_review_outputs_for_close(
     }
 
 
+def _normalize_gate_phase(args: argparse.Namespace, as_json: bool) -> int | None:
+    """cmd_begin/cmd_close 入口归一：旧名（run/test）映射到现阶段名。
+
+    归一后 args.phase 全链路只流动 canonical 名；未知名报错并列出合法名与别名。
+    """
+    resolved = hp.resolve_phase_name(getattr(args, "phase", None))
+    if resolved is not None:
+        args.phase = resolved
+        return None
+    return emit_error(
+        "PHASE_UNKNOWN",
+        f"未知阶段名 {getattr(args, 'phase', None)!r}；合法阶段 "
+        f"{list(hp.WORKFLOW_PHASES)}，旧名别名 {hp.LEGACY_PHASE_ALIASES}。",
+        as_json=as_json,
+        extra={
+            "allowedPhases": list(hp.WORKFLOW_PHASES),
+            "legacyAliases": dict(hp.LEGACY_PHASE_ALIASES),
+        },
+    )
+
+
 def cmd_begin(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
+    normalized = _normalize_gate_phase(args, as_json)
+    if normalized is not None:
+        return normalized
     project = hc.resolve_main_project_root()
     resolved = hc.resolve_change(project, args.change)
     if not resolved.get("ok"):
@@ -2514,7 +2615,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(
@@ -2605,7 +2706,9 @@ def cmd_begin(args: argparse.Namespace) -> int:
     current_lease = hc.inspect_lease(project, resolved["changeId"])
     run_id = explicit_run_id or (
         str(current_lease.get("runId"))
-        if isinstance(current_lease, dict) and current_lease.get("phase") == args.phase
+        if isinstance(current_lease, dict) and (
+            hp.resolve_phase_name(current_lease.get("phase")) == args.phase
+        )
         else "run-" + uuid.uuid4().hex
     )
     try:
@@ -2700,7 +2803,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 +2870,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,
@@ -2828,6 +2932,9 @@ def cmd_begin(args: argparse.Namespace) -> int:
 
 def cmd_close(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
+    normalized = _normalize_gate_phase(args, as_json)
+    if normalized is not None:
+        return normalized
     project = hc.resolve_main_project_root()
     resolved = hc.resolve_change(project, args.change)
     if not resolved.get("ok"):
@@ -2857,6 +2964,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 hp.resolve_phase_name(expired_lease.get("phase")) == 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 +3095,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"
@@ -2921,7 +3107,9 @@ def cmd_close(args: argparse.Namespace) -> int:
             },
         )
     run_id = explicit_run_id or str(current_lease.get("runId") or "")
-    if str(current_lease.get("runId")) != run_id or str(current_lease.get("phase")) != args.phase:
+    if str(current_lease.get("runId")) != run_id or (
+        hp.resolve_phase_name(current_lease.get("phase")) != args.phase
+    ):
         return emit_error(
             "LEASE_OWNER_MISMATCH",
             "active lease does not match close phase/run-id",
@@ -2994,7 +3182,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 +3237,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 +3264,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 +3290,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 +3322,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 +3380,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 +3435,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 +3553,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 +3744,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 +3769,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=[])