@hunter-harness/workflow-harness 0.4.0 → 0.4.2

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

@@ -391,6 +391,404 @@ def count_unadjudicated_findings(summary: dict[str, Any]) -> int:
     return count
 
 
+# --- plan/design-derived knowledge candidates ---------------------------------
+#
+# reviewFindings/knownRisks/decisions 只覆盖“经对抗评审的变更”。没有评审的简单
+# 变更（无 RED/YELLOW 发现、无 knownRisks、无 adopted decisions）仍产出了
+# 经用户确认批准的 design/plan/test-scenarios——这些也是值得沉淀的知识。
+# 这里把 plans/*.md（v2 finalize 派生的机器契约）解析回结构化的自然内容，
+# 与 summary 三源并列，但 confidence 略低（机器派生而非独立评审）。
+
+_PLAN_CONFIDENCE = 0.85
+_PLAN_SOURCE_KIND = "plan"
+
+
+def _unescape_markdown(value: str) -> str:
+    """Reverse the renderer's markdown escaping for clean knowledge text.
+
+    harness-plan finalize 的渲染器对自由文本做了反斜杠/实体转义。知识候选存
+    的是自然语言，不需要保留渲染转义。顺序有讲究：先反转义实体，再反转义
+    反斜杠序列（从长到短）。
+    """
+    value = (
+        value.replace("&lt;", "<")
+        .replace("&gt;", ">")
+        .replace("&amp;", "&")
+        .replace("<br>", "\n")
+    )
+    return (
+        value.replace("\\`", "`")
+        .replace("\\#", "#")
+        .replace("\\*", "*")
+        .replace("\\[", "[")
+        .replace("\\]", "]")
+        .replace("\\\\", "\\")
+    )
+
+
+def _markdown_sections(text: str) -> dict[str, list[str]]:
+    """Split a v2 rendered markdown artifact into its ``## Header`` sections.
+
+    Returns ``{header: [lines...]}``. Only the ``##`` level is split; ``###``
+    and ``####`` content stays inside its parent section's lines.
+    """
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for line in text.splitlines():
+        if line.startswith("## ") and not line.startswith("### "):
+            current = line[3:].strip()
+            sections[current] = []
+        elif current is not None:
+            sections[current].append(line)
+    return sections
+
+
+def _plan_source_refs(change_key: str, package_path: str) -> list[str]:
+    """source_refs must exist in the package (core-v1 containment check)."""
+    return [package_path]
+
+
+def _plan_candidate(
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+    kind: str,
+    entry_type: str,
+    summary: str,
+    body: str,
+    keywords: list[str],
+    source_refs: list[str],
+    reusability_scope: str = "project",
+) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "candidate_id": _candidate_id(change_key, kind, summary),
+        "source_change_key": change_key,
+        "source_refs": source_refs,
+        "summary": summary,
+        "reusability_scope": reusability_scope,
+        "content_hash": _content_hash(entry_type, summary, body, keywords),
+        "confidence": _PLAN_CONFIDENCE,
+        "status": "pending",
+        "entry_type": entry_type,
+        "body": body,
+        "keywords": keywords,
+        "provenance": {
+            "source_kind": _PLAN_SOURCE_KIND,
+            "source_ref": f"archive:{archive_id}",
+            "producer": PRODUCER,
+            "producer_version": producer_version,
+            "created_at": created_at,
+        },
+    }
+
+
+def _requirements_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Requirements`` from design.md into requirement candidates.
+
+    Each line is ``- requirement:sha256:... [kind]: text`` where kind is
+    behavior | invariant | failure_behavior.
+    """
+    sections = _markdown_sections(design_text)
+    lines = sections.get("Requirements", [])
+    out: list[dict[str, Any]] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        prefix = stripped[2:]
+        # kind 位于第一个 `]: ` 之前的方括号内。
+        close_bracket = prefix.find("]")
+        if close_bracket <= 0 or not prefix.startswith("requirement:"):
+            continue
+        kind = prefix[1:close_bracket].strip()
+        if kind not in {"behavior", "invariant", "failure_behavior"}:
+            continue
+        colon = prefix.find(": ", close_bracket + 1)
+        if colon == -1:
+            continue
+        text = _unescape_markdown(prefix[colon + 2:].strip())
+        if not text:
+            continue
+        entry_type = "requirement"
+        body = f"需求类型：{kind}\n{text}"
+        keywords = _keywords(kind, entry_type)
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="requirement",
+            entry_type=entry_type,
+            summary=text,
+            body=body,
+            keywords=keywords,
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+    return out
+
+
+def _risks_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Risks`` (``- risk`` + ``  - Mitigation: ...``) into risk candidates."""
+    sections = _markdown_sections(design_text)
+    lines = sections.get("Risks", [])
+    out: list[dict[str, Any]] = []
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped.startswith("- "):
+            index += 1
+            continue
+        risk = _unescape_markdown(stripped[2:].strip())
+        if not risk or risk == "None.":
+            index += 1
+            continue
+        mitigation = ""
+        if index + 1 < len(lines) and lines[index + 1].strip().startswith("- Mitigation:"):
+            mitigation = _unescape_markdown(
+                lines[index + 1].strip()[len("- Mitigation:"):].strip()
+            )
+            index += 1
+        body = risk if not mitigation else f"{risk}\n缓解：{mitigation}"
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="risk",
+            entry_type="risk",
+            summary=risk,
+            body=body,
+            keywords=_keywords("risk"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+        index += 1
+    return out
+
+
+def _invariants_from_design(
+    design_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Invariants`` bullet list into requirement candidates."""
+    sections = _markdown_sections(design_text)
+    out: list[dict[str, Any]] = []
+    for line in sections.get("Invariants", []):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        text = _unescape_markdown(stripped[2:].strip())
+        if not text or text == "None.":
+            continue
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="invariant",
+            entry_type="requirement",
+            summary=text,
+            body=f"需求类型：invariant\n{text}",
+            keywords=_keywords("invariant", "requirement"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-design.md"),
+        ))
+    return out
+
+
+def _tasks_from_plan(
+    plan_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## Tasks`` from plan.md into implementation candidates.
+
+    Task headings are ``### T1``; the objective is the non-empty text between
+    the heading and the first ``- `` metadata bullet.
+    """
+    sections = _markdown_sections(plan_text)
+    lines = sections.get("Tasks", [])
+    out: list[dict[str, Any]] = []
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped.startswith("### "):
+            index += 1
+            continue
+        task_id = stripped[4:].strip()
+        index += 1
+        objective_parts: list[str] = []
+        while index < len(lines):
+            current = lines[index].strip()
+            if current.startswith("### ") or current.startswith("- "):
+                break
+            if current:
+                objective_parts.append(current)
+            index += 1
+        objective = " ".join(objective_parts).strip()
+        if not objective:
+            continue
+        body = f"任务：{task_id}\n{objective}"
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="task",
+            entry_type="implementation",
+            summary=objective,
+            body=body,
+            keywords=_keywords(task_id, "implementation"),
+            source_refs=_plan_source_refs(change_key, f"plans/{change_key}-plan.md"),
+        ))
+    return out
+
+
+def _scenarios_from_test_scenarios(
+    scenarios_text: str,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Parse ``## <id>: <title>`` headings into test-evidence candidates."""
+    out: list[dict[str, Any]] = []
+    for line in scenarios_text.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("## ") or stripped.startswith("### "):
+            continue
+        heading = stripped[3:].strip()
+        if heading == "Coverage":
+            continue
+        if ":" not in heading:
+            continue
+        scenario_id, title = heading.split(":", 1)
+        title = title.strip()
+        if not title:
+            continue
+        out.append(_plan_candidate(
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+            kind="scenario",
+            entry_type="test-evidence",
+            summary=title,
+            body=f"场景：{scenario_id.strip()}\n{title}",
+            keywords=_keywords(scenario_id.strip(), "test-evidence"),
+            source_refs=_plan_source_refs(
+                change_key, f"plans/{change_key}-test-scenarios.md"
+            ),
+        ))
+    return out
+
+
+def build_plan_candidates(
+    archive_dir,
+    *,
+    change_key: str,
+    archive_id: str,
+    producer_version: str,
+    created_at: str,
+) -> list[dict[str, Any]]:
+    """Extract knowledge candidates from the archive's plans/*.md artifacts.
+
+    Complements ``build_knowledge_candidates`` (summary 三源)。没有评审的简单
+    变更仍然产出 plans/*.md；这些是经用户确认批准的结构化真相源，parse 回来
+    就是可沉淀的知识。缺文件/解析失败返回 []（软失败）。
+    """
+    candidates: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+
+    def collect(items: list[dict[str, Any]]) -> None:
+        for candidate in items:
+            if candidate["candidate_id"] in seen_ids:
+                continue
+            seen_ids.add(candidate["candidate_id"])
+            candidates.append(candidate)
+
+    design_path = archive_dir / "plans" / f"{change_key}-design.md"
+    if design_path.is_file():
+        try:
+            design_text = design_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            design_text = ""
+        collect(_requirements_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+        collect(_risks_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+        collect(_invariants_from_design(
+            design_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+
+    plan_path = archive_dir / "plans" / f"{change_key}-plan.md"
+    if plan_path.is_file():
+        try:
+            plan_text = plan_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            plan_text = ""
+        collect(_tasks_from_plan(
+            plan_text,
+            change_key=change_key,
+            archive_id=archive_id,
+            producer_version=producer_version,
+            created_at=created_at,
+        ))
+
+    scenarios_path = archive_dir / "plans" / f"{change_key}-test-scenarios.md"
+    if scenarios_path.is_file():
+        try:
+            scenarios_text = scenarios_path.read_text(encoding="utf-8-sig")
+        except OSError:
+            scenarios_text = ""
+        collect(_scenarios_from_test_scenarios(
+            scenarios_text,
+            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(

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codex",
-  "coreHash": "8285116e6303495f"
+  "coreHash": "bb4e811a5442f018"
 }

package/harness/bundles/java/codex/harness-apidoc/SKILL.md

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/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=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

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

package/harness/bundles/java/codex/harness-execute/SKILL.md

@@ -4,7 +4,7 @@ description: 执行阶段：按变更簇执行 TDD
   编码循环（RED→GREEN→REFACTOR→编译验证），随后完成单元/接口/数据兼容验证并输出测试报告。仅当用户显式调用
   /harness-execute 时使用；不得因用户提到编码/实现/测试就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-execute — 执行（编码 + 验证）
 
 > 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段。

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

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

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

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

package/harness/bundles/java/codex/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

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

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

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

package/harness/bundles/java/codex/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/java/codex/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/codex/harness-run/SKILL.md

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 > **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，

package/harness/bundles/java/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/codex/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/codex/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=8285116e6303495f; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=bb4e811a5442f018; overlay=java; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 > **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，

package/harness/bundles/java/codex/scripts/harness_archive.py

@@ -4574,22 +4574,45 @@ def write_archive_meta(work_dir: Path, summary: dict[str, Any]) -> Path:
 
 
 def write_knowledge_candidates(work_dir: Path, summary: dict[str, Any]) -> Path:
-    """Generate candidates/knowledge.json from summary-data (single ownership).
+    """Generate candidates/knowledge.json from summary-data + plans/*.md.
 
     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.
+
+    Sources (in merge order):
+    1. Summary 三源 (reviewFindings / knownRisks / decisions)
+    2. Plans/*.md (design Requirements / Risks / Invariants, plan Tasks, test Scenarios)
+
+    Duplicates are deduplicated by candidate_id (summary 三源优先)。
     """
     archive_id = work_dir.name
+    change_key = str(summary.get("changeName") or archive_id)
+    producer_version = SCHEMA_VERSION
+    created_at = now_iso()
+
     candidates = hkc.build_knowledge_candidates(
         summary,
-        change_key=str(summary.get("changeName") or archive_id),
+        change_key=change_key,
         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(),
+        producer_version=producer_version,
+        created_at=created_at,
     )
+
+    # Merge plan-derived candidates (soft-fail: empty plans still produce a valid output).
+    plan_candidates = hkc.build_plan_candidates(
+        work_dir,
+        change_key=change_key,
+        archive_id=archive_id,
+        producer_version=producer_version,
+        created_at=created_at,
+    )
+    existing_ids = {c["candidate_id"] for c in candidates}
+    for candidate in plan_candidates:
+        if candidate["candidate_id"] not in existing_ids:
+            existing_ids.add(candidate["candidate_id"])
+            candidates.append(candidate)
+
     out = work_dir / "candidates" / "knowledge.json"
     out.parent.mkdir(parents=True, exist_ok=True)
     out.write_text(

package/harness/bundles/java/codex/scripts/harness_deploy.py

@@ -70,7 +70,7 @@ SKIP_DIR_NAMES = {
     ".git",
 }
 SKIP_TOP_NAMES = {"harness-merge", "harness-report"}
-HARNESS_AGENTS = ("claude-code", "codex", "cursor", "codebuddy")
+HARNESS_AGENTS = ("claude-code", "codex", "cursor", "codebuddy", "pi")
 AGENTS_WITH_CUSTOM_AGENTS = frozenset({"claude-code", "codebuddy"})