@hunter-harness/workflow-harness 0.2.49 → 0.2.51

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

@@ -119,12 +119,19 @@ def post_json(endpoint: dict[str, str], path: str, body: dict[str, Any]) -> dict
         return json.loads(response.read().decode("utf-8"))
 
 
-def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False) -> dict[str, Any]:
+def sync_change(
+    project: Path,
+    change_dir: Path,
+    *,
+    heartbeat_only: bool = False,
+    run_id: str | None = None,
+    change_key: str | None = None,
+) -> dict[str, Any]:
     endpoint = load_endpoint(project)
     if endpoint is None:
         return {"ok": True, "skipped": True, "reason": "remote credentials not configured"}
-    change_key = change_dir.name
-    rid = run_id_for(change_dir)
+    resolved_key = change_key or change_dir.name
+    rid = run_id or run_id_for(change_dir)
     project_id = endpoint["project_id"]
 
     # Always heartbeat so the console can separate connection vs run status.
@@ -138,20 +145,26 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             {
                 "protocol_version": "hunter-progress-sync/v1",
                 "run_id": rid,
-                "change_key": change_key,
+                "change_key": resolved_key,
                 "client_time": client_time,
-                "title": change_key,
+                "title": resolved_key,
             },
         )
     except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
         return {"ok": False, "error": f"heartbeat failed: {exc}", "run_id": rid}
 
     if heartbeat_only:
-        return {"ok": True, "heartbeat": True, "run_id": rid}
+        return {"ok": True, "heartbeat": True, "run_id": rid, "change_key": resolved_key}
 
     events_file = change_dir / "events.ndjson"
     if not events_file.is_file():
-        return {"ok": True, "run_id": rid, "uploaded": 0, "reason": "no events.ndjson"}
+        return {
+            "ok": True,
+            "run_id": rid,
+            "change_key": resolved_key,
+            "uploaded": 0,
+            "reason": "no events.ndjson",
+        }
 
     lines = events_file.read_text(encoding="utf-8").splitlines()
     acked = load_cursor(change_dir)
@@ -167,7 +180,7 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             continue
         if not isinstance(event, dict):
             continue
-        event_id = str(event.get("id") or f"{change_key}:{acked + offset}")
+        event_id = str(event.get("id") or f"{resolved_key}:{acked + offset}")
         payload = sanitize(event)
         batch.append(
             {
@@ -181,7 +194,13 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
         )
     if not batch:
         save_cursor(change_dir, len(lines))
-        return {"ok": True, "run_id": rid, "uploaded": 0, "acked_lines": len(lines)}
+        return {
+            "ok": True,
+            "run_id": rid,
+            "change_key": resolved_key,
+            "uploaded": 0,
+            "acked_lines": len(lines),
+        }
 
     # Drop None phase keys for strict schema.
     for item in batch:
@@ -195,8 +214,8 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             {
                 "protocol_version": "hunter-progress-sync/v1",
                 "run_id": rid,
-                "change_key": change_key,
-                "title": change_key,
+                "change_key": resolved_key,
+                "title": resolved_key,
                 "events": batch,
             },
         )
@@ -222,6 +241,7 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
     return {
         "ok": accepted == len(batch),
         "run_id": rid,
+        "change_key": resolved_key,
         "uploaded": accepted,
         "batch_size": len(batch),
         "acked_lines": acked_lines,
@@ -229,10 +249,62 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
     }
 
 
+def auto_events_sync(
+    project_root: Path,
+    change_dir: Path,
+    *,
+    heartbeat_only: bool = False,
+    run_id: str | None = None,
+    change_key: str | None = None,
+) -> dict[str, Any]:
+    """Best-effort platform events sync (same style as auto_push_archive_core).
+
+    Failures become warnings so the caller never rolls back the main workflow.
+    """
+    project_root = project_root.resolve()
+    change_dir = change_dir.resolve()
+    if load_endpoint(project_root) is None:
+        return {"skipped": True, "reason": "no remote credentials"}
+    try:
+        result = sync_change(
+            project_root,
+            change_dir,
+            heartbeat_only=heartbeat_only,
+            run_id=run_id,
+            change_key=change_key,
+        )
+    except Exception as exc:  # noqa: BLE001 — best-effort never blocks caller
+        return {
+            "skipped": False,
+            "ok": False,
+            "warning": f"events-sync deferred: {exc}",
+        }
+    if result.get("skipped"):
+        return {"skipped": True, "reason": result.get("reason") or "skipped"}
+    if result.get("ok"):
+        return {"skipped": False, "ok": True, **{
+            key: result[key]
+            for key in ("run_id", "change_key", "uploaded", "acked_lines", "heartbeat")
+            if key in result
+        }}
+    return {
+        "skipped": False,
+        "ok": False,
+        "warning": str(result.get("error") or "events-sync failed"),
+        **{
+            key: result[key]
+            for key in ("run_id", "change_key")
+            if key in result
+        },
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Sync events.ndjson to platform Run monitoring")
     parser.add_argument("--project", default=".", help="Project root")
     parser.add_argument("--change-dir", help="Specific change directory")
+    parser.add_argument("--run-id", help="Override stable run_id (archive finalize continuity)")
+    parser.add_argument("--change-key", help="Override change_key sent to the platform")
     parser.add_argument("--heartbeat-only", action="store_true")
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args(argv)
@@ -243,7 +315,13 @@ def main(argv: list[str] | None = None) -> int:
         root = project / ".harness" / "changes"
         changes = sorted(path for path in root.glob("*") if path.is_dir()) if root.is_dir() else []
     results = [
-        sync_change(project, change_dir, heartbeat_only=args.heartbeat_only)
+        sync_change(
+            project,
+            change_dir,
+            heartbeat_only=args.heartbeat_only,
+            run_id=args.run_id,
+            change_key=args.change_key,
+        )
         for change_dir in changes
     ]
     ok = all(item.get("ok") for item in results) if results else True

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

@@ -31,6 +31,7 @@ if str(SCRIPTS_DIR) not in sys.path:
 
 import harness_change as hc  # noqa: E402
 import harness_events as he  # noqa: E402
+import harness_events_sync as hes  # noqa: E402
 import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
 import harness_plan_finalize as hpf  # noqa: E402
@@ -2213,6 +2214,22 @@ def cmd_begin(args: argparse.Namespace) -> int:
         "gateSeverityMode": severity_mode,
         "gateWarnings": gate_warnings,
     }
+    # C3: best-effort start platform run monitoring (register + running via heartbeat/events).
+    try:
+        monitor = hes.auto_events_sync(project, change_dir)
+        payload["platformMonitor"] = monitor
+        if monitor.get("warning"):
+            warnings_msg = str(monitor["warning"])
+            gate_warnings.append({
+                "code": "PLATFORM_EVENTS_SYNC_WARN",
+                "message": warnings_msg,
+            })
+            payload["gateWarnings"] = gate_warnings
+    except Exception as exc:  # noqa: BLE001 — never block phase begin
+        payload["platformMonitor"] = {
+            "ok": False,
+            "warning": f"events-sync hook failed: {exc}",
+        }
     emit(payload, as_json=as_json)
     return 0
 

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

@@ -852,7 +852,6 @@ def _node_commands(project: Path) -> dict[str, Any]:
         inputs.extend(
             [
                 "harness/scripts/*.py",
-                "harness/harness-knowledge-ingest/scripts/*.py",
                 "harness/harness-test/scripts/*.mjs",
                 "harness/harness-test/scripts/tests/*.mjs",
                 "scripts/*.mjs",

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

@@ -218,11 +218,9 @@ def discover_segment_files(
         project / "harness.json",
     ]
     codebase_map = list((project / ".harness/codebase/map").glob("**/*"))
-    knowledge = [
-        project / ".harness/knowledge/index.json",
-        project / ".harness/knowledge/status.json",
-        project / ".harness/knowledge/config.json",
-    ]
+    # Knowledge is remote-only. Keep the segment for schema compatibility, but
+    # do not discover or fingerprint local indexes/fallback state.
+    knowledge: list[Path] = []
     change_inputs: list[Path] = []
     for folder in ("spec", "plans", "meta"):
         change_inputs.extend((change_dir / folder).glob("**/*"))

package/harness/bundles/java/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "0c4a64243d3f7bfb"
+  "coreHash": "63cbdcb9833a5c07"
 }

package/harness/bundles/java/codebuddy/README.md

@@ -56,8 +56,8 @@
 | harness-review | `[Read, Write, Edit, Glob, Grep, Agent, Bash(powershell.exe:*)]` | 同上 |
 | harness-sync | `[Read, Glob, Grep, Edit, Write, Bash(powershell.exe:*)]` | 同上 |
 | harness-codebase-map | `[Read, Glob, Grep, Write, Edit, Agent, Bash(powershell.exe:*)]` | 同上 |
-| harness-knowledge-query | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
-| harness-knowledge-ingest | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
+| harness-knowledge-query | `[Bash(powershell.exe:*), Read, Glob, Grep]` | 同上 |
+| harness-knowledge-ingest | `[Bash(powershell.exe:*), Read, Glob, Grep]` | 同上 |
 
 > **blocking user confirmation 不预批准**：各 skill 需要向用户确认时通过普通权限提示调用 `blocking user confirmation`（adapter 映射到 `AskUserQuestion`/`request_user_input`/普通对话），不在 `allowed-tools` 中预批准（遵循 skill-optimizer 规则）。`harness-codebase-map` 额外预批准 `Agent` 用于派发并行 mapper。
 
@@ -227,8 +227,8 @@ harness-skills/
 | harness-review | `/harness-review` | 6维度参考性审查（不阻塞后续流程） | `test` | 手动 | `.harness/changes/<cn>/reports/review/` |
 | harness-submit | `/harness-submit` 或 `/harness-merge`（别名） | commit+push（主目录）/ worktree：本地 commit→--no-ff 合并→push 主分支 | `review` | 手动 | ledger `mergeFinalHash` + 控制台报告 |
 | harness-archive | `/harness-archive` | 归档产出到 archive/YYYY-MM-DD-<cn>，释放工作区 | `submit` | 手动 | `.harness/archive/YYYY-MM-DD-<cn>/` |
-| harness-knowledge-query | `/harness-knowledge-query` | 查询 .harness/knowledge 历史上下文，生成需求 context pack | `sync`/独立 | ✅ | `.harness/knowledge/context-packs/` |
-| harness-knowledge-ingest | `/harness-knowledge-ingest` | 从 archive 整理/同步/维护知识索引（promote/demote/audit） | `archive` | ✅ | `.harness/knowledge/index.json` |
+| harness-knowledge-query | `/harness-knowledge-query` | 只查询平台语义知识；无本地索引或离线回退 | 独立 | ✅ | CLI JSON（不落本地知识文件） |
+| harness-knowledge-ingest | `/harness-knowledge-ingest` | 确认归档 ZIP 已由平台保存、解包并 ingest | `archive` | ✅ | 服务端 package/knowledge 收据 |
 
 > 生命周期 skill（plan → run → test → review → submit → archive）为**手动触发**：单阶段结束后停止，不自动接续下一阶段（已设 `disable-model-invocation`）。sync / codebase-map / knowledge 等辅助 skill 仍可按需被调用。`harness-run`、`harness-submit`、`harness-archive` 涉及 git 写操作、文件移动或归档，调用前必须确保前置条件已满足。
 > `<cn>` = change-name，由 harness-plan 阶段7确定。其他 skill 自动扫描未归档变更定位。

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

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=0c4a64243d3f7bfb; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=63cbdcb9833a5c07; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -25,7 +25,7 @@ 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 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol
@@ -54,6 +54,11 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 - 命令结果不得靠猜测；普通 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
 
 ## 渐进披露

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=0c4a64243d3f7bfb; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=63cbdcb9833a5c07; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -58,7 +58,7 @@ 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 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol
@@ -100,7 +100,10 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --intent release-candidate --json` 前置检查。无 CI 项目若已有完整全量 ledger，先运行 `certify-local`；若用户明确只封存事实，则 status/finalize 均使用 `--intent record-only`。
 2. `meta/archive-meta.md` **由 `harness_archive.py finalize` 自动生成**（与 summary-data `finalStatus` 同源）；**禁止 agent 手写**该文件，手写视为数据丢失。维护者结论写入 events（decision/issue）即可，finalize 会汇总到 summary / archive-meta。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent <release-candidate|record-only> --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent <release-candidate|record-only> --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta、ZIP package、上传与服务端 knowledge status）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**本地不再执行知识维护，也不写 maintenance-outbox**；服务端在归档 ZIP 持久保存并解包后 ingest。**finalize 失败或 validate 报错时不删除原目录**。
+   - **归档包上传**：始终先生成一个确定性 ZIP；有远程凭据时再调用 `npx hunter-harness archive upload`。ZIP 仅包含 `summary-data.json`、`spec/**/*.md`、`plans/**/*.md`、`archive-meta.md`、`change-context.json` 和稳定 manifest；明确排除 logs、review/test 报告、HTML、缓存、备份、凭据和临时文件。
+   - **失败可恢复**：无论远端凭据是否齐全，都先生成 ZIP 与 `<change-key>.upload.json`；上传或服务端 ingest 失败不破坏本地归档。待上传 ZIP 与逐 change 回执保留在 `.harness/state/local/archive-packages/`，可枚举独立重试。只有 CLI 核验 package hash 且服务端同时返回 `archive_status=durable`、`knowledge_status=ready` 后，才清理对应 ZIP 与回执；`indexing` 记为 pending，不记为失败。
+   - **监控终态（C3）**：auto-upload 之后自动 `events-sync`，用归档前 change 路径派生的 `run_id` + 原 `change_key` 上报；失败只记 warning。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构
@@ -117,6 +120,11 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 - 命令结果不得靠猜测；普通 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
 
 ## 关键规则（硬门禁速查）

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=0c4a64243d3f7bfb; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=63cbdcb9833a5c07; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -56,6 +56,11 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 - 命令结果不得靠猜测；普通 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 · map 额外：文件存在/行数/hash 为证据
 
 ## 关键规则