npm - @hunter-harness/workflow-harness - Versions diffs - 0.3.0 → 0.4.0 - Mend

@hunter-harness/workflow-harness 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (162) hide show

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

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

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 ## Purpose

package/harness/bundles/general/claude-code/harness-archive/reference.md CHANGED Viewed

@@ -67,10 +67,39 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 - `changedFiles`：path/summary/insertions/deletions —— 来自 `git diff --numstat <base>..<head>`；
 - `reviewSummary`：red/yellow + redFixed/redConfirmed/yellowFixed/yellowDeferred 修复进度；
 - `maintenanceNotes`：给后续维护者看的结论；
-- `knownRisks`：剩余风险或人工确认项。
+- `knownRisks`：剩余风险或人工确认项；
+- `decisions`：已采纳的设计决策/需求/API 契约 —— 来自 `evidence/decisions.json`（见下节），生成器只做校验与透传，不从 markdown 提取。
 报告必须突出业务目标和维护者结论。所有统计数字只能来自 events、summary-data、ledger 或 manifest，不得手写另一套。历史 archive 没有 `events.ndjson` 时，允许从 ledger/log/manifest 回放，并在 `reportPipeline.sources` 中记录来源。
+## evidence/decisions.json（可选，知识沉淀入口）
+重要设计决策、长期约束、API 契约要进入平台知识库的唯一通道：在 plan/execute/review 阶段由人或 agent 把**已采纳**的结论写入 `.harness/changes/<change>/evidence/decisions.json`（schema_version 1）：
+```json
+{
+  "schema_version": 1,
+  "decisions": [
+    {
+      "id": "D-001",
+      "title": "一句话结论（必填，≤500 字）",
+      "rationale": "为什么（可选，≤4000 字）",
+      "entry_type": "decision | requirement | api-contract",
+      "status": "adopted | proposed | rejected | superseded",
+      "path": "docs/design/x.md（可选，相对路径，溯源用）",
+      "line": 42,
+      "keywords": ["可选，≤32 个"],
+      "source": "plan | review | manual | archive"
+    }
+  ]
+}
+```
+- 只有 `status: "adopted"` 的记录会成为知识候选（`entry_type` 原样落到知识条目上）；其余状态保留在 summary 里做记录。
+- 与 reviewFindings 的裁决门槛同源：**筛选必须在上游发生**——不要把讨论过程原文倒进来，归档时不做任何 LLM 提取。
+- 不合 schema 的记录会被丢弃并在 `maintenanceNotes` 留一条计数说明；丢弃不无声。
+- 未裁决（OPEN/UNKNOWN）的 RED/YELLOW findings 若导致候选为 0，finalize 会显式告警提示先裁决再 republish。
 ## 平台展示与数据校验
 平台监控直接读取 `reports/final/summary-data.json`，归档阶段不再生成本地 HTML 报告，也不得由模型临场维护第二份展示数据。

package/harness/bundles/general/claude-code/harness-archive/templates/summary-data-template.json CHANGED Viewed

@@ -213,5 +213,6 @@
   "uncommittedTestEvidence": [],
   "maintenanceNotes": [],
   "knownRisks": [],
+  "decisions": [],
   "manualActions": []
 }

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

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

package/harness/bundles/general/claude-code/harness-execute/SKILL.md CHANGED Viewed

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; overlay=none; agent=claude-code; do not edit -->
 # harness-execute — 执行（编码 + 验证）
 > 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段。

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

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; 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 CHANGED Viewed

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

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

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

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

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

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

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

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

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

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 > **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，

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

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

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

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

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

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 > **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，

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

@@ -503,6 +503,96 @@ def _remote_ci_history_present(change_dir: Path) -> bool:
     )
+# decisions.json 单条记录的上限：防呆，不是安全边界（归档包大小限制在服务端）。
+_DECISIONS_MAX_ENTRIES = 200
+_DECISIONS_MAX_TITLE = 500
+_DECISIONS_MAX_RATIONALE = 4000
+_DECISIONS_MAX_KEYWORDS = 32
+_DECISIONS_MAX_KEYWORD_CHARS = 80
+def _decision_record_valid(record: dict[str, Any]) -> bool:
+    """evidence/decisions.json 单条记录的确定性校验（与 hkc 的消费端口径一致）。"""
+    title = str(record.get("title") or "").strip()
+    if not title or len(title) > _DECISIONS_MAX_TITLE:
+        return False
+    if str(record.get("entry_type") or "").strip() not in {
+        "decision",
+        "requirement",
+        "api-contract",
+    }:
+        return False
+    if str(record.get("status") or "").strip().lower() not in {
+        "adopted",
+        "proposed",
+        "rejected",
+        "superseded",
+    }:
+        return False
+    rationale = record.get("rationale")
+    if rationale is not None and (
+        not isinstance(rationale, str) or len(rationale) > _DECISIONS_MAX_RATIONALE
+    ):
+        return False
+    record_id = record.get("id")
+    if record_id is not None and (
+        not isinstance(record_id, str) or len(record_id.strip()) > 80
+    ):
+        return False
+    path = record.get("path")
+    if path is not None:
+        if not isinstance(path, str) or len(path) > 500:
+            return False
+        normalized = path.replace("\\", "/")
+        if normalized.startswith("/") or ".." in normalized.split("/") or ":" in normalized:
+            return False
+    line = record.get("line")
+    if line is not None and (isinstance(line, bool) or not isinstance(line, int) or line < 1):
+        return False
+    keywords = record.get("keywords")
+    if keywords is not None:
+        if not isinstance(keywords, list) or len(keywords) > _DECISIONS_MAX_KEYWORDS:
+            return False
+        if any(
+            not isinstance(item, str) or not item.strip() or len(item) > _DECISIONS_MAX_KEYWORD_CHARS
+            for item in keywords
+        ):
+            return False
+    source = record.get("source")
+    if source is not None and str(source).strip() not in {"plan", "review", "manual", "archive"}:
+        return False
+    return True
+def load_change_decisions(change_dir: Path) -> tuple[list[dict[str, Any]], int]:
+    """Load ``evidence/decisions.json`` — 上游（plan/execute/review）采纳的结构化决策。
+    Returns (valid records, dropped count). 文件缺失/损坏/版本不符视为没有决策；
+    单条不合法的记录被丢弃并计数，由调用方决定是否告警——丢弃不能无声。
+    """
+    path = _first_archive_path(change_dir, "evidence/decisions.json")
+    if path is None:
+        return [], 0
+    try:
+        data = read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return [], 0
+    if not isinstance(data, dict) or data.get("schema_version") != 1:
+        return [], 0
+    records = data.get("decisions")
+    if not isinstance(records, list):
+        return [], 0
+    valid: list[dict[str, Any]] = []
+    dropped = 0
+    for record in records[: _DECISIONS_MAX_ENTRIES]:
+        if isinstance(record, dict) and _decision_record_valid(record):
+            valid.append(record)
+        else:
+            dropped += 1
+    dropped += max(0, len(records) - _DECISIONS_MAX_ENTRIES)
+    return valid, dropped
 def load_product_candidate_ci(change_dir: Path) -> dict[str, Any] | None:
     """Load platform-neutral candidate evidence, then legacy CI evidence."""
     for relative in (
@@ -4201,11 +4291,16 @@ def _stage_status_from_sources(
     }
     projected_events = he.apply_event_corrections(events)
     execute_phase_end_seen = False
+    # 服务端 CLI schema 2.3 要求全阶段键集 {plan, run, test, review, submit,
+    # archive}，而 2026-08 起事件侧 run+test 已合并为 execute。仍带 run/test
+    # 原名的旧事件在折叠进 execute 之前单独留一份，供归档时拆分还原。
+    raw_run_test: dict[str, str] = {}
     for event in projected_events:
         if event.get("type") != "phase.end":
             continue
         # 旧事件的 run/test phase.end 折叠进 execute，按事件序后写胜。
-        phase = hp.resolve_phase_name(str(event.get("phase") or "").lower()) or ""
+        raw_phase = str(event.get("phase") or "").strip().lower()
+        phase = hp.resolve_phase_name(raw_phase) or ""
         raw = str(event.get("status") or "").upper()
         if phase not in status or not raw:
             continue
@@ -4218,6 +4313,8 @@ def _stage_status_from_sources(
         elif raw in {"SKIP", "SKIPPED"}:
             raw = "USER_SKIPPED"
         status[phase] = raw
+        if raw_phase in {"run", "test"}:
+            raw_run_test[raw_phase] = raw
     # Issues in events can downgrade. H-14: informational / hygiene / agent-preflight
     # notes must not downgrade an already-OK phase.end.
     _informational_markers = (
@@ -4272,7 +4369,18 @@ def _stage_status_from_sources(
     if not review_evidence_present(change_dir, projected_events):
         status["review"] = "ADVISORY"
-    return status
+    # 服务端 schema 2.3 是 passthrough：execute 键保留供既有消费方使用，
+    # 同时补上 run/test 满足必需键。旧事件带 run/test 原名时按原名拆分，
+    # 否则镜像 execute 聚合值（合并事件流里没有更细的信号可拆）。
+    return {
+        "plan": status["plan"],
+        "execute": status["execute"],
+        "run": raw_run_test.get("run", status["execute"]),
+        "test": raw_run_test.get("test", status["execute"]),
+        "review": status["review"],
+        "submit": status["submit"],
+        "archive": status["archive"],
+    }
 def _compute_final_status(
@@ -5264,6 +5372,7 @@ def collect_summary_data(
             "changedFiles",
             "artifacts",
             "reviewSummary",
+            "decisions",
             "archiveManifest",
             "uncommittedTestEvidence",
             "maintenanceNotes",
@@ -5630,6 +5739,12 @@ def collect_summary_data(
     )
     review_status = hr.status(change_dir)
     data["reviewFindings"] = list(review_status.get("items") or [])
+    decisions_dropped = 0
+    if not for_replay:
+        decisions, decisions_dropped = load_change_decisions(change_dir)
+        data["decisions"] = decisions
+    else:
+        data.setdefault("decisions", [])
     if not for_replay:
         data["timeline"] = _timeline_from_events(event_summary, projected_events)
     else:
@@ -5662,10 +5777,20 @@ def collect_summary_data(
                 if note:
                     maintenance_notes.append(note)
         data["maintenanceNotes"] = maintenance_notes
+        if decisions_dropped:
+            # 丢弃不能无声：decisions.json 是人/agent 显式写的上游产物。
+            data["maintenanceNotes"].append(
+                f"evidence/decisions.json：{decisions_dropped} 条记录不符合 "
+                "schema（缺 title/entry_type/status 或越界）已丢弃"
+            )
         scenario_risks, scenario_actions = _risks_from_test_results(change_dir)
         data["knownRisks"] = known_risks + scenario_risks
         data["manualActions"] = scenario_actions
+        execute_status = (data.get("stageStatus") or {}).get("execute")
         for name, value in (data.get("stageStatus") or {}).items():
+            # run/test 镜像 execute 聚合值时不重复生成同一条人工动作。
+            if name in {"run", "test"} and value == execute_status:
+                continue
             if value in {"BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA", "NOT_RUN", "USER_SKIPPED"}:
                 data["manualActions"].append({
                     "stage": name,
@@ -8592,15 +8717,27 @@ def cmd_finalize(
     # --- 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.
+    # knowledge extraction found nothing. An empty array is a valid outcome —
+    # but an empty array in the presence of unadjudicated findings is a
+    # *different* situation and must be said out loud, not silently shown as
+    # "ready / 0 results" downstream.
     try:
         summary = read_json(summary_path)
         candidates_path = write_knowledge_candidates(work_dir, summary)
+        candidate_count = len(read_json(candidates_path))
+        unadjudicated = hkc.count_unadjudicated_findings(summary)
         payload["steps"]["knowledge_candidates"] = {
             "ok": True,
             "path": str(candidates_path),
-            "count": len(read_json(candidates_path)),
+            "count": candidate_count,
+            "droppedUnadjudicated": unadjudicated,
         }
+        if unadjudicated > 0 and candidate_count == 0:
+            warnings.append(
+                f"本次归档有 {unadjudicated} 条未裁决（OPEN/UNKNOWN）的评审发现，"
+                "知识候选为 0：它们按现行策略被丢弃而未形成知识。"
+                "若其中有值得沉淀的内容，请先完成裁决再 republish。"
+            )
     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)}

package/harness/bundles/general/claude-code/scripts/harness_knowledge_candidates.py CHANGED Viewed

@@ -2,17 +2,21 @@
 """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``.
+an independent reviewer and then adjudicated, knownRisks are evidence-derived
+facts, and decisions are structured records adopted upstream (plan/execute/
+review). This module turns those three — and only those three — 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
-("知识来源的选定")::
+("知识来源的选定"), extended 2026-08-23 with the decisions source::
     disposition = FIXED                      -> pitfall   RED 0.95 / YELLOW 0.85
     disposition = ACCEPTED_RISK | DEFERRED   -> risk      RED 0.95 / YELLOW 0.85
     knownRisks[]                             -> risk      0.85
+    decisions[status=adopted]                -> record's entry_type (decision |
+                                                requirement | api-contract)  0.85
     severity = OK | disposition = NOT_APPLICABLE -> dropped
+    decisions[status != adopted]             -> kept in summary, not knowledge
 Dispositions outside the adopted set (OPEN / UNKNOWN) are dropped too: an
 unadjudicated finding is not yet knowledge. maintenanceNotes, finalStatusReasons
@@ -42,6 +46,16 @@ _DISPOSITION_ENTRY_TYPES = {
 _SEVERITY_CONFIDENCE = {"RED": 0.95, "YELLOW": 0.85}
 _KNOWN_RISK_CONFIDENCE = 0.85
+# decisions[]（来自 change 的 evidence/decisions.json，经 summary.decisions 传入）
+# 与 findings 的裁决门槛同源：只有已采纳（adopted）的决策才成为候选——
+# proposed/rejected/superseded 留在 summary 里做记录，但不构成知识。
+# entry_type 直接取自记录，取值与 knowledgeCandidateEntryTypeSchema 对齐；
+# source 对应 candidateProvenanceSourceKindSchema 的枚举。
+_DECISION_ENTRY_TYPES = {"decision", "requirement", "api-contract"}
+_DECISION_STATUSES = {"adopted", "proposed", "rejected", "superseded"}
+_DECISION_SOURCE_KINDS = {"plan", "review", "manual", "archive"}
+_DECISION_CONFIDENCE = 0.85
 _MAX_KEYWORDS = 32
 _MAX_KEYWORD_CHARS = 80
 _MAX_BODY_CHARS = 20_000
@@ -204,6 +218,86 @@ def _risk_candidate(
     }
+def _decision_candidate(
+    record: dict[str, Any],
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> dict[str, Any] | None:
+    """Project one adopted design decision / requirement / API contract entry.
+    Every field is copied from the record (written upstream by a human or an
+    agent during plan/execute/review); nothing is inferred at archive time.
+    """
+    title = _text(record.get("title"))
+    entry_type = _text(record.get("entry_type"))
+    status = _text(record.get("status")).lower()
+    if not title or entry_type not in _DECISION_ENTRY_TYPES or status != "adopted":
+        return None
+    rationale = _text(record.get("rationale"))
+    path = _text(record.get("path"))
+    line = record.get("line")
+    location = _location(path, line)
+    segments = _path_segments(path)
+    record_id = _text(record.get("id"))
+    source = _text(record.get("source"))
+    if source not in _DECISION_SOURCE_KINDS:
+        source = "plan"
+    raw_keywords = record.get("keywords")
+    record_keywords = (
+        [item for item in raw_keywords if isinstance(item, str)]
+        if isinstance(raw_keywords, list)
+        else []
+    )
+    body_lines = [title]
+    if rationale:
+        body_lines.append(f"理由：{rationale}")
+    if location:
+        body_lines.append(f"位置：{location}")
+    body_lines.append(f"类型：{entry_type}")
+    body = "\n".join(body_lines)[:_MAX_BODY_CHARS]
+    keywords = _keywords(
+        *record_keywords,
+        segments[-1] if segments else "",
+        segments[-2] if len(segments) >= 2 else "",
+        entry_type,
+    )
+    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, "decision", record_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": _DECISION_CONFIDENCE,
+        "status": "pending",
+        "entry_type": entry_type,
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": source,
+            "source_ref": f"archive:{archive_id}#{record_id}" if record_id else f"archive:{archive_id}",
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
 def build_knowledge_candidates(
     summary: dict[str, Any],
     *,
@@ -252,9 +346,51 @@ def build_knowledge_candidates(
                     created_at=created_at,
                 ))
+    decisions = summary.get("decisions")
+    if isinstance(decisions, list):
+        for record in decisions:
+            if isinstance(record, dict):
+                collect(_decision_candidate(
+                    record,
+                    change_key=change_key,
+                    archive_id=archive_id,
+                    producer_version=producer_version,
+                    created_at=created_at,
+                ))
     return candidates
+# Dispositions that mean "not yet adjudicated". A finding in this state with a
+# knowledge-carrying severity is dropped by the mapping above — correctly — but
+# the drop must be visible, or an archive with real findings looks identical to
+# an archive with nothing worth keeping (both ship an empty candidates file).
+_UNADJUDICATED_DISPOSITIONS = {"", "OPEN", "UNKNOWN"}
+def count_unadjudicated_findings(summary: dict[str, Any]) -> int:
+    """Count RED/YELLOW reviewFindings whose disposition is not yet adjudicated.
+    These are the findings the mapping table silently drops. Callers use the
+    count to warn when an archive would otherwise show "ready / 0 results"
+    despite carrying real, unprocessed review signal.
+    """
+    if not isinstance(summary, dict):
+        return 0
+    findings = summary.get("reviewFindings")
+    if not isinstance(findings, list):
+        return 0
+    count = 0
+    for finding in findings:
+        if not isinstance(finding, dict):
+            continue
+        severity = _text(finding.get("severity"))
+        disposition = _text(finding.get("disposition")).upper()
+        if severity in _SEVERITIES and disposition in _UNADJUDICATED_DISPOSITIONS:
+            count += 1
+    return count
 def render_knowledge_candidates_json(candidates: list[dict[str, Any]]) -> str:
     """Deterministic bytes for the archive package entry."""
     return json.dumps(

package/harness/bundles/general/codebuddy/.harness-build.json CHANGED Viewed

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "d1485a25236f58dc"
+  "coreHash": "d6fd3fef72cfa62b"
 }

package/harness/bundles/general/codebuddy/harness-archive/SKILL.md CHANGED Viewed

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=d1485a25236f58dc; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d6fd3fef72cfa62b; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 ## Purpose

package/harness/bundles/general/codebuddy/harness-archive/reference.md CHANGED Viewed

@@ -67,10 +67,39 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 - `changedFiles`：path/summary/insertions/deletions —— 来自 `git diff --numstat <base>..<head>`；
 - `reviewSummary`：red/yellow + redFixed/redConfirmed/yellowFixed/yellowDeferred 修复进度；
 - `maintenanceNotes`：给后续维护者看的结论；
-- `knownRisks`：剩余风险或人工确认项。
+- `knownRisks`：剩余风险或人工确认项；
+- `decisions`：已采纳的设计决策/需求/API 契约 —— 来自 `evidence/decisions.json`（见下节），生成器只做校验与透传，不从 markdown 提取。
 报告必须突出业务目标和维护者结论。所有统计数字只能来自 events、summary-data、ledger 或 manifest，不得手写另一套。历史 archive 没有 `events.ndjson` 时，允许从 ledger/log/manifest 回放，并在 `reportPipeline.sources` 中记录来源。
+## evidence/decisions.json（可选，知识沉淀入口）
+重要设计决策、长期约束、API 契约要进入平台知识库的唯一通道：在 plan/execute/review 阶段由人或 agent 把**已采纳**的结论写入 `.harness/changes/<change>/evidence/decisions.json`（schema_version 1）：
+```json
+{
+  "schema_version": 1,
+  "decisions": [
+    {
+      "id": "D-001",
+      "title": "一句话结论（必填，≤500 字）",
+      "rationale": "为什么（可选，≤4000 字）",
+      "entry_type": "decision | requirement | api-contract",
+      "status": "adopted | proposed | rejected | superseded",
+      "path": "docs/design/x.md（可选，相对路径，溯源用）",
+      "line": 42,
+      "keywords": ["可选，≤32 个"],
+      "source": "plan | review | manual | archive"
+    }
+  ]
+}
+```
+- 只有 `status: "adopted"` 的记录会成为知识候选（`entry_type` 原样落到知识条目上）；其余状态保留在 summary 里做记录。
+- 与 reviewFindings 的裁决门槛同源：**筛选必须在上游发生**——不要把讨论过程原文倒进来，归档时不做任何 LLM 提取。
+- 不合 schema 的记录会被丢弃并在 `maintenanceNotes` 留一条计数说明；丢弃不无声。
+- 未裁决（OPEN/UNKNOWN）的 RED/YELLOW findings 若导致候选为 0，finalize 会显式告警提示先裁决再 republish。
 ## 平台展示与数据校验
 平台监控直接读取 `reports/final/summary-data.json`，归档阶段不再生成本地 HTML 报告，也不得由模型临场维护第二份展示数据。

package/harness/bundles/general/codebuddy/harness-archive/templates/summary-data-template.json CHANGED Viewed

@@ -213,5 +213,6 @@
   "uncommittedTestEvidence": [],
   "maintenanceNotes": [],
   "knownRisks": [],
+  "decisions": [],
   "manualActions": []
 }