@hunter-harness/workflow-harness 0.2.5 → 0.2.7

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=5cadfa54663ecdbf; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=89e664933ed69572; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -56,14 +56,21 @@ disallowed-tools:
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
 ## Workflow
 
+测试跟踪的确定性边界为 `harness_test_guard.py begin` 和 `harness_test_guard.py close`；任一失败都必须传递给 `harness_gate.py close`，不得以自然语言覆盖失败状态。
+
+并行服务测试先运行 `harness_change.py lease-port --change <id> --run-id <run-id> --range <start-end> --json`，再把返回端口传给 `harness_service.py ensure --leased-port <port> --lease-owner <run-id>`。`serviceStart` 的 command/health/overlay 可用 `{leasedPort}` 占位符；用户自启进程仍只进入 Service Gate，禁止 kill。测试清理的 `finally` 中运行 `harness_change.py release-port --change <id> --run-id <run-id> --json`，避免租约池耗尽。
+
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-执行 各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+先 `harness_change.py resolve [--change] --json` 解析 change-id；再 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+
+验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`。
 
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续
@@ -181,7 +188,7 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -190,3 +197,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/general/claude-code/harness-test/reference.md

@@ -786,6 +786,6 @@ python <skills-root>/scripts/harness_ledger.py diff-hash --repo . --base <baseCo
 
 ## 执行日志记录
 
-`/harness-test` 只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。Phase 0 之前 append `phase.start`；各阶段写入 `command` / `verification` / `decision` / `issue` / `artifact`，人类可读摘要放 `note`。事件类型与脚本用法见 [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 SKILL.md `## 执行日志`。
+`/harness-test` 只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。Phase 0 之前 append `phase.start`；各阶段写入 `command` / `verification` / `decision` / `issue` / `artifact`，人类可读摘要放 `note`。事件类型与脚本用法见 [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 SKILL.md `## 执行日志`。
 
 关键 `note` / 事件须覆盖：0.1 命令执行模式、fallback 执行器、serviceState、凭证策略、单元测试复用、批量执行器、verification-ledger 写入、关门检查、API 状态（不得把 PARTIAL 写成 NOT_RUN）。

package/harness/bundles/general/claude-code/protocols/ledger-protocol.md

@@ -86,7 +86,7 @@ verification-ledger 把每次验证（compile / unit test / api test / package
     },
     "package": {
       "status": "OK",
-      "command": "<打包命令（按技术栈：Java=mvn package -pl <module> -am -DskipTests；前端=npm run build；Python=python -m build）>",
+      "command": "<打包命令（按技术栈：Java=mvn clean package -pl <module> -am -DskipTests；前端=npm run build；Python=python -m build）>",
       "baseCommit": "<final pushed hash>",
       "deployArtifact": "<构建产物路径（Java=<module>/target/<artifact>.jar；前端=<module>/dist/；Python=<module>/dist/）>",
       "sha256": "<artifact sha256>",

package/harness/bundles/general/claude-code/protocols/report-pipeline-protocol.md

@@ -43,11 +43,11 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 
 `append` 写入契约（Task 4 §6.1）：普通 append = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex`）；仅 `--type phase.end` append 成功后渲染一次 `logs/execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。人类可读摘要（触发指令、降级原因、阶段结论）写入事件的 `note` 字段；阶段开始/结束、命令、验证、artifact、问题、决策各写对应 `type` 事件。旧 archive 缺少 events 可回放兼容；新变更不得以 execution-log 已存在为理由跳过 events。
 
-基础事件结构（schema_version 2）：
+基础事件结构（schema_version 3；兼容读取 v1/v2）：
 
 ```json
 {
-  "schema_version": 2,
+  "schema_version": 3,
   "id": "evt-...",
   "timestamp": "2026-07-02T00:00:00.000Z",
   "phase": "run",
@@ -55,6 +55,13 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
   "command": "npm test",
   "exit_code": 0,
   "duration_ms": 42100,
+  "run_id": "run-...",
+  "attempt": 1,
+  "executor_tool": "codex",
+  "executor_agent": "main",
+  "executor_model": "gpt-5",
+  "handoff_from_tool": "claude-code",
+  "handoff_reason": "continue implementation",
   "note": "可选：触发指令、降级原因、阶段摘要"
 }
 ```
@@ -64,7 +71,7 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 | type | 必填/常用字段 | 用途 |
 |---|---|---|
 | `phase.start` | phase, timestamp | 阶段开始 |
-| `phase.end` | phase, timestamp | 阶段结束，计算耗时 |
+| `phase.end` | phase, timestamp, status | 阶段结束并记录 `OK/WARN/FAIL/BLOCKED`；计算当前 attempt 耗时 |
 | `command` | command, exit_code, duration_ms | 命令事实 |
 | `verification` | name, status, command | 验证事实 |
 | `artifact` | path, kind | 报告、包、manifest 等产物 |
@@ -79,7 +86,7 @@ summary-data 必须保留原 archive final report 维度，并增加事件层摘
 {
   "schemaVersion": "2.2",
   "reportPipeline": {
-    "schema_version": 2,
+    "schema_version": 1,
     "generated_at": "2026-07-02T00:00:00.000Z",
     "event_count": 0,
     "sources": ["events.ndjson", "evidence/verification-ledger.json"],

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Small deterministic helpers for compact API contract reports."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+
+
+COMMIT_ONLY = re.compile(r"^[0-9a-f]{7,64}$", re.IGNORECASE)
+INVALID_FILENAME = re.compile(r"[<>:\"/\\|?*\x00-\x1f]+")
+SEPARATORS = re.compile(r"[\s_-]+")
+
+
+def build_filename(description: str, *, date: str | None = None) -> str:
+    raw = str(description or "").strip()
+    if not raw or COMMIT_ONLY.fullmatch(raw):
+        raise ValueError("a human-readable API change description is required")
+    slug = INVALID_FILENAME.sub("-", raw)
+    slug = SEPARATORS.sub("-", slug).strip(" .-")
+    if not slug:
+        raise ValueError("description does not contain filename-safe text")
+    day = date or dt.date.today().isoformat()
+    slug = slug[:86].rstrip(" .-")
+    return f"{day}-{slug}.md"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    filename = sub.add_parser("filename", help="build a safe dated report filename")
+    filename.add_argument("--description", required=True)
+    filename.add_argument("--date", default=None)
+    filename.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        value = build_filename(args.description, date=args.date)
+    except ValueError as exc:
+        sys.stderr.write(json.dumps({"ok": False, "error": str(exc)}) + "\n")
+        return 1
+    payload = {"ok": True, "filename": value}
+    if args.json:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    else:
+        sys.stdout.write(value + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -359,6 +359,28 @@ def find_review_reports(change_dir: Path) -> list[Path]:
     return found
 
 
+def review_phase_completed(events: list[dict[str, Any]]) -> bool:
+    """True only when structured events record a review phase.end (UT-042)."""
+    for event in events:
+        if event.get("type") != "phase.end":
+            continue
+        if str(event.get("phase") or "").lower() == "review":
+            return True
+    return False
+
+
+def review_evidence_present(
+    change_dir: Path,
+    events: list[dict[str, Any]] | None = None,
+) -> bool:
+    """Review ran only when report files or review phase.end events exist."""
+    if find_review_reports(change_dir):
+        return True
+    if events is None:
+        events = he.load_events(change_dir / "events.ndjson")
+    return review_phase_completed(events)
+
+
 def git_run(project: Path, *args: str) -> tuple[int, str, str]:
     try:
         proc = subprocess.run(
@@ -531,10 +553,9 @@ def check_status(change_dir: Path) -> dict[str, Any]:
     # --- test / review reports ---
     test_reports = find_test_reports(change_dir)
     review_reports = find_review_reports(change_dir)
-    log_text = load_execution_log(change_dir)
-    has_review_section = bool(
-        re.search(r"harness-review|##\s*review", log_text, re.IGNORECASE)
-    )
+    events_path = change_dir / "events.ndjson"
+    events = he.load_events(events_path) if events_path.is_file() else []
+    review_ran = review_evidence_present(change_dir, events)
 
     checks["test_reports"] = [str(p.relative_to(change_dir)) for p in test_reports]
     checks["review_reports"] = [str(p.relative_to(change_dir)) for p in review_reports]
@@ -555,13 +576,13 @@ def check_status(change_dir: Path) -> dict[str, Any]:
 
     if review_reports:
         checks["review_report_status"] = "present"
-    elif has_review_section:
+    elif review_phase_completed(events):
         checks["review_report_status"] = "ran-but-not-persisted"
         warnings.append(
             {
                 "code": "review-not-persisted",
                 "message": (
-                    "execution-log has review section but no review-report file; "
+                    "review phase.end recorded but no review-report file; "
                     "prefer persisting report before archive"
                 ),
             }
@@ -622,13 +643,16 @@ def _ledger_unit_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
     status = str(unit.get("status") or "").upper()
     evidence = unit.get("evidence") or {}
     if isinstance(evidence, dict):
-        run = evidence.get("run", unit.get("run", 0))
+        run = evidence.get(
+            "run",
+            evidence.get("testsRun", unit.get("run", unit.get("testsRun", 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))
         pass_rate = evidence.get("passRate") or unit.get("passRate")
     else:
-        run = unit.get("run", 0)
+        run = unit.get("run", unit.get("testsRun", 0))
         failures = unit.get("failures", 0)
         errors = unit.get("errors", 0)
         skipped = unit.get("skipped", 0)
@@ -886,16 +910,21 @@ def _durations_from_event_phases(event_summary: dict[str, Any]) -> dict[str, Any
         minutes = round((dur or 0) / 60000, 2) if dur is not None else 0
         if dur:
             total_ms += int(dur)
-        stages.append(
-            {
-                "stage": str(name),
-                "skill": f"harness-{name}",
-                "startedAt": info.get("started_at") or NOT_AVAILABLE,
-                "endedAt": info.get("ended_at") or NOT_AVAILABLE,
-                "minutes": minutes,
-                "result": "OK",
-            }
-        )
+        attempts = info.get("attempts") if isinstance(info.get("attempts"), list) else []
+        result = str(info.get("status") or "UNKNOWN").upper()
+        if result in {"PASS", "PASSED", "SUCCESS"}:
+            result = "OK"
+        elif result in {"FAILED", "ERROR"}:
+            result = "FAIL"
+        stages.append({
+            "stage": str(name),
+            "skill": f"harness-{name}",
+            "startedAt": info.get("started_at") or NOT_AVAILABLE,
+            "endedAt": info.get("ended_at") or NOT_AVAILABLE,
+            "minutes": minutes,
+            "result": result,
+            "attempts": attempts,
+        })
     total_min = round(total_ms / 60000, 2)
     return {
         "totalLabel": f"约 {int(round(total_min))} 分",
@@ -917,11 +946,31 @@ def _stage_status_from_sources(
         "submit": "OK",
         "archive": "OK",
     }
+    for event in events:
+        if event.get("type") != "phase.end":
+            continue
+        phase = str(event.get("phase") or "").lower()
+        raw = str(event.get("status") or "").upper()
+        if phase not in status or not raw:
+            continue
+        if raw in {"PASS", "PASSED", "SUCCESS"}:
+            raw = "OK"
+        elif raw in {"FAILED", "ERROR"}:
+            raw = "FAIL"
+        elif raw in {"SKIP", "SKIPPED"}:
+            raw = "USER_SKIPPED"
+        status[phase] = raw
     # Issues in events can downgrade
     for e in events:
         if e.get("type") != "issue":
             continue
         sev = str(e.get("severity") or "").lower()
+        issue_text = " ".join(str(e.get(key) or "") for key in ("message", "note", "code")).lower()
+        if not sev:
+            if any(token in issue_text for token in ("fail", "error", "blocked", "失败", "阻塞")):
+                sev = "error"
+            elif any(token in issue_text for token in ("warn", "skip", "风险", "警告")):
+                sev = "warn"
         phase = str(e.get("phase") or "").lower()
         if phase in status and sev in {"error", "fail", "failed", "critical"}:
             status[phase] = "FAIL"
@@ -930,19 +979,22 @@ def _stage_status_from_sources(
 
     api = _ledger_api_tests(ledger)
     db = _ledger_db_compat(ledger)
-    if api.get("status") == "USER_SKIPPED":
+    api_status = str(api.get("status") or "").upper()
+    if api_status in {"FAIL", "FAILED", "ERROR"} or int(api.get("failed") or 0) > 0:
+        status["test"] = "FAIL"
+    elif api_status in {"BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA"}:
+        status["test"] = api_status
+    elif api_status == "USER_SKIPPED":
         status["test"] = "USER_SKIPPED"
     elif db == "BLOCKED_BY_DBA":
         status["test"] = "BLOCKED_BY_DBA"
     elif api.get("status") == "NOT_RUN" and not find_test_reports(change_dir):
         unit = _ledger_unit_tests(ledger)
         if unit.get("source") == "not-run" and unit.get("run", 0) == 0:
-            status["test"] = "USER_SKIPPED"
+            status["test"] = "NOT_RUN"
 
-    if not find_review_reports(change_dir):
-        log_text = load_execution_log(change_dir)
-        if not re.search(r"harness-review|##\s*review", log_text, re.IGNORECASE):
-            status["review"] = "ADVISORY"
+    if not review_evidence_present(change_dir, events):
+        status["review"] = "ADVISORY"
 
     return status
 
@@ -954,8 +1006,6 @@ def _compute_final_status(
     api = verification.get("apiTests") or {}
     db = str(verification.get("dbCompatibility") or "")
     api_status = str(api.get("status") or "")
-    if api_status == "USER_SKIPPED" or db == "BLOCKED_BY_DBA":
-        return "CONDITIONAL_OK"
     for v in stage_status.values():
         if v == "FAIL":
             return "FAIL"
@@ -964,8 +1014,14 @@ def _compute_final_status(
         return "FAIL"
     if int(api.get("failed") or 0) > 0:
         return "FAIL"
+    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", "PARTIAL", "USER_SKIPPED", "BLOCKED_BY_DBA"}:
+        if v in {"WARN", *conditional}:
             return "WARN" if v == "WARN" else "CONDITIONAL_OK"
     return "OK"
 
@@ -984,6 +1040,8 @@ def _changed_files_from_git(
     changed: list[dict[str, Any]] = []
     if not base or not head:
         return diff_stat, changed
+    # The ledger bounds the complete task.  Using only ``head^..head`` would
+    # silently omit earlier checkpoint commits from the same change.
     rng = f"{base}..{head}"
     code, out, _ = git_run(project, "diff", "--numstat", rng)
     if code != 0 or not out:
@@ -1018,7 +1076,11 @@ def _changed_files_from_git(
     return diff_stat, changed
 
 
-def _review_summary(change_dir: Path, existing: dict[str, Any] | None) -> dict[str, Any]:
+def _review_summary(
+    change_dir: Path,
+    existing: dict[str, Any] | None,
+    events: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     base = {
         "status": "ADVISORY",
         "red": 0,
@@ -1033,13 +1095,102 @@ def _review_summary(change_dir: Path, existing: dict[str, Any] | None) -> dict[s
         merged = dict(base)
         merged.update(existing["reviewSummary"])
         return merged
-    if not find_review_reports(change_dir):
-        log_text = load_execution_log(change_dir)
-        if not re.search(r"harness-review|##\s*review", log_text, re.IGNORECASE):
-            base["status"] = "ADVISORY_NOT_RUN"
+    if not review_evidence_present(change_dir, events):
+        base["status"] = "ADVISORY_NOT_RUN"
     return base
 
 
+def _final_commit_from_sources(
+    ledger: dict[str, Any] | None,
+    events: list[dict[str, Any]],
+    existing: dict[str, Any] | None,
+    project: Path,
+) -> str:
+    if ledger:
+        for key in (
+            "mergeFinalHash", "finalCommit", "finalHash", "changeCommit", "headCommit",
+        ):
+            value = str(ledger.get(key) or "").strip()
+            if value:
+                return value
+    commit_pattern = re.compile(r"\b[0-9a-f]{7,40}\b", re.IGNORECASE)
+    for event in reversed(events):
+        if str(event.get("phase") or "").lower() not in {"submit", "merge", "archive"}:
+            continue
+        text = " ".join(str(event.get(key) or "") for key in ("note", "message", "command"))
+        match = commit_pattern.search(text)
+        if match:
+            return match.group(0)
+    if existing and existing.get("finalCommit"):
+        return str(existing["finalCommit"])
+    code, head, _ = git_run(project, "rev-parse", "HEAD")
+    return head if code == 0 and head else ""
+
+
+def _business_goal_from_sources(change_dir: Path, events: list[dict[str, Any]]) -> str:
+    plans_root = change_dir / "plans"
+    primary = sorted(plans_root.glob("*-plan.md"))
+    secondary = [
+        path for path in sorted(plans_root.glob("*.md"))
+        if path not in primary
+        and "implementation-detail" not in path.name
+        and "test-scenarios" not in path.name
+    ]
+    for plan in [*primary, *secondary]:
+        try:
+            text = plan.read_text(encoding="utf-8-sig")
+        except OSError:
+            continue
+        body = re.sub(r"\A---\s*\n.*?\n---\s*\n", "", text, count=1, flags=re.DOTALL)
+        goal = re.search(r"(?im)^\s*(?:goal|目标|业务目标|需求)\s*[:：]\s*(.+)$", body)
+        if goal:
+            return goal.group(1).strip()
+        scope = re.search(r"(?im)^\s*>?\s*(?:变更范围|目标)\s*[:：]\s*(.+)$", body)
+        if scope:
+            return scope.group(1).strip()
+        first_task = re.search(r"(?m)^\s*\|\s*1\s*\|\s*([^|]+?)\s*\|", body)
+        if first_task:
+            return first_task.group(1).strip()
+        for line in body.splitlines():
+            clean = line.strip().lstrip("#").strip()
+            if clean and not clean.startswith(("---", ">", "|")) and len(clean) > 8:
+                return clean
+    for event in events:
+        if event.get("type") == "decision":
+            value = str(event.get("decision") or event.get("note") or "").strip()
+            if value:
+                return re.sub(r"^(?:需求收敛|目标)\s*[:：]\s*", "", value)
+    return ""
+
+
+def _timeline_from_events(event_summary: dict[str, Any], events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    timeline: list[dict[str, Any]] = []
+    for phase, info in (event_summary.get("phases") or {}).items():
+        attempts = info.get("attempts") if isinstance(info.get("attempts"), list) else []
+        for attempt in attempts:
+            timeline.append({
+                "phase": phase,
+                "attempt": attempt.get("attempt"),
+                "startedAt": attempt.get("started_at"),
+                "endedAt": attempt.get("ended_at"),
+                "durationMs": attempt.get("duration_ms"),
+                "status": attempt.get("status") or "UNKNOWN",
+                "executorTool": attempt.get("executor_tool"),
+                "executorAgent": attempt.get("executor_agent"),
+                "handoffFromTool": attempt.get("handoff_from_tool"),
+            })
+    for event in events:
+        if event.get("type") not in {"decision", "issue"}:
+            continue
+        timeline.append({
+            "phase": event.get("phase"),
+            "timestamp": event.get("timestamp"),
+            "type": event.get("type"),
+            "summary": event.get("decision") or event.get("message") or event.get("note") or "",
+        })
+    return timeline
+
+
 def collect_summary_data(
     change_dir: Path,
     *,
@@ -1118,18 +1269,14 @@ def collect_summary_data(
         if existing and existing.get("businessGoal"):
             data["businessGoal"] = existing["businessGoal"]
         else:
-            data["businessGoal"] = NOT_AVAILABLE if for_replay else ""
+            inferred_goal = _business_goal_from_sources(change_dir, events)
+            data["businessGoal"] = inferred_goal or (NOT_AVAILABLE if for_replay else "")
 
     # commits
     project = find_project_root(change_dir)
     if not data.get("finalCommit") or str(data.get("finalCommit")).startswith("<"):
-        code, head, _ = git_run(project, "rev-parse", "HEAD")
-        if code == 0 and head:
-            data["finalCommit"] = head
-        elif existing and existing.get("finalCommit"):
-            data["finalCommit"] = existing["finalCommit"]
-        else:
-            data["finalCommit"] = NOT_AVAILABLE if for_replay else ""
+        final_commit = _final_commit_from_sources(ledger, events, existing, project)
+        data["finalCommit"] = final_commit or (NOT_AVAILABLE if for_replay else "")
 
     if not data.get("baseCommit") or str(data.get("baseCommit")).startswith("<"):
         if ledger and ledger.get("baseCommit"):
@@ -1235,18 +1382,47 @@ def collect_summary_data(
     if not isinstance(data.get("artifacts"), list):
         data["artifacts"] = []
     if not for_replay:
-        # Keep empty placeholder for build artifacts; event artifacts go to reportPipeline
-        pass
+        data["artifacts"] = _artifacts_from_events(events)
 
-    data["reviewSummary"] = _review_summary(change_dir, existing if for_replay else None)
-    data.setdefault("timeline", [])
+    data["reviewSummary"] = _review_summary(
+        change_dir,
+        existing if for_replay else None,
+        events,
+    )
+    if not for_replay:
+        data["timeline"] = _timeline_from_events(event_summary, events)
+    else:
+        data.setdefault("timeline", [])
     data.setdefault("uncommittedTestEvidence", [])
 
-    # Model-owned fields: leave empty placeholders on finalize; preserve on replay
+    # Derive risks/actions from evidence. These fields are facts, not model prose.
     if not for_replay:
-        data["maintenanceNotes"] = []
-        data["knownRisks"] = []
+        data["maintenanceNotes"] = [
+            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"] = []
+        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({
+                    "stage": name,
+                    "status": value,
+                    "action": "补充或确认该阶段的真实验证证据",
+                })
     else:
         data.setdefault("maintenanceNotes", [])
         data.setdefault("knownRisks", [])
@@ -1978,6 +2154,7 @@ def cmd_finalize(
                 _restore_target,
                 phase="archive",
                 type_="phase.end",
+                status="FAIL",
                 note="finalize aborted; render failed; original preserved",
             )
         except OSError:
@@ -2117,6 +2294,7 @@ def cmd_finalize(
                     _safe_append_restored,
                     phase="archive",
                     type_="phase.end",
+                    status="FAIL",
                     note="finalize aborted; original preserved",
                 )
             except OSError:
@@ -2168,7 +2346,12 @@ def cmd_finalize(
     if service_result.get("warning"):
         warnings.append(str(service_result["warning"]))
 
-    _safe_append(phase="archive", type_="phase.end", note="finalize complete")
+    _safe_append(
+        phase="archive",
+        type_="phase.end",
+        status="WARN" if warnings else "OK",
+        note="finalize complete",
+    )
 
     payload["ok"] = True
     payload["warnings"] = warnings