@hunter-harness/workflow-harness 0.4.3 → 0.4.8

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

@@ -121,6 +121,11 @@ def emit_error(
         sys.stderr.write(json.dumps(payload, ensure_ascii=False) + "\n")
     else:
         sys.stderr.write(f"error: {message} ({code})\n")
+        # 文本模式同样给出恢复指引——--json 的 recoveryAction 一直有，
+        # 但人类读的恰恰是文本模式（2026-08-30 实测：用户翻文档才找到 claim 命令）
+        recovery = payload.get("recoveryAction")
+        if isinstance(recovery, str) and recovery:
+            sys.stderr.write(f"recovery: {recovery}\n")
     return 1
 
 
@@ -1967,12 +1972,20 @@ def validate_context_for_gate_begin(
         return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
     current_phase = str(current.get("phase") or view.get("currentPhase") or "")
     if hp.resolve_phase_name(current_phase) != phase:
+        candidates = hctx.allowed_next_phases(project, change_id, current_phase)
         return {
             "ok": False,
             "code": "CONTEXT_HANDOFF_REQUIRED",
             "message": "阶段交接尚未完成，门禁未启动；请先完成上下文交接。",
             "expectedPhase": current_phase or None,
             "requestedPhase": phase,
+            "recoveryAction": (
+                f"当前上下文停留在 {current_phase} 阶段。一条命令补齐交接"
+                "（自动补租约→写收据→begin 确认，无需 change claim/release）："
+                f"harness_context.py handoff --project . --change {change_id} "
+                f"--to-phase {phase} --executor <tool> --json"
+                + (f"（计划后继阶段：{'/'.join(candidates)}）" if candidates else "")
+            ),
         }
     if isinstance(transitions, list) and transitions:
         latest = transitions[-1] if isinstance(transitions[-1], dict) else {}
@@ -1990,6 +2003,12 @@ def validate_context_for_gate_begin(
                 "code": "CONTEXT_BEGIN_REQUIRED",
                 "message": "阶段交接收据尚未确认，门禁未启动；请先执行上下文 begin。",
                 "requestedPhase": phase,
+                "recoveryAction": (
+                    "交接收据已写入但缺 begin 确认。一条命令补齐："
+                    f"harness_context.py handoff --project . --change {change_id} "
+                    f"--to-phase {phase} --executor <tool> --json"
+                    "（检测到收据已存在时只补 begin 确认，不写重复 receipt）"
+                ),
             }
     return {"ok": True, "code": "CONTEXT_READY"}
 
@@ -2503,7 +2522,11 @@ def validate_review_outputs_for_close(
             "code": "REVIEW_OUTPUTS_INCOMPLETE",
             "message": "评审的结构化发现或处置记录缺失，尚不能结束评审阶段。",
             "missing": missing,
-            "recoveryAction": "补写 review-findings.json 与 fixback-dispositions.json 后重试关门",
+            "recoveryAction": (
+                "用骨架生成器补写：harness_review.py scaffold --change-dir <change-dir>"
+                "（无 findings 时先生成发现骨架→write-findings 落地→重跑 scaffold "
+                "生成处置骨架→write-dispositions 落地），再重试关门"
+            ),
         }
     try:
         findings = json.loads(findings_path.read_text(encoding="utf-8-sig"))
@@ -2930,6 +2953,169 @@ def cmd_begin(args: argparse.Namespace) -> int:
     return 0
 
 
+def _emit_close_summary(
+    code: str,
+    phase: str,
+    status: str,
+    to_phase: str | None,
+    *,
+    derived: bool = False,
+) -> None:
+    """关门成功的一行摘要（stderr，不污染 stdout 的 JSON 契约）。"""
+    suffix = "(auto)" if derived and to_phase else ""
+    sys.stderr.write(
+        f"{code} · phase={phase} · status={status} · next={to_phase or '-'}{suffix}\n"
+    )
+
+
+def _finalize_close_journal(
+    change_dir: Path,
+    phase: str,
+    run_id: str,
+    close_status: str,
+) -> None:
+    """续跑成功后把 capsule 的 closeTransaction 收口为 CLOSED（best-effort）。"""
+    if not run_id:
+        return
+    try:
+        capsule = load_phase_capsule(change_dir, phase, run_id)
+    except (OSError, ValueError):
+        capsule = None
+    if not isinstance(capsule, dict):
+        return
+    transaction = capsule.get("closeTransaction")
+    if not isinstance(transaction, dict):
+        return
+    transaction.update({
+        "status": "CLOSED",
+        "retryable": False,
+        "leaseReleased": True,
+        "updatedAt": he.now_iso(),
+    })
+    capsule["closedAt"] = he.now_iso()
+    capsule["closeStatus"] = close_status
+    try:
+        write_phase_capsule(change_dir, phase, run_id, capsule)
+    except OSError:
+        pass
+
+
+def _resume_closed_phase(
+    project: Path,
+    resolved: dict[str, Any],
+    args: argparse.Namespace,
+    terminal: dict[str, Any],
+    *,
+    as_json: bool,
+) -> int:
+    """phase.end 已写、租约已释放、收尾未走完的幂等续跑。
+
+    这个中间态是"租约释放早于后续步骤"（或输出中断）留下的：本地关门事实
+    已经存在，剩下的 handoff/monitor/recovery/scratch 全部幂等。识别并补跑，
+    而不是报 LEASE_ABSENT 逼调用方手工 claim 重取租约（2026-08-30 实测路径）。
+    """
+    change_id = str(resolved["changeId"])
+    change_dir = Path(resolved["changeDir"])
+    run_id = str(terminal.get("run_id") or getattr(args, "run_id", None) or "")
+    close_status = str(terminal.get("status") or args.status)
+    to_phase = getattr(args, "to_phase", None)
+
+    view = hctx.context_view(project, change_id)
+    transitions = view.get("transitions") if isinstance(view, dict) else None
+    handoff_recorded = isinstance(transitions, list) and any(
+        isinstance(item, dict)
+        and hp.resolve_phase_name(item.get("fromPhase")) == args.phase
+        for item in transitions
+    )
+
+    handoff: dict[str, Any] | None = None
+    derived_to_phase: str | None = None
+    if handoff_recorded:
+        # 交接收据已在 transitions.ndjson——重放 close_transition 也只会幂等命中
+        handoff = {"ok": True, "code": "TRANSITION_ALREADY_CLOSED", "resumed": True}
+    else:
+        candidates = [
+            candidate
+            for candidate in hctx.allowed_next_phases(project, change_id, args.phase)
+            if hp.resolve_phase_name(candidate) != args.phase
+        ]
+        if to_phase is None and len(candidates) == 1:
+            # 计划后继唯一（排除 fixback 自环）：close 的意图没有歧义，直接补跑 handoff
+            to_phase = candidates[0]
+            args.to_phase = to_phase
+            derived_to_phase = to_phase
+        if to_phase is None and candidates:
+            return emit_error(
+                "PHASE_HANDOFF_PENDING",
+                "phase gate already closed locally (phase.end recorded), but the context "
+                "handoff is still pending and the successor is ambiguous; re-run with --to-phase",
+                as_json=as_json,
+                extra={
+                    "localCloseComplete": True,
+                    "retryable": True,
+                    "phase": args.phase,
+                    "status": close_status,
+                    "changeId": change_id,
+                    "candidateNextPhases": candidates,
+                    "recoveryAction": (
+                        "本地关门已完成（phase.end 已写、租约已释放），只剩上下文交接。"
+                        "不需要重新 claim 租约——用原命令补 --to-phase 重跑即幂等续跑："
+                        "python <skills-root>/scripts/harness_gate.py close "
+                        f"--phase {args.phase} --change {change_id} --status {close_status} "
+                        f"--to-phase <{'|'.join(candidates)}> --json"
+                    ),
+                },
+            )
+        if to_phase is not None:
+            handoff = _close_context_handoff(
+                project,
+                change_id,
+                args,
+                status=close_status,
+            )
+    monitor = _sync_after_phase_close(project, change_dir)
+    if isinstance(handoff, dict) and not handoff.get("ok"):
+        return emit_error(
+            "PHASE_HANDOFF_PENDING",
+            "phase gate is closed, but context handoff still needs attention",
+            as_json=as_json,
+            extra={
+                "localCloseComplete": True,
+                "retryable": True,
+                "contextHandoff": handoff,
+                "platformMonitor": monitor,
+            },
+        )
+    recovery_result = record_gate_recovered(
+        change_dir,
+        phase=args.phase,
+        run_id=run_id,
+    )
+    try:
+        scratch_swept = hruntime.sweep_scratch(change_dir)
+    except Exception as exc:  # noqa: BLE001 — 收尾步骤失败只记录，绝不阻断续跑
+        scratch_swept = {"ok": False, "code": "SCRATCH_SWEEP_FAILED", "error": str(exc)}
+    _finalize_close_journal(change_dir, args.phase, run_id, close_status)
+    emit(
+        {
+            "ok": True,
+            "code": "PHASE_CLOSE_RESUMED",
+            "phase": args.phase,
+            "status": close_status,
+            "changeId": change_id,
+            "localCloseComplete": True,
+            "contextHandoff": handoff,
+            "platformMonitor": monitor,
+            "gateRecovery": recovery_result,
+            "scratchSwept": scratch_swept,
+            **({"derivedToPhase": derived_to_phase} if derived_to_phase else {}),
+        },
+        as_json=as_json,
+    )
+    _emit_close_summary("PHASE_CLOSE_RESUMED", args.phase, close_status, to_phase, derived=derived_to_phase is not None)
+    return 0
+
+
 def cmd_close(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     normalized = _normalize_gate_phase(args, as_json)
@@ -3043,47 +3229,13 @@ def cmd_close(args: argparse.Namespace) -> int:
 
     if current_lease is None:
         terminal = _latest_phase_end(change_dir, args.phase, explicit_run_id)
-        if (
-            getattr(args, "to_phase", None)
-            and terminal is not None
-            and _terminal_matches_context_session(
-                project, str(resolved["changeId"]), args.phase, terminal
-            )
+        if terminal is not None and _terminal_matches_context_session(
+            project, str(resolved["changeId"]), args.phase, terminal
         ):
-            terminal_status = str(terminal.get("status") or args.status)
-            handoff = _close_context_handoff(
-                project,
-                str(resolved["changeId"]),
-                args,
-                status=terminal_status,
-            )
-            monitor = _sync_after_phase_close(project, change_dir)
-            if not isinstance(handoff, dict) or not handoff.get("ok"):
-                return emit_error(
-                    "PHASE_HANDOFF_PENDING",
-                    "phase gate is closed, but context handoff still needs attention",
-                    as_json=as_json,
-                    extra={
-                        "localCloseComplete": True,
-                        "retryable": True,
-                        "contextHandoff": handoff,
-                        "platformMonitor": monitor,
-                    },
-                )
-            emit(
-                {
-                    "ok": True,
-                    "code": "PHASE_CLOSE_RESUMED",
-                    "phase": args.phase,
-                    "status": terminal_status,
-                    "changeId": resolved["changeId"],
-                    "localCloseComplete": True,
-                    "contextHandoff": handoff,
-                    "platformMonitor": monitor,
-                },
-                as_json=as_json,
-            )
-            return 0
+            # phase.end 已写且属于当前会话：本地关门已完成，租约缺失是历史运行的
+            # 释放顺序（或输出中断）留下的中间态——幂等续跑剩余步骤，与是否携带
+            # --to-phase 无关；后继未显式给出时从计划派生（唯一后继自动补跑）。
+            return _resume_closed_phase(project, resolved, args, terminal, as_json=as_json)
         resume_run_id = explicit_run_id or _latest_open_run_id(change_dir, args.phase)
         return emit_error(
             "LEASE_ABSENT",
@@ -3457,39 +3609,32 @@ def cmd_close(args: argparse.Namespace) -> int:
         close_transaction["updatedAt"] = he.now_iso()
         write_phase_capsule(change_dir, args.phase, run_id, capsule)
 
-    release = hc.release_lease(
-        project,
-        change_id=resolved["changeId"],
-        phase=args.phase,
-        run_id=run_id,
-    )
-    if not release.get("ok"):
-        if capsule is not None:
-            close_transaction.update({
-                "status": "RELEASE_PENDING",
-                "retryable": True,
-                "lastError": release,
-                "updatedAt": he.now_iso(),
-            })
-            write_phase_capsule(change_dir, args.phase, run_id, capsule)
-        return emit_error(
-            str(release.get("code", "LEASE_RELEASE_FAILED")),
-            str(release.get("message", "lease release failed")),
-            as_json=as_json,
-            extra={k: v for k, v in release.items() if k not in {"ok", "message", "code"}},
-        )
-
-    if capsule is not None:
-        close_transaction.update({
-            "status": "CLOSED",
-            "retryable": False,
-            "leaseReleased": True,
-            "updatedAt": he.now_iso(),
-        })
-        capsule["closedAt"] = he.now_iso()
-        capsule["closeStatus"] = close_status
-        write_phase_capsule(change_dir, args.phase, run_id, capsule)
-
+    # 租约释放必须是关门的最后一个可失败步骤。历史上它排在 handoff/monitor
+    # 之前，一旦中途失败就留下“phase.end 已写 + 租约已放 + 交接没写”的三不管
+    # 状态，重试直接死在 LEASE_ABSENT（2026-08-30 sales-insight-agent 实测）。
+    # 现在顺序为：handoff → monitor → recovery → scratch → release → emit；
+    # 任何中途失败时租约仍持有，重试同一命令按 closeTransaction journal 幂等续跑。
+    # P0-1：plain close 不得静默跳过交接。上下文状态存在且计划后继唯一
+    # （排除 fixback 自环）时自动派生后继并执行交接——断链从根上消失；
+    # 多后继仍要求显式 --to-phase。
+    derived_to_phase: str | None = None
+    if not getattr(args, "to_phase", None):
+        context_view = hctx.context_view(project, str(resolved["changeId"]))
+        if (
+            isinstance(context_view, dict)
+            and context_view.get("ok")
+            and isinstance(context_view.get("current"), dict)
+        ):
+            forward = [
+                candidate
+                for candidate in hctx.allowed_next_phases(
+                    project, str(resolved["changeId"]), args.phase
+                )
+                if hp.resolve_phase_name(candidate) != args.phase
+            ]
+            if len(forward) == 1:
+                derived_to_phase = forward[0]
+                args.to_phase = derived_to_phase
     context_handoff = _close_context_handoff(
         project,
         str(resolved["changeId"]),
@@ -3517,6 +3662,10 @@ def cmd_close(args: argparse.Namespace) -> int:
                 "changeId": resolved["changeId"],
                 "contextHandoff": context_handoff,
                 "platformMonitor": platform_monitor,
+                "recoveryAction": (
+                    "租约仍持有，无需重新 claim——原样重跑同一 close 命令即可幂等续跑"
+                    "（phase.end 已落会跳过，handoff 会重试）"
+                ),
             },
         )
 
@@ -3530,9 +3679,50 @@ def cmd_close(args: argparse.Namespace) -> int:
     # 直接把归档挡住了。白名单式删除，证据/报告/运行态一律不碰；失败只记不阻断。
     try:
         scratch_swept = hruntime.sweep_scratch(change_dir)
-    except OSError as exc:
+    except Exception as exc:  # noqa: BLE001 — 清草稿是收尾便利，任何失败都不得阻断关门
         scratch_swept = {"ok": False, "code": "SCRATCH_SWEEP_FAILED", "error": str(exc)}
 
+    release = hc.release_lease(
+        project,
+        change_id=resolved["changeId"],
+        phase=args.phase,
+        run_id=run_id,
+    )
+    if not release.get("ok"):
+        if capsule is not None:
+            close_transaction.update({
+                "status": "RELEASE_PENDING",
+                "retryable": True,
+                "lastError": release,
+                "updatedAt": he.now_iso(),
+            })
+            write_phase_capsule(change_dir, args.phase, run_id, capsule)
+        return emit_error(
+            str(release.get("code", "LEASE_RELEASE_FAILED")),
+            str(release.get("message", "lease release failed")),
+            as_json=as_json,
+            extra={
+                **{k: v for k, v in release.items() if k not in {"ok", "message", "code"}},
+                "localCloseComplete": True,
+                "retryable": True,
+                "recoveryAction": (
+                    "本地关门与上下文交接均已完成，仅租约释放失败——原样重跑同一 close "
+                    "命令即幂等续跑（phase.end/handoff 幂等命中，仅重试释放）"
+                ),
+            },
+        )
+
+    if capsule is not None:
+        close_transaction.update({
+            "status": "CLOSED",
+            "retryable": False,
+            "leaseReleased": True,
+            "updatedAt": he.now_iso(),
+        })
+        capsule["closedAt"] = he.now_iso()
+        capsule["closeStatus"] = close_status
+        write_phase_capsule(change_dir, args.phase, run_id, capsule)
+
     payload = {
         "ok": True,
         "code": close_code,
@@ -3553,11 +3743,21 @@ def cmd_close(args: argparse.Namespace) -> int:
         "gateRecovery": recovery_result,
         "scratchSwept": scratch_swept,
     }
+    if derived_to_phase is not None:
+        # plain close 自动派生的后继，调用方必须看得到这不是显式选择。
+        payload["derivedToPhase"] = derived_to_phase
     if lease_lapsed is not None:
         # 与 context transition receipt 的 leaseLapsed 同名同义：记录这个阶段
         # 跑过了 TTL 且租约是自动重取的，不隐藏。
         payload["leaseLapsed"] = lease_lapsed
     emit(payload, as_json=as_json)
+    _emit_close_summary(
+        close_code,
+        args.phase,
+        close_status,
+        getattr(args, "to_phase", None),
+        derived=derived_to_phase is not None,
+    )
     return 0
 
 
@@ -3754,7 +3954,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_begin.add_argument("--executor-model", default=None)
     p_begin.set_defaults(func=cmd_begin)
 
-    p_close = sub.add_parser("close", parents=[shared])
+    p_close = sub.add_parser(
+        "close",
+        parents=[shared],
+        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(

package/harness/bundles/general/cursor/scripts/harness_review.py

@@ -575,6 +575,115 @@ def cmd_write_dispositions(args: argparse.Namespace) -> int:
     return _emit(write_dispositions(Path(args.change_dir), doc), as_json=True)
 
 
+def _latest_review_run_id(change_dir: Path) -> str | None:
+    """从 events.ndjson 取最近一轮 review phase.start 的 run_id（best-effort）。"""
+    candidates = [change_dir / "events.ndjson"]
+    state_events = _state_dir(change_dir) / "events.ndjson"
+    if state_events != candidates[0]:
+        candidates.append(state_events)
+    run_id: str | None = None
+    for path in candidates:
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            try:
+                item = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if (
+                isinstance(item, dict)
+                and item.get("type") == "phase.start"
+                and item.get("phase") == "review"
+                and isinstance(item.get("run_id"), str)
+                and item["run_id"].strip()
+            ):
+                run_id = item["run_id"]
+    return run_id
+
+
+def scaffold(change_dir: Path, run_id: str | None) -> dict[str, Any]:
+    """按当前轮次生成 review-findings / fixback-dispositions 的写入骨架。
+
+    sidecar 的 schema 以前只能从 harness_review.py 源码里挖；骨架直接能喂给
+    write-findings / write-dispositions --stdin，消除手拼 JSON 的整类错误。
+    已有 findings 时，骨架为每条 finding 生成一条占位处置（disposition=OPEN，
+    由调用方逐条改判），并复用 findings 的 runId，保证两份 sidecar 同属一轮。
+    """
+    change_dir = Path(change_dir)
+    findings_doc = _load_findings(change_dir)
+    if findings_doc is not None:
+        effective_run_id = str(findings_doc.get("runId") or "").strip()
+        if not effective_run_id:
+            return {
+                "ok": False,
+                "code": "FINDINGS_RUN_ID_MISSING",
+                "problems": ["review-findings.json 缺少 runId，无法生成同轮处置骨架"],
+            }
+        dispositions = [
+            {"findingId": f["id"], "disposition": "OPEN"}
+            for f in findings_doc.get("findings", [])
+            if isinstance(f, dict) and isinstance(f.get("id"), str)
+        ]
+        return {
+            "ok": True,
+            "code": "REVIEW_SCAFFOLD_DISPOSITIONS",
+            "runId": effective_run_id,
+            "dispositionsInput": {
+                "schemaVersion": 1,
+                "runId": effective_run_id,
+                "dispositions": dispositions,
+            },
+            "writeCommand": (
+                "harness_review.py write-dispositions "
+                f"--change-dir {change_dir} --stdin"
+            ),
+            "note": "逐条把 disposition 改判为 FIXED/ACCEPTED_RISK/DEFERRED/NOT_APPLICABLE；"
+            "OPEN 表示待修复，gate 关门时所有 finding 都必须有处置记录。",
+        }
+    effective_run_id = (run_id or "").strip() or _latest_review_run_id(change_dir)
+    if not effective_run_id:
+        return {
+            "ok": False,
+            "code": "SCAFFOLD_RUN_ID_REQUIRED",
+            "problems": [
+                "无法从 events.ndjson 推断本轮 review runId；请显式传 --run-id"
+            ],
+        }
+    return {
+        "ok": True,
+        "code": "REVIEW_SCAFFOLD_FINDINGS",
+        "runId": effective_run_id,
+        "findingsInput": {
+            "schemaVersion": 1,
+            "runId": effective_run_id,
+            "changeName": change_dir.name,
+            "findings": [],
+            "_exampleFinding": {
+                "dimension": "正确性",
+                "severity": "YELLOW",
+                "path": "src/example.ts",
+                "line": 1,
+                "title": "一句话问题标题",
+                "fixbackAction": "code",
+            },
+        },
+        "writeCommand": (
+            f"harness_review.py write-findings --change-dir {change_dir} --stdin"
+        ),
+        "note": "无发现时保持 findings 为空数组即合法；write-findings 会为每条 "
+        "finding 分配稳定 id。落地后重跑 scaffold 生成对应的处置骨架。",
+    }
+
+
+def cmd_scaffold(args: argparse.Namespace) -> int:
+    return _emit(
+        scaffold(Path(args.change_dir), getattr(args, "run_id", None)),
+        as_json=True,
+    )
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     return _emit(status(Path(args.change_dir)), as_json=True)
 
@@ -611,6 +720,17 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_dispositions.set_defaults(func=cmd_write_dispositions)
 
+    p_scaffold = sub.add_parser(
+        "scaffold",
+        help="按当前轮次生成 review-findings / fixback-dispositions 的写入骨架",
+    )
+    p_scaffold.add_argument("--change-dir", required=True)
+    p_scaffold.add_argument(
+        "--run-id",
+        help="本轮 review runId；缺省从 events.ndjson 最新的 review phase.start 推断",
+    )
+    p_scaffold.set_defaults(func=cmd_scaffold)
+
     p_status = sub.add_parser("status")
     p_status.add_argument("--change-dir", required=True)
     p_status.set_defaults(func=cmd_status)

package/harness/bundles/general/cursor/scripts/harness_runtime.py

@@ -324,6 +324,7 @@ def _sensitive_candidates(
                 for pattern in (_SENSITIVE_ASSIGNMENT, _AUTHORIZATION_ASSIGNMENT)
                 for match in pattern.finditer(raw)
                 if not _is_sensitive_placeholder(match.group("value"))
+                and not _is_harness_internal_key(raw, match)
             ),
             None,
         )
@@ -337,6 +338,18 @@ def _sensitive_candidates(
     return candidates
 
 
+def _is_harness_internal_key(raw: bytes, match: re.Match[bytes]) -> bool:
+    """harness 自己生成的系统字段不是用户秘密。
+
+    plan finalize 发布日志（meta/publication-journals/*.json）里的
+    ``recovery_token`` 是内部续跑凭证，会被通用 ``token`` 规则误伤
+    （2026-08-30 sales-insight-agent archive 实测：两个发布日志串行阻断）。
+    正则从关键字（如 ``token``）处起匹配，豁免看关键字前面的字段名前缀。
+    """
+    prefix = raw[max(0, match.start() - 16):match.start()]
+    return bool(re.search(rb'(?i)recovery_["\']?$', prefix))
+
+
 def _is_sensitive_placeholder(value: bytes) -> bool:
     text = value.decode("utf-8", errors="ignore").strip().strip("`'").strip()
     return bool(

package/harness/bundles/general/pi/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "pi",
-  "coreHash": "f56294054b3b6088"
+  "coreHash": "626fde5b3e847963"
 }

package/harness/bundles/general/pi/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=f56294054b3b6088; overlay=none; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=626fde5b3e847963; overlay=none; agent=pi; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -126,11 +126,12 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 `execute` 内部运行自动门禁。实际计划最后阶段已终态、边界快照存在且 `status.archivable=true` 时直接执行；未满足时返回阻断且不移动原目录。用户取消后不得重跑。
 
-### 二·A、两个常见阻断的正规出路（不要自己拼 python -c）
+### 二·A、常见阻断的正规出路（不要自己拼 python -c）
 
 | 阻断 | 出路 |
 |------|------|
-| `SENSITIVE_EVIDENCE_UNQUARANTINED`（默认只告警，`HUNTER_HARNESS_SENSITIVE_SCAN=block` 时才阻断） | `python <skills-root>/scripts/harness_runtime.py quarantine-evidence --project . --change-dir ".harness/changes/<cn>" --file "<相对 change-dir 的路径>" --reason "<为什么是敏感证据>" --json`（`--file` 可重复）。私有根默认已与项目同盘、且在项目根之外——**不要**手工指定项目内的路径，归档的密钥扫描会以 `SECRET_SCAN_PRIVATE_PATH_IN_COPY_ROOT` 拒绝 |
+| `PROJECT_RELEASE_POLICY_BLOCKED` / `LOCAL_RELEASE_NOT_AUTHORIZED`（本地可复现证据未获发布授权） | `python <skills-root>/scripts/harness_change.py allow-local-release --change <cn> --json`（在 `meta/gate-policy.json` 写入 `candidateVerification.allowLocalRelease=true`，幂等，保留既有策略内容）。**不要**手改 `gate-policy.json` |
+| `SENSITIVE_EVIDENCE_UNQUARANTINED`（默认只告警，`HUNTER_HARNESS_SENSITIVE_SCAN=block` 时才阻断） | 报错的 `nextAction` 自带含全部 `--file` 的完整命令；等价于 `python <skills-root>/scripts/harness_runtime.py quarantine-evidence --project . --change-dir ".harness/changes/<cn>" --file "<相对 change-dir 的路径>" --reason "<为什么是敏感证据>" --json`（`--file` 可重复）。私有根默认已与项目同盘、且在项目根之外——**不要**手工指定项目内的路径，归档的密钥扫描会以 `SECRET_SCAN_PRIVATE_PATH_IN_COPY_ROOT` 拒绝。harness 自生成发布日志里的 `recovery_token` 是系统字段，0.4.7（workflow-harness）起扫描器已豁免，无需隔离 |
 | `DIFF_ZERO_WITH_NONEMPTY_COMMIT`（提交范围非空但 filesChanged=0） | 契约缺 `ownership.productPaths`，全部改动被判为 `foreignPaths`。用 `python <skills-root>/scripts/harness_change.py declare-ownership --change <cn> --product-path "<目录前缀或精确文件>" --json` 按计划的实际改动范围声明（可重复；只收精确路径，不支持通配）。**不要**手改 `change-context.json` |
 
 ### 二·A·1、发布内容预检与服务端 422

package/harness/bundles/general/pi/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=f56294054b3b6088; overlay=none; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=626fde5b3e847963; overlay=none; agent=pi; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose