@hunter-harness/workflow-harness 0.4.9 → 0.4.11

package/harness/bundles/general/codebuddy/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=8aa1d6994e1d3d22; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=cdc01b6329bacd46; overlay=none; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -57,6 +57,17 @@ review 默认优先在独立上下文执行，避免主会话已形成的实现
 
 无隔离能力、定义损坏、spawn 失败、空返回或只有元数据时，不重试，立即由主会话按同一 6 维度检查清单完成审查。无论是否委派，都必须追加一条结构化 `decision` 事件：`--execution-mode delegated|inline` 标明执行方式；委派时写 `--executor-agent harness-reviewer --decision-reason-code REVIEW_DELEGATED`；回退时只写一个 `--fallback-reason-code REVIEW_INLINE_UNAVAILABLE|REVIEW_INLINE_SPAWN_FAILED|REVIEW_INLINE_INVALID_RESULT`。`decision` 和 `reason` 必须用中文完整说明，禁止把原因码拼进正文。正常主会话评审是可接受结果，不显示成流程故障；`fallbackPolicy=inline-no-retry`。
 
+完整示例（委派路径，可直接复制改参）：
+
+```bash
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<cn>" \
+  --phase review --type decision --execution-mode delegated \
+  --executor-agent harness-reviewer --decision-reason-code REVIEW_DELEGATED \
+  --decision "已使用独立评审完成 6 维度审查" --reason "固定 reviewer 可用，避免主会话实现结论影响审查" --json
+```
+
+注意：`decision` 事件**不接受** `--name`/`--status`（那是 verification 的字段）；`issue` 事件必须带 `--severity`。
+
 项目规模小、风险低或没有 CodeGraph 都不是跳过独立评审的理由。原因码是稳定机器字段，仅用于协议与技术详情；面向用户的事件摘要必须写成「已使用独立评审」或「当前环境没有可用的隔离评审能力，已由主会话完成评审」等中文说明。
 
 3. **持久化报告与事实 sidecar（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`，并调用 `python <skills-root>/scripts/harness_review.py scaffold --change-dir <change-dir> [--run-id <id>]` 生成 findings 写入骨架（runId 缺省从 events.ndjson 最新 review phase.start 推断），补齐每一条发现后经 `harness_review.py write-findings --change-dir <change-dir> --stdin` 落地。每条发现必须填写 `fixbackAction=code|manual|workflow`：只有确实需要修改产品代码的项使用 `code`；人工验收用 `manual`；流程、暂存或工具使用建议用 `workflow`。权威计数来自 `reports/review/review-findings.json`，不是 Markdown。任一写入缺失 → 评审未完整结束，不得关门。

package/harness/bundles/general/codebuddy/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8aa1d6994e1d3d22; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=cdc01b6329bacd46; overlay=none; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/codebuddy/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=8aa1d6994e1d3d22; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=cdc01b6329bacd46; overlay=none; agent=codebuddy; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -478,6 +478,55 @@ def _phase_has_ended(event_paths: list[Path], phase: str) -> bool:
     )
 
 
+def _ensure_phase_end_event(
+    contract_root: Path,
+    *,
+    phase: str,
+    status: str,
+    executor: str,
+) -> dict[str, Any] | None:
+    """补齐 phase.start/end 事件对（P0-2）。
+
+    平台 Run 计时由 events-sync 上报的 phase.start/end 事件对驱动。不经
+    gate close 收尾的阶段（典型：plan 走 finalize + context close）只写
+    transitions 收据，phase.end 永远缺席，平台计时永不停——连续两个 change
+    复现，属结构性缺口（2026-08-30 sales-insight-agent demo-datasource 实测）。
+    close_transition 是所有跨阶段推进的共同通道，在此按事件配对补齐：
+    有 start 无 end → 复用 start 的 run_id/attempt 代写 end；已有 end（gate
+    close 先行写入）或连 start 都没有 → 不动，返回 None。
+    """
+    import harness_events as he
+
+    events_file = contract_root / "events.ndjson"
+    events = _read_ndjson(events_file)
+    starts = [
+        item
+        for item in events
+        if hpaths.resolve_phase_name(item.get("phase")) == phase
+        and item.get("type") == "phase.start"
+    ]
+    if not starts or any(
+        hpaths.resolve_phase_name(item.get("phase")) == phase
+        and item.get("type") == "phase.end"
+        for item in events
+    ):
+        return None
+    start = starts[-1]
+    result = he.append_event(
+        contract_root,
+        phase=phase,
+        type_="phase.end",
+        run_id=str(start.get("run_id") or f"{phase}_unknown"),
+        attempt=int(start.get("attempt") or 1),
+        status=status,
+        executor_tool=executor,
+        note="context close 自动补齐 phase.end（平台计时事件对配对）",
+    )
+    if not result.get("ok"):
+        return {"code": "PHASE_END_PAIR_FAILED", "detail": result}
+    return {"code": "PHASE_END_AUTO_PAIRED", "event": result.get("event")}
+
+
 def _reselect_review_fixback(
     project: Path,
     change: str,
@@ -1334,6 +1383,12 @@ def close_transition(
             and latest.get("artifacts") == artifact_entries
             and (executor is None or latest.get("executor") == executor)
         ):
+            paired = _ensure_phase_end_event(
+                contract_root,
+                phase=from_phase,
+                status=status,
+                executor=executor or str(latest.get("executor") or "unknown"),
+            )
             return {
                 "ok": True,
                 "code": "TRANSITION_ALREADY_CLOSED",
@@ -1341,6 +1396,7 @@ def close_transition(
                 "receipt": latest,
                 "path": str(paths["transitions"]),
                 "invalidation": None,
+                "phaseEndPair": paired,
             }
         return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
     try:
@@ -1397,6 +1453,12 @@ def close_transition(
     receipt["receiptHash"] = _payload_hash(receipt)
     _append_ndjson(paths["transitions"], receipt)
     paths["lease"].unlink(missing_ok=True)
+    paired = _ensure_phase_end_event(
+        contract_root,
+        phase=from_phase,
+        status=status,
+        executor=effective_executor,
+    )
     invalidation = None
     if to_phase == "execute" and from_phase in {"execute", "review"}:
         invalidation = _invalidate_for_fixback(
@@ -1411,6 +1473,7 @@ def close_transition(
         "receipt": receipt,
         "path": str(paths["transitions"]),
         "invalidation": invalidation,
+        "phaseEndPair": paired,
     }
 
 
@@ -1898,7 +1961,7 @@ def build_parser() -> argparse.ArgumentParser:
     prepare = sub.add_parser("prepare")
     prepare.add_argument("--json", action="store_true")
     prepare.add_argument("--project", required=True, type=Path)
-    prepare.add_argument("--change")
+    prepare.add_argument("--change", "--change-dir", dest="change")
     prepare.add_argument("--phase", required=True)
     prepare.add_argument("--executor", required=True)
     prepare.add_argument("--title")
@@ -1907,7 +1970,7 @@ def build_parser() -> argparse.ArgumentParser:
     bootstrap = sub.add_parser("bootstrap-plan")
     bootstrap.add_argument("--json", action="store_true")
     bootstrap.add_argument("--project", required=True, type=Path)
-    bootstrap.add_argument("--change", required=True)
+    bootstrap.add_argument("--change", "--change-dir", dest="change", required=True)
     bootstrap.add_argument("--executor", required=True)
     bootstrap.add_argument("--title")
     bootstrap.add_argument("--stage", default="plan", choices=["plan", "post-run"])
@@ -1915,7 +1978,7 @@ def build_parser() -> argparse.ArgumentParser:
     close = sub.add_parser("close")
     close.add_argument("--json", action="store_true")
     close.add_argument("--project", required=True, type=Path)
-    close.add_argument("--change", required=True)
+    close.add_argument("--change", "--change-dir", dest="change", required=True)
     close.add_argument("--from-phase", required=True)
     close.add_argument("--to-phase", required=True)
     close.add_argument("--executor", required=True)
@@ -1924,7 +1987,7 @@ def build_parser() -> argparse.ArgumentParser:
     begin = sub.add_parser("begin")
     begin.add_argument("--json", action="store_true")
     begin.add_argument("--project", required=True, type=Path)
-    begin.add_argument("--change", required=True)
+    begin.add_argument("--change", "--change-dir", dest="change", required=True)
     begin.add_argument("--phase", required=True)
     begin.add_argument("--executor", required=True)
     handoff = sub.add_parser(
@@ -1933,7 +1996,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     handoff.add_argument("--json", action="store_true")
     handoff.add_argument("--project", required=True, type=Path)
-    handoff.add_argument("--change", required=True)
+    handoff.add_argument("--change", "--change-dir", dest="change", required=True)
     handoff.add_argument("--to-phase", required=True)
     handoff.add_argument(
         "--from-phase",
@@ -1946,20 +2009,20 @@ def build_parser() -> argparse.ArgumentParser:
     )
     renew.add_argument("--json", action="store_true")
     renew.add_argument("--project", required=True, type=Path)
-    renew.add_argument("--change", required=True)
+    renew.add_argument("--change", "--change-dir", dest="change", required=True)
     renew.add_argument("--executor", required=True)
     renew.add_argument("--ttl-seconds", type=int, default=3600)
     configure = sub.add_parser("configure-plan")
     configure.add_argument("--json", action="store_true")
     configure.add_argument("--project", required=True, type=Path)
-    configure.add_argument("--change", required=True)
+    configure.add_argument("--change", "--change-dir", dest="change", required=True)
     configure.add_argument("--phases", required=True)
     configure.add_argument("--operator", required=True)
     configure.add_argument("--reason", required=True)
     view = sub.add_parser("view")
     view.add_argument("--json", action="store_true")
     view.add_argument("--project", required=True, type=Path)
-    view.add_argument("--change", required=True)
+    view.add_argument("--change", "--change-dir", dest="change", required=True)
     return parser
 
 

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

@@ -884,22 +884,32 @@ def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dic
 def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
     """Validate type-specific append fields before any file is mutated."""
     event_type = str(args.type)
-    for field in _EVENT_REQUIRED_FIELDS.get(event_type, ()):
-        value = getattr(args, field, None)
-        if value is None or (isinstance(value, str) and not value.strip()):
-            return (
-                "EVENT_REQUIRED_FIELD",
-                f"EVENT_REQUIRED_FIELD: {event_type} requires --{field.replace('_', '-')}",
-            )
+    missing = [
+        f"--{field.replace('_', '-')}"
+        for field in _EVENT_REQUIRED_FIELDS.get(event_type, ())
+        if getattr(args, field, None) is None
+        or (isinstance(getattr(args, field, None), str)
+            and not getattr(args, field).strip())
+    ]
+    if missing:
+        # 一次性列出全部缺失字段——逐个报错会让调用方每个字段往返一轮（E-3）
+        return (
+            "EVENT_REQUIRED_FIELD",
+            f"EVENT_REQUIRED_FIELD: {event_type} requires " + ", ".join(missing),
+        )
     allowed = _EVENT_ALLOWED_FIELDS[event_type]
-    for field in OPTIONAL_FIELDS:
-        value = getattr(args, field, None)
-        if value is not None and field not in allowed:
-            return (
-                "EVENT_FIELD_NOT_ALLOWED",
-                "EVENT_FIELD_NOT_ALLOWED: "
-                f"{event_type} does not accept --{field.replace('_', '-')}",
-            )
+    disallowed = [
+        f"--{field.replace('_', '-')}"
+        for field in OPTIONAL_FIELDS
+        if getattr(args, field, None) is not None and field not in allowed
+    ]
+    if disallowed:
+        # 一次列出全部不被接受的字段——逐个报错会让调用方每字段往返一轮（R-4）
+        return (
+            "EVENT_FIELD_NOT_ALLOWED",
+            f"EVENT_FIELD_NOT_ALLOWED: {event_type} does not accept "
+            + ", ".join(disallowed),
+        )
     for field, length in (("trace_id", 32), ("span_id", 16), ("parent_span_id", 16)):
         value = getattr(args, field, None)
         if value is not None and not re.fullmatch(rf"[0-9a-f]{{{length}}}", str(value)):
@@ -2146,7 +2156,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="append one event and auto-render execution-log",
     )
-    p_append.add_argument("--change-dir", required=True)
+    p_append.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_append.add_argument("--phase", required=True)
     p_append.add_argument("--type", required=True)
     p_append.add_argument("--command", default=None)
@@ -2200,7 +2210,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="validate and append many events under one lock (H-15)",
     )
-    p_batch.add_argument("--change-dir", required=True)
+    p_batch.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_batch.add_argument(
         "--file",
         required=True,
@@ -2213,7 +2223,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="re-render execution-log.md from events.ndjson",
     )
-    p_render.add_argument("--change-dir", required=True)
+    p_render.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_render.set_defaults(func=cmd_render)
 
     p_summary = sub.add_parser(
@@ -2221,7 +2231,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="summarize phases/issues from events.ndjson",
     )
-    p_summary.add_argument("--change-dir", required=True)
+    p_summary.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_summary.set_defaults(func=cmd_summary)
 
     return parser

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

@@ -75,6 +75,14 @@ def _write_json(path: Path, value: dict[str, Any]) -> None:
         temporary.unlink(missing_ok=True)
 
 
+def _read_json(path: Path) -> Any:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return value
+
+
 def _load(change_dir: Path, batch_id: str) -> dict[str, Any]:
     path = _batch_path(change_dir, batch_id)
     try:
@@ -1186,7 +1194,21 @@ def evidence_template(
         "provenance": provenance,
     }
     target = Path(out) if out else Path("runtime") / f"fixback-{resolved_id}.json"
-    path = target if target.is_absolute() else (change_dir / target)
+    if target.is_absolute():
+        path = target
+    else:
+        # F-3：与 ledger --out 同一类坑——相对路径已含 change-dir 前缀时直接拼
+        # change_dir 会产生嵌套幽灵目录（2026-08-31 实测）。前缀命中按 cwd 解析。
+        cwd = Path.cwd().resolve()
+        change_resolved = change_dir.resolve()
+        if _is_within(change_resolved, [cwd]):
+            change_rel = change_resolved.relative_to(cwd)
+            if target.parts[: len(change_rel.parts)] == change_rel.parts:
+                path = cwd / target
+            else:
+                path = change_dir / target
+        else:
+            path = change_dir / target
     path = path.resolve()
     if not _is_within(path, [change_dir.resolve(), state_root, _project_root(change_dir)]):
         return {
@@ -1708,6 +1730,20 @@ def close_batch(
         }
     )
     _write_json(_batch_path(change_dir, batch_id), batch)
+    # F-5：批次关闭会同步把托管会话置为 CLOSED——否则 session 永远 ACTIVE，
+    # 后续 launch-review 被 CONTEXT_PREPARATION_ACTIVE 幂等保护误拦（2026-08-31
+    # demo-datasource 实测）。
+    session_file = _session_path(change_dir)
+    session = _read_json(session_file)
+    if (
+        isinstance(session, dict)
+        and session.get("batchId") == batch_id
+        and session.get("status") == "ACTIVE"
+    ):
+        session["status"] = "CLOSED"
+        session["nextStep"] = "done"
+        session["updatedAt"] = closed_at
+        _write_json(session_file, session)
     return batch
 
 

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

@@ -2594,6 +2594,64 @@ def _normalize_gate_phase(args: argparse.Namespace, as_json: bool) -> int | None
     )
 
 
+def _verification_target_coverage_warning(
+    change_dir: Path, phase: str
+) -> dict[str, Any] | None:
+    """E-5：场景表引用未声明的 verification target 时提前 WARN。
+
+    场景带 execution_level（unit/integration/…），但 build-profile 的
+    verificationGraph.targets 未声明对应 target 时，问题要等到 ledger record
+    才以 unsupported verification 报错——太迟。gate begin 提前列出待补清单。
+    映射约定：unit → unitTest；其他 level → 任一以其名开头的 target。
+    """
+    if phase != "execute":
+        return None
+    manifest_path = change_dir / "meta" / "scenario-manifest.json"
+    profile_path = change_dir / "meta" / "build-profile.json"
+    if not profile_path.is_file():
+        # build-profile 常规位置在项目 .harness/config/；change meta 下优先
+        profile_path = change_dir.parents[2] / ".harness" / "config" / "build-profile.json"
+    if not manifest_path.is_file() or not profile_path.is_file():
+        return None
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
+        profile = json.loads(profile_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    content = manifest.get("content") if isinstance(manifest, dict) else None
+    scenarios = content.get("scenarios") if isinstance(content, dict) else None
+    if not isinstance(scenarios, list):
+        return None
+    levels = sorted({
+        str(s.get("execution_level")).strip()
+        for s in scenarios
+        if isinstance(s, dict) and str(s.get("execution_level") or "").strip()
+    })
+    graph = profile.get("verificationGraph")
+    targets = graph.get("targets") if isinstance(graph, dict) else None
+    target_names = set(targets.keys()) if isinstance(targets, dict) else set()
+    uncovered = [
+        level for level in levels
+        if level != "unit"
+        and not any(name.lower().startswith(level.lower()) for name in target_names)
+    ]
+    # unit 场景由 unitTest 覆盖；只在完全没有 unitTest 时才算缺口
+    if "unit" in levels and "unitTest" not in target_names:
+        uncovered.append("unit(→unitTest)")
+    if not uncovered:
+        return None
+    return {
+        "code": "VERIFICATION_TARGETS_UNDECLARED",
+        "message": (
+            "场景表涉及未声明的验证级别: " + ", ".join(uncovered) +
+            "；ledger record 将报 unsupported verification。请在 "
+            ".harness/config/build-profile.json 的 verificationGraph.targets "
+            "声明对应 target（如 integrationTest）"
+        ),
+        "uncoveredLevels": uncovered,
+    }
+
+
 def cmd_begin(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     normalized = _normalize_gate_phase(args, as_json)
@@ -2911,6 +2969,14 @@ def cmd_begin(args: argparse.Namespace) -> int:
         )
         raise
 
+    coverage_warning = _verification_target_coverage_warning(change_dir, args.phase)
+    if coverage_warning is not None:
+        gate_warnings.append(coverage_warning)
+        print(
+            f"[harness-gate] WARNING {coverage_warning['code']}: "
+            f"{coverage_warning['message']}",
+            file=sys.stderr,
+        )
     payload = {
         "ok": True,
         "code": "PHASE_BEGUN",
@@ -3039,6 +3105,20 @@ def _resume_closed_phase(
             for candidate in hctx.allowed_next_phases(project, change_id, args.phase)
             if hp.resolve_phase_name(candidate) != args.phase
         ]
+        # F-4：续跑路径同样——fixback 回环的 execute 关门应回 review 的后继
+        if args.phase == "execute" and isinstance(transitions, list) and transitions:
+            latest_t = transitions[-1]
+            if (
+                isinstance(latest_t, dict)
+                and hp.resolve_phase_name(latest_t.get("fromPhase")) == "review"
+                and hp.resolve_phase_name(latest_t.get("toPhase")) == "execute"
+                and latest_t.get("trigger") == "review-fixback"
+            ):
+                candidates = [
+                    candidate
+                    for candidate in hctx.allowed_next_phases(project, change_id, "review")
+                    if hp.resolve_phase_name(candidate) != args.phase
+                ]
         if to_phase is None and len(candidates) == 1:
             # 计划后继唯一（排除 fixback 自环）：close 的意图没有歧义，直接补跑 handoff
             to_phase = candidates[0]
@@ -3625,10 +3705,25 @@ def cmd_close(args: argparse.Namespace) -> int:
             and context_view.get("ok")
             and isinstance(context_view.get("current"), dict)
         ):
+            # F-4：fixback 回环（最新交接是 review→execute 且 trigger=
+            # review-fixback）关门时，后继不是再来一轮 review，而是 review
+            # 当时的计划后继（submit）。不按此处理会把 transitions 链写成
+            # …→review→execute→review 的语义错乱（2026-08-31 实测）。
+            source_phase = args.phase
+            transitions = context_view.get("transitions") or []
+            if args.phase == "execute" and transitions:
+                latest = transitions[-1]
+                if (
+                    isinstance(latest, dict)
+                    and hp.resolve_phase_name(latest.get("fromPhase")) == "review"
+                    and hp.resolve_phase_name(latest.get("toPhase")) == "execute"
+                    and latest.get("trigger") == "review-fixback"
+                ):
+                    source_phase = "review"
             forward = [
                 candidate
                 for candidate in hctx.allowed_next_phases(
-                    project, str(resolved["changeId"]), args.phase
+                    project, str(resolved["changeId"]), source_phase
                 )
                 if hp.resolve_phase_name(candidate) != args.phase
             ]
@@ -3800,11 +3895,25 @@ def cmd_classify(args: argparse.Namespace) -> int:
     payload["classifiedAt"] = classified_at
 
     if change_dir is not None and change_dir.is_dir():
-        policy_doc = gate_policy_document(payload)
-        policy_path = change_dir / "meta" / "gate-policy.json"
-        _write_json(policy_path, policy_doc)
-        payload["policyPersisted"] = True
-        payload["policyPath"] = str(policy_path)
+        finalized = (change_dir / "meta" / "plan-profile.json").is_file()
+        if finalized and not getattr(args, "force", False):
+            # P1-1：classify 形态像只读查询，实际是写操作。已发布的 change
+            # 被误跑 classify 会覆盖 configure-plan 写入的工作副本（2026-08-30
+            # demo-datasource 实测 plannedPhases 被清）。默认拒写并显式提示。
+            payload["policyPersisted"] = False
+            payload["warning"] = (
+                "change 已发布（meta/plan-profile.json 存在），classify 不再重写 "
+                "meta/gate-policy.json 工作副本；确需重算请显式传 --force"
+            )
+            payload["writeGuarded"] = True
+        else:
+            policy_doc = gate_policy_document(payload)
+            policy_path = change_dir / "meta" / "gate-policy.json"
+            _write_json(policy_path, policy_doc)
+            payload["policyPersisted"] = True
+            payload["policyPath"] = str(policy_path)
+            if finalized:
+                payload["warning"] = "--force：已发布 change 的工作副本已被重写"
     else:
         payload["policyPersisted"] = False
         payload["warning"] = (
@@ -3930,7 +4039,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_begin = sub.add_parser("begin", parents=[shared])
     p_begin.add_argument("--phase", required=True)
-    p_begin.add_argument("--change", default=None)
+    p_begin.add_argument("--change", "--change-dir", dest="change", default=None)
     p_begin.add_argument(
         "--project",
         default=None,
@@ -3960,7 +4069,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="关闭阶段门禁（关门只调本命令；上下文交接由 --to-phase 内联完成，不要再单独调 harness_context.py close）",
     )
     p_close.add_argument("--phase", required=True)
-    p_close.add_argument("--change", default=None)
+    p_close.add_argument("--change", "--change-dir", dest="change", default=None)
     p_close.add_argument(
         "--project",
         default=None,
@@ -3985,7 +4094,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_classify = sub.add_parser("classify", parents=[shared])
     p_classify.add_argument("--project", default=None, type=Path, help=_PROJECT_ROOT_HELP)
-    p_classify.add_argument("--change", default=None)
+    p_classify.add_argument("--change", "--change-dir", dest="change", default=None)
     p_classify.add_argument("--stage", required=True, choices=["plan", "post-run"])
     p_classify.add_argument(
         "--tier-override",
@@ -3993,13 +4102,18 @@ def build_parser() -> argparse.ArgumentParser:
         choices=["fast", "standard", "full"],
     )
     p_classify.add_argument("--override-by", default="user")
+    p_classify.add_argument(
+        "--force",
+        action="store_true",
+        help="已发布 change 也强制重写 gate-policy.json 工作副本",
+    )
     p_classify.set_defaults(func=cmd_classify)
 
     p_checkpoint = sub.add_parser("checkpoint", parents=[shared])
     p_checkpoint.add_argument("--project", default=None, type=Path, help=_PROJECT_ROOT_HELP)
     p_checkpoint.add_argument("checkpoint_action", choices=["status", "approve"])
     p_checkpoint.add_argument("--id", required=True)
-    p_checkpoint.add_argument("--change", default=None)
+    p_checkpoint.add_argument("--change", "--change-dir", dest="change", default=None)
     p_checkpoint.add_argument("--reviewer", default=None)
     p_checkpoint.set_defaults(func=cmd_checkpoint)