@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/pi/scripts/harness_workflow_policy.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Strict loader for harness/contracts/workflow-policy.json.
+
+Unknown fields at any depth fail validation. Python 3.10+, stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+POLICY_REL = Path("harness") / "contracts" / "workflow-policy.json"
+
+TOP_LEVEL_KEYS = frozenset(
+    {
+        "schemaVersion",
+        "testExecution",
+        "riskTiers",
+        "skills",
+        "requiredArtifacts",
+        "requiredValidations",
+        "validationPhases",
+        "capabilityGates",
+        "conditionalStages",
+        "interactionWhitelist",
+        "checkpointRules",
+    }
+)
+
+RISK_TIER_KEYS = frozenset(
+    {
+        "description",
+        "defaultPhases",
+        "requiredValidations",
+        "conditionalStages",
+        "upgradeTriggers",
+    }
+)
+
+SKILL_KEYS = frozenset(
+    {
+        "phase",
+        "inputs",
+        "artifacts",
+        "events",
+        "allowedInteractions",
+        "capabilities",
+        "profiles",
+    }
+)
+
+CONDITIONAL_STAGE_KEYS = frozenset({"tiers", "signals"})
+CAPABILITY_GATE_KEYS = frozenset(
+    {"signals", "requiredStages", "requiredValidations"}
+)
+CHECKPOINT_RULE_KEYS = frozenset(
+    {
+        "afterTasks",
+        "beforeTasks",
+        "blocking",
+        "requiredReport",
+        "reviewerTool",
+    }
+)
+TEST_EXECUTION_KEYS = frozenset(
+    {
+        "runner",
+        "defaultProfile",
+        "maxWorkers",
+        "singleInstance",
+        "processTreeCleanup",
+        "detachedProcessPreflight",
+        "confirmationFlag",
+        "confirmationRequiredProfiles",
+        "resourceIntensiveModules",
+        "profiles",
+    }
+)
+TEST_EXECUTION_PROFILE_KEYS = frozenset(
+    {
+        "description",
+        "includesResourceIntensive",
+        "moduleTimeoutSeconds",
+    }
+)
+
+
+class PolicyValidationError(ValueError):
+    """Raised when workflow-policy.json contains unknown or invalid fields."""
+
+
+def _reject_unknown(data: dict[str, Any], allowed: frozenset[str], path: str) -> None:
+    unknown = sorted(set(data) - allowed)
+    if unknown:
+        raise PolicyValidationError(
+            f"unknown field(s) at {path}: {', '.join(unknown)}"
+        )
+
+
+def _require_type(value: Any, expected: type | tuple[type, ...], path: str) -> None:
+    if not isinstance(value, expected):
+        names = (
+            expected.__name__
+            if isinstance(expected, type)
+            else "|".join(t.__name__ for t in expected)
+        )
+        raise PolicyValidationError(f"{path} must be {names}, got {type(value).__name__}")
+
+
+def validate_policy(data: Any) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise PolicyValidationError("workflow policy root must be an object")
+    _reject_unknown(data, TOP_LEVEL_KEYS, "root")
+    _require_type(data.get("schemaVersion"), int, "schemaVersion")
+    if data["schemaVersion"] != 1:
+        raise PolicyValidationError("unsupported schemaVersion")
+
+    test_execution = data["testExecution"]
+    _require_type(test_execution, dict, "testExecution")
+    _reject_unknown(test_execution, TEST_EXECUTION_KEYS, "testExecution")
+    for key in ("runner", "defaultProfile", "confirmationFlag"):
+        _require_type(test_execution[key], str, f"testExecution.{key}")
+    max_workers = test_execution["maxWorkers"]
+    _require_type(max_workers, int, "testExecution.maxWorkers")
+    if isinstance(max_workers, bool) or max_workers < 1 or max_workers > 2:
+        raise PolicyValidationError("testExecution.maxWorkers must be 1 or 2")
+    for key in (
+        "singleInstance",
+        "processTreeCleanup",
+        "detachedProcessPreflight",
+    ):
+        _require_type(test_execution[key], bool, f"testExecution.{key}")
+        if not test_execution[key]:
+            raise PolicyValidationError(f"testExecution.{key} must be true")
+    for key in ("confirmationRequiredProfiles", "resourceIntensiveModules"):
+        values = test_execution[key]
+        _require_type(values, list, f"testExecution.{key}")
+        if any(not isinstance(item, str) or not item for item in values):
+            raise PolicyValidationError(
+                f"testExecution.{key} must contain non-empty strings"
+            )
+
+    execution_profiles = test_execution["profiles"]
+    _require_type(execution_profiles, dict, "testExecution.profiles")
+    required_profile_names = {"safe", "system", "full"}
+    if set(execution_profiles) != required_profile_names:
+        raise PolicyValidationError(
+            "testExecution.profiles must define exactly safe, system, and full"
+        )
+    if test_execution["defaultProfile"] != "safe":
+        raise PolicyValidationError("testExecution.defaultProfile must be safe")
+    confirmation_profiles = set(test_execution["confirmationRequiredProfiles"])
+    if not {"system", "full"}.issubset(confirmation_profiles):
+        raise PolicyValidationError(
+            "testExecution confirmation must cover system and full"
+        )
+    for profile_name, profile in execution_profiles.items():
+        path = f"testExecution.profiles.{profile_name}"
+        _require_type(profile, dict, path)
+        _reject_unknown(profile, TEST_EXECUTION_PROFILE_KEYS, path)
+        _require_type(profile["description"], str, f"{path}.description")
+        _require_type(
+            profile["includesResourceIntensive"],
+            bool,
+            f"{path}.includesResourceIntensive",
+        )
+        timeout = profile["moduleTimeoutSeconds"]
+        _require_type(timeout, int, f"{path}.moduleTimeoutSeconds")
+        if isinstance(timeout, bool) or timeout <= 0:
+            raise PolicyValidationError(
+                f"{path}.moduleTimeoutSeconds must be a positive integer"
+            )
+    if execution_profiles["safe"]["includesResourceIntensive"]:
+        raise PolicyValidationError(
+            "testExecution.profiles.safe must exclude resource-intensive tests"
+        )
+    for profile_name in ("system", "full"):
+        if not execution_profiles[profile_name]["includesResourceIntensive"]:
+            raise PolicyValidationError(
+                f"testExecution.profiles.{profile_name} must include resource-intensive tests"
+            )
+
+    risk_tiers = data["riskTiers"]
+    _require_type(risk_tiers, dict, "riskTiers")
+    for tier_name, tier in risk_tiers.items():
+        path = f"riskTiers.{tier_name}"
+        _require_type(tier, dict, path)
+        _reject_unknown(tier, RISK_TIER_KEYS, path)
+        _require_type(tier["description"], str, f"{path}.description")
+        _require_type(tier["defaultPhases"], list, f"{path}.defaultPhases")
+        _require_type(tier["requiredValidations"], list, f"{path}.requiredValidations")
+        _require_type(tier["conditionalStages"], list, f"{path}.conditionalStages")
+        _require_type(tier["upgradeTriggers"], list, f"{path}.upgradeTriggers")
+
+    skills = data["skills"]
+    _require_type(skills, dict, "skills")
+    for skill_name, skill in skills.items():
+        path = f"skills.{skill_name}"
+        _require_type(skill, dict, path)
+        _reject_unknown(skill, SKILL_KEYS, path)
+        _require_type(skill["phase"], str, f"{path}.phase")
+        for key in ("inputs", "artifacts", "events", "allowedInteractions", "capabilities"):
+            _require_type(skill[key], list, f"{path}.{key}")
+        profiles = skill.get("profiles", ["general", "java"])
+        _require_type(profiles, list, f"{path}.profiles")
+        if not profiles or any(item not in {"general", "java"} for item in profiles):
+            raise PolicyValidationError(f"{path}.profiles must contain general and/or java")
+
+    for section in ("requiredArtifacts", "requiredValidations"):
+        section_data = data[section]
+        _require_type(section_data, dict, section)
+        for phase, items in section_data.items():
+            _require_type(items, list, f"{section}.{phase}")
+
+    validation_phases = data["validationPhases"]
+    _require_type(validation_phases, dict, "validationPhases")
+    for verification, phase in validation_phases.items():
+        _require_type(phase, str, f"validationPhases.{verification}")
+
+    capability_gates = data["capabilityGates"]
+    _require_type(capability_gates, dict, "capabilityGates")
+    for capability, gate in capability_gates.items():
+        path = f"capabilityGates.{capability}"
+        _require_type(gate, dict, path)
+        _reject_unknown(gate, CAPABILITY_GATE_KEYS, path)
+        for key in CAPABILITY_GATE_KEYS:
+            _require_type(gate[key], list, f"{path}.{key}")
+
+    conditional = data["conditionalStages"]
+    _require_type(conditional, dict, "conditionalStages")
+    for stage_name, stage in conditional.items():
+        path = f"conditionalStages.{stage_name}"
+        _require_type(stage, dict, path)
+        _reject_unknown(stage, CONDITIONAL_STAGE_KEYS, path)
+        _require_type(stage["tiers"], list, f"{path}.tiers")
+        _require_type(stage["signals"], list, f"{path}.signals")
+
+    interaction = data["interactionWhitelist"]
+    _require_type(interaction, dict, "interactionWhitelist")
+    for key, items in interaction.items():
+        _require_type(items, list, f"interactionWhitelist.{key}")
+
+    checkpoints = data["checkpointRules"]
+    _require_type(checkpoints, dict, "checkpointRules")
+    for checkpoint_id, rule in checkpoints.items():
+        path = f"checkpointRules.{checkpoint_id}"
+        _require_type(rule, dict, path)
+        _reject_unknown(rule, CHECKPOINT_RULE_KEYS, path)
+        _require_type(rule["afterTasks"], list, f"{path}.afterTasks")
+        _require_type(rule["beforeTasks"], list, f"{path}.beforeTasks")
+        _require_type(rule["blocking"], bool, f"{path}.blocking")
+
+    return data
+
+
+def policy_path_for_repo(repo_root: Path) -> Path:
+    return repo_root / POLICY_REL
+
+
+def load_policy(repo_root: Path) -> dict[str, Any]:
+    path = policy_path_for_repo(repo_root)
+    if not path.is_file():
+        raise FileNotFoundError(f"workflow policy missing: {path}")
+    data = json.loads(path.read_text(encoding="utf-8-sig"))
+    return validate_policy(data)

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "f371fd8f594f8477"
+  "coreHash": "45b278c44cd66b19"
 }

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f371fd8f594f8477; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=45b278c44cd66b19; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

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

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

package/harness/bundles/java/claude-code/harness-archive/reference.md

@@ -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/java/claude-code/harness-archive/templates/summary-data-template.json

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

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

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

package/harness/bundles/java/claude-code/harness-execute/SKILL.md

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

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

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

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

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

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=f371fd8f594f8477; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=45b278c44cd66b19; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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