@hunter-harness/workflow-harness 0.2.85 → 0.3.0

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
 
 
@@ -201,14 +202,16 @@ def frozen_ownership_check(change_dir: Path) -> dict[str, Any]:
     if not capsule_root.is_dir():
         return {"ok": True, "code": "OWNERSHIP_FREEZE_NOT_APPLICABLE"}
     capsules: list[dict[str, Any]] = []
-    for path in capsule_root.glob("run-*.json"):
+    # capsule 文件名是 <phase>-<hash>.json；execute 合并（run/test→execute）后
+    # 新旧两批名字都可能躺在在途 change 里，按内容归一判定而不是按文件名。
+    for path in capsule_root.glob("*.json"):
         try:
             item = json.loads(path.read_text(encoding="utf-8-sig"))
         except (OSError, json.JSONDecodeError):
             continue
         if (
             isinstance(item, dict)
-            and item.get("phase") == "run"
+            and harness_paths.resolve_phase_name(item.get("phase")) == "execute"
             and not item.get("closedAt")
             and _nonempty_str(item.get("ownershipHash"))
         ):
@@ -1629,6 +1632,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 +1715,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 +2854,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 +3100,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,67 @@ 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",
+    "execute",
+    "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 与已落盘 transitions 继续可读，不必迁移
+# 已落盘的 change。注意：映射只能用在哈希校验之后的业务比较层——对已哈希
+# 的 receipt 先映射再重算会断 _payload_hash 链。
+# 2026-08 run+test 合并为 execute（方案 c，review 保留独立阶段）。
+LEGACY_PHASE_ALIASES: dict[str, str] = {"run": "execute", "test": "execute"}
+
+
+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(
@@ -170,6 +231,120 @@ def load_change_contract(contract_dir: Path) -> dict[str, Any]:
     return data
 
 
+def _unpack_v2_gate_policy(wrapper: Any) -> dict[str, Any] | None:
+    """meta/plan-profile.json（v2 包装体）→ Python schemaVersion:1 形状。
+
+    门禁权威所需的四个字段（mode/planned_phases/required_gate_dag/
+    required_validations_by_phase）缺一即视为不完整快照（0.2.92-era 的发布
+    没有门禁 overlay），调用方回退工作副本。返回 None 表示不可用作权威。
+    """
+    if not isinstance(wrapper, dict):
+        return None
+    if wrapper.get("artifact_type") != "gate_policy":
+        return None
+    content = wrapper.get("content")
+    if not isinstance(content, dict):
+        return None
+    planned = content.get("planned_phases")
+    dag = content.get("required_gate_dag")
+    by_phase = content.get("required_validations_by_phase")
+    if (
+        not isinstance(content.get("mode"), str)
+        or not (isinstance(planned, list) and all(isinstance(p, str) for p in planned))
+        or not isinstance(dag, dict)
+        or not isinstance(by_phase, dict)
+    ):
+        return None
+    policy: dict[str, Any] = {
+        "schemaVersion": 1,
+        "tier": content.get("tier"),
+        "source": content.get("source"),
+        "plannedPhases": list(planned),
+        "requiredValidations": list(content.get("required_validations") or []),
+        "requiredValidationsByPhase": dict(by_phase),
+        "requiredGateDag": dict(dag),
+    }
+    return policy
+
+
+def load_change_gate_policy(change_dir: Path) -> dict[str, Any]:
+    """v2-first 的每 change 门禁策略加载（权威切换 2026-08）。
+
+    meta/plan-profile.json（v2 发布快照，门禁字段已哈希绑定）优先于
+    meta/gate-policy.json（classify 在 0.5 写的工作副本）。v2 快照不完整
+    或缺失 → 回退工作副本。两者并存且 plannedPhases（canonical 归一去重
+    后）不一致 → drift 报告，策略以 v2 为准（已审批定稿 > 工作副本；
+    发布后改写工作副本本身就是异常）。
+
+    返回 ``{"policy": <schemaVersion:1 dict 或 None>, "source":
+    "v2-plan-profile" | "gate-policy-json" | None, "drift": dict | None,
+    "working_error": bool}``——``working_error`` 区分"工作副本不存在"与
+    "存在但不可读"（`_phase_plan` 的 legacy:policy-unreadable 语义靠它）。
+    """
+    change_dir = Path(change_dir)
+    v2_policy: dict[str, Any] | None = None
+    v2_path = change_dir / "meta" / "plan-profile.json"
+    if v2_path.is_file():
+        try:
+            v2_policy = _unpack_v2_gate_policy(
+                json.loads(v2_path.read_text(encoding="utf-8-sig"))
+            )
+        except (OSError, ValueError, json.JSONDecodeError):
+            v2_policy = None
+
+    working: dict[str, Any] | None = None
+    working_error = False
+    working_path = change_dir / "meta" / "gate-policy.json"
+    if working_path.is_file():
+        try:
+            candidate = json.loads(working_path.read_text(encoding="utf-8-sig"))
+            # 工作副本保持与历史一致的宽松接受：任何 dict 都交给下游各自的
+            # 形状校验（effective_workflow_policy 查 schemaVersion，reconcile
+            # 查 requiredGateDag），加载器不提前收紧。
+            if isinstance(candidate, dict):
+                working = candidate
+            else:
+                working_error = True
+        except (OSError, ValueError, json.JSONDecodeError):
+            working_error = True
+
+    drift: dict[str, Any] | None = None
+    if v2_policy is not None and working is not None:
+        canonical = lambda names: sorted(
+            {name for raw in (names or []) if (name := resolve_phase_name(raw))}
+        )
+        v2_phases = canonical(v2_policy.get("plannedPhases"))
+        working_phases = canonical(working.get("plannedPhases"))
+        if v2_phases != working_phases:
+            drift = {
+                "kind": "plannedPhases",
+                "v2": v2_phases,
+                "gate_policy_json": working_phases,
+                "resolution": "v2-plan-profile wins (approved publication snapshot)",
+            }
+
+    if v2_policy is not None:
+        return {
+            "policy": v2_policy,
+            "source": "v2-plan-profile",
+            "drift": drift,
+            "working_error": working_error,
+        }
+    if working is not None:
+        return {
+            "policy": working,
+            "source": "gate-policy-json",
+            "drift": None,
+            "working_error": False,
+        }
+    return {
+        "policy": None,
+        "source": None,
+        "drift": None,
+        "working_error": working_error,
+    }
+
+
 def contract_layout_kind(contract: dict[str, Any]) -> str:
     """``split-v1`` when the contract declares a separate runtime root."""
     ownership = contract.get("stateOwnership")

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

@@ -33,14 +33,16 @@ 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",
-    "unitTestFull": "test",
-    "apiTest": "test",
-    "browserTest": "test",
-    "dbCompatibility": "test",
+    "compile": "execute",
+    "unitTest": "execute",
+    "unitTestFull": "execute",
+    "apiTest": "execute",
+    "browserTest": "execute",
+    "dbCompatibility": "execute",
     "package": "package",
 }
 FINAL_SEQUENCE_RECEIPTS_REL = (
@@ -74,10 +76,11 @@ def _write_json(path: Path, value: Any) -> None:
 
 
 def _final_sequence_contract(change_dir: Path) -> dict[str, Any] | None:
-    policy_path = change_dir / "meta" / "gate-policy.json"
-    if not policy_path.is_file():
+    # 权威切换（2026-08）：v2 发布快照优先，classify 工作副本回退。
+    loaded = hpaths.load_change_gate_policy(change_dir)
+    policy = loaded.get("policy")
+    if policy is None:
         return None
-    policy = _read_json(policy_path)
     declared = policy.get("finalSequence")
     if isinstance(declared, dict) and isinstance(declared.get("nodeIds"), list):
         return declared
@@ -700,8 +703,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 +731,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:"
@@ -768,6 +787,13 @@ def select_phase_capsule(
             "message": f"invalid phase selector: {phase}",
             "remediation": "pass the phase name emitted by harness_gate.py begin",
         }
+    # 在途 change 的 capsule 可能按旧名（run/test）写入：归一后按 canonical
+    # 优先、旧名兜底查找。新写一律 canonical。
+    phase = hpaths.resolve_phase_name(phase) or phase
+    phase_names = [phase] + [
+        legacy for legacy, canonical in hpaths.LEGACY_PHASE_ALIASES.items()
+        if canonical == phase
+    ]
     state_dir = hpaths.resolve_state_dir_for_contract(change_dir, project_root)
     capsule_dir = state_dir / "runtime" / "phase-context"
     candidates = (
@@ -775,7 +801,7 @@ def select_phase_capsule(
             path
             for path in capsule_dir.iterdir()
             if path.is_file()
-            and path.name.startswith(f"{phase}-")
+            and any(path.name.startswith(f"{name}-") for name in phase_names)
             and path.suffix == ".json"
         ]
         if capsule_dir.is_dir()
@@ -795,14 +821,20 @@ def select_phase_capsule(
             "message": f"{len(candidates)} capsule(s) exist for phase {phase}",
             "remediation": f"rerun reconcile with --phase {phase} --run-id <run-id>",
         }
-    key = hashlib.sha256(f"{phase}\0{run_id}".encode("utf-8")).hexdigest()[:20]
-    path = capsule_dir / f"{phase}-{key}.json"
-    if not path.is_file():
+    path: Path | None = None
+    for name in phase_names:
+        key = hashlib.sha256(f"{name}\0{run_id}".encode("utf-8")).hexdigest()[:20]
+        candidate = capsule_dir / f"{name}-{key}.json"
+        if candidate.is_file():
+            path = candidate
+            break
+    if path is None:
+        key = hashlib.sha256(f"{phase}\0{run_id}".encode("utf-8")).hexdigest()[:20]
         return {
             "ok": False,
             "code": "PHASE_CAPSULE_NOT_FOUND",
             "message": f"no capsule for phase {phase} and run-id {run_id}",
-            "expectedPath": str(path),
+            "expectedPath": str(capsule_dir / f"{phase}-{key}.json"),
             "remediation": f"begin/resume the phase or verify --phase {phase} --run-id {run_id}",
         }
     try:
@@ -815,7 +847,10 @@ def select_phase_capsule(
             "path": str(path),
             "remediation": f"repair or resume the capsule for --phase {phase} --run-id {run_id}",
         }
-    if capsule.get("phase") != phase or capsule.get("runId") != run_id:
+    if (
+        hpaths.resolve_phase_name(capsule.get("phase")) != phase
+        or capsule.get("runId") != run_id
+    ):
         return {
             "ok": False,
             "code": "PHASE_CAPSULE_IDENTITY_MISMATCH",
@@ -1350,7 +1385,14 @@ def reconcile(
 ) -> dict[str, Any]:
     change_dir = change_dir.resolve()
     project_root = project_root.resolve()
-    policy = _read_json(change_dir / "meta" / "gate-policy.json")
+    # 权威切换（2026-08）：v2 发布快照优先，classify 工作副本回退。
+    loaded = hpaths.load_change_gate_policy(change_dir)
+    policy = loaded.get("policy")
+    if policy is None:
+        raise ValueError(
+            "gate policy missing; run harness_gate.py classify "
+            "or publish via plan finalize"
+        )
     dag = (
         target_required_dag(policy, target_phase)
         if target_phase is not None
@@ -1615,7 +1657,7 @@ def build_parser() -> argparse.ArgumentParser:
     reconcile_parser.add_argument("--json", action="store_true")
     reconcile_parser.add_argument("--output")
     reconcile_parser.add_argument("--close", action="store_true")
-    reconcile_parser.add_argument("--phase", default="run")
+    reconcile_parser.add_argument("--phase", default="execute")
     reconcile_parser.add_argument("--run-id")
     reconcile_parser.set_defaults(func=_cmd_reconcile)