npm - @hunter-harness/workflow-harness - Versions diffs - 0.3.1 → 0.4.1 - Mend

@hunter-harness/workflow-harness 0.3.1 → 0.4.1

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 (402) 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": "f7d84565fb42d77f"
+  "coreHash": "ec59ac2389d9dce9"
 }

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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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=f7d84565fb42d77f; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; 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 (
@@ -4484,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(
@@ -5282,6 +5395,7 @@ def collect_summary_data(
             "changedFiles",
             "artifacts",
             "reviewSummary",
+            "decisions",
             "archiveManifest",
             "uncommittedTestEvidence",
             "maintenanceNotes",
@@ -5648,6 +5762,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:
@@ -5680,6 +5800,12 @@ 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
@@ -8614,15 +8740,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_deploy.py CHANGED Viewed

@@ -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"})