@hunter-harness/workflow-harness 0.2.40 → 0.2.42

package/harness/bundles/general/cursor/harness-knowledge-query/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

package/harness/bundles/general/cursor/harness-plan/SKILL.md

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

package/harness/bundles/general/cursor/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/general/cursor/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/cursor/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/cursor/harness-run/reference.md

@@ -533,7 +533,7 @@ python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/cha
 
 > 这样 harness-test 的 Phase 1 可读取 ledger 判断是否复用 run 的 unitTest（diffHash commit-invariant + reuse 规则 #2 允许 HEAD 前移 → run 的 checkpoint commit 不破坏复用），submit 也可复用 compile 结果。详见 `../protocols/ledger-protocol.md`。
 >
-> **Ledger v3（v2 契约 / split-v1 布局起）**：`record` 自动解析并强制顶层身份（`schemaVersion=3/repositoryId/changeName/baseCommit/currentHead/diffHash/ownershipHash`），缺字段非零退出、不写账本；`--metrics-json` 必须通过 typed schema（unit=`total/passed/failed`，apiContract=`scenariosTotal/passed/failed`，browserE2E=`total/passed/failed`，dbCompatibility=`applicability(+reason)`）；新增 `--base-commit/--diff-hash/--applicability/--applicability-reason`。legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
+> **Ledger v3**：`record` 自动解析并强制顶层身份（`schemaVersion=3/repositoryId/changeName/baseCommit/currentHead/diffHash/ownershipHash`），缺字段非零退出、不写账本；已有 v1/v2 ledger 在写前透明迁移，`migrationHistory` 回执记录原/目标 schema 与迁移前后 evidence identity。无法迁移时返回 `LEDGER_MIGRATION_REQUIRED` 和确定性 `rerecordCommand`，不得半升级。v2 契约下 `--metrics-json` 必须通过 typed schema（unit=`total/passed/failed`，apiContract=`scenariosTotal/passed/failed`，browserE2E=`total/passed/failed`，dbCompatibility=`applicability(+reason)`）。详见 `../protocols/ledger-protocol.md` 第十节。
 
 阶段边界：`harness_gate.py begin/close`；测试跟踪：`harness_test_guard.py begin/close`。close 失败不得用自然语言覆盖。
 

package/harness/bundles/general/cursor/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=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/cursor/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=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; do not edit -->
 # harness-sync
 
 ## Purpose
@@ -13,13 +13,10 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
 
 ## Before running
 
-读取 `reference.md`。先执行只读能力握手；若最低 CLI 版本或任一必需能力不满足，立即停止，不得先运行 knowledge、refresh 或其他重操作：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流要求 `sync@1`、`rules-sync@1`、`rules-review@1`、`knowledge-sync@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，不得降级为手工拼接旧流程。
+读取 `reference.md`。`sync` 自身会在任何重操作之前完成能力握手；不要另起一个
+`capabilities` 进程。工作流要求 `sync@2`、`rules-sync@1`、`rules-review@1`、
+`knowledge-sync@3`、`codegraph-status@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，
+不得降级为手工拼接旧流程。
 
 ## Run
 
@@ -29,17 +26,26 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 
 CLI 负责 Python runtime 解析、投影事务、knowledge、rules、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用内部 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。
 
-长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的 `reportPath`，并带 `reportSha256`。不得把完整 JSON 报告直接回显到对话。
+只读诊断使用 `--check`（`--dry-run` 为兼容别名）；它不得写报告、receipt 或投影。
+长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的
+`reportPath`，并带 `reportSha256`。需要组件级证据时显式加 `--verbose`，不得默认把完整
+JSON 报告回显到对话。
+
+摘要中的 `remediations[]` 是稳定修复契约。先用对应 `previewCommand` 预览；低风险修复用
+`--apply safe`，指定修复用 `--fix <id>`。需覆盖受管投影的修复必须同时提供 `--yes`，
+并依赖 refresh 事务留下的 before snapshot；不允许绕过确认或无备份覆盖。指定修复时，
+无关组件只做只读评估，不得顺带写入。
 
 ## Interpret
 
 - `OK`：所有可验证组件通过。
+- `ADVISORY`：索引最新，但有待评审候选等非阻塞健康提示；退出码仍为 0。
 - `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按 `reportPath` 中的 `nextAction` 处理。
 - `FAIL`：组件执行失败；不得宣称同步完成。
 - `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。
 - `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。
 
-非交互或 CI 使用 `--profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
+非交互或 CI 使用 `--check --profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
 
 ## Safety
 

package/harness/bundles/general/cursor/harness-sync/reference.md

@@ -6,13 +6,8 @@ description: harness-sync 的能力契约、统一状态模型、报告收据和
 
 ## 1. 能力握手
 
-统一入口执行前读取：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。CLI 在任何高成本阶段之前核对版本与能力；缺失时返回：
+工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。`sync` 在任何高成本
+阶段之前自行核对版本与能力；Skill 不要再运行独立的 `capabilities` 子进程。缺失时返回：
 
 ```json
 {
@@ -47,22 +42,41 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 CI/非交互式：
 
 ```powershell
-npx hunter-harness sync --project <项目路径> --profile general --progress jsonl --json
+npx hunter-harness sync --check --project <项目路径> --profile general --progress jsonl --json
 ```
 
-`--dry-run` 只做只读检查或事务预览，不应生成持久报告、receipt 或投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 只输出：
+`--check` 是严格只读检查；`--dry-run` 是兼容别名。两者都不生成持久报告、receipt 或
+投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 默认只输出：
 
 ```json
 {
   "status": "WARN",
   "runId": "<run-id>",
-  "components": {"ok": 7, "warn": 1, "fail": 0, "blocked": 0, "unknown": 1},
+  "components": {"ok": 7, "advisory": 1, "warn": 0, "fail": 0, "blocked": 0, "unknown": 0},
+  "versions": {
+    "cliVersion": "0.0.0",
+    "workflowBundleVersion": "0.0.0",
+    "adapterBundleVersions": {}
+  },
+  "remediations": [],
   "reportPath": ".harness/runtime/sync/<run-id>/reports/sync-report.json",
   "reportSha256": "<sha256>"
 }
 ```
 
-详细报告必须受大小限制，并包含每个组件的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动修复及 `nextAction`。
+只读检查的 `reportPath/reportSha256` 为 `null`。详细报告必须受大小限制，并包含每个组件
+的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动
+修复及 `nextAction`；只有显式 `--verbose` 才把组件级详情写到 stdout。
+
+### 结构化修复
+
+- `remediations[]` 含稳定 `id`、风险、写入范围、备份/回滚说明、预计耗时、是否需确认、
+  `previewCommand` 与 `applyCommand`。
+- `--apply safe` 只执行低风险、无需确认的修复。
+- `--fix <id>` 只执行该项；需要覆盖受管 Adapter 时必须加 `--yes`。
+- 指定修复时，其他组件仍参与诊断但保持只读。
+- Adapter 覆盖由 refresh 事务执行，before snapshot 位于最新 committed refresh
+  transaction；事务失败会自动回滚。预览永远不得产生写入。
 
 ## 4. 组件状态
 
@@ -77,15 +91,21 @@ npx hunter-harness sync --project <项目路径> --profile general --progress js
 | instruction graph | 入口、include 边、环、主题可达性 | 缺失引用或循环为 `FAIL` |
 | config origins | canonical/projection 路径与 hash | 漂移 `WARN`，不静默覆盖 |
 | changes | 五态分类及归档收据 | `INVALID`/`ORPHAN` 不自动删除 |
-| CodeGraph | 索引文件、守护进程管道、watcher 日志、pending、watcher lag | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；不自动全量 reindex |
+| CodeGraph | `codegraph status --json` 的 pending、数据库观察时间、watcher 可达性 | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；日志 mtime 只证明 watcher 活动，不证明索引完成；不自动全量 reindex |
 
-全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `OK`。任一 `UNKNOWN` 至少使全局结果为 `WARN`。
+全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `ADVISORY` → `OK`。任一 `UNKNOWN`
+至少使全局结果为 `WARN`。knowledge freshness 与 health 分开：索引一致但仍有待裁决候选时
+为 `ADVISORY`，不得误报为过期。
 
 ## 5. Git 与 CodeGraph
 
 增量基线来自上次成功 sync receipt 的 `headCommit`。首次运行或 receipt 不可用时，仅收集当前 HEAD 和有界文件统计；禁止固定 `HEAD~5`。
 
-CodeGraph 状态探测读取 `.codegraph/codegraph.db`、daemon receipt/log，尝试有界管道连接，并比较项目文件与最近索引观察时间。只有服务可达、watcher 已启用且 `pendingFileCount=0` 时为 `CURRENT`；此时才可将当前 HEAD 记录为推断的 `indexedCommit`。不可用、待同步或证据不足时分别报告 `STALE/PENDING/INDEX_PRESENT_UNVERIFIED/UNKNOWN` 与明确后续动作。不要在 sync 内执行全量索引，不使用依赖 shell 连接符的跨平台命令。
+CodeGraph 状态探测优先读取 `codegraph status --json` 的权威 pending 列表；只有该 API
+不可用时才退回受限文件扫描，并把来源标成 `database-scan` 或 `unverified`。`.agents/`、
+`.cursor/`、`.claude/` 等 Adapter 投影和 Markdown 文档不计入源码 pending。daemon log
+mtime 只写入 `watcherObservedAt`，不能冒充 `indexObservedAt`。只有服务可达、watcher 已
+启用且权威 `pendingFileCount=0` 时为 `CURRENT`。不要在 sync 内执行全量索引。
 
 ## 6. Instruction graph
 

package/harness/bundles/general/cursor/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=fdb3d1e38e10f19c; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=4caa698ed8bc50c8; overlay=none; agent=cursor; 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/general/cursor/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/general/cursor/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/general/cursor/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/general/cursor/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>/` 是变更状态真相源，但根目录不得继续堆放所有文件。新产物按子目录分层；旧路径保留读取兼容。