@hunter-harness/workflow-harness 0.2.77 → 0.2.79

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

@@ -36,6 +36,8 @@ def _git_output(args: list[str]) -> str | None:
             cwd=str(ROOT),
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=5,
         )
     except (OSError, subprocess.SubprocessError):

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

@@ -184,6 +184,8 @@ def _head(project: Path) -> str | None:
     process = subprocess.run(
         ["git", "-C", str(project), "rev-parse", "--verify", "HEAD"],
         text=True,
+        encoding="utf-8",
+        errors="replace",
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         check=False,
@@ -196,6 +198,8 @@ def _git_common_dir(project: Path) -> Path | None:
     process = subprocess.run(
         ["git", "-C", str(project), "rev-parse", "--git-common-dir"],
         text=True,
+        encoding="utf-8",
+        errors="replace",
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         check=False,

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

@@ -587,6 +587,13 @@ def launch_review_fixback(
         "transition": begun,
         "gate": gate,
         "batch": batch,
+        # 证据要求随开批次一起交底：晚一步暴露，调用方就已经改完代码，
+        # 只能回退伪造 RED。
+        "evidenceContract": evidence_contract(
+            change_dir=str(change_dir),
+            batch_id=str(batch.get("batchId") or ""),
+            product_identity=str(batch.get("productIdentity") or ""),
+        ),
     }
 
 
@@ -802,12 +809,102 @@ def _resolve_evidence_path(change_dir: Path, raw_path: str) -> Path:
     )
     path = next((candidate for candidate in candidates if candidate.is_file()), None)
     if path is None:
-        raise ValueError(f"FIXBACK_EVIDENCE_MISSING: {raw_path}")
+        raise ValueError(evidence_error_message("FIXBACK_EVIDENCE_MISSING", raw_path))
     if not _is_within(path, [contract_root, state_root, project_root]):
-        raise ValueError(f"FIXBACK_EVIDENCE_OUTSIDE_PROJECT: {raw_path}")
+        raise ValueError(
+            evidence_error_message("FIXBACK_EVIDENCE_OUTSIDE_PROJECT", raw_path)
+        )
     return path
 
 
+def evidence_contract(
+    *,
+    change_dir: str | None = None,
+    batch_id: str | None = None,
+    product_identity: str | None = None,
+) -> dict[str, Any]:
+    """开批次时就交出证据契约，而不是等 resolve-issue 报错才逼调用方逆向。
+
+    契约本身没变过：每个 code 项需要一条修复前的 RED（会话 FAIL）与一条修复后的
+    GREEN（会话 OK），两者都必须是 run-start 产出的托管会话证据，且先注册后引用。
+    问题在于它此前只写在实现里——调用方通常已经改完代码才发现 RED 要"修复前"，
+    于是把改动回退、跑一次假 RED、再改回来，凭空多出一轮返工与一段脏工作树。
+    """
+    change = change_dir or "<change-dir>"
+    batch = batch_id or "<batch-id>"
+    product = product_identity or "<product-identity>"
+    return {
+        "why": "RED 证明问题真实存在，GREEN 证明修复真的生效；缺任一条都无法关批次。",
+        "order": [
+            "1. 修复前：先用 run-start 跑一次能复现该问题的命令，得到 status=FAIL 的会话（RED）",
+            "2. 实施修复",
+            "3. 修复后：用同一条命令再跑一次 run-start，得到 status=OK 的会话（GREEN）",
+            "4. 两条证据各写一个 JSON 文件，分别 register-evidence 注册",
+            "5. resolve-issue 引用这两个已注册的证据文件",
+        ],
+        "antiPattern": (
+            "不要先改完再把修改回退来凑 RED：那样 RED 证明的只是回退后的状态，"
+            "不是原始缺陷，中途还会留下脏工作树。"
+        ),
+        "commands": {
+            "collectSession": (
+                "python harness_runtime.py run-start --state-root "
+                f"{change} --verification <名称> --working-directory . "
+                f"--product-identity {product} --json -- <复现/验证命令>"
+            ),
+            "awaitSession": (
+                "python harness_runtime.py run-status --state-root "
+                f"{change} --session-id <sessionId> --wait --json"
+            ),
+            "register": (
+                "python harness_fixback.py register-evidence --change-dir "
+                f"{change} --evidence <证据 JSON 路径>"
+            ),
+            "resolve": (
+                "python harness_fixback.py resolve-issue --change-dir "
+                f"{change} --batch-id {batch} --issue-id <issueId> "
+                "--red-evidence <red.json> --green-evidence <green.json>"
+            ),
+        },
+        "evidenceFile": {
+            "schemaVersion": 2,
+            "kind": ["red", "green"],
+            "status": {"red": "FAIL", "green": "OK"},
+            "provenance": {
+                "type": "managed-run-session",
+                "note": "指向 run-start 产出的 runtime/run-sessions/<sessionId>/session.json",
+            },
+        },
+    }
+
+
+_EVIDENCE_ERROR_HINTS = {
+    "FIXBACK_EVIDENCE_MISSING": (
+        "路径未找到证据文件。它应当是 run-start 产出的托管会话证据 JSON"
+        "（schemaVersion=2，kind=red|green，provenance.type=managed-run-session）；"
+        "先用 run-start 采集会话，再据此写证据文件。"
+    ),
+    "FIXBACK_EVIDENCE_UNREGISTERED": (
+        "证据文件存在但未注册，或注册后内容已变。"
+        "先执行 register-evidence 注册（内容改动后需重新注册），再引用。"
+    ),
+    "FIXBACK_EVIDENCE_INVALID": (
+        "证据文件不是合法的 schemaVersion=2 托管会话证据。"
+        "检查 kind / status / provenance 三个字段。"
+    ),
+    "FIXBACK_EVIDENCE_OUTSIDE_PROJECT": (
+        "证据路径落在项目之外。证据必须放在变更目录或项目内，便于随归档留痕。"
+    ),
+}
+
+
+def evidence_error_message(code: str, raw_path: str) -> str:
+    """把只回显路径的错误码，补成能直接照做的一句话。"""
+    hint = _EVIDENCE_ERROR_HINTS.get(code)
+    base = f"{code}: {raw_path}"
+    return base if hint is None else f"{base} — {hint}"
+
+
 def register_evidence(change_dir: Path, raw_path: str) -> dict[str, Any]:
     """Register evidence only after validating its authoritative provenance."""
     path = _resolve_evidence_path(change_dir, raw_path)
@@ -968,7 +1065,9 @@ def _evidence_record(
         or ledger_record.get("productIdentity") != evidence_product
         or ledger_record.get("passedGates") != sorted(set(passed_gates))
     ):
-        raise ValueError(f"FIXBACK_EVIDENCE_UNREGISTERED: {raw_path}")
+        raise ValueError(
+            evidence_error_message("FIXBACK_EVIDENCE_UNREGISTERED", raw_path)
+        )
     if product_identity is not None and evidence_product != product_identity:
         raise ValueError(
             "FIXBACK_EVIDENCE_IDENTITY_MISMATCH: "

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

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Knowledge candidate generation from an archived change's summary-data.json.
+
+The archive workflow has already filtered once: review findings were produced by
+an independent reviewer and then adjudicated, and knownRisks are evidence-derived
+facts. This module turns those two — and only those two — into KnowledgeCandidate
+records for the archive package's ``candidates/knowledge.json``.
+
+Mapping is fixed by docs/superpowers/specs/2026-08-18-three-views-data-flow-design.md
+("知识来源的选定")::
+
+    disposition = FIXED                      -> pitfall   RED 0.95 / YELLOW 0.85
+    disposition = ACCEPTED_RISK | DEFERRED   -> risk      RED 0.95 / YELLOW 0.85
+    knownRisks[]                             -> risk      0.85
+    severity = OK | disposition = NOT_APPLICABLE -> dropped
+
+Dispositions outside the adopted set (OPEN / UNKNOWN) are dropped too: an
+unadjudicated finding is not yet knowledge. maintenanceNotes, finalStatusReasons
+and manualActions are deliberately excluded — the spec evaluated each and found
+them too noisy or empty to be worth persisting.
+
+No LLM is involved. Every emitted field is copied or derived from a real
+summary-data field, so the output is reproducible and free of invention.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+SCHEMA_VERSION = 1
+PRODUCER = "harness-archive"
+
+# Only these severities carry knowledge; OK is explicitly dropped by the spec.
+_SEVERITIES = {"RED", "YELLOW"}
+# Adjudicated dispositions the spec adopts, mapped to the knowledge entry type.
+_DISPOSITION_ENTRY_TYPES = {
+    "FIXED": "pitfall",
+    "ACCEPTED_RISK": "risk",
+    "DEFERRED": "risk",
+}
+_SEVERITY_CONFIDENCE = {"RED": 0.95, "YELLOW": 0.85}
+_KNOWN_RISK_CONFIDENCE = 0.85
+
+_MAX_KEYWORDS = 32
+_MAX_KEYWORD_CHARS = 80
+_MAX_BODY_CHARS = 20_000
+
+
+def _text(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _digest(*parts: str) -> str:
+    return hashlib.sha256("\0".join(parts).encode("utf-8")).hexdigest()
+
+
+def _candidate_id(change_key: str, kind: str, identity: str) -> str:
+    return f"kc_{_digest(change_key, kind, identity)[:32]}"
+
+
+def _content_hash(entry_type: str, summary: str, body: str, keywords: list[str]) -> str:
+    canonical = json.dumps(
+        {"entry_type": entry_type, "summary": summary, "body": body, "keywords": keywords},
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _keywords(*values: str) -> list[str]:
+    """Deduplicate, preserve order, and honour the contract's bounds."""
+    seen: list[str] = []
+    for value in values:
+        keyword = _text(value)[:_MAX_KEYWORD_CHARS]
+        if keyword and keyword not in seen:
+            seen.append(keyword)
+    return seen[:_MAX_KEYWORDS]
+
+
+def _path_segments(path: str) -> list[str]:
+    return [segment for segment in path.replace("\\", "/").split("/") if segment]
+
+
+def _location(path: str, line: Any) -> str:
+    """``path:line`` when the line number is real, otherwise just the path."""
+    if not path:
+        return ""
+    if isinstance(line, bool) or not isinstance(line, int) or line < 1:
+        return path
+    return f"{path}:{line}"
+
+
+def _finding_candidate(
+    finding: dict[str, Any],
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> dict[str, Any] | None:
+    severity = _text(finding.get("severity"))
+    disposition = _text(finding.get("disposition"))
+    entry_type = _DISPOSITION_ENTRY_TYPES.get(disposition)
+    title = _text(finding.get("title"))
+    if severity not in _SEVERITIES or entry_type is None or not title:
+        return None
+
+    path = _text(finding.get("path"))
+    line = finding.get("line")
+    location = _location(path, line)
+    segments = _path_segments(path)
+    finding_id = _text(finding.get("id"))
+
+    body_lines = [title]
+    if location:
+        body_lines.append(f"位置：{location}")
+    body_lines.append(f"严重度：{severity}")
+    body_lines.append(f"裁决：{disposition}")
+    body = "\n".join(body_lines)[:_MAX_BODY_CHARS]
+
+    keywords = _keywords(
+        segments[-1] if segments else "",
+        segments[-2] if len(segments) >= 2 else "",
+        severity,
+        disposition,
+    )
+    source_ref = f"archive:{archive_id}#{finding_id}" if finding_id else f"archive:{archive_id}"
+    if path and location != path:
+        source_refs = [f"{path}#L{line}"]
+    elif path:
+        source_refs = [path]
+    else:
+        source_refs = [f"archive:{archive_id}"]
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "candidate_id": _candidate_id(
+            change_key, "review", finding_id or f"{title}\0{path}\0{line}"
+        ),
+        "source_change_key": change_key,
+        "source_refs": source_refs,
+        "summary": title,
+        "reusability_scope": segments[0] if segments else "project",
+        "content_hash": _content_hash(entry_type, title, body, keywords),
+        "confidence": _SEVERITY_CONFIDENCE[severity],
+        "status": "pending",
+        "entry_type": entry_type,
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": "review",
+            "source_ref": source_ref,
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
+
+
+def _risk_candidate(
+    risk: dict[str, Any],
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> dict[str, Any] | None:
+    message = _text(risk.get("message"))
+    if not message:
+        return None
+    phase = _text(risk.get("phase"))
+    severity = _text(risk.get("severity"))
+
+    body_lines = [message]
+    if phase:
+        body_lines.append(f"阶段：{phase}")
+    if severity:
+        body_lines.append(f"严重度：{severity}")
+    body = "\n".join(body_lines)[:_MAX_BODY_CHARS]
+    keywords = _keywords(phase, severity)
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "candidate_id": _candidate_id(change_key, "known_risk", f"{phase}\0{message}"),
+        "source_change_key": change_key,
+        "source_refs": [f"archive:{archive_id}"],
+        "summary": message,
+        "reusability_scope": phase or "project",
+        "content_hash": _content_hash("risk", message, body, keywords),
+        "confidence": _KNOWN_RISK_CONFIDENCE,
+        "status": "pending",
+        "entry_type": "risk",
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": "archive",
+            "source_ref": f"archive:{archive_id}",
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
+
+
+def build_knowledge_candidates(
+    summary: dict[str, Any],
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Project reviewFindings + knownRisks into KnowledgeCandidate records.
+
+    Returns [] for missing or malformed input: an archive with nothing worth
+    persisting must still produce a valid (empty) candidates file.
+    """
+    if not isinstance(summary, dict):
+        return []
+    candidates: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+
+    def collect(candidate: dict[str, Any] | None) -> None:
+        if candidate is None or candidate["candidate_id"] in seen_ids:
+            return
+        seen_ids.add(candidate["candidate_id"])
+        candidates.append(candidate)
+
+    findings = summary.get("reviewFindings")
+    if isinstance(findings, list):
+        for finding in findings:
+            if isinstance(finding, dict):
+                collect(_finding_candidate(
+                    finding,
+                    change_key=change_key,
+                    archive_id=archive_id,
+                    producer_version=producer_version,
+                    created_at=created_at,
+                ))
+
+    risks = summary.get("knownRisks")
+    if isinstance(risks, list):
+        for risk in risks:
+            if isinstance(risk, dict):
+                collect(_risk_candidate(
+                    risk,
+                    change_key=change_key,
+                    archive_id=archive_id,
+                    producer_version=producer_version,
+                    created_at=created_at,
+                ))
+
+    return candidates
+
+
+def render_knowledge_candidates_json(candidates: list[dict[str, Any]]) -> str:
+    """Deterministic bytes for the archive package entry."""
+    return json.dumps(
+        candidates, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ) + "\n"

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

@@ -444,6 +444,8 @@ def infer_execution_project_root(change_dir: Path) -> Path | None:
         process = subprocess.run(
             ["git", "-C", str(root), "rev-parse", "--path-format=absolute", "--git-common-dir"],
             text=True,
+            encoding="utf-8",
+            errors="replace",
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             check=False,
@@ -461,6 +463,8 @@ def infer_execution_project_root(change_dir: Path) -> Path | None:
         process = subprocess.run(
             ["git", "-C", str(candidate), "rev-parse", "--show-toplevel"],
             text=True,
+            encoding="utf-8",
+            errors="replace",
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             check=False,

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

@@ -217,10 +217,14 @@ def _secure_private_path(path: Path, *, directory: bool) -> str:
 
 def _sensitive_candidates(root: Path) -> list[dict[str, Any]]:
     """Find high-confidence plaintext assignments without treating prose as a secret."""
-    receipt = _sensitive_evidence_receipt_path(root)
+    # Compare by relative path, not by resolve() per file: this loop covers the
+    # whole change tree, and on Windows each resolve() is a realpath syscall.
+    receipt_rel = SECRET_SCAN_RECEIPT_REL.as_posix()
     candidates: list[dict[str, Any]] = []
     for path in sorted(root.rglob("*")):
-        if not path.is_file() or path.resolve() == receipt.resolve():
+        if not path.is_file():
+            continue
+        if path.relative_to(root).as_posix() == receipt_rel:
             continue
         try:
             raw = path.read_bytes()
@@ -1578,7 +1582,7 @@ def _run_session_worker_with_log(state_root: Path, session_id: str) -> int:
             return _run_session_worker(state_root, session_id)
 
 
-def run_session_status(state_root: Path, session_id: str) -> dict[str, Any]:
+def _run_session_status_raw(state_root: Path, session_id: str) -> dict[str, Any]:
     from harness_service import is_pid_alive
 
     receipt = _load_run_receipt(state_root, session_id)
@@ -1651,6 +1655,65 @@ def run_session_status(state_root: Path, session_id: str) -> dict[str, Any]:
     return receipt
 
 
+# 终态判定此前只活在脚本内部的 RUN_TERMINAL_STATUSES 里，从不出现在返回体中。
+# 调用方于是只能按状态名猜——而 "INCOMPLETE" 读起来最像"还没结束"，实际是终态。
+# 2026-08-18 的一次 fixback 执行里，一个启动即失败（LAUNCHER_FAILED）的会话
+# 被连等 20s、60s，纯属这个缺口造成的浪费。
+_TERMINAL_HINTS = {
+    "LAUNCHER_FAILED": (
+        "被测进程未能启动（testProcessStarted=false），不是超时；"
+        "先核对 argv 的可执行文件在该工作目录下能否直接运行，再重跑 run-start。"
+    ),
+    "HEARTBEAT_LOST": "worker 心跳丢失，会话已判定结束；日志可能不完整。",
+    "WORKER_IDENTITY_MISMATCH": "worker 身份校验不通过，会话已终止且未采信其结果。",
+    "WORKER_EXITED_WITHOUT_FINAL_RECEIPT": "worker 未写最终回执即退出。",
+}
+
+
+def _annotate_run_status(receipt: dict[str, Any]) -> dict[str, Any]:
+    """给回执补上可判定的终态标记与可行动线索。
+
+    FINALIZING 刻意判为非终态：结果虽已确定，但 worker 尚未退出，
+    调用方此时取读数会与清理竞争。
+    """
+    status = receipt.get("status")
+    terminal = status in RUN_TERMINAL_STATUSES and status != "FINALIZING"
+    annotated = dict(receipt)
+    annotated["terminal"] = bool(terminal)
+    hint = _TERMINAL_HINTS.get(str(receipt.get("reasonCode") or ""))
+    if terminal and hint is not None:
+        annotated["terminalHint"] = hint
+    return annotated
+
+
+def run_session_status(state_root: Path, session_id: str) -> dict[str, Any]:
+    return _annotate_run_status(_run_session_status_raw(state_root, session_id))
+
+
+def await_run_session(
+    state_root: Path,
+    session_id: str,
+    *,
+    timeout_seconds: float = 600.0,
+    poll_seconds: float = 2.0,
+) -> dict[str, Any]:
+    """阻塞到会话进入终态，或超时后带 waitTimedOut 标记返回。
+
+    没有这个入口时，调用方只能 `sleep <猜一个时长>` 再查一次；上述执行日志里
+    连猜了 5s / 20s / 60s / 100s 四轮。等待逻辑属于会话语义，应由这里承担。
+    """
+    deadline = time.monotonic() + max(float(timeout_seconds), 0.0)
+    while True:
+        current = run_session_status(state_root, session_id)
+        if current.get("terminal") is True:
+            current["waitTimedOut"] = False
+            return current
+        if time.monotonic() >= deadline:
+            current["waitTimedOut"] = True
+            return current
+        time.sleep(max(float(poll_seconds), 0.01))
+
+
 def read_run_session_log(
     state_root: Path,
     session_id: str,
@@ -1974,6 +2037,13 @@ def build_parser() -> argparse.ArgumentParser:
     p_status = sub.add_parser("run-status", help="read a managed run receipt")
     p_status.add_argument("--state-root", required=True)
     p_status.add_argument("--session-id", required=True)
+    p_status.add_argument(
+        "--wait",
+        action="store_true",
+        help="阻塞到会话进入终态再返回，替代调用方自己 sleep 猜时长",
+    )
+    p_status.add_argument("--wait-timeout-seconds", type=float, default=600.0)
+    p_status.add_argument("--poll-seconds", type=float, default=2.0)
     p_status.add_argument("--json", action="store_true")
     p_log = sub.add_parser("run-log", help="read an incremental log page")
     p_log.add_argument("--state-root", required=True)
@@ -2022,7 +2092,15 @@ def main(argv: list[str] | None = None) -> int:
                 resource_locks=list(args.resource_lock),
             )
         elif args.command == "run-status":
-            result = run_session_status(Path(args.state_root), args.session_id)
+            if getattr(args, "wait", False):
+                result = await_run_session(
+                    Path(args.state_root),
+                    args.session_id,
+                    timeout_seconds=args.wait_timeout_seconds,
+                    poll_seconds=args.poll_seconds,
+                )
+            else:
+                result = run_session_status(Path(args.state_root), args.session_id)
         elif args.command == "run-log":
             result = read_run_session_log(
                 Path(args.state_root),

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "38a69f76225f5fab"
+  "coreHash": "c8c212940eb5848d"
 }

package/harness/bundles/general/codex/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=38a69f76225f5fab; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c8c212940eb5848d; overlay=none; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -130,9 +130,24 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 | 阻断 | 出路 |
 |------|------|
-| `SENSITIVE_EVIDENCE_UNQUARANTINED` | `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` 拒绝 |
+| `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` 拒绝 |
 | `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` |
 
+### 二·B、归档补传（上传失败或历史归档缺条目）
+
+归档上传成功后 ZIP 与回执会被清理，旧版本产生的归档从未入 outbox——所以
+`harness-push --scope archive` 找不到可复用的包属于正常状态，不是故障。补传从已封存的
+归档目录重建确定性包：
+
+```powershell
+python <skills-root>/scripts/harness_archive.py republish --change <change-key> --dry-run --json   # 只看包内容
+python <skills-root>/scripts/harness_archive.py republish --change <change-key> --json             # 重建并上传
+```
+
+归档目录是封存的（after-manifest 覆盖其每个字节），因此 `republish` **不写回**归档目录：
+缺失的 `candidates/knowledge.json` 只在内存中按已归档 summary 生成并放进包里。平台的知识
+条目只来自这个包；`--scope all` 走的是 branch_file 通道，不进知识管道。
+
 ### 三、文件移动只用内置工具或 PowerShell
 
 移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。

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

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

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=38a69f76225f5fab; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c8c212940eb5848d; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/general/codex/harness-knowledge-query/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=38a69f76225f5fab; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c8c212940eb5848d; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/general/codex/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=38a69f76225f5fab; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c8c212940eb5848d; overlay=none; agent=codex; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/codex/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=38a69f76225f5fab; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c8c212940eb5848d; overlay=none; agent=codex; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose