@hunter-harness/workflow-harness 0.2.85 → 0.3.0

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

@@ -1,19 +1,27 @@
 #!/usr/bin/env python3
-"""Validate and publish a complete Harness plan artifact set transactionally."""
+"""已发布计划的只读验收与 v2 清单解包（read-side only）。
+
+legacy staging/finalize/republish 写侧已于 2026-08 移除（roadmap 14；采纳度
+gating 由用户决策解除）。新 change 的发布走 `hunter-harness plan evidence-pack`
++ `plan finalize`（v2）；计划修订走 evidence-pack 重跑（expected_baseline
+= present + 新 attempt）。本模块保留：
+- `verify_plan`：已发布计划的只读验收（legacy receipt 与 v2 事务/journal 两种
+  证据形状），供 `harness_gate.validate_plan_handoff` 与 `verify` 子命令使用；
+- v2 manifest / checkpoints 解包与 plan/scenario 表解析：供 gate 与 ledger
+  在只读侧消费（哈希校验后）。
+
+历史 change 的 legacy 产物必须保持可读；删除的是写入路径，不是读路径。
+"""
 
 from __future__ import annotations
 
 import argparse
-import contextlib
 import hashlib
-import io
 import json
 import os
 import re
-import shutil
 import stat
 import sys
-import tempfile
 from pathlib import Path, PurePosixPath
 from typing import Any
 
@@ -44,7 +52,7 @@ _BUILD_FILE_NAMES = {
 }
 
 # C8: valid ownerPhase values (lifecycle phases that can own tasks).
-VALID_OWNER_PHASES = {"plan", "run", "test", "review", "submit"}
+VALID_OWNER_PHASES = {"plan", "execute", "review", "submit"}
 SLICE_CANDIDATE_TYPES = {
     "independent-release-candidate",
     "child-of-aggregate",
@@ -210,7 +218,7 @@ def parse_test_scenarios(scenarios_path: Path) -> list[dict[str, Any]]:
                         and complete_row
                         and owner_phase_index < len(cells)
                         and cells[owner_phase_index].strip()
-                        else "test"
+                        else "execute"
                     ),
                     "requiredEvidenceKind": PRIORITY_EVIDENCE_KIND.get(
                         priority,
@@ -261,6 +269,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.
 
@@ -334,21 +463,6 @@ def parse_plan_tasks(plan_path: Path) -> list[dict[str, str]]:
     return tasks
 
 
-def _atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    fd, raw_tmp = tempfile.mkstemp(
-        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
-    )
-    tmp = Path(raw_tmp)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
-            json.dump(payload, handle, ensure_ascii=False, indent=2)
-            handle.write("\n")
-            handle.flush()
-            os.fsync(handle.fileno())
-        os.replace(tmp, path)
-    finally:
-        tmp.unlink(missing_ok=True)
 
 
 def _frontmatter(text: str) -> dict[str, str] | None:
@@ -388,362 +502,17 @@ def _is_link_or_reparse(path: Path) -> bool:
     return bool(attributes & _FILE_ATTRIBUTE_REPARSE_POINT)
 
 
-def lint_slice_plan(plan_path: Path) -> dict[str, Any]:
-    """Validate the identity, reuse, and storage contract for a slice plan."""
-    text = Path(plan_path).read_text(encoding="utf-8-sig")
-    frontmatter = _frontmatter(text)
-    if frontmatter is None:
-        return _result_error(
-            "SLICE_PLAN_CONTRACT_INVALID",
-            f"{plan_path.name}: frontmatter is required",
-        )
-    enabled = (
-        str(frontmatter.get("slice-plan") or "").strip().lower()
-        in {"true", "yes", "1"}
-        or "candidate-type" in frontmatter
-    )
-    if not enabled:
-        return {
-            "ok": True,
-            "configured": False,
-            "code": "SLICE_PLAN_NOT_CONFIGURED",
-        }
 
-    issues: list[str] = []
-    candidate_type = str(frontmatter.get("candidate-type") or "").strip()
-    aggregate_parent = str(frontmatter.get("aggregate-parent") or "").strip()
-    evidence_reuse = str(frontmatter.get("evidence-reuse") or "").strip()
-    raw_budget = str(frontmatter.get("artifact-budget-bytes") or "").strip()
-    if candidate_type not in SLICE_CANDIDATE_TYPES:
-        issues.append(
-            "candidate-type must be one of "
-            + ", ".join(sorted(SLICE_CANDIDATE_TYPES))
-        )
-    if not aggregate_parent:
-        issues.append(
-            "aggregate-parent is required (use 'none' for an independent candidate)"
-        )
-    if not evidence_reuse:
-        issues.append(
-            "evidence-reuse is required (use 'none' when no evidence is reused)"
-        )
-    try:
-        artifact_budget = int(raw_budget)
-        if artifact_budget <= 0:
-            raise ValueError
-    except ValueError:
-        artifact_budget = 0
-        issues.append("artifact-budget-bytes must be a positive integer")
-    if issues:
-        return {
-            "ok": False,
-            "code": "SLICE_PLAN_CONTRACT_INVALID",
-            "error": f"{plan_path.name}: " + "; ".join(issues),
-            "issues": issues,
-        }
-    return {
-        "ok": True,
-        "configured": True,
-        "code": "SLICE_PLAN_CONTRACT_OK",
-        "candidateType": candidate_type,
-        "aggregateParent": aggregate_parent,
-        "evidenceReuse": evidence_reuse,
-        "artifactBudgetBytes": artifact_budget,
-    }
 
 
-def _artifact_files(staging: Path) -> list[Path]:
-    files: list[Path] = []
-    for path in staging.rglob("*"):
-        if _is_link_or_reparse(path):
-            raise ValueError(f"PLAN_ARTIFACT_SYMLINK: {path}")
-        if path.is_file():
-            files.append(path)
-    return sorted(files, key=lambda item: item.relative_to(staging).as_posix())
 
 
-def validate_staging(staging: Path, change_name: str) -> dict[str, Any]:
-    staging = staging.resolve()
-    required = {Path(name) for name in _required_artifact_names(change_name)}
-    try:
-        files = _artifact_files(staging)
-    except ValueError as exc:
-        code = str(exc).split(":", 1)[0]
-        return _result_error(code, str(exc))
-    rel_files = {path.relative_to(staging) for path in files}
-    missing = sorted(path.as_posix() for path in required - rel_files)
-    if missing:
-        return _result_error(
-            "PLAN_ARTIFACT_MISSING", "missing required artifacts: " + ", ".join(missing)
-        )
 
-    for path in files:
-        rel = path.relative_to(staging)
-        if rel.parts[0] not in {"spec", "plans", "meta"}:
-            return _result_error(
-                "PLAN_ARTIFACT_PATH_INVALID", f"unexpected artifact root: {rel.as_posix()}"
-            )
-        if path.suffix.lower() == ".json":
-            try:
-                payload = json.loads(path.read_text(encoding="utf-8-sig"))
-            except (OSError, json.JSONDecodeError) as exc:
-                return _result_error(
-                    "PLAN_ARTIFACT_INVALID_JSON", f"{rel.as_posix()}: {exc}"
-                )
-            if not isinstance(payload, dict):
-                return _result_error(
-                    "PLAN_ARTIFACT_INVALID_JSON",
-                    f"{rel.as_posix()}: top-level JSON must be an object",
-                )
-        elif path.suffix.lower() == ".md":
-            try:
-                text = path.read_text(encoding="utf-8-sig")
-            except OSError as exc:
-                return _result_error("PLAN_ARTIFACT_UNREADABLE", str(exc))
-            frontmatter = _frontmatter(text)
-            if frontmatter is None or frontmatter.get("change-name") != change_name:
-                return _result_error(
-                    "PLAN_ARTIFACT_FRONTMATTER_INVALID",
-                    f"{rel.as_posix()}: change-name frontmatter mismatch",
-                )
-            for raw_link in _LINK.findall(text):
-                link = raw_link.strip().split("#", 1)[0]
-                if not link or "://" in link or link.startswith("mailto:"):
-                    continue
-                target = (path.parent / link).resolve()
-                try:
-                    target.relative_to(staging)
-                except ValueError:
-                    return _result_error(
-                        "PLAN_ARTIFACT_REFERENCE_INVALID",
-                        f"{rel.as_posix()}: reference escapes staging: {raw_link}",
-                    )
-                if not target.is_file():
-                    return _result_error(
-                        "PLAN_ARTIFACT_REFERENCE_MISSING",
-                        f"{rel.as_posix()}: missing reference {raw_link}",
-                    )
 
-    # C8: validate ownerPhase values in plan.md task table.
-    plan_path = staging / "plans" / f"{change_name}-plan.md"
-    try:
-        tasks = parse_plan_tasks(plan_path)
-    except PlanParseError as exc:
-        return _result_error(exc.code, str(exc))
-    if not tasks:
-        return _result_error(
-            "PLAN_TASKS_EMPTY",
-            f"{plan_path.relative_to(staging).as_posix()}: no task rows were parsed",
-        )
-    task_ids = [str(task.get("num") or "").strip() for task in tasks]
-    duplicate_task_ids = sorted(
-        {task_id for task_id in task_ids if task_ids.count(task_id) > 1}
-    )
-    if duplicate_task_ids:
-        return _result_error(
-            "PLAN_TASK_ID_DUPLICATE",
-            "duplicate task IDs: " + ", ".join(duplicate_task_ids),
-        )
-    for task in tasks:
-        owner = task.get("ownerPhase")
-        if owner is not None and owner != "" and owner not in VALID_OWNER_PHASES:
-            return _result_error(
-                "PLAN_OWNER_PHASE_INVALID",
-                f"task {task.get('num', '?')}: ownerPhase '{owner}' not in {sorted(VALID_OWNER_PHASES)}",
-            )
-    slice_plan = lint_slice_plan(plan_path)
-    if not slice_plan.get("ok"):
-        return slice_plan
 
-    # C9: parse test-scenarios.md for scenario manifest.
-    scenarios_path = staging / "plans" / f"{change_name}-test-scenarios.md"
-    try:
-        scenarios = parse_test_scenarios(scenarios_path)
-    except PlanParseError as exc:
-        return _result_error(exc.code, str(exc))
-    if not scenarios:
-        return _result_error(
-            "PLAN_SCENARIOS_EMPTY",
-            f"{scenarios_path.relative_to(staging).as_posix()}: no scenario rows were parsed",
-        )
-    scenario_ids = [str(item.get("id") or "").strip() for item in scenarios]
-    duplicate_scenario_ids = sorted(
-        {
-            scenario_id
-            for scenario_id in scenario_ids
-            if scenario_ids.count(scenario_id) > 1
-        }
-    )
-    if duplicate_scenario_ids:
-        return _result_error(
-            "PLAN_SCENARIO_ID_DUPLICATE",
-            "duplicate scenario IDs: " + ", ".join(duplicate_scenario_ids),
-        )
-    for scenario in scenarios:
-        priority = str(scenario.get("priority") or "").upper()
-        if priority not in PRIORITY_EVIDENCE_KIND:
-            return _result_error(
-                "PLAN_SCENARIO_PRIORITY_INVALID",
-                f"scenario {scenario.get('id', '?')}: unsupported priority '{priority}'",
-            )
-        owner = str(scenario.get("ownerPhase") or "")
-        if owner not in VALID_OWNER_PHASES:
-            return _result_error(
-                "PLAN_SCENARIO_OWNER_PHASE_INVALID",
-                f"scenario {scenario.get('id', '?')}: unsupported ownerPhase '{owner}'",
-            )
-        if (
-            scenario.get("requiredEvidenceKind") == "ledger"
-            and scenario.get("executableMappingDeclared")
-        ):
-            missing_mapping = [
-                field
-                for field in ("executableTestId", "testFile", "testTitle")
-                if not str(scenario.get(field) or "").strip()
-            ]
-            if missing_mapping:
-                return _result_error(
-                    "PLAN_SCENARIO_EXECUTABLE_MAPPING_MISSING",
-                    f"scenario {scenario.get('id', '?')}: missing executable mapping fields: "
-                    + ", ".join(missing_mapping),
-                )
 
-    digest = hashlib.sha256()
-    artifact_names: list[str] = []
-    for path in files:
-        rel = path.relative_to(staging).as_posix()
-        artifact_names.append(rel)
-        digest.update(rel.encode("utf-8"))
-        digest.update(b"\0")
-        digest.update(path.read_bytes())
-        digest.update(b"\0")
-    return {
-        "ok": True,
-        "files": artifact_names,
-        "artifactsHash": "sha256:" + digest.hexdigest(),
-        "tasks": tasks,
-        "scenarios": scenarios,
-        "slicePlan": slice_plan,
-    }
 
 
-def validate_product_ownership(change_dir: Path, staging: Path) -> dict[str, Any]:
-    """Ensure Plan declares stable prefix ownership for explicit code/test/build paths."""
-    context_path = change_dir / "meta" / "change-context.json"
-    if not context_path.is_file():
-        return {"ok": True, "code": "PLAN_PRODUCT_PATHS_LEGACY_UNDECLARED"}
-    try:
-        context = json.loads(context_path.read_text(encoding="utf-8-sig"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return _result_error("PLAN_CHANGE_CONTEXT_INVALID", str(exc))
-    ownership = context.get("ownership") if isinstance(context, dict) else None
-    raw_paths = ownership.get("productPaths") if isinstance(ownership, dict) else None
-    product_paths = [
-        str(item).strip().replace("\\", "/").removeprefix("./")
-        for item in raw_paths or []
-        if isinstance(item, str) and item.strip()
-    ]
-    unsupported = sorted(path for path in product_paths if any(char in path for char in "*?[]"))
-    if unsupported:
-        result = _result_error(
-            "PLAN_PRODUCT_PATHS_GLOB_UNSUPPORTED",
-            "productPaths 只接受精确文件或目录前缀，不支持通配：" + ", ".join(unsupported),
-        )
-        result["unsupportedPaths"] = unsupported
-        return result
-
-    planned_paths: set[str] = set()
-    for document in sorted(staging.rglob("*.md")):
-        text = document.read_text(encoding="utf-8-sig")
-        for raw in _BACKTICK.findall(text):
-            candidate = raw.strip().strip("'\"").replace("\\", "/")
-            if not candidate or " " in candidate or "://" in candidate or "<" in candidate:
-                continue
-            candidate = re.sub(r":\d+(?::\d+)?$", "", candidate)
-            candidate = candidate.removeprefix("./").strip("/.,;，；")
-            if not candidate or candidate.startswith("../") or candidate.startswith(".harness/"):
-                continue
-            pure = PurePosixPath(candidate)
-            if pure.name.lower() in _BUILD_FILE_NAMES or pure.suffix.lower() in _CODE_PATH_SUFFIXES:
-                planned_paths.add(candidate)
-
-    def covered(path: str) -> bool:
-        return any(
-            path == owned.rstrip("/")
-            or path.startswith(owned.rstrip("/") + "/")
-            for owned in product_paths
-            if owned.rstrip("/")
-        )
-
-    missing = sorted(path for path in planned_paths if not covered(path))
-    if missing:
-        result = _result_error(
-            "PLAN_PRODUCT_PATHS_INCOMPLETE",
-            "productPaths 未覆盖计划明确引用的产品文件：" + ", ".join(missing),
-        )
-        result["missingPaths"] = missing
-        result["recoveryAction"] = "在 Plan 阶段补充精确文件或目录前缀后重新 finalize。"
-        return result
-    return {
-        "ok": True,
-        "code": "PLAN_PRODUCT_PATHS_COMPLETE",
-        "plannedPaths": sorted(planned_paths),
-        "productPaths": product_paths,
-    }
-
-
-def _terminal_exists(change_dir: Path, run_id: str, attempt: int) -> bool:
-    try:
-        events = harness_events.load_events(harness_events.events_path(change_dir))
-    except (OSError, ValueError):
-        return False
-    return any(
-        event.get("phase") == "plan"
-        and event.get("type") == "phase.end"
-        and event.get("run_id") == run_id
-        and event.get("attempt") == attempt
-        and str(event.get("status") or "").upper() == "OK"
-        for event in events
-    )
-
-
-def _validate_plan_start(
-    change_dir: Path,
-    run_id: str,
-    attempt: int,
-) -> dict[str, Any]:
-    events_path = harness_events.events_path(change_dir)
-    try:
-        events = harness_events.load_events(events_path)
-    except (OSError, ValueError) as exc:
-        return _result_error("EVENTS_PARSE_ERROR", str(exc))
-    matching = [
-        event
-        for event in events
-        if event.get("phase") == "plan"
-        and event.get("type") == "phase.start"
-        and event.get("run_id") == run_id
-        and event.get("attempt") == attempt
-    ]
-    if not matching:
-        return _result_error(
-            "PHASE_START_MISSING",
-            "no matching plan phase.start event found for finalizer runId/attempt; "
-            "append one with the same run id and attempt before finalizing, or use "
-            "the `republish` subcommand which allocates and appends both for you",
-        )
-    if len(matching) > 1:
-        return _result_error(
-            "PHASE_START_DUPLICATE",
-            f"found {len(matching)} matching plan phase.start events for run id "
-            f"{run_id}. `harness_gate.py begin` already appends phase.start; a "
-            "second manual append of the same run id creates this state. Recover "
-            "with a fresh run id and the next attempt number (attempts are global "
-            "per phase, not per run id): append phase.start with both, then "
-            "finalize with the same pair.",
-        )
-    return {"ok": True, "phaseStartCount": 1}
-
 
 def _receipt_artifact_targets(
     change_dir: Path,
@@ -877,7 +646,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))
@@ -1203,515 +974,27 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
     }
 
 
-def _read_design_capabilities(staging: Path, change_name: str) -> list[str]:
-    """Read capabilities from design frontmatter (retro §5.4)."""
-    design_path = staging / "spec" / f"{change_name}-design.md"
-    if not design_path.is_file():
-        return []
-    try:
-        text = design_path.read_text(encoding="utf-8-sig")
-    except OSError:
-        return []
-    frontmatter = _frontmatter(text)
-    if not frontmatter:
-        return []
-    raw = frontmatter.get("capabilities") or ""
-    if not raw:
-        return []
-    # capabilities may be comma-separated or YAML list
-    if raw.startswith("["):
-        try:
-            parsed = json.loads(raw)
-            if isinstance(parsed, list):
-                return [str(c) for c in parsed if isinstance(c, str)]
-        except json.JSONDecodeError:
-            pass
-    return [c.strip() for c in raw.split(",") if c.strip()]
-
-
-def _reclassify_gate_policy(
-    staging: Path,
-    change_name: str,
-) -> dict[str, Any]:
-    """Reclassify gate policy based on approved design capabilities (retro §5.4).
-
-    Reads design frontmatter `capabilities`, invokes harness_gate.py classify
-    to recompute the gate DAG, and updates staging/meta/gate-policy.json.
-    Returns {"ok": bool, "capabilities": [...], "drift": bool}.
-    """
-    capabilities = _read_design_capabilities(staging, change_name)
-    if not capabilities:
-        return {"ok": True, "capabilities": [], "drift": False, "updated": False}
-
-    gate_policy_path = staging / "meta" / "gate-policy.json"
-    try:
-        existing = json.loads(gate_policy_path.read_text(encoding="utf-8-sig"))
-    except (OSError, json.JSONDecodeError):
-        existing = {}
 
-    existing_caps = set(existing.get("capabilities") or [])
-    design_caps = set(capabilities)
-    drift = existing_caps != design_caps
 
-    if drift:
-        # Update gate-policy.json with design capabilities
-        existing["capabilities"] = sorted(design_caps)
-        try:
-            gate_policy_path.write_text(
-                json.dumps(existing, ensure_ascii=False, indent=2) + "\n",
-                encoding="utf-8",
-                newline="\n",
-            )
-        except OSError as exc:
-            return {
-                "ok": False,
-                "error": f"failed to update gate-policy.json: {exc}",
-                "capabilities": capabilities,
-                "drift": True,
-                "updated": False,
-            }
 
-    return {
-        "ok": True,
-        "capabilities": sorted(design_caps),
-        "drift": drift,
-        "updated": drift,
-    }
-
-
-def _append_terminal(change_dir: Path, run_id: str, attempt: int) -> tuple[int, str]:
-    stdout = io.StringIO()
-    stderr = io.StringIO()
-    with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
-        code = harness_events.main(
-            [
-                "append",
-                "--change-dir",
-                str(change_dir),
-                "--phase",
-                "plan",
-                "--type",
-                "phase.end",
-                "--status",
-                "OK",
-                "--reason",
-                "plan artifacts validated and published",
-                "--run-id",
-                run_id,
-                "--attempt",
-                str(attempt),
-                "--json",
-            ]
-        )
-    return code, stderr.getvalue().strip()
-
-
-def _rollback_publish(
-    created: list[Path], replaced: list[tuple[Path, bytes]]
-) -> None:
-    """Undo a failed publish: delete new files, restore overwritten ones."""
-    for target in reversed(created):
-        target.unlink(missing_ok=True)
-    for target, original in reversed(replaced):
-        try:
-            target.write_bytes(original)
-        except OSError:
-            # Best effort: the caller already reports the publish failure.
-            pass
-
-
-def _plan_attempts(change_dir: Path) -> list[int]:
-    """Every attempt number already used by a plan lifecycle event."""
-    try:
-        events = harness_events.load_events(harness_events.events_path(change_dir))
-    except (OSError, ValueError):
-        return []
-    attempts: list[int] = []
-    for event in events:
-        if event.get("phase") != "plan":
-            continue
-        value = event.get("attempt")
-        if isinstance(value, int) and not isinstance(value, bool):
-            attempts.append(value)
-    return attempts
-
-
-def _run_id_in_use(change_dir: Path, run_id: str) -> bool:
-    try:
-        events = harness_events.load_events(harness_events.events_path(change_dir))
-    except (OSError, ValueError):
-        return False
-    return any(event.get("run_id") == run_id for event in events)
-
-
-def _append_plan_start(
-    change_dir: Path, run_id: str, attempt: int, reason: str
-) -> tuple[int, str]:
-    stdout = io.StringIO()
-    stderr = io.StringIO()
-    with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
-        code = harness_events.main(
-            [
-                "append",
-                "--change-dir",
-                str(change_dir),
-                "--phase",
-                "plan",
-                "--type",
-                "phase.start",
-                # phase.start accepts only `note` beyond provenance fields.
-                "--note",
-                reason,
-                "--run-id",
-                run_id,
-                "--attempt",
-                str(attempt),
-                "--json",
-            ]
-        )
-    return code, stderr.getvalue().strip()
 
 
-def finalize_plan(
-    change_dir: Path,
-    staging: Path,
-    *,
-    change_name: str,
-    run_id: str,
-    attempt: int,
-    allow_amend: bool = False,
-    amend_reason: str | None = None,
-) -> dict[str, Any]:
-    change_dir = change_dir.resolve()
-    staging = staging.resolve()
-
-    # C2 (retro §5.4): reclassify gate policy based on approved design capabilities.
-    # This updates staging/meta/gate-policy.json before validation, so the hash
-    # reflects the final gate policy. Drift between design capabilities and
-    # gate-policy capabilities is resolved in favor of the approved design.
-    reclassify = _reclassify_gate_policy(staging, change_name)
-    if not reclassify.get("ok"):
-        return _result_error("CAPABILITY_GATE_DRIFT", reclassify.get("error", "reclassify failed"))
-
-    validation = validate_staging(staging, change_name)
-    if not validation["ok"]:
-        return validation
-    ownership_validation = validate_product_ownership(change_dir, staging)
-    if not ownership_validation["ok"]:
-        return ownership_validation
-    start_validation = _validate_plan_start(change_dir, run_id, attempt)
-    if not start_validation["ok"]:
-        return start_validation
 
-    receipt_path = change_dir / "meta" / "plan-finalization.json"
-    lock_path = change_dir / "meta" / "plan-finalize.lock"
-    receipt: dict[str, Any] | None = None
-    supersedes: dict[str, Any] | None = None
-    if receipt_path.is_file():
-        try:
-            loaded = json.loads(receipt_path.read_text(encoding="utf-8-sig"))
-            receipt = loaded if isinstance(loaded, dict) else None
-        except (OSError, json.JSONDecodeError) as exc:
-            return _result_error("PLAN_FINALIZATION_RECEIPT_INVALID", str(exc))
-        if receipt and receipt.get("artifactsHash") != validation["artifactsHash"]:
-            if not allow_amend:
-                return _result_error(
-                    "PLAN_FINALIZATION_HASH_CONFLICT",
-                    "finalizer was already invoked with a different artifact set; "
-                    "to publish an approved amendment run: harness_plan_finalize.py "
-                    "republish --change-dir <dir> --staging-dir <dir> --change "
-                    f"{change_name} --run-id <fresh-run-id> --reason \"<why>\"",
-                )
-            # Authorized amendment: keep the superseded identity in the new
-            # receipt so the published history stays auditable.
-            supersedes = {
-                "artifactsHash": receipt.get("artifactsHash"),
-                "runId": receipt.get("runId"),
-                "attempt": receipt.get("attempt"),
-            }
-        elif (
-            receipt
-            and receipt.get("status") == "finalized"
-            and _terminal_exists(change_dir, run_id, attempt)
-        ):
-            return {
-                "ok": True,
-                "action": "finalize",
-                "idempotent": True,
-                "artifactsHash": validation["artifactsHash"],
-                "files": validation["files"],
-                "receiptPath": str(receipt_path),
-                "artifactRef": "meta/plan-finalization.json",
-            }
 
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    try:
-        lock_fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
-        os.close(lock_fd)
-    except FileExistsError:
-        return _result_error("PLAN_FINALIZATION_LOCKED", f"lock exists: {lock_path}")
-
-    created: list[Path] = []
-    # Amendment overwrites replace already-published bytes. Keep the originals
-    # so a failed publish restores them instead of deleting the published plan.
-    replaced: list[tuple[Path, bytes]] = []
-    terminal_committed = False
-    try:
-        for rel_text in validation["files"]:
-            source = staging / rel_text
-            target = change_dir / rel_text
-            if (
-                not allow_amend
-                and target.exists()
-                and target.read_bytes() != source.read_bytes()
-            ):
-                return _result_error(
-                    "PLAN_TARGET_CONFLICT",
-                    f"refusing to overwrite {rel_text}; publish an approved "
-                    "amendment with the `republish` subcommand instead",
-                )
 
-        for rel_text in validation["files"]:
-            source = staging / rel_text
-            target = change_dir / rel_text
-            existed = target.exists()
-            if existed:
-                original = target.read_bytes()
-                if not allow_amend or original == source.read_bytes():
-                    continue
-            target.parent.mkdir(parents=True, exist_ok=True)
-            fd, raw_tmp = tempfile.mkstemp(
-                prefix=f".{target.name}.", suffix=".tmp", dir=str(target.parent)
-            )
-            os.close(fd)
-            tmp = Path(raw_tmp)
-            try:
-                shutil.copyfile(source, tmp)
-                os.replace(tmp, target)
-                if existed:
-                    replaced.append((target, original))
-                else:
-                    created.append(target)
-            finally:
-                tmp.unlink(missing_ok=True)
-
-        # C8: write implementation-checkpoints.json with parsed task ownerPhase.
-        tasks = validation.get("tasks") or []
-        if tasks:
-            checkpoints_path = change_dir / "meta" / "implementation-checkpoints.json"
-            checkpoints_payload = {
-                "schemaVersion": 1,
-                "changeName": change_name,
-                "tasks": tasks,
-                "foundationGate": "approved",
-            }
-            if checkpoints_path.is_file():
-                replaced.append((checkpoints_path, checkpoints_path.read_bytes()))
-            else:
-                created.append(checkpoints_path)
-            _atomic_write_json(checkpoints_path, checkpoints_payload)
-
-        # C9: write scenario-manifest.json with parsed scenarios.
-        scenarios = validation.get("scenarios") or []
-        manifest_path = change_dir / "meta" / "scenario-manifest.json"
-        manifest_payload = {
-            "schemaVersion": scenario_manifest_schema_version(scenarios),
-            "changeName": change_name,
-            "scenarios": [
-                {
-                    key: value
-                    for key, value in scenario.items()
-                    if key != "executableMappingDeclared"
-                }
-                for scenario in scenarios
-            ],
-        }
-        if manifest_path.is_file():
-            replaced.append((manifest_path, manifest_path.read_bytes()))
-        else:
-            created.append(manifest_path)
-        _atomic_write_json(manifest_path, manifest_payload)
-
-        pending_receipt = {
-            "schemaVersion": SCHEMA_VERSION,
-            "changeName": change_name,
-            "status": "publishing",
-            "artifactsHash": validation["artifactsHash"],
-            "files": validation["files"],
-            "runId": run_id,
-            "attempt": attempt,
-        }
-        if supersedes is not None:
-            pending_receipt["supersedes"] = supersedes
-            pending_receipt["amendReason"] = amend_reason or ""
-        _atomic_write_json(receipt_path, pending_receipt)
-        terminal_code, terminal_error = _append_terminal(change_dir, run_id, attempt)
-        terminal_committed = _terminal_exists(change_dir, run_id, attempt)
-        if terminal_code != 0 and not terminal_committed:
-            _rollback_publish(created, replaced)
-            receipt_path.unlink(missing_ok=True)
-            return _result_error(
-                "PLAN_TERMINAL_APPEND_FAILED",
-                terminal_error or "phase.end append failed",
-            )
-        pending_receipt["status"] = "finalized"
-        _atomic_write_json(receipt_path, pending_receipt)
-        result: dict[str, Any] = {
-            "ok": True,
-            "action": "republish" if supersedes is not None else "finalize",
-            "idempotent": False,
-            "artifactsHash": validation["artifactsHash"],
-            "files": validation["files"],
-            "receiptPath": str(receipt_path),
-            "artifactRef": "meta/plan-finalization.json",
-            "executionLogPath": str(harness_events.execution_log_path(change_dir)),
-        }
-        if supersedes is not None:
-            result["supersedes"] = supersedes
-            result["scenarioCount"] = len(scenarios)
-            result["taskCount"] = len(tasks)
-        return result
-    except OSError as exc:
-        if terminal_committed or _terminal_exists(change_dir, run_id, attempt):
-            return _result_error(
-                "PLAN_FINALIZATION_RECOVERY_REQUIRED",
-                f"terminal committed; retry finalization to complete receipt: {exc}",
-            )
-        _rollback_publish(created, replaced)
-        receipt_path.unlink(missing_ok=True)
-        return _result_error("PLAN_FINALIZATION_IO_ERROR", str(exc))
-    finally:
-        lock_path.unlink(missing_ok=True)
 
 
-def republish_plan(
-    change_dir: Path,
-    staging: Path,
-    *,
-    change_name: str,
-    run_id: str,
-    reason: str,
-) -> dict[str, Any]:
-    """Publish an approved amendment to an already-finalized plan.
-
-    Amending a published plan (adding a scenario, correcting a task) used to
-    require reverse-engineering a five-step lifecycle dance across three
-    modules — new run id, incremented attempt, stale receipt removal, dangling
-    attempt sealing — and every wrong turn produced a different error code
-    (PLAN_FINALIZATION_HASH_CONFLICT / PHASE_START_MISSING /
-    EVENT_ATTEMPT_CONFLICT / PHASE_ALREADY_CLOSED). Agents that gave up
-    hand-edited meta/scenario-manifest.json, creating exactly the drift the
-    hash guard exists to prevent.
-
-    This performs the whole sequence atomically and keeps the superseded
-    identity in the receipt, so amendment stays auditable rather than silent.
-    """
-    change_dir = change_dir.resolve()
-    staging = staging.resolve()
 
-    if not str(reason).strip():
-        return _result_error(
-            "PLAN_AMEND_REASON_REQUIRED",
-            "--reason is required: an amendment to a published plan must record why",
-        )
 
-    receipt_path = change_dir / "meta" / "plan-finalization.json"
-    if not receipt_path.is_file():
-        return _result_error(
-            "PLAN_NOT_FINALIZED",
-            "no plan-finalization.json to amend; use `finalize` for the first "
-            "publication",
-        )
 
-    if _run_id_in_use(change_dir, run_id):
-        return _result_error(
-            "PLAN_AMEND_RUN_ID_IN_USE",
-            f"run id {run_id} already appears in this change's events; "
-            "an amendment needs a fresh run id",
-        )
 
-    # Nothing to amend is a no-op, not a new attempt: probe the staged hash
-    # before writing any lifecycle event.
-    reclassify = _reclassify_gate_policy(staging, change_name)
-    if not reclassify.get("ok"):
-        return _result_error(
-            "CAPABILITY_GATE_DRIFT", reclassify.get("error", "reclassify failed")
-        )
-    probe = validate_staging(staging, change_name)
-    if not probe["ok"]:
-        return probe
-    try:
-        published = json.loads(receipt_path.read_text(encoding="utf-8-sig"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return _result_error("PLAN_FINALIZATION_RECEIPT_INVALID", str(exc))
-    if (
-        isinstance(published, dict)
-        and published.get("status") == "finalized"
-        and published.get("artifactsHash") == probe["artifactsHash"]
-    ):
-        return {
-            "ok": True,
-            "action": "republish",
-            "idempotent": True,
-            "artifactsHash": probe["artifactsHash"],
-            "files": probe["files"],
-            "receiptPath": str(receipt_path),
-            "artifactRef": "meta/plan-finalization.json",
-            "note": "published plan already matches staging; nothing to amend",
-        }
 
-    attempt = max(_plan_attempts(change_dir), default=0) + 1
-    start_code, start_error = _append_plan_start(
-        change_dir, run_id, attempt, f"plan amendment: {reason}"
-    )
-    if start_code != 0:
-        return _result_error(
-            "PLAN_AMEND_START_FAILED",
-            start_error or "failed to append plan phase.start for the amendment",
-        )
 
-    result = finalize_plan(
-        change_dir,
-        staging,
-        change_name=change_name,
-        run_id=run_id,
-        attempt=attempt,
-        allow_amend=True,
-        amend_reason=reason,
-    )
-    if isinstance(result, dict):
-        result.setdefault("runId", run_id)
-        result.setdefault("attempt", attempt)
-    return result
 
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_plan_finalize.py")
     sub = parser.add_subparsers(dest="command", required=True)
-    republish = sub.add_parser(
-        "republish",
-        help=(
-            "publish an approved amendment to an already-finalized plan "
-            "(allocates a fresh attempt and records what it supersedes)"
-        ),
-    )
-    republish.add_argument("--change-dir", required=True)
-    republish.add_argument("--staging-dir", required=True)
-    republish.add_argument("--change", required=True)
-    republish.add_argument(
-        "--run-id", required=True, help="a fresh run id, unused by this change"
-    )
-    republish.add_argument(
-        "--reason", required=True, help="why the published plan is being amended"
-    )
-    republish.add_argument("--json", action="store_true")
-    finalize = sub.add_parser("finalize")
-    finalize.add_argument("--change-dir", required=True)
-    finalize.add_argument("--staging-dir", required=True)
-    finalize.add_argument("--change", required=True)
-    finalize.add_argument("--run-id", required=True)
-    finalize.add_argument("--attempt", required=True, type=int)
-    finalize.add_argument("--json", action="store_true")
     verify = sub.add_parser("verify")
     verify.add_argument("--change-dir", required=True)
     verify.add_argument("--json", action="store_true")
@@ -1720,24 +1003,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
-    if args.command == "verify":
-        result = verify_plan(Path(args.change_dir))
-    elif args.command == "republish":
-        result = republish_plan(
-            Path(args.change_dir),
-            Path(args.staging_dir),
-            change_name=args.change,
-            run_id=args.run_id,
-            reason=args.reason,
-        )
-    else:
-        result = finalize_plan(
-            Path(args.change_dir),
-            Path(args.staging_dir),
-            change_name=args.change,
-            run_id=args.run_id,
-            attempt=args.attempt,
-        )
+    result = verify_plan(Path(args.change_dir))
     stream = sys.stdout if result["ok"] else sys.stderr
     if args.json:
         stream.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")