@hunter-harness/workflow-harness 0.2.30 → 0.2.31

package/harness/bundles/java/codebuddy/scripts/harness_plan_finalize.py

@@ -51,6 +51,28 @@ def _result_error(code: str, message: str) -> dict[str, Any]:
     return {"ok": False, "code": code, "error": message}
 
 
+def _normalize_header(value: str) -> str:
+    return re.sub(r"[\s_-]+", "", value).lower()
+
+
+def _column_index(
+    headers: list[str],
+    *aliases: str,
+) -> int | None:
+    normalized = {
+        _normalize_header(header): index for index, header in enumerate(headers)
+    }
+    for alias in aliases:
+        index = normalized.get(_normalize_header(alias))
+        if index is not None:
+            return index
+    return None
+
+
+def _table_cells(line: str) -> list[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
 def parse_test_scenarios(scenarios_path: Path) -> list[dict[str, str]]:
     """C9: parse test-scenarios.md tables, extracting scenario rows.
 
@@ -60,42 +82,100 @@ def parse_test_scenarios(scenarios_path: Path) -> list[dict[str, str]]:
     text = Path(scenarios_path).read_text(encoding="utf-8-sig")
     lines = text.splitlines()
     scenarios: list[dict[str, str]] = []
-    # Find all tables whose header includes "ID" and "优先级" (or "priority").
     i = 0
     while i < len(lines):
         line = lines[i].strip()
-        if line.startswith("|") and "ID" in line and ("优先级" in line or "priority" in line):
-            header_line = line
-            headers = [h.strip() for h in header_line.strip("|").split("|")]
-            col_map: dict[str, int] = {}
-            for idx, name in enumerate(headers):
-                key = name.lower()
-                col_map[key] = idx
-            # Skip separator row
-            i += 2
-            while i < len(lines):
-                row = lines[i].strip()
+        if line.startswith("|"):
+            headers = _table_cells(line)
+            id_index = _column_index(headers, "ID", "#", "编号", "场景 ID")
+            scenario_index = _column_index(
+                headers,
+                "场景",
+                "场景描述",
+                "scenario",
+                "description",
+            )
+            if id_index is None or scenario_index is None:
+                i += 1
+                continue
+            priority_index = _column_index(headers, "优先级", "priority")
+            category_index = _column_index(headers, "分类", "category")
+            verification_index = _column_index(
+                headers,
+                "验证方式",
+                "verification",
+                "可复用证据",
+            )
+            owner_phase_index = _column_index(
+                headers,
+                "owner phase",
+                "ownerPhase",
+                "负责阶段",
+            )
+            execution_tier_index = _column_index(
+                headers,
+                "执行层级",
+                "execution tier",
+                "tier",
+            )
+            expected_index = _column_index(headers, "预期", "expected")
+
+            row_index = i + 2
+            while row_index < len(lines):
+                row = lines[row_index].strip()
                 if not row.startswith("|"):
                     break
-                cells = [c.strip() for c in row.strip("|").split("|")]
-                if len(cells) < len(headers):
-                    i += 1
+                cells = _table_cells(row)
+                if max(id_index, scenario_index) >= len(cells):
+                    row_index += 1
                     continue
-                scenario: dict[str, str] = {}
-                for cn, en in (
-                    ("ID", "id"),
-                    ("优先级", "priority"),
-                    ("场景", "scenario"),
-                    ("验证方式", "verification"),
-                    ("owner phase", "ownerPhase"),
+                complete_row = len(cells) == len(headers)
+                scenario_id = cells[id_index].strip()
+                if not scenario_id or set(scenario_id) <= {"-", ":"}:
+                    row_index += 1
+                    continue
+                priority = (
+                    cells[priority_index].strip().upper()
+                    if priority_index is not None
+                    and priority_index < len(cells)
+                    and cells[priority_index].strip()
+                    else "P1"
+                )
+                scenario = {
+                    "id": scenario_id,
+                    "priority": priority,
+                    "scenario": cells[scenario_index].strip(),
+                    "ownerPhase": (
+                        cells[owner_phase_index].strip()
+                        if owner_phase_index is not None
+                        and complete_row
+                        and owner_phase_index < len(cells)
+                        and cells[owner_phase_index].strip()
+                        else "test"
+                    ),
+                    "requiredEvidenceKind": PRIORITY_EVIDENCE_KIND.get(
+                        priority,
+                        "advisory",
+                    ),
+                }
+                if category_index is not None and category_index < len(cells):
+                    if cells[category_index].strip():
+                        scenario["category"] = cells[category_index].strip()
+                for key, index in (
+                    ("verification", verification_index),
+                    ("executionTier", execution_tier_index),
+                    ("expected", expected_index),
                 ):
-                    if cn.lower() in col_map:
-                        scenario[en] = cells[col_map[cn.lower()]]
-                # Derive requiredEvidenceKind from priority
-                priority = scenario.get("priority", "")
-                scenario["requiredEvidenceKind"] = PRIORITY_EVIDENCE_KIND.get(priority, "advisory")
+                    if (
+                        complete_row
+                        and index is not None
+                        and index < len(cells)
+                        and cells[index].strip()
+                    ):
+                        scenario[key] = cells[index].strip()
                 scenarios.append(scenario)
-                i += 1
+                row_index += 1
+            i = row_index
             continue
         i += 1
     return scenarios
@@ -110,40 +190,52 @@ def parse_plan_tasks(plan_path: Path) -> list[dict[str, str]]:
     """
     text = Path(plan_path).read_text(encoding="utf-8-sig")
     lines = text.splitlines()
-    # Find the task table: a header row starting with "| #" followed by a separator row.
-    header_idx = -1
-    for i, line in enumerate(lines):
-        stripped = line.strip()
-        if stripped.startswith("|") and "#" in stripped and "任务" in stripped:
-            header_idx = i
-            break
-    if header_idx < 0:
-        return []
-    header_line = lines[header_idx]
-    headers = [h.strip() for h in header_line.strip().strip("|").split("|")]
-    # Map header names to column indices (case-insensitive, English keys).
-    col_map: dict[str, int] = {}
-    for idx, name in enumerate(headers):
-        key = name.lower()
-        col_map[key] = idx
     tasks: list[dict[str, str]] = []
-    for line in lines[header_idx + 2 :]:  # skip header + separator
-        stripped = line.strip()
-        if not stripped.startswith("|"):
-            break  # end of table
-        cells = [c.strip() for c in stripped.strip("|").split("|")]
-        if len(cells) < len(headers):
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+        if not line.startswith("|"):
+            i += 1
+            continue
+        headers = _table_cells(line)
+        number_index = _column_index(headers, "#", "任务编号", "task ID")
+        task_index = _column_index(headers, "任务", "task")
+        if number_index is None or task_index is None:
+            i += 1
             continue
-        task: dict[str, str] = {}
-        # Chinese headers
-        for cn, en in (("#", "num"), ("簇", "cluster"), ("任务", "task")):
-            if cn in col_map:
-                task[en] = cells[col_map[cn]]
-        # English optional columns
-        for en in ("ownerPhase", "implementationDoneWhen", "verificationPhase", "requiresExplicitAuthority"):
-            if en.lower() in col_map:
-                task[en] = cells[col_map[en.lower()]]
-        tasks.append(task)
+        cluster_index = _column_index(headers, "簇", "cluster")
+        optional_indices = {
+            name: _column_index(headers, name)
+            for name in (
+                "ownerPhase",
+                "implementationDoneWhen",
+                "verificationPhase",
+                "requiresExplicitAuthority",
+            )
+        }
+        row_index = i + 2
+        while row_index < len(lines):
+            row = lines[row_index].strip()
+            if not row.startswith("|"):
+                break
+            cells = _table_cells(row)
+            if len(cells) < len(headers):
+                row_index += 1
+                continue
+            number = cells[number_index].strip()
+            task_text = cells[task_index].strip()
+            if not number or not task_text or set(number) <= {"-", ":"}:
+                row_index += 1
+                continue
+            task: dict[str, str] = {"num": number, "task": task_text}
+            if cluster_index is not None and cells[cluster_index].strip():
+                task["cluster"] = cells[cluster_index].strip()
+            for name, index in optional_indices.items():
+                if index is not None and cells[index].strip():
+                    task[name] = cells[index].strip()
+            tasks.append(task)
+            row_index += 1
+        i = row_index
     return tasks
 
 
@@ -325,6 +417,20 @@ def validate_staging(staging: Path, change_name: str) -> dict[str, Any]:
     # C8: validate ownerPhase values in plan.md task table.
     plan_path = staging / "plans" / f"{change_name}-plan.md"
     tasks = parse_plan_tasks(plan_path)
+    if not tasks:
+        return _result_error(
+            "PLAN_TASKS_EMPTY",
+            f"{plan_path.relative_to(staging).as_posix()}: no task rows were parsed",
+        )
+    task_ids = [str(task.get("num") or "").strip() for task in tasks]
+    duplicate_task_ids = sorted(
+        {task_id for task_id in task_ids if task_ids.count(task_id) > 1}
+    )
+    if duplicate_task_ids:
+        return _result_error(
+            "PLAN_TASK_ID_DUPLICATE",
+            "duplicate task IDs: " + ", ".join(duplicate_task_ids),
+        )
     for task in tasks:
         owner = task.get("ownerPhase")
         if owner is not None and owner != "" and owner not in VALID_OWNER_PHASES:
@@ -339,6 +445,37 @@ def validate_staging(staging: Path, change_name: str) -> dict[str, Any]:
     # C9: parse test-scenarios.md for scenario manifest.
     scenarios_path = staging / "plans" / f"{change_name}-test-scenarios.md"
     scenarios = parse_test_scenarios(scenarios_path)
+    if not scenarios:
+        return _result_error(
+            "PLAN_SCENARIOS_EMPTY",
+            f"{scenarios_path.relative_to(staging).as_posix()}: no scenario rows were parsed",
+        )
+    scenario_ids = [str(item.get("id") or "").strip() for item in scenarios]
+    duplicate_scenario_ids = sorted(
+        {
+            scenario_id
+            for scenario_id in scenario_ids
+            if scenario_ids.count(scenario_id) > 1
+        }
+    )
+    if duplicate_scenario_ids:
+        return _result_error(
+            "PLAN_SCENARIO_ID_DUPLICATE",
+            "duplicate scenario IDs: " + ", ".join(duplicate_scenario_ids),
+        )
+    for scenario in scenarios:
+        priority = str(scenario.get("priority") or "").upper()
+        if priority not in PRIORITY_EVIDENCE_KIND:
+            return _result_error(
+                "PLAN_SCENARIO_PRIORITY_INVALID",
+                f"scenario {scenario.get('id', '?')}: unsupported priority '{priority}'",
+            )
+        owner = str(scenario.get("ownerPhase") or "")
+        if owner not in VALID_OWNER_PHASES:
+            return _result_error(
+                "PLAN_SCENARIO_OWNER_PHASE_INVALID",
+                f"scenario {scenario.get('id', '?')}: unsupported ownerPhase '{owner}'",
+            )
 
     digest = hashlib.sha256()
     artifact_names: list[str] = []
@@ -374,6 +511,37 @@ def _terminal_exists(change_dir: Path, run_id: str, attempt: int) -> bool:
     )
 
 
+def _validate_plan_start(
+    change_dir: Path,
+    run_id: str,
+    attempt: int,
+) -> dict[str, Any]:
+    events_path = harness_events.events_path(change_dir)
+    try:
+        events = harness_events.load_events(events_path)
+    except (OSError, ValueError) as exc:
+        return _result_error("EVENTS_PARSE_ERROR", str(exc))
+    matching = [
+        event
+        for event in events
+        if event.get("phase") == "plan"
+        and event.get("type") == "phase.start"
+        and event.get("run_id") == run_id
+        and event.get("attempt") == attempt
+    ]
+    if not matching:
+        return _result_error(
+            "PHASE_START_MISSING",
+            "no matching plan phase.start event found for finalizer runId/attempt",
+        )
+    if len(matching) > 1:
+        return _result_error(
+            "PHASE_START_DUPLICATE",
+            f"found {len(matching)} matching plan phase.start events",
+        )
+    return {"ok": True, "phaseStartCount": 1}
+
+
 def verify_plan(change_dir: Path) -> dict[str, Any]:
     """Read-only verification of a finalized plan (retro §5.8).
 
@@ -405,6 +573,18 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
     files_list = receipt.get("files")
     if not isinstance(files_list, list) or not files_list:
         return _result_error("RECEIPT_INVALID", "receipt files list missing or empty")
+    if receipt.get("status") != "finalized":
+        return _result_error(
+            "RECEIPT_NOT_FINALIZED",
+            f"receipt status is {receipt.get('status')!r}, expected 'finalized'",
+        )
+    receipt_run_id = str(receipt.get("runId") or "").strip()
+    receipt_attempt = receipt.get("attempt")
+    if not receipt_run_id or not isinstance(receipt_attempt, int):
+        return _result_error(
+            "RECEIPT_INVALID",
+            "receipt runId/attempt identity is missing or malformed",
+        )
 
     # Recompute artifacts hash from published files.
     digest = hashlib.sha256()
@@ -453,19 +633,105 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
             "status": fm.get("status"),
         }
 
+    plan_path = change_dir / "plans" / f"{change_name}-plan.md"
+    expected_tasks = parse_plan_tasks(plan_path)
+    if not expected_tasks:
+        return _result_error(
+            "PLAN_TASKS_EMPTY",
+            f"no task rows parsed from {plan_path.relative_to(change_dir).as_posix()}",
+        )
+    checkpoints_path = change_dir / "meta" / "implementation-checkpoints.json"
+    if not checkpoints_path.is_file():
+        return _result_error(
+            "IMPLEMENTATION_CHECKPOINTS_MISSING",
+            f"derived task metadata missing: {checkpoints_path}",
+        )
+    try:
+        checkpoints = json.loads(
+            checkpoints_path.read_text(encoding="utf-8-sig")
+        )
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("IMPLEMENTATION_CHECKPOINTS_INVALID", str(exc))
+    actual_tasks = checkpoints.get("tasks") if isinstance(checkpoints, dict) else None
+    expected_task_ids = [str(item.get("num") or "") for item in expected_tasks]
+    actual_task_ids = (
+        [str(item.get("num") or "") for item in actual_tasks if isinstance(item, dict)]
+        if isinstance(actual_tasks, list)
+        else []
+    )
+    if expected_task_ids != actual_task_ids:
+        return _result_error(
+            "IMPLEMENTATION_CHECKPOINTS_DRIFT",
+            "derived task IDs do not match the finalized plan: "
+            f"expected={expected_task_ids}, actual={actual_task_ids}",
+        )
+
+    scenarios_path = (
+        change_dir / "plans" / f"{change_name}-test-scenarios.md"
+    )
+    expected_scenarios = parse_test_scenarios(scenarios_path)
+    if not expected_scenarios:
+        return _result_error(
+            "PLAN_SCENARIOS_EMPTY",
+            f"no scenario rows parsed from {scenarios_path.relative_to(change_dir).as_posix()}",
+        )
+    scenario_manifest_path = change_dir / "meta" / "scenario-manifest.json"
+    if not scenario_manifest_path.is_file():
+        return _result_error(
+            "SCENARIO_MANIFEST_MISSING",
+            f"derived scenario metadata missing: {scenario_manifest_path}",
+        )
+    try:
+        manifest = json.loads(
+            scenario_manifest_path.read_text(encoding="utf-8-sig")
+        )
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("SCENARIO_MANIFEST_INVALID", str(exc))
+    actual_scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
+    if not isinstance(actual_scenarios, list) or not actual_scenarios:
+        return _result_error(
+            "SCENARIO_MANIFEST_EMPTY",
+            "scenario-manifest.json must contain at least one scenario",
+        )
+
+    def scenario_identity(item: dict[str, Any]) -> tuple[str, str, str, str]:
+        return (
+            str(item.get("id") or ""),
+            str(item.get("priority") or ""),
+            str(item.get("ownerPhase") or ""),
+            str(item.get("requiredEvidenceKind") or ""),
+        )
+
+    expected_scenario_identities = [
+        scenario_identity(item) for item in expected_scenarios
+    ]
+    actual_scenario_identities = [
+        scenario_identity(item)
+        for item in actual_scenarios
+        if isinstance(item, dict)
+    ]
+    if expected_scenario_identities != actual_scenario_identities:
+        return _result_error(
+            "SCENARIO_MANIFEST_DRIFT",
+            "derived scenario identities do not match the finalized scenario table",
+        )
+
     # Validate gate-policy.json is parseable JSON.
     gate_policy_path = change_dir / "meta" / "gate-policy.json"
+    if not gate_policy_path.is_file():
+        return _result_error(
+            "GATE_POLICY_MISSING",
+            f"gate policy missing: {gate_policy_path}",
+        )
+    try:
+        json.loads(gate_policy_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("GATE_POLICY_INVALID", str(exc))
     gate_policy_consistent = True
-    if gate_policy_path.is_file():
-        try:
-            json.loads(gate_policy_path.read_text(encoding="utf-8-sig"))
-        except (OSError, json.JSONDecodeError):
-            gate_policy_consistent = False
-    else:
-        gate_policy_consistent = False
 
-    # Validate events.ndjson: count phase.end, check for parse errors.
+    # Validate events.ndjson: require one matching start/end lifecycle.
     events_path = change_dir / "events.ndjson"
+    phase_start_count = 0
     phase_end_count = 0
     phase_end_status: str | None = None
     events_parse_errors: list[str] = []
@@ -481,10 +747,16 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
             if not isinstance(event, dict):
                 events_parse_errors.append(f"line {line_no}: not an object")
                 continue
+            if event.get("phase") != "plan":
+                continue
             if (
-                event.get("phase") == "plan"
-                and event.get("type") == "phase.end"
+                str(event.get("run_id") or "") != receipt_run_id
+                or event.get("attempt") != receipt_attempt
             ):
+                continue
+            if event.get("type") == "phase.start":
+                phase_start_count += 1
+            elif event.get("type") == "phase.end":
                 phase_end_count += 1
                 phase_end_status = str(event.get("status") or "").upper()
     else:
@@ -495,15 +767,27 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
             "EVENTS_PARSE_ERROR", "; ".join(events_parse_errors[:5])
         )
 
+    if phase_start_count == 0:
+        return _result_error(
+            "PHASE_START_MISSING",
+            "no matching plan phase.start event found",
+        )
+    if phase_start_count > 1:
+        return _result_error(
+            "PHASE_START_DUPLICATE",
+            f"found {phase_start_count} matching plan phase.start events",
+        )
     if phase_end_count == 0:
         return _result_error("PHASE_END_MISSING", "no plan phase.end event found")
     if phase_end_count > 1:
         return _result_error(
             "PHASE_END_DUPLICATE", f"found {phase_end_count} phase.end events"
         )
-
-    # Receipt consistency: status should be finalized.
-    receipt_consistent = receipt.get("status") == "finalized"
+    if phase_end_status != "OK":
+        return _result_error(
+            "PHASE_END_NOT_OK",
+            f"plan phase.end status is {phase_end_status!r}, expected 'OK'",
+        )
 
     return {
         "ok": True,
@@ -511,11 +795,14 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
         "changeDir": str(change_dir),
         "changeName": change_name,
         "artifactsHash": actual_hash,
+        "phaseStartCount": phase_start_count,
         "phaseEndCount": phase_end_count,
         "phaseEndStatus": phase_end_status,
         "frontmatter": frontmatter_results,
         "gatePolicyConsistent": gate_policy_consistent,
-        "receiptConsistent": receipt_consistent,
+        "receiptConsistent": True,
+        "taskCount": len(expected_tasks),
+        "scenarioCount": len(expected_scenarios),
         "files": artifact_names,
     }
 
@@ -645,6 +932,9 @@ def finalize_plan(
     validation = validate_staging(staging, change_name)
     if not validation["ok"]:
         return validation
+    start_validation = _validate_plan_start(change_dir, run_id, attempt)
+    if not start_validation["ok"]:
+        return start_validation
 
     receipt_path = change_dir / "meta" / "plan-finalization.json"
     lock_path = change_dir / "meta" / "plan-finalize.lock"

package/harness/bundles/java/codex/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codex",
-  "coreHash": "cdb3eeb74bd77050"
+  "coreHash": "8673695c7e2a1c19"
 }

package/harness/bundles/java/codex/harness-apidoc/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=cdb3eeb74bd77050; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=8673695c7e2a1c19; overlay=java; agent=codex; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -69,12 +69,12 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 `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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
 ```
 
 > **脚本接线**：`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` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`apidoc`

package/harness/bundles/java/codex/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=cdb3eeb74bd77050; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=8673695c7e2a1c19; overlay=java; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -208,12 +208,12 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 `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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
 ```
 
 > **脚本接线**：`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` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`archive`

package/harness/bundles/java/codex/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=cdb3eeb74bd77050; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=8673695c7e2a1c19; overlay=java; agent=codex; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -89,12 +89,12 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 `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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
 ```
 
 > **脚本接线**：`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` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`codebase-map`；默认写 reports，有未归档变更时另写 change events

package/harness/bundles/java/codex/harness-knowledge-ingest/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=cdb3eeb74bd77050; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=8673695c7e2a1c19; overlay=java; agent=codex; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -238,12 +238,12 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 `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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
 ```
 
 > **脚本接线**：`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` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`knowledge-ingest` · 默认控制台报告；变更上下文写 phase/decision/issue/artifact