@hunter-harness/workflow-harness 0.2.5 → 0.2.7

package/harness/bundles/java/claude-code/scripts/harness_workflow_policy.py

@@ -0,0 +1,160 @@
+#!/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",
+        "riskTiers",
+        "skills",
+        "requiredArtifacts",
+        "requiredValidations",
+        "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"})
+CHECKPOINT_RULE_KEYS = frozenset(
+    {
+        "afterTasks",
+        "beforeTasks",
+        "blocking",
+        "requiredReport",
+        "reviewerTool",
+    }
+)
+
+
+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")
+
+    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}")
+
+    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/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "a90894841bbf814e"
+  "coreHash": "48a6bb3c8d0d04e0"
 }

package/harness/bundles/java/codebuddy/contracts/workflow-policy.json

@@ -0,0 +1,169 @@
+{
+  "schemaVersion": 1,
+  "riskTiers": {
+    "fast": {
+      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency.",
+      "defaultPhases": ["plan", "run", "submit", "archive"],
+      "requiredValidations": ["unitTest"],
+      "conditionalStages": ["review", "package", "apidoc"],
+      "upgradeTriggers": ["api-change", "security", "migration", "concurrency", "breaking-contract"]
+    },
+    "standard": {
+      "description": "Ordinary production code and non-breaking API/features.",
+      "defaultPhases": ["plan", "run", "test", "submit", "archive"],
+      "requiredValidations": ["compile", "unitTest", "unitTestFull"],
+      "conditionalStages": ["review", "package", "apidoc"],
+      "upgradeTriggers": ["auth", "security", "delete", "migration", "concurrency", "artifact-protocol", "shared-state", "breaking-api"]
+    },
+    "full": {
+      "description": "Auth/security/delete/migration/concurrency/service protocol/shared state/breaking contracts.",
+      "defaultPhases": ["plan", "run", "test", "review", "submit", "archive"],
+      "requiredValidations": ["compile", "unitTest", "unitTestFull", "apiTest"],
+      "conditionalStages": ["package", "apidoc"],
+      "upgradeTriggers": []
+    }
+  },
+  "skills": {
+    "harness-plan": {
+      "phase": "plan",
+      "inputs": ["requirements", "change-context"],
+      "artifacts": ["plans", "spec", "test-scenarios", "implementation-detail"],
+      "events": ["phase.start", "phase.end", "decision"],
+      "allowedInteractions": [],
+      "capabilities": ["risk-classify-plan"]
+    },
+    "harness-run": {
+      "phase": "run",
+      "inputs": ["implementation-detail", "state-snapshot"],
+      "artifacts": ["code", "verification-ledger"],
+      "events": ["phase.start", "phase.end", "command", "verification"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close", "ledger-record"]
+    },
+    "harness-test": {
+      "phase": "test",
+      "inputs": ["test-scenarios", "verification-ledger"],
+      "artifacts": ["test-reports", "verification-ledger"],
+      "events": ["phase.start", "phase.end", "command", "verification"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close", "test-guard", "ledger-record"]
+    },
+    "harness-review": {
+      "phase": "review",
+      "inputs": ["diff", "verification-ledger", "test-reports"],
+      "artifacts": ["review-report"],
+      "events": ["phase.start", "phase.end", "issue", "artifact"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close"]
+    },
+    "harness-submit": {
+      "phase": "submit",
+      "inputs": ["verification-ledger", "test-tracking"],
+      "artifacts": ["git-integration"],
+      "events": ["phase.start", "phase.end", "command", "artifact"],
+      "allowedInteractions": ["merge-conflict-resolution"],
+      "capabilities": ["gate-begin", "gate-close", "integration-lock", "test-guard-stage"]
+    },
+    "harness-package": {
+      "profiles": ["java"],
+      "phase": "package",
+      "inputs": ["verification-ledger", "final-commit"],
+      "artifacts": ["deploy-artifact"],
+      "events": ["phase.start", "phase.end", "command", "verification"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close", "ledger-can-reuse"]
+    },
+    "harness-archive": {
+      "phase": "archive",
+      "inputs": ["events", "verification-ledger", "reports"],
+      "artifacts": ["summary-data", "archive-manifest"],
+      "events": ["phase.start", "phase.end", "artifact"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close"]
+    },
+    "harness-sync": {
+      "phase": "sync",
+      "inputs": ["canonical-harness"],
+      "artifacts": ["bundle-projection"],
+      "events": ["phase.start", "phase.end", "command"],
+      "allowedInteractions": [],
+      "capabilities": []
+    },
+    "harness-codebase-map": {
+      "phase": "codebase-map",
+      "inputs": ["project-root"],
+      "artifacts": ["codebase-map"],
+      "events": ["phase.start", "phase.end"],
+      "allowedInteractions": [],
+      "capabilities": []
+    },
+    "harness-knowledge-query": {
+      "phase": "knowledge-query",
+      "inputs": ["knowledge-index"],
+      "artifacts": [],
+      "events": ["phase.start", "phase.end"],
+      "allowedInteractions": [],
+      "capabilities": ["read-only"]
+    },
+    "harness-knowledge-ingest": {
+      "phase": "knowledge-ingest",
+      "inputs": ["archive-evidence"],
+      "artifacts": ["knowledge-index"],
+      "events": ["phase.start", "phase.end", "command"],
+      "allowedInteractions": [],
+      "capabilities": []
+    },
+    "harness-apidoc": {
+      "profiles": ["java"],
+      "phase": "apidoc",
+      "inputs": ["api-diff"],
+      "artifacts": ["api-contract-summary"],
+      "events": ["phase.start", "phase.end", "artifact"],
+      "allowedInteractions": [],
+      "capabilities": ["gate-begin", "gate-close"]
+    }
+  },
+  "requiredArtifacts": {
+    "plan": ["plans", "spec"],
+    "run": [],
+    "test": ["tests/test-report-*.md"],
+    "review": ["reports/review/review-report-*.md"],
+    "submit": [],
+    "package": [],
+    "archive": ["reports/final/summary-data.json"]
+  },
+  "requiredValidations": {
+    "run": ["compile", "unitTest"],
+    "test": ["unitTestFull"],
+    "submit": [],
+    "package": ["package"]
+  },
+  "conditionalStages": {
+    "review": {
+      "tiers": ["standard", "full"],
+      "signals": ["security", "auth", "breaking-api", "shared-state"]
+    },
+    "package": {
+      "tiers": ["standard", "full"],
+      "signals": ["deploy-required", "install-verification"]
+    },
+    "apidoc": {
+      "tiers": ["standard", "full"],
+      "signals": ["api-diff-present"]
+    }
+  },
+  "interactionWhitelist": {
+    "global": [],
+    "harness-submit": ["merge-conflict-resolution"],
+    "harness-plan": ["risk-confirmation"]
+  },
+  "checkpointRules": {
+    "foundation-gate": {
+      "afterTasks": [1, 2, 3, 4],
+      "beforeTasks": [6, 7, 8, 9, 10],
+      "blocking": true,
+      "requiredReport": "reports/review/foundation-gate-review.md",
+      "reviewerTool": "codex"
+    }
+  }
+}

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

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -24,11 +24,18 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
 ## Workflow
 
+先用 `harness_change.py resolve [--change] --json` 解析 change；多个 active change 未显式选择时返回 `CHANGE_SELECTION_REQUIRED`。确认存在真实 API diff；无变化时记录跳过，不生成空文档。阶段边界使用 `harness_gate.py begin --phase apidoc --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json` 与 `harness_gate.py close --phase apidoc --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --json`，禁止手工追加阶段事件。
+
+默认输出 40–80 行契约差异摘要，只保留前端动作、变化接口、请求/响应边界、变化的枚举/错误码、兼容性和证据链接；显式 `--full` 才生成完整七章节。文件名使用 `YYYY-MM-DD-<变更语义安全名称>.md`，不以 commit hash 充当标题。
+
+文件名必须由 `harness_apidoc.py filename --description "<做了什么变更>" --json` 生成，避免 Windows 非法字符、超长路径和不可读 hash 文件名。
+
 1. 确定 change-name（Glob plans，读 frontmatter）
 2. append `phase.start`
 3. 扫描变更涉及 Controller/VO/ErrorCode（CodeGraph 优先）
@@ -57,7 +64,7 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -66,3 +73,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=a90894841bbf814e; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -49,11 +49,14 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
 ## Workflow
 
+先用 `harness_change.py resolve [--change] --json` 解析 change；多个 active change 未显式选择时返回 `CHANGE_SELECTION_REQUIRED`，禁止按 Glob/mtime 自动选择。`harness_archive.py finalize` 内部负责且仅负责一次 `harness_gate.py begin` 与 `harness_gate.py close`。调用者禁止重复调用阶段门禁，避免重复事件和幽灵 change 目录。
+
 ### Phase 0：读取规则和上下文
 
 1. 读取本文件。
@@ -185,7 +188,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -194,3 +197,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/java/codebuddy/harness-archive/reference.md

@@ -92,4 +92,4 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 ## 执行日志记录
 
-归档只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。
+归档只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。