@hunter-harness/workflow-harness 0.2.76 → 0.2.78

package/harness/bundles/java/cursor/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/java/cursor/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/java/cursor/scripts/harness_runtime.py

@@ -1578,7 +1578,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 +1651,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 +2033,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 +2088,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/manifests/general/claude-code.json

@@ -2,9 +2,9 @@
   "schema_version": 2,
   "profile": "general",
   "adapter": "claude-code",
-  "bundle_version": "0.2.65",
+  "bundle_version": "0.2.67",
   "requires": {
-    "minimumCliVersion": "0.2.84",
+    "minimumCliVersion": "0.2.86",
     "capabilities": [
       "sync@2",
       "rules-sync@1",
@@ -25,7 +25,7 @@
   "files": [
     {
       "path": ".harness-build.json",
-      "sha256": "afc63fd684e23521c2f50072e6cca9b7f1b2b8888b5d6297006e4a4734dece62"
+      "sha256": "cc158bb89a59e384d0b343e7f3c52a874a5ea7879a7aea66709e7b9b98c4dcaa"
     },
     {
       "path": "agents/harness-evaluator.md",
@@ -97,7 +97,7 @@
     },
     {
       "path": "harness-archive/SKILL.md",
-      "sha256": "6f4b9061fac582da91d6f49e9c9366cb9c9db7b43e5a9826ce6698c0c82666ae"
+      "sha256": "f81ef9835b374ba758f0d6fad02fb7112411856c7f5406027876e33fb61b8648"
     },
     {
       "path": "harness-archive/templates/summary-data-template.json",
@@ -113,7 +113,7 @@
     },
     {
       "path": "harness-codebase-map/SKILL.md",
-      "sha256": "96c33bd02dc458171174eef38036a4ecd8ca55a8d40c5b9eff9d5082baa01da9"
+      "sha256": "e52941ab45203d0ca3a784429b428523124829adc83f971ef6098c0064b72b90"
     },
     {
       "path": "harness-codebase-map/templates/ARCHITECTURE.md",
@@ -153,11 +153,11 @@
     },
     {
       "path": "harness-knowledge-ingest/SKILL.md",
-      "sha256": "6661efc406f2ce89547afcc375b44688a43cde96a83b487d56701a2e7e85b055"
+      "sha256": "8fdf89699db58fc4aec5585da55f6a1f9952cdec4f5b594365504c35e0de8094"
     },
     {
       "path": "harness-knowledge-query/SKILL.md",
-      "sha256": "032e4123cb0c61233aa6674f9fdc93617edea856f20cf526c350d86d7a3aa3b4"
+      "sha256": "415ae4026c2e43df75a86d7f1685e31c1474c53a0f75844399d7435a77be6ee0"
     },
     {
       "path": "harness-plan/checklist.md",
@@ -173,15 +173,15 @@
     },
     {
       "path": "harness-plan/SKILL.md",
-      "sha256": "5b4d279fc3c8708d6050195e6195bfb688edb3fc63d18320886d0e960f6c6a57"
+      "sha256": "6a19ce510aa26f773b0562171fd099b8a22cdbe0fb34d395e34ed0c414745dfd"
     },
     {
       "path": "harness-pull/SKILL.md",
-      "sha256": "b6746c4de3f880f5e8bf6b84868ce915c4eb078a3344d4de24f77c18d6cb27b0"
+      "sha256": "9b5d350dbb6f3f2a77b44bfe2038251c868fac6ddc048a1b7883f4b93515727f"
     },
     {
       "path": "harness-push/SKILL.md",
-      "sha256": "0d96f9391fc090d7d5c0ff9f443b9d81c762ac08d53d41dc1346e1eb44eedba6"
+      "sha256": "582b2ee80d72649ec51efbe4f60d52fea4c59a5addf9db316a116e5562b7d2de"
     },
     {
       "path": "harness-review/checklist.md",
@@ -197,7 +197,7 @@
     },
     {
       "path": "harness-review/SKILL.md",
-      "sha256": "1e087a09f1d81cc3e12be17869cd40d47ed8c9f2f54bea2471d051a95d827f4b"
+      "sha256": "699d69c44a8bbfe13badf6d4ec7ad9cdb6513f818fb7ef56becf80cc8e1ad6fb"
     },
     {
       "path": "harness-run/checklist.md",
@@ -213,7 +213,7 @@
     },
     {
       "path": "harness-run/SKILL.md",
-      "sha256": "2417fb4b0f261735c7e130ff3e7146568ad74aa41c5844b562c6420b6edf5f25"
+      "sha256": "a6e72fa4bffb277237904c482a915c66f53287e78dcd83975c100ba7763d5a48"
     },
     {
       "path": "harness-submit/checklist.md",
@@ -225,7 +225,7 @@
     },
     {
       "path": "harness-submit/SKILL.md",
-      "sha256": "4e2f38d337bc848db1f93852369e421f4f0827afa213efd19354cae798bc0ca5"
+      "sha256": "6956d9e69fa4c7ce78761a90980e66f3ec2a8df727443e3ab6ccb7327eae164f"
     },
     {
       "path": "harness-sync/reference.md",
@@ -233,7 +233,7 @@
     },
     {
       "path": "harness-sync/SKILL.md",
-      "sha256": "0d6a7937acf93cccab0a1d9545c5fc065d0db874a4740908b5c1516b279f3284"
+      "sha256": "cdfc86c932e9a2e41879cc136b5adf00f0447f55fbe43e218111e9a95102d737"
     },
     {
       "path": "harness-test/checklist.md",
@@ -257,7 +257,7 @@
     },
     {
       "path": "harness-test/SKILL.md",
-      "sha256": "67b2095d756cd3d7b2b14875b97c1df4b55ec1402c21e12903569e4d4efecc6b"
+      "sha256": "c51e8ee818ffb7078341d634ad357eb205bd16cb3f788902703fd55bbf478c56"
     },
     {
       "path": "protocols/archive-report-protocol.md",
@@ -293,7 +293,7 @@
     },
     {
       "path": "protocols/powershell-protocol.md",
-      "sha256": "948d217c9d651f1f9060efc2f869cc4e0f7172b516283966d027154d683c3a89"
+      "sha256": "6812ea19e75474a2ab668854c4d08f693e0cc2a577c3ec0542f0d3811883f4fa"
     },
     {
       "path": "protocols/registry-governance-protocol.md",
@@ -329,7 +329,7 @@
     },
     {
       "path": "scripts/harness_archive.py",
-      "sha256": "2637b2a82bfbd6c594183bb35cfa9ba8c42e8c77f67ccdecce628066f93d8048"
+      "sha256": "c90932fb5234281a6d3e75b818580c12820373084c03815dc8d17d1f49955253"
     },
     {
       "path": "scripts/harness_change.py",
@@ -337,11 +337,11 @@
     },
     {
       "path": "scripts/harness_check_gate.py",
-      "sha256": "9cae8f7fc2ff4519b0c27566b9d5aaa81bd8921153ec1f9534cb5d08af3a21b3"
+      "sha256": "a4965d22d27bc4105db24a55e1fb6d1f94f7c1e970c75b809e470130df53814c"
     },
     {
       "path": "scripts/harness_context.py",
-      "sha256": "352ab9104dd4821930311411c353fe0b98e02ef0833f4f4ccf4f4190a5cb4eeb"
+      "sha256": "e61bbeb3073d77a34ac9aefb13421c187a8d16c8f95597d1ca50d91b0c6af1d2"
     },
     {
       "path": "scripts/harness_deploy.py",
@@ -369,7 +369,7 @@
     },
     {
       "path": "scripts/harness_fixback.py",
-      "sha256": "709fdf91e37286a5e1bf90b8b4d6b81355fe8185650867c862fa1f5d9f0ff6fe"
+      "sha256": "287bac38427c7fe60de5384d2b867df9d4cf7be2fd03fbffa307f3ac63b55bfd"
     },
     {
       "path": "scripts/harness_gate.py",
@@ -383,9 +383,13 @@
       "path": "scripts/harness_integration.py",
       "sha256": "cded86ca9fb6b87301945b4d81919e5d0301730c0bb75c925e0d4c8246851d30"
     },
+    {
+      "path": "scripts/harness_knowledge_candidates.py",
+      "sha256": "efbc52faa1f01053e033c3a609ab99a0a3df153567a7fb89558f6b3a87e041f7"
+    },
     {
       "path": "scripts/harness_ledger.py",
-      "sha256": "239d80d9d2c448e5bc8e456df517ad2b2f70281f9de10cf167d53085c6cecaf2"
+      "sha256": "476832333a63089fe312d9fb288b9e8a51d081a44b30548e1dac9a2b8298e0fb"
     },
     {
       "path": "scripts/harness_migration_head.py",
@@ -437,7 +441,7 @@
     },
     {
       "path": "scripts/harness_runtime.py",
-      "sha256": "493edc124eda6b79be6242c7d94ec8d619cb14ff134afbfa154795749374091c"
+      "sha256": "b02c4953d9237bdebf308fb61f6cda55b7f377a01102fe635196d443421f7a2f"
     },
     {
       "path": "scripts/harness_service.py",