@hunter-harness/workflow-harness 0.2.8 → 0.2.10

package/harness/bundles/general/codebuddy/scripts/harness_archive.py

@@ -54,14 +54,23 @@ MANIFEST_COMPARE_EXCLUDE = frozenset(
     }
 )
 
-SCHEMA_VERSION = "2.2"
+SCHEMA_VERSION = "2.3"
 NOT_AVAILABLE = "not_available"
 
+# Compiled once for evidence-text count fallbacks in _ledger_unit_tests / _ledger_api_tests.
+_RE_UNIT_COUNTS = re.compile(
+    r"Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)"
+)
+_RE_API_PASSED = re.compile(r"(\d+)/(\d+)\s*passed", re.I)
+
 # Ensure sibling harness_events is importable.
 if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_events as he  # noqa: E402
+import harness_ledger as hl  # noqa: E402
+import harness_paths as hp  # noqa: E402
+import harness_review as hr  # noqa: E402
 
 
 # ---------------------------------------------------------------------------
@@ -429,7 +438,11 @@ def worktree_requested(change_dir: Path) -> bool:
 # ---------------------------------------------------------------------------
 
 
-def check_status(change_dir: Path) -> dict[str, Any]:
+def check_status(
+    change_dir: Path,
+    *,
+    allow_missing_review: bool = False,
+) -> dict[str, Any]:
     """Read-only archive preconditions. Never mutates."""
     blockers: list[dict[str, str]] = []
     warnings: list[dict[str, str]] = []
@@ -574,6 +587,10 @@ def check_status(change_dir: Path) -> dict[str, Any]:
             }
         )
 
+    gate_policy = load_gate_policy(change_dir)
+    risk_tier = str((gate_policy or {}).get("tier") or "unknown")
+    checks["riskTier"] = risk_tier
+
     if review_reports:
         checks["review_report_status"] = "present"
     elif review_phase_completed(events):
@@ -589,12 +606,23 @@ def check_status(change_dir: Path) -> dict[str, Any]:
         )
     else:
         checks["review_report_status"] = "not-run"
-        warnings.append(
-            {
-                "code": "review-not-run",
-                "message": "no review report; mark reviewSummary as ADVISORY_NOT_RUN",
+        review_msg = {
+            "code": "review-not-run",
+            "message": "no review report; mark reviewSummary as ADVISORY_NOT_RUN",
+        }
+        warnings.append(review_msg)
+        if risk_tier == "full" and not review_ran:
+            tier_issue = {
+                "code": "review-required-on-full-tier",
+                "message": (
+                    "gate-policy tier=full requires review evidence; "
+                    "pass --allow-missing-review to override"
+                ),
             }
-        )
+            if allow_missing_review:
+                warnings.append(tier_issue)
+            else:
+                blockers.append(tier_issue)
 
     archivable = len(blockers) == 0
     return {
@@ -637,33 +665,87 @@ def _ledger_unit_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
     if not ledger:
         return empty
     validations = ledger.get("validations") or ledger.get("verification") or {}
-    unit = validations.get("unitTest") or validations.get("unitTests") or {}
+    unit = (
+        validations.get("unitTestFull")
+        or validations.get("unitTest")
+        or validations.get("unitTests")
+        or {}
+    )
     if not isinstance(unit, dict):
         return empty
     status = str(unit.get("status") or "").upper()
-    evidence = unit.get("evidence") or {}
-    if isinstance(evidence, dict):
-        run = evidence.get(
-            "run",
-            evidence.get("testsRun", unit.get("run", unit.get("testsRun", 0))),
+
+    run = failures = errors = skipped = 0
+    pass_rate: Any = None
+    source = "committed"
+    counted = False
+
+    metrics = unit.get("metrics")
+    if isinstance(metrics, dict) and any(
+        k in metrics for k in ("run", "testsRun", "total", "failures", "errors", "skipped")
+    ):
+        if "total" in metrics:
+            # ledger v3 typed metrics (UT-005/RET-15): total/passed/failed.
+            run = int(metrics.get("total", 0) or 0)
+            failures = int(metrics.get("failed", 0) or 0)
+            errors = int(metrics.get("errors", 0) or 0)
+            skipped = int(metrics.get("skipped", 0) or 0)
+        else:
+            run = int(metrics.get("run", metrics.get("testsRun", 0)) or 0)
+            failures = int(metrics.get("failures", 0) or 0)
+            errors = int(metrics.get("errors", 0) or 0)
+            skipped = int(metrics.get("skipped", 0) or 0)
+        pass_rate = metrics.get("passRate")
+        source = "committed"
+        counted = run > 0 or failures > 0 or errors > 0 or skipped > 0
+
+    evidence = unit.get("evidence")
+    if not counted and isinstance(evidence, dict):
+        run = int(
+            evidence.get(
+                "run",
+                evidence.get("testsRun", unit.get("run", unit.get("testsRun", 0))),
+            )
+            or 0
         )
-        failures = evidence.get("failures", unit.get("failures", 0))
-        errors = evidence.get("errors", unit.get("errors", 0))
-        skipped = evidence.get("skipped", unit.get("skipped", 0))
+        failures = int(evidence.get("failures", unit.get("failures", 0)) or 0)
+        errors = int(evidence.get("errors", unit.get("errors", 0)) or 0)
+        skipped = int(evidence.get("skipped", unit.get("skipped", 0)) or 0)
         pass_rate = evidence.get("passRate") or unit.get("passRate")
-    else:
-        run = unit.get("run", unit.get("testsRun", 0))
-        failures = unit.get("failures", 0)
-        errors = unit.get("errors", 0)
-        skipped = unit.get("skipped", 0)
+        source = "committed"
+        counted = run > 0 or failures > 0 or errors > 0 or skipped > 0
+
+    evidence_text = evidence if isinstance(evidence, str) else ""
+    if not counted and evidence_text:
+        matches = list(_RE_UNIT_COUNTS.finditer(evidence_text))
+        if matches:
+            m = matches[-1]
+            run = int(m.group(1))
+            failures = int(m.group(2))
+            errors = int(m.group(3))
+            skipped = int(m.group(4))
+            source = "evidence-text"
+            counted = True
+
+    if not counted:
+        run = int(unit.get("run", unit.get("testsRun", 0)) or 0)
+        failures = int(unit.get("failures", 0) or 0)
+        errors = int(unit.get("errors", 0) or 0)
+        skipped = int(unit.get("skipped", 0) or 0)
         pass_rate = unit.get("passRate")
+        source = "committed"
 
-    source = "committed"
     if status in {"NOT_RUN", "SKIPPED", "USER_SKIPPED"}:
         source = "not-run"
     elif str(unit.get("reused") or "").lower() in {"true", "1"} or "REUSED" in status:
         source = "committed"
 
+    if pass_rate is None and run > 0:
+        passed = max(run - failures - errors, 0)
+        pass_rate = f"{passed / run:.0%}"
+    elif pass_rate is None:
+        pass_rate = NOT_AVAILABLE
+
     result = {
         "run": int(run or 0),
         "failures": int(failures or 0),
@@ -677,7 +759,11 @@ def _ledger_unit_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
     return result
 
 
-def _ledger_api_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
+def _ledger_api_tests(
+    ledger: dict[str, Any] | None,
+    *,
+    change_dir: Path | None = None,
+) -> dict[str, Any]:
     empty = {
         "status": "NOT_RUN",
         "total": 0,
@@ -685,6 +771,7 @@ def _ledger_api_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
         "failed": 0,
         "blocked": 0,
         "passRate": NOT_AVAILABLE,
+        "source": "not-run",
     }
     if not ledger:
         return empty
@@ -697,12 +784,76 @@ def _ledger_api_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
         status = "OK"
     elif status in {"SKIP", "SKIPPED"}:
         status = "USER_SKIPPED"
-    evidence = api.get("evidence") if isinstance(api.get("evidence"), dict) else {}
-    total = evidence.get("total", api.get("total", 0))
-    passed = evidence.get("passed", api.get("passed", 0))
-    failed = evidence.get("failed", api.get("failed", 0))
-    blocked = evidence.get("blocked", api.get("blocked", 0))
-    pass_rate = evidence.get("passRate") or api.get("passRate")
+
+    total = passed = failed = blocked = 0
+    pass_rate: Any = None
+    source = "committed"
+    counted = False
+
+    metrics = api.get("metrics")
+    if isinstance(metrics, dict) and any(
+        k in metrics for k in ("total", "passed", "failed", "blocked")
+    ):
+        total = int(metrics.get("total", 0) or 0)
+        passed = int(metrics.get("passed", 0) or 0)
+        failed = int(metrics.get("failed", 0) or 0)
+        blocked = int(metrics.get("blocked", 0) or 0)
+        pass_rate = metrics.get("passRate")
+        source = "committed"
+        counted = total > 0 or passed > 0 or failed > 0 or blocked > 0
+
+    evidence_raw = api.get("evidence")
+    if not counted and isinstance(evidence_raw, dict):
+        total = int(evidence_raw.get("total", api.get("total", 0)) or 0)
+        passed = int(evidence_raw.get("passed", api.get("passed", 0)) or 0)
+        failed = int(evidence_raw.get("failed", api.get("failed", 0)) or 0)
+        blocked = int(evidence_raw.get("blocked", api.get("blocked", 0)) or 0)
+        pass_rate = evidence_raw.get("passRate") or api.get("passRate")
+        source = "committed"
+        counted = total > 0 or passed > 0 or failed > 0 or blocked > 0
+
+    evidence_text = evidence_raw if isinstance(evidence_raw, str) else ""
+    if not counted and evidence_text:
+        matches = list(_RE_API_PASSED.finditer(evidence_text))
+        if matches:
+            m = matches[-1]
+            passed = int(m.group(1))
+            total = int(m.group(2))
+            failed = max(total - passed, 0)
+            blocked = 0
+            source = "evidence-text"
+            counted = True
+
+    if not counted and change_dir is not None:
+        results_path = change_dir / "runtime" / "api-test-results.json"
+        if results_path.is_file():
+            try:
+                raw = read_json(results_path)
+            except (OSError, json.JSONDecodeError):
+                raw = None
+            if isinstance(raw, dict) and all(
+                isinstance(raw.get(k), int) for k in ("total", "passed", "failed", "blocked")
+            ):
+                total = int(raw["total"])
+                passed = int(raw["passed"])
+                failed = int(raw["failed"])
+                blocked = int(raw["blocked"])
+                source = "api-test-results"
+                counted = True
+
+    if not counted:
+        total = int(api.get("total", 0) or 0)
+        passed = int(api.get("passed", 0) or 0)
+        failed = int(api.get("failed", 0) or 0)
+        blocked = int(api.get("blocked", 0) or 0)
+        pass_rate = api.get("passRate")
+        source = "committed"
+
+    if pass_rate is None and total > 0:
+        pass_rate = f"{passed / total:.0%}"
+    elif pass_rate is None:
+        pass_rate = NOT_AVAILABLE
+
     return {
         "status": status,
         "total": int(total or 0),
@@ -710,9 +861,57 @@ def _ledger_api_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
         "failed": int(failed or 0),
         "blocked": int(blocked or 0),
         "passRate": pass_rate if pass_rate is not None else NOT_AVAILABLE,
+        "source": source,
     }
 
 
+def _risks_from_test_results(change_dir: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """PARTIAL/OPEN/UNKNOWN/DEFERRED scenarios -> (knownRisks, manualActions).
+
+    Scenario IDs are preserved so risks stay traceable to the test report
+    (UT-013/RET-25); PARTIAL is a fact, not a pass.
+    """
+    risk_statuses = {"PARTIAL", "OPEN", "UNKNOWN", "DEFERRED", "BLOCKED"}
+    results_path = change_dir / "runtime" / "api-test-results.json"
+    if not results_path.is_file():
+        return [], []
+    try:
+        raw = read_json(results_path)
+    except (OSError, json.JSONDecodeError):
+        return [], []
+    scenarios = raw.get("scenarios") if isinstance(raw, dict) else None
+    if not isinstance(scenarios, list):
+        return [], []
+    risks: list[dict[str, Any]] = []
+    actions: list[dict[str, Any]] = []
+    for item in scenarios:
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status") or "").upper()
+        if status not in risk_statuses:
+            continue
+        scenario_id = str(item.get("id") or item.get("scenario") or "").strip()
+        note = str(item.get("note") or item.get("message") or "").strip()
+        risks.append(
+            {
+                "phase": "test",
+                "severity": "medium",
+                "scenarioId": scenario_id,
+                "status": status,
+                "message": f"{scenario_id}: {status}" + (f" — {note}" if note else ""),
+            }
+        )
+        actions.append(
+            {
+                "stage": "test",
+                "status": status,
+                "scenarioId": scenario_id,
+                "action": "补齐该场景的完整验证或显式接受风险",
+            }
+        )
+    return risks, actions
+
+
 def _ledger_db_compat(ledger: dict[str, Any] | None) -> str:
     if not ledger:
         return "NOT_RUN"
@@ -728,6 +927,58 @@ def _ledger_db_compat(ledger: dict[str, Any] | None) -> str:
     return "NOT_RUN"
 
 
+def _typed_test_metrics(entry: dict[str, Any], *, total_key: str) -> dict[str, Any]:
+    """Project a ledger v3 typed metrics entry to the canonical view."""
+    metrics = entry.get("metrics") if isinstance(entry.get("metrics"), dict) else {}
+    total = int(metrics.get(total_key, 0) or 0)
+    passed = int(metrics.get("passed", 0) or 0)
+    failed = int(metrics.get("failed", 0) or 0)
+    status = str(entry.get("status") or "").upper() or "NOT_RUN"
+    out: dict[str, Any] = {
+        "status": status,
+        "total": total,
+        "passed": passed,
+        "failed": failed,
+        "passRate": f"{passed / total:.0%}" if total > 0 else NOT_AVAILABLE,
+        "source": "committed" if total > 0 else "not-run",
+    }
+    if "blocked" in metrics:
+        out["blocked"] = int(metrics.get("blocked", 0) or 0)
+    if "skipped" in metrics:
+        out["skipped"] = int(metrics.get("skipped", 0) or 0)
+    applicability = entry.get("applicability")
+    if isinstance(applicability, dict):
+        out["applicability"] = applicability
+    return out
+
+
+def build_verification_projection(
+    ledger: dict[str, Any] | None,
+    *,
+    change_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Canonical verification view shared by collector and validators (RET-16).
+
+    apiContract and browserE2E are distinct typed projections; the legacy
+    apiTests mapping is retained for schema compatibility.
+    """
+    validations = (ledger or {}).get("validations") or {}
+    projection: dict[str, Any] = {
+        "unitTests": _ledger_unit_tests(ledger),
+        "apiTests": _ledger_api_tests(ledger, change_dir=change_dir),
+        "dbCompatibility": _ledger_db_compat(ledger),
+    }
+    api_contract = validations.get("apiContract")
+    if isinstance(api_contract, dict):
+        projection["apiContract"] = _typed_test_metrics(
+            api_contract, total_key="scenariosTotal"
+        )
+    browser_e2e = validations.get("browserE2E")
+    if isinstance(browser_e2e, dict):
+        projection["browserE2E"] = _typed_test_metrics(browser_e2e, total_key="total")
+    return projection
+
+
 def _parse_durations_from_log(log_text: str) -> dict[str, Any]:
     """Best-effort parse of harness-* sections from execution-log."""
     stages: list[dict[str, Any]] = []
@@ -902,7 +1153,15 @@ def _artifacts_from_events(events: list[dict[str, Any]]) -> list[dict[str, Any]]
     return out
 
 
-def _durations_from_event_phases(event_summary: dict[str, Any]) -> dict[str, Any]:
+def _durations_from_event_phases(
+    event_summary: dict[str, Any],
+    events: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    # Canonical per-phase timing (UT-008/RET-20): one reducer feeds every view.
+    canonical: dict[str, dict[str, Any]] = {}
+    if events:
+        for phase_name, phase_events in he.group_events_by_phase(events):
+            canonical[phase_name] = he.canonical_phase_timing(phase_events)
     stages: list[dict[str, Any]] = []
     total_ms = 0
     for name, info in (event_summary.get("phases") or {}).items():
@@ -916,7 +1175,7 @@ def _durations_from_event_phases(event_summary: dict[str, Any]) -> dict[str, Any
             result = "OK"
         elif result in {"FAILED", "ERROR"}:
             result = "FAIL"
-        stages.append({
+        stage: dict[str, Any] = {
             "stage": str(name),
             "skill": f"harness-{name}",
             "startedAt": info.get("started_at") or NOT_AVAILABLE,
@@ -924,7 +1183,13 @@ def _durations_from_event_phases(event_summary: dict[str, Any]) -> dict[str, Any
             "minutes": minutes,
             "result": result,
             "attempts": attempts,
-        })
+        }
+        timing = canonical.get(name)
+        if timing:
+            stage["activeExecutionMs"] = timing.get("activeExecutionMs")
+            stage["wallClockSpanMs"] = timing.get("wallClockSpanMs")
+            stage["lateEventCount"] = timing.get("lateEventCount")
+        stages.append(stage)
     total_min = round(total_ms / 60000, 2)
     return {
         "totalLabel": f"约 {int(round(total_min))} 分",
@@ -977,7 +1242,7 @@ def _stage_status_from_sources(
         elif phase in status and sev in {"warn", "warning"} and status[phase] == "OK":
             status[phase] = "WARN"
 
-    api = _ledger_api_tests(ledger)
+    api = _ledger_api_tests(ledger, change_dir=change_dir)
     db = _ledger_db_compat(ledger)
     api_status = str(api.get("status") or "").upper()
     if api_status in {"FAIL", "FAILED", "ERROR"} or int(api.get("failed") or 0) > 0:
@@ -1002,28 +1267,178 @@ def _stage_status_from_sources(
 def _compute_final_status(
     stage_status: dict[str, str],
     verification: dict[str, Any],
-) -> str:
+) -> tuple[str, list[str]]:
     api = verification.get("apiTests") or {}
     db = str(verification.get("dbCompatibility") or "")
     api_status = str(api.get("status") or "")
-    for v in stage_status.values():
+    reasons: list[str] = []
+    for phase, v in stage_status.items():
         if v == "FAIL":
-            return "FAIL"
+            return "FAIL", [f"stage {phase}=FAIL"]
     unit = verification.get("unitTests") or {}
-    if int(unit.get("failures") or 0) > 0 or int(unit.get("errors") or 0) > 0:
-        return "FAIL"
+    if int(unit.get("failures") or 0) > 0:
+        return "FAIL", [f"unitTests.failures={unit.get('failures')}"]
+    if int(unit.get("errors") or 0) > 0:
+        return "FAIL", [f"unitTests.errors={unit.get('errors')}"]
     if int(api.get("failed") or 0) > 0:
-        return "FAIL"
+        return "FAIL", [f"apiTests.failed={api.get('failed')}"]
     conditional = {
         "USER_SKIPPED", "BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA",
         "NOT_RUN", "PARTIAL",
     }
-    if api_status in conditional or db in conditional:
-        return "CONDITIONAL_OK"
-    for v in stage_status.values():
-        if v in {"WARN", *conditional}:
-            return "WARN" if v == "WARN" else "CONDITIONAL_OK"
-    return "OK"
+    if api_status in conditional:
+        reasons.append(f"apiTests.status={api_status}")
+    if db in conditional:
+        reasons.append(f"dbCompatibility={db}")
+    if reasons:
+        return "CONDITIONAL_OK", reasons
+    for phase, v in stage_status.items():
+        if v == "WARN":
+            return "WARN", [f"stage {phase}=WARN"]
+        if v in conditional:
+            return "CONDITIONAL_OK", [f"stage {phase}={v}"]
+    return "OK", []
+
+
+def load_gate_policy(change_dir: Path) -> dict[str, Any] | None:
+    path = change_dir / "meta" / "gate-policy.json"
+    if not path.is_file():
+        return None
+    try:
+        data = read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict) or data.get("schemaVersion") != 1:
+        return None
+    return data
+
+
+_RISK_SEVERITIES = frozenset({"warning", "error", "critical"})
+
+
+def _cleanup_transients(work_dir: Path) -> dict[str, Any]:
+    """Delete lock/pid/launcher/credential files; truncate oversized logs."""
+    deleted: list[str] = []
+    truncated: list[dict[str, Any]] = []
+
+    def _rel(path: Path) -> str:
+        try:
+            return path.relative_to(work_dir).as_posix()
+        except ValueError:
+            return str(path)
+
+    lock = work_dir / "events.ndjson.lock"
+    if lock.is_file():
+        try:
+            lock.unlink()
+            deleted.append(_rel(lock))
+        except OSError:
+            pass
+
+    runtime = work_dir / "runtime"
+    if runtime.is_dir():
+        for path in sorted(runtime.iterdir()):
+            if not path.is_file():
+                continue
+            name = path.name
+            drop = False
+            if name.endswith(".pid"):
+                drop = True
+            elif name in {
+                "_harness_service_launcher.py",
+                "_harness_service.command.txt",
+            }:
+                drop = True
+            elif re.search(r"credential|token|secret", name, re.I):
+                drop = True
+            if drop:
+                try:
+                    path.unlink()
+                    deleted.append(_rel(path))
+                except OSError:
+                    pass
+
+    logs_root = work_dir / "logs"
+    if logs_root.is_dir():
+        for path in sorted(logs_root.rglob("*.log")):
+            if not path.is_file():
+                continue
+            try:
+                size = path.stat().st_size
+            except OSError:
+                continue
+            if size <= 65536:
+                continue
+            try:
+                with path.open("rb") as handle:
+                    handle.seek(-65536, 2)
+                    tail = handle.read()
+                header = (
+                    f"# [truncated by harness-archive finalize: original {size} bytes]\n"
+                ).encode("utf-8")
+                path.write_bytes(header + tail)
+                truncated.append({"path": _rel(path), "originalBytes": size})
+            except OSError:
+                pass
+
+    return {"deleted": deleted, "truncated": truncated}
+
+
+def write_archive_meta(work_dir: Path, summary: dict[str, Any]) -> Path:
+    """Generate meta/archive-meta.md from summary-data (single ownership)."""
+    archive_id = work_dir.name
+    change_name = str(summary.get("changeName") or work_dir.name)
+    archived_at = dt.datetime.now().strftime("%Y-%m-%d %H:%M")
+    final_status = str(summary.get("finalStatus") or "UNKNOWN")
+    lines = [
+        "---",
+        f"archive-id: {archive_id}",
+        f"change-name: {change_name}",
+        f"archived-at: {archived_at}",
+        f"final-commit: {summary.get('finalCommit') or ''}",
+        f"base-commit: {summary.get('baseCommit') or ''}",
+        f"final-status: {final_status}",
+        "source: harness-archive",
+        "---",
+        f"# 归档元数据 — {change_name}",
+        "",
+        "## 阶段状态",
+        "",
+        "| 阶段 | 状态 |",
+        "|---|---|",
+    ]
+    for stage, status in (summary.get("stageStatus") or {}).items():
+        lines.append(f"| {stage} | {status} |")
+    lines.extend(["", "## 变更文件", "", "| 路径 | + | - |", "|---|---|---|"])
+    changed = summary.get("changedFiles") or []
+    if changed:
+        for item in changed:
+            lines.append(
+                f"| {item.get('path') or ''} | "
+                f"{item.get('insertions', 0)} | {item.get('deletions', 0)} |"
+            )
+    else:
+        lines.append("| （无） |  |  |")
+    lines.extend(["", "## 已知风险", ""])
+    risks = summary.get("knownRisks") or []
+    if risks:
+        for risk in risks:
+            if isinstance(risk, dict):
+                lines.append(
+                    f"- [{risk.get('severity') or 'unknown'}] "
+                    f"{risk.get('message') or risk}"
+                )
+            else:
+                lines.append(f"- {risk}")
+    else:
+        lines.append("无")
+    lines.append("")
+    out = work_dir / "meta" / "archive-meta.md"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("\n".join(lines), encoding="utf-8", newline="\n")
+    return out
+
+
 
 
 def _changed_files_from_git(
@@ -1091,6 +1506,37 @@ def _review_summary(
         "yellowDeferred": 0,
         "summary": "",
     }
+    sidecar = hr.findings_path(change_dir)
+    if sidecar.is_file():
+        status = hr.status(change_dir)
+        items = status.get("items") or []
+        red_items = [item for item in items if item.get("severity") == "RED"]
+        yellow_items = [item for item in items if item.get("severity") == "YELLOW"]
+        base.update(
+            {
+                "status": "ADVISORY",
+                "red": len(red_items),
+                "yellow": len(yellow_items),
+                "redFixed": sum(
+                    1 for item in red_items if item.get("disposition") == "FIXED"
+                ),
+                "redConfirmed": sum(
+                    1
+                    for item in red_items
+                    if item.get("disposition") in {"OPEN", "ACCEPTED_RISK", "DEFERRED"}
+                ),
+                "yellowFixed": sum(
+                    1 for item in yellow_items if item.get("disposition") == "FIXED"
+                ),
+                "yellowDeferred": sum(
+                    1
+                    for item in yellow_items
+                    if item.get("disposition") in {"DEFERRED", "ACCEPTED_RISK"}
+                ),
+                "summary": f"structured review run {status.get('runId') or 'unknown'}",
+            }
+        )
+        return base
     if existing and isinstance(existing.get("reviewSummary"), dict):
         merged = dict(base)
         merged.update(existing["reviewSummary"])
@@ -1148,6 +1594,24 @@ def _business_goal_from_sources(change_dir: Path, events: list[dict[str, Any]])
         scope = re.search(r"(?im)^\s*>?\s*(?:变更范围|目标)\s*[:：]\s*(.+)$", body)
         if scope:
             return scope.group(1).strip()
+        # UT-015/RET-27: structured "## 目标" section body wins over the first
+        # task-table row — the task row is an activity, not the objective.
+        section = re.search(
+            r"(?im)^#{1,4}\s*(?:\d+[\.、]\s*)?(?:目标|业务目标|需求背景)\s*$",
+            body,
+        )
+        if section:
+            lines: list[str] = []
+            for line in body[section.end():].splitlines():
+                if re.match(r"^\s*#{1,4}\s", line):
+                    break
+                clean = line.strip()
+                if clean and not clean.startswith(("|", ">", "---")):
+                    lines.append(clean)
+                if lines:
+                    break
+            if lines:
+                return lines[0]
         first_task = re.search(r"(?m)^\s*\|\s*1\s*\|\s*([^|]+?)\s*\|", body)
         if first_task:
             return first_task.group(1).strip()
@@ -1297,9 +1761,10 @@ def collect_summary_data(
 
     # verification
     if not for_replay or not isinstance(data.get("verification"), dict):
-        unit = _ledger_unit_tests(ledger)
-        api = _ledger_api_tests(ledger)
-        db = _ledger_db_compat(ledger)
+        projection = build_verification_projection(ledger, change_dir=change_dir)
+        unit = projection["unitTests"]
+        api = projection["apiTests"]
+        db = projection["dbCompatibility"]
         if not find_test_reports(change_dir) and unit.get("run", 0) == 0:
             if "status" not in unit:
                 unit["status"] = "NOT_RUN"
@@ -1314,6 +1779,9 @@ def collect_summary_data(
             "dbCompatibility": db,
             "coverageDisplay": coverage,
         }
+        for typed_key in ("apiContract", "browserE2E"):
+            if typed_key in projection:
+                data["verification"][typed_key] = projection[typed_key]
     else:
         # Ensure nested keys exist for old schema 2.1
         ver = data.setdefault("verification", {})
@@ -1326,14 +1794,21 @@ def collect_summary_data(
     if not for_replay or not isinstance(data.get("stageStatus"), dict):
         data["stageStatus"] = _stage_status_from_sources(events, ledger, change_dir)
     if not for_replay or not data.get("finalStatus") or str(data.get("finalStatus")).startswith("OK |"):
-        data["finalStatus"] = _compute_final_status(
+        final_status, final_reasons = _compute_final_status(
             data.get("stageStatus") or {},
             data.get("verification") or {},
         )
+        data["finalStatus"] = final_status
+        data["finalStatusReasons"] = list(final_reasons)
+    else:
+        data.setdefault("finalStatusReasons", [])
+
+    gate_policy = load_gate_policy(change_dir)
+    data["riskTier"] = str((gate_policy or {}).get("tier") or "unknown")
 
     # durations / skillCalls
     if events:
-        data["durations"] = _durations_from_event_phases(event_summary)
+        data["durations"] = _durations_from_event_phases(event_summary, events)
         data["skillCalls"] = _skill_calls_from_stages(data["durations"].get("stages") or [])
     elif log_text and (not for_replay or not data.get("durations")):
         data["durations"] = _parse_durations_from_log(log_text)
@@ -1352,6 +1827,32 @@ def collect_summary_data(
         head = data.get("finalCommit")
         if base and head and base != NOT_AVAILABLE and head != NOT_AVAILABLE:
             diff_stat, changed = _changed_files_from_git(project, str(base), str(head))
+            ownership_projection: dict[str, Any] | None = None
+            try:
+                hp.load_change_contract(change_dir)
+                ownership_projection = hl.compute_ownership_diff(
+                    project,
+                    base=str(base),
+                    head=str(head),
+                    change_dir=change_dir,
+                )
+            except (OSError, ValueError, RuntimeError):
+                ownership_projection = None
+            if ownership_projection is not None:
+                allowed = set(ownership_projection.get("files") or [])
+                changed = [item for item in changed if item.get("path") in allowed]
+                diff_stat = {
+                    **diff_stat,
+                    "filesChanged": len(changed),
+                    "insertions": sum(int(item.get("insertions") or 0) for item in changed),
+                    "deletions": sum(int(item.get("deletions") or 0) for item in changed),
+                }
+                data["ownershipDiff"] = ownership_projection
+                if write:
+                    write_json(
+                        change_dir / "evidence" / "ownership-diff.json",
+                        ownership_projection,
+                    )
             if changed:
                 data["diffStat"] = diff_stat
                 data["changedFiles"] = changed
@@ -1378,6 +1879,17 @@ def collect_summary_data(
             }
             data["changedFiles"] = []
 
+    data.setdefault(
+        "ownershipDiff",
+        {
+            "files": [item.get("path") for item in data.get("changedFiles") or []],
+            "staticEvidenceFiles": [],
+            "foreignPaths": [],
+            "excludedRuntimeCount": 0,
+            "ownedFileCount": len(data.get("changedFiles") or []),
+        },
+    )
+
     # artifacts (build products stay empty unless already known; reportPipeline has event artifacts)
     if not isinstance(data.get("artifacts"), list):
         data["artifacts"] = []
@@ -1397,25 +1909,35 @@ def collect_summary_data(
 
     # Derive risks/actions from evidence. These fields are facts, not model prose.
     if not for_replay:
-        data["maintenanceNotes"] = [
+        maintenance_notes: list[str] = [
             str(event.get("note") or event.get("message") or "")
             for event in events
             if event.get("type") == "decision" and (event.get("note") or event.get("message"))
         ]
-        data["knownRisks"] = [
-            {
-                "phase": event.get("phase"),
-                "severity": event.get("severity") or "unknown",
-                "message": event.get("message") or event.get("note") or event.get("code") or "",
-            }
-            for event in events
-            if event.get("type") == "issue"
-            and not (
-                event.get("phase") == "archive"
-                and event.get("code") == "missing-command"
-            )
-        ]
-        data["manualActions"] = []
+        known_risks: list[dict[str, Any]] = []
+        for event in events:
+            if event.get("type") != "issue":
+                continue
+            if event.get("phase") == "archive" and event.get("code") == "missing-command":
+                continue
+            sev = str(event.get("severity") or "").strip().lower()
+            message = event.get("message") or event.get("note") or event.get("code") or ""
+            if sev in _RISK_SEVERITIES:
+                known_risks.append(
+                    {
+                        "phase": event.get("phase"),
+                        "severity": sev,
+                        "message": message,
+                    }
+                )
+            else:
+                note = str(message).strip()
+                if note:
+                    maintenance_notes.append(note)
+        data["maintenanceNotes"] = maintenance_notes
+        scenario_risks, scenario_actions = _risks_from_test_results(change_dir)
+        data["knownRisks"] = known_risks + scenario_risks
+        data["manualActions"] = scenario_actions
         for name, value in (data.get("stageStatus") or {}).items():
             if value in {"BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA", "NOT_RUN", "USER_SKIPPED"}:
                 data["manualActions"].append({
@@ -1427,6 +1949,8 @@ def collect_summary_data(
         data.setdefault("maintenanceNotes", [])
         data.setdefault("knownRisks", [])
         data.setdefault("manualActions", [])
+        data.setdefault("finalStatusReasons", [])
+        data.setdefault("riskTier", "unknown")
 
     # archiveManifest
     am = {
@@ -1521,7 +2045,13 @@ def render_fallback_html(summary: dict[str, Any]) -> str:
         f'<h2 id="changeName">{esc(summary.get("changeName"))}</h2>',
         f'<p><strong>finalStatus</strong>: '
         f'<span id="finalStatus">{esc(summary.get("finalStatus"))}</span></p>',
+        f'<div id="finalStatusReasons"><strong>finalStatusReasons</strong><ul>',
     ]
+    for reason in summary.get("finalStatusReasons") or []:
+        parts.append(f"<li>{esc(reason)}</li>")
+    parts.append("</ul></div>")
+    if summary.get("riskTier"):
+        parts.append(f"<p><strong>riskTier</strong>: {esc(summary.get('riskTier'))}</p>")
 
     pipeline = summary.get("reportPipeline") or {}
     cmds = pipeline.get("commands") or []
@@ -1681,6 +2211,288 @@ def render_final_summary(
 # ---------------------------------------------------------------------------
 
 
+def _manifest_self_stats(
+    work_dir: Path,
+    manifest: dict[str, Any],
+    manifest_path: Path,
+) -> dict[str, Any]:
+    """UT-011/RET-23: physical files vs manifest entries (self-exclusion)."""
+    physical = sum(1 for path in work_dir.rglob("*") if path.is_file())
+    entries = int(manifest.get("fileCount") or len(manifest.get("files") or []))
+    rel_manifest = manifest_path.resolve().relative_to(work_dir.resolve()).as_posix()
+    in_entries = any(
+        str(item.get("path") or "").replace("\\", "/") == rel_manifest
+        for item in manifest.get("files") or []
+        if isinstance(item, dict)
+    )
+    coverage = round(entries / physical * 100, 2) if physical else 100.0
+    return {
+        "physicalFileCount": physical,
+        "entryCount": entries,
+        "selfExcluded": not in_entries,
+        "coveragePercent": coverage,
+    }
+
+
+def _append_finalize_failure_issue(
+    original_change_dir: Path,
+    code: str,
+    message: str,
+) -> None:
+    """Record a finalize failure on the restored original as an issue event.
+
+    Never a second phase.end: the frozen cutoff already closed the archive
+    phase exactly once (RET-19/RET-21).
+    """
+    if not original_change_dir.is_dir():
+        return
+    try:
+        append_event(
+            original_change_dir,
+            phase="archive",
+            type_="issue",
+            code=code,
+            severity="error",
+            message=message,
+        )
+    except OSError:
+        pass
+
+
+def _freeze_evidence_cutoff(work_dir: Path) -> dict[str, Any]:
+    """Freeze the events cutoff: fsync events, write evidence-cutoff.json.
+
+    After this point no event may be appended to the archived events file;
+    the cutoff hash lets any later reader prove that (INT-006/RET-19).
+    """
+    events_file = he.events_path(work_dir)
+    events = he.load_events(events_file) if events_file.is_file() else []
+    if events_file.is_file():
+        # Windows fsync requires a writable handle; O_RDONLY raises EBADF.
+        fd = os.open(str(events_file), os.O_RDWR | os.O_BINARY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        raw = events_file.read_bytes()
+    else:
+        raw = b""
+    cutoff = {
+        "eventCount": len(events),
+        "sha256": "sha256:" + hashlib.sha256(raw).hexdigest(),
+        "frozenAt": now_iso(),
+        "path": "events.ndjson",
+    }
+    write_json(work_dir / "evidence" / "evidence-cutoff.json", cutoff)
+    return cutoff
+
+
+def validate_artifact_immutability(entries: list[dict[str, Any]]) -> dict[str, Any]:
+    """Same artifact path with two different hashes -> conflict (UT-003/RET-07)."""
+    issues: list[dict[str, str]] = []
+    seen: dict[str, str] = {}
+    for item in entries:
+        if not isinstance(item, dict):
+            continue
+        rel = str(item.get("path") or "").strip()
+        digest = str(item.get("sha256") or "").strip()
+        if not rel or not digest:
+            continue
+        prior = seen.get(rel)
+        if prior is not None and prior != digest:
+            issues.append(
+                {
+                    "code": "artifact-hash-conflict",
+                    "severity": "error",
+                    "message": f"immutable artifact conflict at {rel}: {prior[:12]}… != {digest[:12]}…",
+                }
+            )
+        else:
+            seen[rel] = digest
+    errors = [i for i in issues if i.get("severity") == "error"]
+    return {
+        "ok": len(errors) == 0,
+        "issues": issues,
+        "error_count": len(errors),
+        "warning_count": len(issues) - len(errors),
+    }
+
+
+def validate_source_consistency(
+    change_dir: Path,
+    summary: dict[str, Any],
+) -> dict[str, Any]:
+    """Layer 1: summary facts must equal the frozen sources (UT-014/RET-26).
+
+    Checks event count against the cutoff file, verification counts against
+    ledger typed metrics, and review counts against sidecars when present.
+    """
+    issues: list[dict[str, str]] = []
+
+    # 1. event count/hash vs frozen cutoff (fallback: live events file).
+    events_file = he.events_path(change_dir)
+    actual_count = None
+    cutoff_path = change_dir / "evidence" / "evidence-cutoff.json"
+    cutoff: dict[str, Any] | None = None
+    if cutoff_path.is_file():
+        try:
+            cutoff = read_json(cutoff_path)
+            actual_count = cutoff.get("eventCount")
+        except (OSError, json.JSONDecodeError):
+            actual_count = None
+    if actual_count is None and events_file.is_file():
+        actual_count = len(he.load_events(events_file))
+    summary_count = (summary.get("reportPipeline") or {}).get("event_count")
+    if actual_count is not None and summary_count is not None:
+        if int(summary_count) != int(actual_count):
+            issues.append(
+                {
+                    "code": "event-count-mismatch",
+                    "severity": "error",
+                    "message": (
+                        f"summary event_count={summary_count} but cutoff has "
+                        f"{actual_count} events"
+                    ),
+                }
+            )
+
+    if cutoff is not None and events_file.is_file():
+        actual_hash = "sha256:" + hashlib.sha256(events_file.read_bytes()).hexdigest()
+        if cutoff.get("sha256") != actual_hash:
+            issues.append(
+                {
+                    "code": "cutoff-hash-mismatch",
+                    "severity": "error",
+                    "message": "evidence cutoff hash does not match events.ndjson",
+                }
+            )
+
+    # 2. verification vs ledger typed metrics.
+    ledger = load_ledger(change_dir)
+    if ledger:
+        projection = build_verification_projection(ledger, change_dir=change_dir)
+        ver = summary.get("verification") or {}
+        unit_src = projection.get("unitTests") or {}
+        unit_sum = ver.get("unitTests") or {}
+        if unit_src.get("run"):
+            if int(unit_sum.get("run") or 0) != int(unit_src["run"]):
+                issues.append(
+                    {
+                        "code": "verification-mismatch",
+                        "severity": "error",
+                        "message": (
+                            f"unitTests: summary run={unit_sum.get('run')} but "
+                            f"ledger projection run={unit_src['run']}"
+                        ),
+                    }
+                )
+        for typed_key in ("apiContract", "browserE2E"):
+            src = projection.get(typed_key)
+            if not isinstance(src, dict) or not src.get("total"):
+                continue
+            rendered = ver.get(typed_key) or {}
+            if int(rendered.get("total") or 0) != int(src["total"]):
+                issues.append(
+                    {
+                        "code": "verification-mismatch",
+                        "severity": "error",
+                        "message": (
+                            f"{typed_key}: summary total={rendered.get('total')} "
+                            f"but ledger projection total={src['total']}"
+                        ),
+                    }
+                )
+
+    # 3. Rebuild canonical projections from frozen sources and compare the
+    # fields that must never come from prose or an existing summary.
+    expected = collect_summary_data(change_dir, write=False, for_replay=False)
+    projection_fields = {
+        "reviewSummary": "review-mismatch",
+        "knownRisks": "risk-mismatch",
+        "manualActions": "manual-actions-mismatch",
+        "durations": "phase-timing-mismatch",
+        "changedFiles": "ownership-diff-mismatch",
+        "ownershipDiff": "ownership-diff-mismatch",
+        "artifacts": "artifact-mismatch",
+    }
+    for field, code in projection_fields.items():
+        if summary.get(field) != expected.get(field):
+            issues.append(
+                {
+                    "code": code,
+                    "severity": "error",
+                    "message": f"summary {field} does not match frozen source projection",
+                }
+            )
+
+    # 4. Manifest structure/checksums and summary semantics.
+    before_path = change_dir / "evidence" / "archive-manifest-before.json"
+    if before_path.is_file():
+        try:
+            manifest = read_json(before_path)
+            entries = manifest.get("files") if isinstance(manifest, dict) else None
+            valid = isinstance(entries, list) and manifest.get("fileCount") == len(entries)
+            seen: set[str] = set()
+            if valid:
+                for entry in entries:
+                    rel = str(entry.get("path") or "") if isinstance(entry, dict) else ""
+                    digest = str(entry.get("sha256") or "") if isinstance(entry, dict) else ""
+                    if (
+                        not rel
+                        or rel in seen
+                        or re.fullmatch(r"[0-9a-f]{64}", digest) is None
+                    ):
+                        valid = False
+                        break
+                    seen.add(rel)
+                    target = (change_dir / rel).resolve()
+                    if not target.is_relative_to(change_dir.resolve()) or not target.is_file():
+                        valid = False
+                        break
+                    if not _manifest_path_excluded(rel) and sha256_file(target) != digest:
+                        valid = False
+                        break
+            if not valid:
+                issues.append(
+                    {
+                        "code": "manifest-invalid",
+                        "severity": "error",
+                        "message": "archive-manifest-before structure or checksum is invalid",
+                    }
+                )
+        except (OSError, json.JSONDecodeError):
+            issues.append(
+                {
+                    "code": "manifest-invalid",
+                    "severity": "error",
+                    "message": "archive-manifest-before is unreadable",
+                }
+            )
+
+    # 5. Artifact paths must resolve to immutable files inside the archive.
+    root = change_dir.resolve()
+    for artifact in summary.get("artifacts") or []:
+        raw = str(artifact.get("path") or "") if isinstance(artifact, dict) else ""
+        candidate = (root / raw).resolve() if raw else root
+        if not raw or not candidate.is_relative_to(root) or not candidate.is_file():
+            issues.append(
+                {
+                    "code": "artifact-missing",
+                    "severity": "error",
+                    "message": f"artifact path is missing or outside archive: {raw}",
+                }
+            )
+
+    errors = [i for i in issues if i.get("severity") == "error"]
+    warnings = [i for i in issues if i.get("severity") != "error"]
+    return {
+        "ok": len(errors) == 0,
+        "issues": issues,
+        "error_count": len(errors),
+        "warning_count": len(warnings),
+    }
+
+
 def validate_summary(
     summary: dict[str, Any],
     html_path: Path | None,
@@ -1795,7 +2607,12 @@ def validate_summary(
 
         # risks / manual actions — empty arrays are OK (placeholder)
         for risk in summary.get("knownRisks") or []:
-            text = str(risk)
+            # UT-016/RET-28: canonical projection — structured risk objects
+            # project to their message; str(dict) never matches rendered HTML.
+            if isinstance(risk, dict):
+                text = str(risk.get("message") or risk.get("summary") or "").strip()
+            else:
+                text = str(risk)
             if text and text not in html and _html_escape(text) not in html:
                 issues.append(
                     {
@@ -2006,6 +2823,7 @@ def cmd_finalize(
     archive_root: Path,
     *,
     skip_ingest: bool = False,
+    allow_missing_review: bool = False,
 ) -> tuple[int, dict[str, Any]]:
     """Execute the 9-step finalize pipeline. Returns (exit_code, payload)."""
     warnings: list[str] = []
@@ -2015,6 +2833,43 @@ def cmd_finalize(
     archive_root.mkdir(parents=True, exist_ok=True)
     archive_dir = archive_root / f"{today_date()}-{change_name}"
     project_root = find_project_root(original_change_dir)
+    try:
+        resolved_state_dir = hp.resolve_state_dir_for_contract(
+            original_change_dir, project_root
+        )
+    except ValueError as exc:
+        return 1, {
+            "ok": False,
+            "action": "finalize",
+            "change_dir": str(original_change_dir),
+            "error": f"invalid split runtime root: {exc}",
+        }
+    split_state_dir = (
+        resolved_state_dir
+        if resolved_state_dir.resolve() != original_change_dir.resolve()
+        else None
+    )
+    split_materialized_names = (
+        {item.name for item in split_state_dir.iterdir()}
+        if split_state_dir is not None and split_state_dir.is_dir()
+        else set()
+    )
+
+    def _restore_finalize_failure() -> None:
+        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
+        if split_state_dir is None or not original_change_dir.is_dir():
+            return
+        # The split state remains authoritative on failure. Remove only the
+        # top-level names materialized from that state so retry starts clean.
+        for name in sorted(split_materialized_names):
+            target = original_change_dir / name
+            try:
+                if target.is_dir():
+                    shutil.rmtree(target)
+                elif target.exists():
+                    target.unlink()
+            except OSError as exc:
+                warnings.append(f"could not dematerialize split state {target}: {exc}")
 
     payload: dict[str, Any] = {
         "ok": False,
@@ -2035,6 +2890,7 @@ def cmd_finalize(
         return 1, payload
 
     work_dir = original_change_dir
+    before_manifest: dict[str, Any] | None = None
 
     def _safe_append(**kwargs: Any) -> None:
         nonlocal work_dir
@@ -2046,6 +2902,30 @@ def cmd_finalize(
     # Step 9 starts here: phase.start
     _safe_append(phase="archive", type_="phase.start", note="finalize start")
 
+    # --- 0. cleanup transients (before before-manifest) ---
+    try:
+        cleanup_result = _cleanup_transients(split_state_dir or work_dir)
+        payload["steps"]["cleanup"] = cleanup_result
+        deleted_n = len(cleanup_result.get("deleted") or [])
+        trunc_n = len(cleanup_result.get("truncated") or [])
+        _safe_append(
+            phase="archive",
+            type_="command",
+            command="cleanup-transients",
+            exit_code=0,
+            note=f"deleted={deleted_n} truncated={trunc_n}",
+        )
+    except OSError as exc:
+        warnings.append(f"cleanup failed: {exc}")
+        payload["steps"]["cleanup"] = {"ok": False, "error": str(exc)}
+
+    if split_state_dir is not None and split_state_dir.is_dir():
+        _merge_runtime_state(split_state_dir, work_dir)
+        payload["steps"]["split_state_merge"] = {
+            "ok": True,
+            "stateDir": str(split_state_dir),
+        }
+
     # --- 1. before-manifest ---
     before_path = work_dir / "evidence" / "archive-manifest-before.json"
     try:
@@ -2079,6 +2959,10 @@ def cmd_finalize(
         )
         return 1, payload
 
+    # Sync events/evidence appended after the first materialization.
+    if split_state_dir is not None and split_state_dir.is_dir():
+        _merge_runtime_state(split_state_dir, work_dir)
+
     # --- 2. move ---
     try:
         archive_root.mkdir(parents=True, exist_ok=True)
@@ -2110,7 +2994,33 @@ def cmd_finalize(
             pass
         return 1, payload
 
-    # --- 3. collect ---
+    # --- 2b. user-flag decision (archive fact, must precede the cutoff) ---
+    if allow_missing_review:
+        _safe_append(
+            phase="archive",
+            type_="decision",
+            note="review missing on full tier (allowed by user)",
+        )
+
+    # --- 3. unique phase.end + freeze cutoff (RET-19 freeze-first) ---
+    # From here on, NO event may be appended to the archived events file;
+    # report generation runs as pure functions over the frozen sources.
+    _safe_append(
+        phase="archive",
+        type_="phase.end",
+        status="WARN" if warnings else "OK",
+        note="finalize facts complete",
+    )
+    try:
+        cutoff = _freeze_evidence_cutoff(work_dir)
+        payload["steps"]["freeze"] = {"ok": True, "eventCount": cutoff["eventCount"]}
+    except OSError as exc:
+        payload["error"] = f"freeze failed: {exc}"
+        payload["steps"]["freeze"] = {"ok": False, "error": str(exc)}
+        _restore_finalize_failure()
+        return 1, payload
+
+    # --- 4. collect (pure function of frozen sources) ---
     try:
         summary = collect_summary_data(
             work_dir,
@@ -2119,46 +3029,49 @@ def cmd_finalize(
             for_replay=False,
         )
         summary_path = work_dir / "reports" / "final" / "summary-data.json"
+        if allow_missing_review:
+            reasons = list(summary.get("finalStatusReasons") or [])
+            reason = "review missing on full tier (allowed by user)"
+            if reason not in reasons:
+                reasons.append(reason)
+            summary["finalStatusReasons"] = reasons
+            write_json(summary_path, summary)
         payload["steps"]["collect"] = {"ok": True, "path": str(summary_path)}
-        _safe_append(
-            phase="archive",
-            type_="artifact",
-            path="reports/final/summary-data.json",
-            kind="summary-data",
-        )
     except Exception as exc:  # noqa: BLE001 — surface collect failures
         payload["error"] = f"collect failed: {exc}"
         payload["steps"]["collect"] = {"ok": False, "error": str(exc)}
-        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
+        _restore_finalize_failure()
+        return 1, payload
+
+    # --- 5. source consistency (layer 1; UT-014) ---
+    source_result = validate_source_consistency(work_dir, summary)
+    payload["steps"]["source_consistency"] = source_result
+    summary.setdefault("reportPipeline", {})["sourceConsistency"] = {
+        "ok": bool(source_result.get("ok")),
+        "issues": source_result.get("issues") or [],
+    }
+    try:
+        write_json(summary_path, summary)
+    except OSError as exc:
+        warnings.append(f"could not write sourceConsistency: {exc}")
+    if not source_result.get("ok"):
+        payload["issues"] = source_result.get("issues") or []
+        payload["error"] = "source consistency failed; original change dir restored"
+        _restore_finalize_failure()
+        _append_finalize_failure_issue(original_change_dir, "source-consistency-failed", payload["error"])
+        payload["warnings"] = warnings
+        payload["ok"] = False
         return 1, payload
 
-    # --- 4. render (Node, else Python fallback) ---
+    # --- 6. render (Node, else Python fallback) ---
     render_result = render_final_summary(work_dir, summary_path)
     payload["steps"]["render"] = render_result
     if not render_result.get("ok"):
-        # Node + fallback both failed: restore + exit non-0 (§4.1 rule 4)。
         # 永不关闭一个没有 final-summary 的归档。
         msg = str(render_result.get("fallbackReason") or "render failed")
         payload["error"] = f"final-summary render failed: {msg}"
-        _safe_append(
-            phase="archive",
-            type_="issue",
-            code="render-failed",
-            severity="error",
-            message=msg,
-        )
-        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
-        _restore_target = original_change_dir if original_change_dir.is_dir() else work_dir
-        try:
-            append_event(
-                _restore_target,
-                phase="archive",
-                type_="phase.end",
-                status="FAIL",
-                note="finalize aborted; render failed; original preserved",
-            )
-        except OSError:
-            pass
+        _restore_finalize_failure()
+        _append_finalize_failure_issue(original_change_dir, "render-failed", msg)
         payload["warnings"] = warnings
         payload["ok"] = False
         return 1, payload
@@ -2168,24 +3081,10 @@ def cmd_finalize(
             f"node render unavailable; used python-fallback: "
             f"{render_result.get('fallbackReason')}"
         )
-    _safe_append(
-        phase="archive",
-        type_="artifact",
-        path="reports/final/final-summary.html",
-        kind="final-report",
-    )
-    _safe_append(
-        phase="archive",
-        type_="command",
-        command=f"render-final-summary ({renderer})",
-        exit_code=0,
-        note=f"final-summary rendered by {renderer}",
-    )
 
     html_path = work_dir / "reports" / "final" / "final-summary.html"
 
-    # --- 5. validate (same process, no re-collect) ---
-    # Refresh summary from disk (collect already wrote it); do not re-collect.
+    # --- 7. renderer consistency (layer 2) ---
     try:
         summary = read_json(summary_path)
     except (OSError, json.JSONDecodeError):
@@ -2203,20 +3102,19 @@ def cmd_finalize(
     except OSError as exc:
         warnings.append(f"could not write validationIssues: {exc}")
 
-    for issue in validate_result.get("issues") or []:
-        _safe_append(
-            phase="archive",
-            type_="issue",
-            code=str(issue.get("code") or "validate"),
-            severity=str(issue.get("severity") or "warning"),
-            message=str(issue.get("message") or ""),
-        )
+    # --- 8. archive-meta (before after-manifest so the manifest covers it) ---
+    try:
+        summary = read_json(summary_path)
+        meta_path = write_archive_meta(work_dir, summary)
+        payload["steps"]["archive_meta"] = {"ok": True, "path": str(meta_path)}
+    except Exception as exc:  # noqa: BLE001 — meta soft-fail
+        warnings.append(f"archive-meta write failed: {exc}")
+        payload["steps"]["archive_meta"] = {"ok": False, "error": str(exc)}
 
-    # --- 6. after-manifest + compare ---
+    # --- 9. after-manifest + compare ---
     after_path = work_dir / "evidence" / "archive-manifest-after.json"
     try:
         after_manifest = generate_manifest(work_dir, after_path)
-        # Re-read before from archive (moved with the tree)
         before_in_archive = work_dir / "evidence" / "archive-manifest-before.json"
         if before_in_archive.is_file():
             before_manifest = read_json(before_in_archive)
@@ -2226,46 +3124,34 @@ def cmd_finalize(
             "path": str(after_path),
             "compare": compare_result,
         }
-        _safe_append(
-            phase="archive",
-            type_="artifact",
-            path="evidence/archive-manifest-after.json",
-            kind="manifest-after",
-        )
     except (OSError, json.JSONDecodeError, ValueError) as exc:
         payload["error"] = f"after-manifest failed: {exc}"
         payload["steps"]["after_manifest"] = {"ok": False, "error": str(exc)}
-        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
+        _restore_finalize_failure()
         return 1, payload
 
-    # Update archiveManifest in summary-data with compare stats
+    # --- 10. final summary update + final render/validate (no more events) ---
+    summary = read_json(summary_path)
     summary["archiveManifest"] = {
         "movedFiles": compare_result.get("movedFiles", 0),
         "generatedFiles": compare_result.get("generatedFiles", 0),
         "totalArchiveFiles": compare_result.get("totalArchiveFiles", 0),
         "checksumStatus": compare_result.get("checksumStatus", "FAIL"),
+        **_manifest_self_stats(work_dir, after_manifest, after_path),
     }
-    try:
-        write_json(summary_path, summary)
-    except OSError as exc:
-        warnings.append(f"could not update archiveManifest: {exc}")
-
-    # The first render is needed so the after-manifest includes a final report,
-    # but it predates the final manifest statistics.  Render and validate once
-    # more from the now-final summary so HTML never contradicts summary-data.
+    write_json(summary_path, summary)
     render_result = render_final_summary(work_dir, summary_path)
     if not render_result.get("ok"):
         payload["error"] = f"final summary re-render failed: {render_result.get('error')}"
-        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
+        _restore_finalize_failure()
         return 1, payload
+    summary = read_json(summary_path)
     validate_result = validate_summary(summary, html_path if html_path.is_file() else None)
     payload["steps"]["validate"] = validate_result
     summary.setdefault("reportPipeline", {})["validationIssues"] = validate_result.get("issues") or []
     write_json(summary_path, summary)
 
-    # --- 7. delete original only if validate+manifest OK ---
-    # After move, "original" is gone; on failure we restore. On success, ensure
-    # the changes path does not linger.
+    # --- 11. closure: only when both validators and manifest pass ---
     validate_ok = bool(validate_result.get("ok"))
     manifest_ok = bool(compare_result.get("ok"))
     can_close = validate_ok and manifest_ok
@@ -2286,19 +3172,10 @@ def cmd_finalize(
         payload["issues"] = issues_out
         payload["error"] = "validate or manifest check failed; original change dir restored"
         payload["steps"]["delete_original"] = {"ok": False, "deleted": False}
-        _restore_on_failure(archive_dir, original_change_dir, payload, warnings)
-        _safe_append_restored = original_change_dir if original_change_dir.is_dir() else None
-        if _safe_append_restored:
-            try:
-                append_event(
-                    _safe_append_restored,
-                    phase="archive",
-                    type_="phase.end",
-                    status="FAIL",
-                    note="finalize aborted; original preserved",
-                )
-            except OSError:
-                pass
+        _restore_finalize_failure()
+        _append_finalize_failure_issue(
+            original_change_dir, "closure-failed", payload["error"]
+        )
         payload["warnings"] = warnings
         payload["ok"] = False
         return 1, payload
@@ -2318,16 +3195,15 @@ def cmd_finalize(
             "note": "removed by move",
         }
 
-    _safe_append(
-        phase="archive",
-        type_="verification",
-        name="archive-closure",
-        status="ok",
-        note="manifest+validate passed; original removed",
-    )
+    if split_state_dir is not None and split_state_dir.is_dir():
+        try:
+            shutil.rmtree(split_state_dir)
+            payload["steps"]["delete_runtime_state"] = {"ok": True, "deleted": True}
+        except OSError as exc:
+            warnings.append(f"could not remove archived runtime state: {exc}")
+            payload["steps"]["delete_runtime_state"] = {"ok": False, "error": str(exc)}
 
-    # --- 8. maintenance outbox + service (§8.2: close no longer runs the four
-    # knowledge subprocesses; it enqueues a pending outbox item and returns) ---
+    # --- 12. maintenance outbox + service ---
     if skip_ingest:
         payload["steps"]["knowledge"] = {"skipped": True, "reason": "--skip-ingest"}
         payload["knowledgeMaintenance"] = "SKIPPED"
@@ -2346,13 +3222,6 @@ def cmd_finalize(
     if service_result.get("warning"):
         warnings.append(str(service_result["warning"]))
 
-    _safe_append(
-        phase="archive",
-        type_="phase.end",
-        status="WARN" if warnings else "OK",
-        note="finalize complete",
-    )
-
     payload["ok"] = True
     payload["warnings"] = warnings
     payload["summary_data"] = str(summary_path)
@@ -2360,6 +3229,17 @@ def cmd_finalize(
     return 0, payload
 
 
+def _merge_runtime_state(state_dir: Path, contract_dir: Path) -> None:
+    """Materialize split-v1 dynamic state into the archive contract tree."""
+    for source in sorted(state_dir.iterdir()):
+        target = contract_dir / source.name
+        if source.is_dir():
+            shutil.copytree(source, target, dirs_exist_ok=True, copy_function=shutil.copy2)
+        elif source.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source, target)
+
+
 def _restore_on_failure(
     archive_dir: Path,
     original_change_dir: Path,
@@ -2455,7 +3335,10 @@ def cmd_replay(
 
 def cmd_status_cli(args: argparse.Namespace) -> int:
     change_dir = resolve_path(args.change_dir)
-    result = check_status(change_dir)
+    result = check_status(
+        change_dir,
+        allow_missing_review=bool(getattr(args, "allow_missing_review", False)),
+    )
     emit_json(result)
     # Checks completed → exit 0; archivable flag conveys the gate result.
     return 0 if result.get("ok") else 1
@@ -2468,6 +3351,7 @@ def cmd_finalize_cli(args: argparse.Namespace) -> int:
         change_dir,
         archive_root,
         skip_ingest=bool(args.skip_ingest),
+        allow_missing_review=bool(getattr(args, "allow_missing_review", False)),
     )
     emit_json(payload)
     return code
@@ -2481,6 +3365,144 @@ def cmd_replay_cli(args: argparse.Namespace) -> int:
     return code
 
 
+def _render_html_to(
+    change_dir: Path,
+    summary_path: Path,
+    out_path: Path,
+) -> dict[str, Any]:
+    """Render summary HTML to an arbitrary path (node first, python fallback).
+
+    Unlike ``render_final_summary`` this never touches the canonical
+    ``reports/final/final-summary.html`` — repair renders into staging.
+    """
+    project = find_project_root(change_dir)
+    node = resolve_node_path(project)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if node and RENDER_SCRIPT.is_file():
+        try:
+            proc = subprocess.run(
+                [node, str(RENDER_SCRIPT), "--summary", str(summary_path), "--out", str(out_path)],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=60,
+                check=False,
+            )
+            if proc.returncode == 0 and out_path.is_file():
+                return {"ok": True, "renderer": "node", "out_path": str(out_path)}
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    try:
+        summary = read_json(summary_path)
+        html = render_fallback_html(summary)
+        out_path.write_text(html, encoding="utf-8", newline="\n")
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        return {"ok": False, "renderer": "none", "error": str(exc)}
+    return {"ok": True, "renderer": "python-fallback", "out_path": str(out_path)}
+
+
+def cmd_repair(archive_dir: Path) -> tuple[int, dict[str, Any]]:
+    """Versioned repair (task 11 / RET-40).
+
+    Re-collect a candidate from the frozen sources, run both validators, and
+    only then write an immutable ``derived/v<N>/`` plus a repair record. The
+    original summary/HTML/manifest is never overwritten; the authoritative
+    pointer moves only when both validators pass.
+    """
+    payload: dict[str, Any] = {
+        "ok": False,
+        "action": "repair",
+        "archive_dir": str(archive_dir),
+    }
+    if not archive_dir.is_dir():
+        payload["error"] = f"archive dir not found: {archive_dir}"
+        return 1, payload
+    summary_path = archive_dir / "reports" / "final" / "summary-data.json"
+    if not summary_path.is_file():
+        payload["error"] = "summary-data.json missing; cannot repair"
+        return 1, payload
+
+    # 1. candidate: fresh collect from frozen sources (read-only on archive).
+    try:
+        candidate = collect_summary_data(archive_dir, write=False, for_replay=False)
+    except Exception as exc:  # noqa: BLE001
+        payload["error"] = f"repair collect failed: {exc}"
+        return 1, payload
+
+    # 2. stage outside the archive; run both validators on the candidate.
+    staging = Path(tempfile.mkdtemp(prefix="harness-repair-"))
+    try:
+        staged_summary = staging / "summary-data.json"
+        write_json(staged_summary, candidate)
+        source_result = validate_source_consistency(archive_dir, candidate)
+        render_result = _render_html_to(
+            archive_dir, staged_summary, staging / "final-summary.html"
+        )
+        staged_html = staging / "final-summary.html"
+        renderer_result = validate_summary(
+            candidate,
+            staged_html if staged_html.is_file() else None,
+        )
+        payload["validators"] = {
+            "source": source_result,
+            "renderer": renderer_result,
+        }
+        if not (source_result.get("ok") and renderer_result.get("ok")):
+            payload["error"] = "repair validators failed; derived version not written"
+            return 1, payload
+
+        # 3. immutable derived version.
+        derived = archive_dir / "derived"
+        derived.mkdir(exist_ok=True)
+        existing = [
+            int(p.name[1:])
+            for p in derived.iterdir()
+            if p.is_dir() and p.name.startswith("v") and p.name[1:].isdigit()
+        ]
+        version = f"v{(max(existing) + 1) if existing else 1}"
+        version_dir = derived / version
+        version_dir.mkdir()
+        final_summary = version_dir / "summary-data.json"
+        write_json(final_summary, candidate)
+        if staged_html.is_file():
+            shutil.copy2(staged_html, version_dir / "final-summary.html")
+        record = {
+            "version": version,
+            "createdAt": now_iso(),
+            "summarySha256": "sha256:" + hashlib.sha256(final_summary.read_bytes()).hexdigest(),
+            "baseSummarySha256": "sha256:" + hashlib.sha256(summary_path.read_bytes()).hexdigest(),
+            "validators": {
+                "source": {"ok": bool(source_result.get("ok")), "issues": source_result.get("issues") or []},
+                "renderer": {"ok": bool(renderer_result.get("ok")), "issues": renderer_result.get("issues") or []},
+            },
+        }
+        write_json(version_dir / "repair-record.json", record)
+
+        # 4. authoritative pointer — only after both validators passed.
+        write_json(
+            derived / "authoritative.json",
+            {
+                "version": version,
+                "summarySha256": record["summarySha256"],
+                "updatedAt": record["createdAt"],
+            },
+        )
+        payload["ok"] = True
+        payload["version"] = version
+        payload["derived_dir"] = str(version_dir)
+        return 0, payload
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+
+def cmd_repair_cli(args: argparse.Namespace) -> int:
+    archive_dir = resolve_path(args.archive_dir)
+    code, payload = cmd_repair(archive_dir)
+    emit_json(payload)
+    return code
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="harness_archive.py",
@@ -2491,12 +3513,22 @@ def build_parser() -> argparse.ArgumentParser:
     p_status = sub.add_parser("status", help="pre-archive gate checks (read-only)")
     p_status.add_argument("--change-dir", required=True)
     p_status.add_argument("--json", action="store_true", default=True)
+    p_status.add_argument(
+        "--allow-missing-review",
+        action="store_true",
+        help="downgrade full-tier missing review from blocker to warning",
+    )
     p_status.set_defaults(func=cmd_status_cli)
 
     p_fin = sub.add_parser("finalize", help="single-process archive finalize")
     p_fin.add_argument("--change-dir", required=True)
     p_fin.add_argument("--archive-root", required=True)
     p_fin.add_argument("--skip-ingest", action="store_true")
+    p_fin.add_argument(
+        "--allow-missing-review",
+        action="store_true",
+        help="record override when full-tier review evidence is missing",
+    )
     p_fin.add_argument("--json", action="store_true", default=True)
     p_fin.set_defaults(func=cmd_finalize_cli)
 
@@ -2506,6 +3538,13 @@ def build_parser() -> argparse.ArgumentParser:
     p_rep.add_argument("--json", action="store_true", default=True)
     p_rep.set_defaults(func=cmd_replay_cli)
 
+    p_repair = sub.add_parser(
+        "repair", help="versioned repair: validated derived version, original untouched"
+    )
+    p_repair.add_argument("--archive-dir", required=True)
+    p_repair.add_argument("--json", action="store_true", default=True)
+    p_repair.set_defaults(func=cmd_repair_cli)
+
     return parser