@hunter-harness/workflow-harness 0.4.0 → 0.4.1

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

@@ -0,0 +1,574 @@
+{
+  "schemaVersion": 1,
+  "testExecution": {
+    "runner": "harness/scripts/harness_test_runner.py",
+    "defaultProfile": "safe",
+    "maxWorkers": 2,
+    "singleInstance": true,
+    "processTreeCleanup": true,
+    "detachedProcessPreflight": true,
+    "confirmationFlag": "--confirm-resource-intensive",
+    "confirmationRequiredProfiles": [
+      "system",
+      "full"
+    ],
+    "resourceIntensiveModules": [
+      "test_harness_integration.py",
+      "test_harness_service.py"
+    ],
+    "profiles": {
+      "safe": {
+        "description": "Default low-load profile; runs regular test modules sequentially in isolated processes.",
+        "includesResourceIntensive": false,
+        "moduleTimeoutSeconds": 300
+      },
+      "system": {
+        "description": "Runs integration and service-lifecycle modules only after explicit confirmation.",
+        "includesResourceIntensive": true,
+        "moduleTimeoutSeconds": 600
+      },
+      "full": {
+        "description": "Runs regular modules followed by resource-intensive modules after explicit confirmation.",
+        "includesResourceIntensive": true,
+        "moduleTimeoutSeconds": 600
+      }
+    }
+  },
+  "riskTiers": {
+    "fast": {
+      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency. Policy notes: checkpointRules apply only when meta/implementation-checkpoints.json defines the entry for this change; missing file/entry = disabled (gate must not require --task).",
+      "defaultPhases": [
+        "plan",
+        "execute",
+        "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. Policy notes: requiredValidations may close DEGRADED when ledger status=NOT_RUN and evidence starts with 'DEGRADED: <reason>' (close code CLOSED_DEGRADED, phase status <= WARN); do not fake OK with unrelated tests.",
+      "defaultPhases": [
+        "plan",
+        "execute",
+        "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. Policy notes: (1) DEGRADED close — ledger status=NOT_RUN and evidence 'DEGRADED: <reason>' → CLOSED_DEGRADED with phase <= WARN; never fake OK with unrelated tests. (2) checkpointRules — only when plan created meta/implementation-checkpoints.json entry; missing file/entry = not enabled, gate must not require --task.",
+      "defaultPhases": [
+        "plan",
+        "execute",
+        "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": "execute",
+      "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": "execute",
+      "inputs": [
+        "test-scenarios",
+        "verification-ledger"
+      ],
+      "artifacts": [
+        "test-reports",
+        "verification-ledger"
+      ],
+      "events": [
+        "phase.start",
+        "phase.end",
+        "command",
+        "verification"
+      ],
+      "allowedInteractions": [
+        "resource-intensive-test-confirmation"
+      ],
+      "capabilities": [
+        "gate-begin",
+        "gate-close",
+        "test-guard",
+        "ledger-record",
+        "resource-safe-test-runner"
+      ]
+    },
+    "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": []
+    },
+    "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"
+      ]
+    },
+    "harness-push": {
+      "phase": "sync",
+      "inputs": [
+        "remote-baseline",
+        "local-content"
+      ],
+      "artifacts": [
+        "push-receipt"
+      ],
+      "events": [],
+      "allowedInteractions": [
+        "upload-confirmation"
+      ],
+      "capabilities": [
+        "remote-sync-push@1"
+      ]
+    },
+    "harness-pull": {
+      "phase": "sync",
+      "inputs": [
+        "remote-snapshot"
+      ],
+      "artifacts": [
+        "pull-receipt"
+      ],
+      "events": [],
+      "allowedInteractions": [
+        "conflict-decision"
+      ],
+      "capabilities": [
+        "remote-sync-pull@1"
+      ]
+    },
+    "harness-execute": {
+      "phase": "execute",
+      "inputs": [
+        "implementation-detail",
+        "state-snapshot",
+        "test-scenarios",
+        "verification-ledger"
+      ],
+      "artifacts": [
+        "code",
+        "test-reports",
+        "verification-ledger"
+      ],
+      "events": [
+        "command",
+        "phase.end",
+        "phase.start",
+        "verification"
+      ],
+      "allowedInteractions": [
+        "resource-intensive-test-confirmation"
+      ],
+      "capabilities": [
+        "gate-begin",
+        "gate-close",
+        "ledger-record",
+        "resource-safe-test-runner",
+        "test-guard"
+      ]
+    }
+  },
+  "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": {
+    "execute": [
+      "compile",
+      "unitTest",
+      "unitTestFull"
+    ],
+    "submit": [],
+    "package": [
+      "package"
+    ]
+  },
+  "validationPhases": {
+    "compile": "execute",
+    "unitTest": "execute",
+    "unitTestFull": "execute",
+    "apiTest": "execute",
+    "browserTest": "execute",
+    "dbCompatibility": "execute",
+    "package": "package"
+  },
+  "capabilityGates": {
+    "deployment": {
+      "signals": [
+        "deploy-required"
+      ],
+      "requiredStages": [
+        "package"
+      ],
+      "requiredValidations": [
+        "package"
+      ]
+    },
+    "container": {
+      "signals": [
+        "install-verification"
+      ],
+      "requiredStages": [
+        "package"
+      ],
+      "requiredValidations": [
+        "package"
+      ]
+    },
+    "api": {
+      "signals": [
+        "api-diff-present"
+      ],
+      "requiredStages": [
+        "apidoc"
+      ],
+      "requiredValidations": [
+        "apiTest"
+      ]
+    },
+    "database": {
+      "signals": [
+        "migration"
+      ],
+      "requiredStages": [],
+      "requiredValidations": [
+        "dbCompatibility"
+      ]
+    }
+  },
+  "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-test": [
+      "resource-intensive-test-confirmation"
+    ],
+    "harness-submit": [
+      "merge-conflict-resolution"
+    ],
+    "harness-plan": [
+      "risk-confirmation"
+    ],
+    "harness-execute": [
+      "resource-intensive-test-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/pi/harness-apidoc/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: harness-apidoc
+description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
+  /harness-apidoc 时使用，不得自动触发。
+---
+<!-- generated by harness_deploy.py; core=45b278c44cd66b19; overlay=java; agent=pi; do not edit -->
+# harness-apidoc — 前端接口文档（Java overlay）
+
+## Purpose
+
+基于 Controller、VO、ErrorCode 生成结构化前端接口文档（增量 + 全量）。
+
+## When to Use
+
+- 新功能完成需出接口文档
+- 触发语："接口文档""API 文档""写文档给前端"
+
+## 统一读取协议
+
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+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>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-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 优先）
+4. 生成/更新 `reports/apidoc/` 下 Markdown
+5. append `artifact` + `phase.end`
+
+## Output
+
+- `.harness/changes/<cn>/reports/apidoc/api-doc-*.md`（或项目约定路径）
+- 控制台摘要：新增/变更接口数
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
+- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
+- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust
+
+## 渐进披露
+
+- **Read `reference.md`** — 文档模板与字段规则
+- **Read `checklist.md`** — 逐步勾选
+
+## 交互白名单
+
+**无** blocking user confirmation；缺输入记 `issue`。
+
+## 执行日志
+
+`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]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
+```
+
+> **脚本接线**：`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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`apidoc`