@hunter-harness/workflow-harness 0.2.40 → 0.2.41

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

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; 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 的上下文归属。

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=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

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

@@ -228,35 +228,35 @@ status: approved
 
 #### 1.1 <类名.方法名>
 
-| ID | 优先级 | 分类 | 场景描述 | 输入 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:------:|:----:|----------|------|------|----------|----------|----------|------|------------|
-| UT-001 | P0 | 正常 | ... | ... | ... | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
-| UT-002 | P0 | 异常 | ... | ... | 抛 xxxException | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
-| UT-003 | P1 | 边界 | ... | ... | ... | module | ≤60s | ≤50% CPU / ≤1GB | 120s | ledger identity |
+| ID | 优先级 | 分类 | 场景描述 | 输入 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 | 可执行测试 ID | 测试文件 | 测试标题 |
+|:--:|:------:|:----:|----------|------|------|----------|----------|----------|------|------------|----------------|----------|----------|
+| UT-001 | P0 | 正常 | ... | ... | ... | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command | service::happy-path | tests/service.test.ts | returns expected result |
+| UT-002 | P0 | 异常 | ... | ... | 抛 xxxException | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command | service::invalid-input | tests/service.test.ts | rejects invalid input |
+| UT-003 | P1 | 边界 | ... | ... | ... | module | ≤60s | ≤50% CPU / ≤1GB | 120s | ledger identity | service::boundary | tests/service.test.ts | handles boundary |
 
 ### 二、接口测试场景
 
 #### 2.1 POST /xxx
 
-| ID | 优先级 | 分类 | 场景描述 | 关键字段 | HTTP | code | message | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:------:|:----:|----------|----------|:----:|:----:|--------|----------|----------|----------|------|------------|
-| API-001 | P0 | 正常 | ... | ... | 200 | 0 | 成功 | module | ≤60s | 1 service / ≤1GB | 120s | environmentHash + ledger |
-| API-002 | P1 | 校验 | ... | ... | 200 | xxx | ... | affected | ≤20s | 1 service / ≤1GB | 60s | environmentHash + ledger |
+| ID | 优先级 | 分类 | 场景描述 | 关键字段 | HTTP | code | message | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 | 可执行测试 ID | 测试文件 | 测试标题 |
+|:--:|:------:|:----:|----------|----------|:----:|:----:|--------|----------|----------|----------|------|------------|----------------|----------|----------|
+| API-001 | P0 | 正常 | ... | ... | 200 | 0 | 成功 | module | ≤60s | 1 service / ≤1GB | 120s | environmentHash + ledger | api::success | tests/api.spec.ts | creates resource |
+| API-002 | P1 | 校验 | ... | ... | 200 | xxx | ... | affected | ≤20s | 1 service / ≤1GB | 60s | environmentHash + ledger | api::validation | tests/api.spec.ts | rejects invalid body |
 
 ### 三、数据兼容场景
 
-| ID | 优先级 | 分类 | 场景描述 | 操作 | 数据特征 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:------:|:----:|----------|:----:|----------|------|----------|----------|----------|------|------------|
-| COM-001 | P1 | 旧数据 | ... | ... | ... | ... | module | ≤60s | isolated DB / ≤1GB | 120s | dbSchemaHash + ledger |
+| ID | 优先级 | 分类 | 场景描述 | 操作 | 数据特征 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 | 可执行测试 ID | 测试文件 | 测试标题 |
+|:--:|:------:|:----:|----------|:----:|----------|------|----------|----------|----------|------|------------|----------------|----------|----------|
+| COM-001 | P1 | 旧数据 | ... | ... | ... | ... | module | ≤60s | isolated DB / ≤1GB | 120s | dbSchemaHash + ledger | db::legacy-row | tests/db-compat.spec.ts | reads legacy row |
 
 ### 四、集成场景
 
-| ID | 优先级 | 分类 | 场景描述 | 前置条件 | 步骤 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:------:|:----:|----------|----------|------|------|----------|----------|----------|------|------------|
-| INT-001 | P0 | 端到端 | ... | ... | N 步操作 | ... | candidate | ≤10m | ≤50% CPU / ≤2GB | 15m | verification identity |
+| ID | 优先级 | 分类 | 场景描述 | 前置条件 | 步骤 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 | 可执行测试 ID | 测试文件 | 测试标题 |
+|:--:|:------:|:----:|----------|----------|------|------|----------|----------|----------|------|------------|----------------|----------|----------|
+| INT-001 | P0 | 端到端 | ... | ... | N 步操作 | ... | candidate | ≤10m | ≤50% CPU / ≤2GB | 15m | verification identity | e2e::workflow | tests/workflow.e2e.ts | completes workflow |
 ```
 
-新计划必须显式使用 `ID` 和 `优先级` 列；`P0/P1` 都要求 ledger 证据，`P2` 才是 advisory。解析器兼容旧的 `#`、`分类`、`场景描述` 表头，旧表缺优先级时保守按 `P1` 处理。执行层级固定为 `affected`（快速反馈）、`module`（变更模块门禁）、`candidate`（产品候选）。禁止所有场景默认跑全仓库；无法给出预算或超时时必须说明原因，并拆分或隔离高成本场景。只有 command、inputs/toolchain/environment 身份一致的成功 ledger 证据可以复用。
+新计划必须显式使用 `ID`、`优先级`、`可执行测试 ID`、`测试文件`、`测试标题` 列；每个 P0/P1 场景都必须填写稳定的三元测试身份，缺任一字段时 plan finalize 返回 `PLAN_SCENARIO_EXECUTABLE_MAPPING_MISSING`。`P0/P1` 都要求结构化 runner receipt + ledger 证据，`P2` 才是 advisory。解析器兼容旧的 `#`、`分类`、`场景描述` 表头，旧表缺优先级时保守按 `P1` 处理。执行层级固定为 `affected`（快速反馈）、`module`（变更模块门禁）、`candidate`（产品候选）。禁止所有场景默认跑全仓库；无法给出预算或超时时必须说明原因，并拆分或隔离高成本场景。只有 command、inputs/toolchain/environment 身份一致，且 declared/selected/collected/executed/passed 闭环完整的成功 ledger 证据可以复用。
 
 ## 产物保存规则（跨阶段：阶段0.5/4/6/8）
 

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=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

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=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

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=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

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

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, knowledge, rules, instruction entrypoints, config origins,
   or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; 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=987b03720a6febfd; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3a5923039708d7bb; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -70,6 +70,8 @@ python harness/scripts/harness_test_runner.py unittest --profile safe --tests-di
 
 Runner 强制同项目单实例、低调度优先级、逐命令超时、正常结束和异常结束的进程树清理。`HARNESS_TEST_MAX_WORKERS` 默认且最高为 `2`，只能调低，不能调高；技术栈自身的并发参数也必须收敛到该值。Windows detached-service 模块在执行前先做 nested-breakaway 能力探测，受限沙箱不支持时立即返回 `DETACHED_PROCESS_CAPABILITY_UNAVAILABLE`，不得让每个服务用例逐一超时。出现该错误、`TEST_RUN_ALREADY_ACTIVE`、`PROCESS_TREE_ISOLATION_UNAVAILABLE` 或 `TEST_COMMAND_TIMEOUT` 必须停止，不得绕过 Runner 重跑裸命令。完整约束见 `checklist.md`「0.0-A 资源安全档位」。
 
+动态数据库/Redis/令牌字段必须先由 `harness_environment.py prepare` 生成 secret-free receipt，再用 `exec --environment-receipt <file> --required-environment-field <NAME>` 闭包注入；缺失或指纹变化在启动测试前返回 `VERIFICATION_ENVIRONMENT_INCOMPLETE`。复杂 JSON、Docker template 或含引号参数不得跨多层 `-Command` 传递，改用 `exec --argv-file <utf8-json> --runtime-receipt <file>`；参数文件记录 PowerShell edition/version，运行回执只存 argv hash。`harness_service.py ensure` 属于正式持久服务模式，禁止从 bounded runner 内启动；命中时返回 `PERSISTENT_SERVICE_MODE_REQUIRED`。
+
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
 先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。

package/harness/bundles/java/codebuddy/protocols/archive-report-protocol.md

@@ -109,6 +109,16 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 - generatedFiles：archive 过程中生成的文件数；
 - totalArchiveFiles：归档目录最终文件总数。
 
+## Durable archive
+
+同一工作区内从 `changes/` move 到 `archive/` 只属于 local archive。需要抗工作区删除时，finalize 必须配置独立 `--durable-root`：
+
+- payload 以整树 digest 写入 `<durable-root>/objects/sha256/<digest>/payload/`，对象不可变且可内容寻址；
+- `<durable-root>/receipts/<archive-id>.json` 记录 digest、来源 identity、保留策略与验证时间；
+- durable 写入采用 staging → hash/readback verify → atomic publish；失败时保留原 change，且不得留下可被误认成功的 local archive；
+- `restore-durable` 先验证 receipt 与对象 digest，只恢复到不存在的目标，完成后再次比对整树 digest；
+- 成功状态区分 `ARCHIVED_DURABLE` 与 `ARCHIVED_LOCAL_ONLY`，后者必须进入 knownRisks。
+
 ## 页面内容
 
 final-summary 必须突出：

package/harness/bundles/java/codebuddy/protocols/ledger-protocol.md

@@ -351,3 +351,15 @@ v2 契约下 `record` 写入前强制解析并校验顶层身份字段，缺失
 ### 10.4 原子写入
 
 `write_ledger` 采用 tmp → fsync → `os.replace`；replace 失败时旧账本字节不变、不留 `.tmp` 残骸。所有写路径（record / 其他命令）统一走原子写。
+
+### 10.5 写前透明迁移
+
+Reader 继续读取当前 v3 与前一支持窗口 v2（并保守识别无 schema 的 v1）。已有 schemaVersion 2 ledger，或显式携带 identity 参数的 legacy ledger，再次 `record` 时必须先完成身份迁移再修改任何 evidence；无 schema 且未显式请求 identity 的旧调用继续保持兼容行为：
+
+- 解析 repository/change/base/current/diff/ownership identity，目标固定为 schemaVersion 3；
+- 对 `validations`、`verificationTargets`、`integration`、`artifacts` 生成迁移前 evidence identity；
+- 迁移只增加 schema/identity 元数据，迁移后 evidence identity 必须完全相同；
+- 把 receipt 原子嵌入 `migrationHistory[]`，记录 original/target schema、before/after identity 与 `receiptId`；
+- 版本超出支持窗口、仓库/ownership/diff 无法确认、或 evidence identity 漂移时不写文件，返回 `LEDGER_MIGRATION_REQUIRED` 与参数数组形式的 `rerecordCommand`。
+
+submit/review/test/archive 只能通过 `harness_ledger.py` 读取/写入，禁止各自实现 schema 猜测或手工改 ledger。

package/harness/bundles/java/codebuddy/protocols/powershell-protocol.md

@@ -195,3 +195,24 @@ Windows 默认常为 Windows PowerShell **5.1**。下列特性在 5.1 不可用
 
 - 非 ASCII 路径（含中文）仓库：git/构建/文件操作一律 PowerShell；Bash 被 hook 拒绝（如 `Denied: non-ASCII path`）后**立即**改用 PowerShell 重发等价命令，禁止原样重试 Bash。
 - Maven `-D` 参数在 PowerShell 中加引号：`"-Dmaven.test.skip=true"`。
+
+## 13. PS5/PS7 原生参数合同
+
+复杂 JSON、Docker Go template、here-string 内容及多层引号不得作为 native process 的内联参数跨 `Bash → powershell -Command → native executable` 传递。统一写 UTF-8 JSON 参数文件：
+
+```json
+{
+  "schemaVersion": 1,
+  "transport": "utf8-json-argument-file",
+  "argv": ["python", "tool.py", "--template", "{{json .State}}"],
+  "powershell": {"edition": "Desktop", "version": "5.1"}
+}
+```
+
+执行入口：
+
+```powershell
+python harness/scripts/harness_test_runner.py exec --argv-file <file> --runtime-receipt <receipt>
+```
+
+Runner 直接把 `argv[]` 传给 native process（`shell=False`），不重新拼接或解析命令文本。PowerShell Desktop 5.1 与 Core 7 使用同一参数文件必须产生相同 argv。运行回执记录 edition/version、参数数量和 argv SHA-256，不写原始参数，避免凭证或模板内容泄漏。

package/harness/bundles/java/codebuddy/protocols/state-layout-protocol.md

@@ -4,6 +4,17 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 
 # State Layout Protocol
 
+## 升级与本地状态保护边界
+
+`.harness/archive/`、`.harness/changes/`、`.harness/knowledge/project-local/` 是 protected local roots。CLI init/configure/refresh/rules 操作前必须：
+
+1. 综合 project marker、adapter `.harness-build.json`、managed block、恢复事务和非空 `.harness` 判断 `absent / valid / partial / recovery-required`；
+2. 对 protected roots 记录文件数、目录数、字节数、Merkle root，以及 archive 首末 identity；
+3. 事务 journal 声明每个允许修改的路径；任何未声明的 protected-root mutation 立即回滚；
+4. partial 或 recovery-required 状态 fail closed，输出 sentinels、inventory 与恢复指引，禁止当成空项目自动 init。
+
+事务提交前后 protected inventory 必须一致；除非当前命令显式以该 protected root 为操作目标。删除 `project.yaml` 但保留 archive，或删除 `.harness` 但保留 adapter marker，均属于 partial state，不是首次安装。
+
 ## 目标
 
 `.harness/changes/<change-name>/` 是变更状态真相源，但根目录不得继续堆放所有文件。新产物按子目录分层；旧路径保留读取兼容。