@hunter-harness/workflow-harness 0.2.76 → 0.2.78

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "c36ef57a49412e5c"
+  "coreHash": "5fc6a7ba2a0556ad"
 }

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -221,11 +221,13 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 su
 | 上传 | 载什么 | 结果在哪 |
 |------|--------|---------|
 | `steps.archive_push` | 归档 ZIP（核心产物） | `archiveId`/`archiveStatus`/`uploadStatus`/`knowledgeStatus`，同时落盘 `state/local/archive-packages/<cn>.remote.json` |
-| `steps.managed_snapshot_push` | **归档交付物（每个变更目录的 `plans/`、`spec/`、`reports/`、`docs/`）、`.harness/codebase` 架构地图、`.harness/rules`、`.harness/project.yaml`、指令入口** | `ok`/`reasonCode`/`exitCode`/`cliCode`/`detail` |
+| `steps.managed_snapshot_push` | **归档交付物（每个变更目录的 `plans/`、`spec/`、`docs/` 全部，`reports/` 只取 `final/` 定稿）、`.harness/codebase` 架构地图、`.harness/rules`、`.harness/project.yaml`、指令入口** | `ok`/`reasonCode`/`exitCode`/`cliCode`/`detail` |
 
 走 `harness-push`（remote-sync，产生分支快照）而非 legacy `push`（proposal 管道）。
 归档目录下的 `runtime/`、`meta/`、`evidence/`、`logs/`、`fixback/`、`.publication-staging/`
-等过程文件不上传；交付物目录里的 `*.log`、`*.tmp`、凭证与 `.env*` 也仍被安全规则拦下。
+等过程文件不上传；`reports/review/` 与 `reports/test/` 同样是过程产物，不上传——
+这条边界与归档 ZIP 的包内容边界一致。交付物目录里的 `*.log`、`*.tmp`、凭证与 `.env*`
+也仍被安全规则拦下。
 
 ```
 远端归档：arc_3ff325bb…（archiveStatus=durable，uploadStatus=ready，knowledgeStatus=ready，8 文件）

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

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

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=c36ef57a49412e5c; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=5fc6a7ba2a0556ad; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -196,6 +196,26 @@ Windows 默认常为 Windows PowerShell **5.1**。下列特性在 5.1 不可用
 - 非 ASCII 路径（含中文）仓库：git/构建/文件操作一律 PowerShell；Bash 被 hook 拒绝（如 `Denied: non-ASCII path`）后**立即**改用 PowerShell 重发等价命令，禁止原样重试 Bash。
 - Maven `-D` 参数在 PowerShell 中加引号：`"-Dmaven.test.skip=true"`。
 
+### 捕获子进程中文输出：`$env:PYTHONUTF8=1` 不够
+
+`PYTHONUTF8=1` 只让 **Python 按 UTF-8 输出**，不改变 **PowerShell 按什么编码读**。
+控制台代码页是 GBK(936) 时，PowerShell 会用 GBK 解码 UTF-8 字节，得到形如
+`绫?javadoc 鏈�闅� 6 绾х簿绠€` 的乱码——内容已在捕获阶段损坏，落进报告、回执与
+JSON 字段后无法还原。
+
+调用任何会输出中文的子进程前，**必须同时设置输出编码**：
+
+```powershell
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+$env:PYTHONUTF8 = 1
+python harness/scripts/harness_fixback.py <子命令> --json
+```
+
+- 两行缺一不可：只设 `PYTHONUTF8` 会乱码，只设 `OutputEncoding` 则 Python 可能仍按本地编码输出。
+- 写脚本时把这两行放在脚本开头，不要依赖调用方记得加。
+- 少用 `2>&1` 合并流：PowerShell 5.1 会把 stderr 包装成 `NativeCommandError`，
+  与编码问题叠加后更难判断真实失败原因；需要 stderr 时分开捕获。
+
 ## 13. PS5/PS7 原生参数合同
 
 复杂 JSON、Docker Go template、here-string 内容及多层引号不得作为 native process 的内联参数跨 `Bash → powershell -Command → native executable` 传递。统一写 UTF-8 JSON 参数文件：

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

@@ -91,6 +91,7 @@ import harness_events as he  # noqa: E402
 import harness_events_sync as hes  # noqa: E402
 import harness_efficiency as heff  # noqa: E402
 import harness_gate as hgate  # noqa: E402
+import harness_knowledge_candidates as hkc  # noqa: E402
 import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
 import harness_phase as hphase  # noqa: E402
@@ -4173,6 +4174,33 @@ def write_archive_meta(work_dir: Path, summary: dict[str, Any]) -> Path:
     return out
 
 
+def write_knowledge_candidates(work_dir: Path, summary: dict[str, Any]) -> Path:
+    """Generate candidates/knowledge.json from summary-data (single ownership).
+
+    Mirrors write_archive_meta: derived from the same summary, written before the
+    after-manifest so its bytes are covered. The archive directory name is the
+    archive id, matching write_archive_meta's `archive-id` field.
+    """
+    archive_id = work_dir.name
+    candidates = hkc.build_knowledge_candidates(
+        summary,
+        change_key=str(summary.get("changeName") or archive_id),
+        archive_id=archive_id,
+        # The archive schema version identifies the producing format; there is
+        # no separate harness version constant to borrow here.
+        producer_version=SCHEMA_VERSION,
+        created_at=now_iso(),
+    )
+    out = work_dir / "candidates" / "knowledge.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(
+        hkc.render_knowledge_candidates_json(candidates),
+        encoding="utf-8",
+        newline="\n",
+    )
+    return out
+
+
 
 
 def _changed_files_from_git(
@@ -8269,6 +8297,21 @@ def cmd_finalize(
         warnings.append(f"archive-meta write failed: {exc}")
         payload["steps"]["archive_meta"] = {"ok": False, "error": str(exc)}
 
+    # --- 8b. knowledge candidates (also before the after-manifest) ---
+    # Soft-fail like archive-meta: an archive must never be rolled back because
+    # knowledge extraction found nothing. An empty array is a valid outcome.
+    try:
+        summary = read_json(summary_path)
+        candidates_path = write_knowledge_candidates(work_dir, summary)
+        payload["steps"]["knowledge_candidates"] = {
+            "ok": True,
+            "path": str(candidates_path),
+            "count": len(read_json(candidates_path)),
+        }
+    except Exception as exc:  # noqa: BLE001 — candidates soft-fail
+        warnings.append(f"knowledge candidates write failed: {exc}")
+        payload["steps"]["knowledge_candidates"] = {"ok": False, "error": str(exc)}
+
     # --- 9/10. final summary stats, then LAST manifest (IA-7) ---
     # Post-manifest rewrites of covered bytes are forbidden. We update the
     # summary first, regenerate after-manifest last, then verify on-disk hashes.
@@ -8885,6 +8928,12 @@ def _archive_core_file_specs(
                     file_specs.append(
                         (source, f"{folder}/{relative}", role, "text/markdown")
                     )
+    add_if_file(
+        archive / "candidates" / "knowledge.json",
+        "candidates/knowledge.json",
+        "knowledge_candidates",
+        "application/json",
+    )
     add_if_file(
         archive / "meta" / "archive-meta.md",
         "archive-meta.md",
@@ -8913,6 +8962,8 @@ def _archive_source_identity(project_root: Path) -> dict[str, str | None]:
                 ["git", *args],
                 cwd=str(project_root),
                 text=True,
+                encoding="utf-8",
+                errors="replace",
                 stdout=subprocess.PIPE,
                 stderr=subprocess.DEVNULL,
                 timeout=10,
@@ -9449,6 +9500,10 @@ def auto_push_archive_core(
             command,
             cwd=str(project_root),
             text=True,
+            # 不指定 encoding 时中文 Windows 按 cp936 解码 UTF-8，
+            # CLI 的中文回执会被损坏，随后的 json.loads 也可能失败。
+            encoding="utf-8",
+            errors="replace",
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             timeout=180,

package/harness/bundles/general/claude-code/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/claude-code/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/claude-code/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: "