@hunter-harness/workflow-harness 0.2.6 → 0.2.7

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=9fa8511a55ff544c; 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
@@ -30,6 +30,12 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 
 ## 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 优先）

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=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -55,6 +55,8 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ## 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. 读取本文件。

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

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

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/scripts/harness_knowledge.py

@@ -2982,6 +2982,7 @@ def query_index(
     file_filters: list[str] | None = None,
     statuses: list[str] | None = None,
     types: list[str] | None = None,
+    change_id: str | None = None,
 ) -> dict[str, Any]:
     project = project.resolve()
     knowledge = project / ".harness" / "knowledge"
@@ -2994,6 +2995,26 @@ def query_index(
     build_index(project, snapshot=snapshot)
     entries = search_entries(sqlite_path, query, limit, file_filters, statuses, types)
     context_path = write_context_pack(project, knowledge, query, entries)
+    if change_id:
+        changes_root = (project / ".harness" / "changes").resolve()
+        change_dir = (changes_root / change_id).resolve()
+        try:
+            change_dir.relative_to(changes_root)
+        except ValueError as exc:
+            raise ValueError("change id escapes .harness/changes") from exc
+        if not change_dir.is_dir():
+            raise ValueError(f"change does not exist: {change_id}")
+        write_json(
+            change_dir / "meta" / "knowledge-context.json",
+            {
+                "schemaVersion": 1,
+                "changeId": change_id,
+                "generatedAt": now_iso(),
+                "query": query,
+                "contextPack": str(context_path),
+                "matchIds": [entry["id"] for entry in entries],
+            },
+        )
     filters = {
         "files": file_filters or [],
         "statuses": statuses or [],
@@ -4391,6 +4412,7 @@ def main(argv: list[str] | None = None) -> int:
     query.add_argument("--file", action="append", dest="files", default=[], help="Only return entries linked to this source file")
     query.add_argument("--status", action="append", dest="statuses", default=[], help="Only return entries with this lifecycle status")
     query.add_argument("--type", action="append", dest="types", default=[], help="Only return entries of this knowledge type")
+    query.add_argument("--change", default=None, help="Write a change-scoped knowledge-context pointer")
 
     promote = sub.add_parser("promote", help="Promote a candidate knowledge entry to active")
     promote.add_argument("--project", default=".", help="Project root containing .harness/knowledge")
@@ -4487,7 +4509,10 @@ def main(argv: list[str] | None = None) -> int:
         print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0
     if args.command == "query":
-        result = query_index(Path(args.project), args.query, args.limit, args.files, args.statuses, args.types)
+        result = query_index(
+            Path(args.project), args.query, args.limit, args.files, args.statuses,
+            args.types, args.change,
+        )
         print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0
     if args.command == "promote":

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/scripts/harness_knowledge_mcp.py

@@ -219,6 +219,7 @@ def create_server() -> Any:
         files: list[str] | None = None,
         statuses: list[str] | None = None,
         types: list[str] | None = None,
+        change_id: str | None = None,
     ) -> dict[str, Any]:
         return hk.query_index(
             Path(project),
@@ -227,6 +228,7 @@ def create_server() -> Any:
             file_filters=files or [],
             statuses=statuses or [],
             types=types or [],
+            change_id=change_id,
         )
 
     @server.tool(description=TOOL_DESCRIPTIONS[7]["description"])

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

@@ -3,9 +3,11 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
+并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。
+
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
 
 此 skill 只负责查询和使用知识。整理、同步和 promote 条目由 `harness-knowledge-ingest` 负责。

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

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。使用场景：打包、package、发版准备
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose
@@ -37,10 +37,13 @@ description: 增量模块打包：拉取最新→编译验证→mvn package→
 
 ## Workflow
 
-1. 读 ledger + build-profile 的 `commands.package`（v2，按 profile key resolve）
+0. `harness_change.py resolve` → **`harness_gate.py begin --phase package --change <id>`**
+1. 读 ledger + build-profile 的 `commands.package`（v2，按 profile key resolve）；验证经 `harness_ledger.py can-reuse` / `record`（禁止手写 ledger）
 2. 识别变更模块（git diff + pom 结构）
 3. **单次** Maven package lifecycle（spec §3.3 去重，不预先 compile/test）：full test 可复用（`can-reuse unitTestFull=true`）→ 按 `commands.package` resolve 执行一次 skip-tests package；不可复用 → 按 `commands.package` resolve 执行一次含测试 package
-4. 写打包报告 + append 事件
+4. 写打包报告 → **`harness_gate.py close --phase package --status ...`**（禁止手工 phase.end）
+
+> `MISSING_V2_FIELDS` 时必须重新 `record`/执行验证，禁止用自然语言绕过。
 
 ## P0 执行可信度规则
 

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

@@ -2,11 +2,13 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
 
+确定 change 后必须运行 `python <skills-root>/scripts/harness_gate.py classify --change <id> --stage plan --json`，并把脚本返回的 risk tier、默认阶段、条件阶段和必需验证写入计划；不得凭模型印象另建风险分级。
+
 需求 → 设计文档 → 任务拆分 → 测试场景表（编码/测试唯一真相源）。存在 `.harness/archive/` 或 `.harness/knowledge/` 时须先 `harness-knowledge-query`。
 
 ## When to Use

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

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -45,6 +45,8 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 
 ## Workflow
 
+先用 `harness_change.py resolve [--change] --json` 解析 change；多个 active change 未显式选择时返回 `CHANGE_SELECTION_REQUIRED`，禁止再按 Glob/mtime 猜测。阶段边界固定使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json` 和 `harness_gate.py close --phase review --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --json`。不得手工追加 `phase.start/phase.end`；close 失败不得宣称审查完成。
+
 0. **启动准备** — 确定变更名（Glob `.harness/changes/*/plans/*-plan.md`，排除 `.harness/archive/*/`，读 frontmatter 提取 change-name）；**append `phase.start` 事件**（不得等审查完成才补）
 1. **读取 worktree 状态（门禁检查）** — 读 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 但 worktree 不存在 → 停止并提示先修复 `harness-run`，不得静默回主目录（否则 git diff 为空）；`requested=true` 且 worktree 已创建 → spawned agent 用该 worktree 路径执行 `git diff`（确保审查 worktree 变更而非主目录）；`requested=false` → 审查主目录变更
 <!-- @section-id review.delegate -->

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

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -54,15 +54,17 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## Workflow 概要
 
-0. 加载上下文（change-name、spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback）→ append `phase.start`
-0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5
+0. 加载上下文：先 `harness_change.py resolve [--change] --json`（多 active 缺参 → `CHANGE_SELECTION_REQUIRED`，禁止按 mtime 猜测）；读 spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback → **`harness_gate.py begin --phase run --change <id>`**（内部 claim + phase.start + identity；禁止手工 Write `events.ndjson` / 手工 `phase.end`）
+0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；进入 TDD 前执行 `harness_test_guard.py begin --project . --change-dir ".harness/changes/<cn>" --json`
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + 写 ledger（`harness_ledger.py diff-hash --change-dir` 纳入 ignored tests，`reference.md` Step 2c）
+2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-4. **关门检查**（10 项）+ 计划状态持久化
+4. **关门检查**（10 项）→ `harness_test_guard.py close` → **`harness_gate.py close --phase run --change <id> --status <OK|WARN|FAIL>`**（内部 phase.end + 释放租约；close 失败不得用自然语言宣称成功）
 
 **Fixback**：`--fixback` 或用户要求时读 `reports/review/fixback-*.md`；RED 优先；未选用则记 `fixback: advisory-not-applied`。
 
+**Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
+
 ### Java 构建验证（Maven）
 
 - 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `commands`（v2，按 profile key resolve；**禁止 hardcode 模块名/端口**）
@@ -87,7 +89,8 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | **变更簇 TDD** | 一簇一次 RED/GREEN；低价值项豁免；新分支必须 RED |
 | **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过；greenfield 大重写豁免见 reference |
 | **Mapper/DB** | 纯 Mock 不得宣称 DB 验证通过；迁移脚本**永不自动执行** |
-| **探测/ledger** | 基础设施先探测；每次构建/测试写 ledger；用 canonical `diff-hash --change-dir` |
+| **探测/ledger** | 基础设施先探测；每次构建/测试经 `harness_ledger.py record`；禁止手写 ledger JSON；用 canonical `diff-hash --change-dir` |
+| **Gate/Guard** | 阶段边界只用 `harness_gate.py begin/close`；测试跟踪用 `harness_test_guard.py begin/close/record/stage` |
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
 | **Worktree** | `requested=true` 时代码只写 worktree |

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

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -50,18 +50,20 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 
 ## Workflow
 
+worktree 合并前必须运行 `harness_change.py integration-lock acquire --run-id <run-id> --json`；获取失败即停止。无论成功、冲突或异常，都在 `finally` 运行 `harness_change.py integration-lock release --run-id <run-id> --json`。持有 integration lock 后不得反向申请 change lease。
+
 **模式判定**：读 `meta/worktree.json`。`requested=false` → 步骤 0–7（主目录）；`requested=true` → 步骤 0–6 在 worktree 执行，成功后**不结束**，接续「worktree 合并流程」。用户仅调用 `/harness-merge` 且 worktree 已有本地 commit 时，从合并流程步骤 M0 重入。
 
 ### 提交流程（步骤 0–7）
 
-0. **启动准备** — 确定变更名；读 ledger，以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类；append `phase.start`
+0. **启动准备** — `harness_change.py resolve` 确定变更名；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（禁止手写 ledger / 手工 phase.end）
 1. **合并最新代码** — 主目录：`stash` → `pull --rebase` → `stash pop`；**worktree：N/A**（远端同步在合并段主分支完成）
-2. **最终验证** — ledger 复用优先；**提交前最终门禁只调 `can-reuse`**（删除与 coverage 冲突的二次全量门禁）：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <resolved commands.unitTestFull.command>`。`--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command，**不复制示例模块名**（文档示例只展示 key）。`--profile-input unitTestFull` 从 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开依赖闭包，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包。`reuse=true` → 不再执行二次全量测试；仅 `reuse=false` 时执行**同一 resolved verification**（profile `unitTestFull` 命令），成功后用同一文件集、command、`scope=module` 写回 ledger `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
+2. **最终验证** — ledger 复用优先；**提交前最终门禁只调 `can-reuse`**（删除与 coverage 冲突的二次全量门禁）：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <resolved commands.unitTestFull.command>`。`--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command，**不复制示例模块名**（文档示例只展示 key）。`--profile-input unitTestFull` 从 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开依赖闭包，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包。`reuse=true` → 不再执行二次全量测试；仅 `reuse=false` 时执行**同一 resolved verification**（profile `unitTestFull` 命令），成功后用同一文件集、command、`scope=module` 经 **`harness_ledger.py record`** 写回 ledger `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
 3. **.gitignore + 精确暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**。若存在 `evidence/test-tracking.json`，先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；失败即硬停止。无 manifest 时不使用 `-f`。manifest 之外的文件按精确业务路径正常暂存，**禁止全局 force-add**。
 4. **提交方式** — 主目录：AskUserQuestion 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**
 5. **commit-message.txt** ⚠️ — 展示 staged、diff stat、完整中文 message；用户确认
 6. **commit / push** — `git commit -F`；主目录按选项 push（push 前 fetch 检查远端）；**worktree：只 commit，记录 local hash**
-7. **收尾引导** — 主目录：可选 worktree 清理 + 提示 `/harness-archive`；**worktree：接续下方合并流程**
+7. **收尾** — **`harness_gate.py close --phase submit --status ...`**；主目录：可选 worktree 清理 + 提示 `/harness-archive`；**worktree：接续下方合并流程**
 
 详细步骤见 `checklist.md`。
 
@@ -75,7 +77,7 @@ M4. **冲突处理** — 若 `CONFLICT` → **停下**，列出冲突文件，
 M5. **合并后验证** — 他人提交引入 → 必须重跑构建+测试；否则 ledger 复用 🔁REUSED
 M6. **push 主分支** — fetch 后 `log HEAD..@{u}` 非空则回 M2；否则 push，记录 `mergeFinalHash`
 M7. **清理 worktree** — `worktree remove` + `branch -D`（Windows 兜底见 `reference.md`）；更新 `worktree.json`（`created=false` + removedAt 等）
-M8. **ledger + 收尾** — 写入 `mergeFinalHash`；append `phase.end`；提示 `/harness-archive`
+M8. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
 
 ### Java 提交前验证补充
 

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

@@ -2,7 +2,7 @@
 name: harness-sync
 description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=9fa8511a55ff544c; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=48a6bb3c8d0d04e0; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -42,9 +42,15 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 
 ## Workflow
 
+测试跟踪的确定性边界为 `harness_test_guard.py begin` 和 `harness_test_guard.py close`；任一失败都必须传递给 `harness_gate.py close`，不得以自然语言覆盖失败状态。
+
+并行服务测试先运行 `harness_change.py lease-port --change <id> --run-id <run-id> --range <start-end> --json`，再把返回端口传给 `harness_service.py ensure --leased-port <port> --lease-owner <run-id>`。`serviceStart` 的 command/health/overlay 可用 `{leasedPort}` 占位符；用户自启进程仍只进入 Service Gate，禁止 kill。测试清理的 `finally` 中运行 `harness_change.py release-port --change <id> --run-id <run-id> --json`，避免租约池耗尽。
+
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
-执行 各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+先 `harness_change.py resolve [--change] --json` 解析 change-id；再 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
+
+验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`。
 
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Small deterministic helpers for compact API contract reports."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+
+
+COMMIT_ONLY = re.compile(r"^[0-9a-f]{7,64}$", re.IGNORECASE)
+INVALID_FILENAME = re.compile(r"[<>:\"/\\|?*\x00-\x1f]+")
+SEPARATORS = re.compile(r"[\s_-]+")
+
+
+def build_filename(description: str, *, date: str | None = None) -> str:
+    raw = str(description or "").strip()
+    if not raw or COMMIT_ONLY.fullmatch(raw):
+        raise ValueError("a human-readable API change description is required")
+    slug = INVALID_FILENAME.sub("-", raw)
+    slug = SEPARATORS.sub("-", slug).strip(" .-")
+    if not slug:
+        raise ValueError("description does not contain filename-safe text")
+    day = date or dt.date.today().isoformat()
+    slug = slug[:86].rstrip(" .-")
+    return f"{day}-{slug}.md"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    filename = sub.add_parser("filename", help="build a safe dated report filename")
+    filename.add_argument("--description", required=True)
+    filename.add_argument("--date", default=None)
+    filename.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        value = build_filename(args.description, date=args.date)
+    except ValueError as exc:
+        sys.stderr.write(json.dumps({"ok": False, "error": str(exc)}) + "\n")
+        return 1
+    payload = {"ok": True, "filename": value}
+    if args.json:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    else:
+        sys.stdout.write(value + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())