@hunter-harness/workflow-harness 0.2.2 → 0.2.4

package/harness/bundles/general/claude-code/harness-run/protocols.md

@@ -34,8 +34,9 @@ REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回
 
 - `evidence/verification-ledger.json`：构建/测试命令、证据、diffHash、复用状态。
 - `evidence/run-task-status.md`：任务状态、对应场景、未验证项。
-- `logs/execution-log.md`：RED 类型、GREEN 结果、REFACTOR 结果、验证证据。
-- `events.ndjson`：关键 command / verification / issue / artifact 事件。
+- `events.ndjson`：关键 command / verification / issue / artifact 事件；RED 类型、GREEN 结果、REFACTOR 结果和验证证据放入事件 `note`。
+
+执行日志是上述事件在阶段边界生成的只读投影，不作为变更簇的直接输出目标。
 
 禁止把静态验证写成“测试通过”。静态 RED/GREEN 的最终状态至少是 🟡WARN，除非后续真实验证已完成。
 

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -148,7 +148,7 @@ git 经 PowerShell；commit/报告不得含明文密钥。遵循 `../protocols/s
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/claude-code/harness-submit/checklist.md

@@ -380,14 +380,14 @@ powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=
 
 重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
 
-**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check（省 ~350s）。三重校验（marker ts<10min + command + HEAD），任一不满足照跑。
+**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check。三重校验（marker ts<10min + command + commit tree），任一不满足照跑。marker 写入时记录 `git write-tree`，因此验证后创建 commit 不会仅因 HEAD 前移而使缓存失效。
 
 ```powershell
 # npm run check exit 0 后立即写 marker（M5 或 REUSED 后均可）
 powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
 ```
 
-> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 读 marker：HEAD 自写 marker 后未变 + ts<10min + command 匹配 → 跳过 npm run check；否则照跑（安全默认）。
+> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 比较 `HEAD^{tree}` 与 marker 的 `treeHash`，再校验 ts<10min + command；commit tree 未变化即可跳过，任何内容变化都照跑（安全默认）。
 
 ### 步骤 M6：push 主分支
 

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -71,7 +71,7 @@ disallowed-tools:
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -169,7 +169,7 @@ Phase 1 前先读 `.harness/changes/<change-name>/evidence/verification-ledger.j
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/claude-code/scripts/harness_check_gate.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python3
 """Pre-push gate: skip `npm run check` when a recent check-ok marker matches
-the current HEAD.
+the tree of the commit being pushed.
 
 Triple check (all must pass to skip, else exit 1 → hook runs npm run check):
   1. marker exists and its `ts` is within MAX_AGE_S (10 min) of now
   2. marker `command` == EXPECTED_CMD ("npm run check")
-  3. current `git rev-parse HEAD` == marker `commitHash`
+  3. current `git rev-parse HEAD^{tree}` == marker `treeHash`
 
-The marker is written by harness-submit M5 right after a green `npm run check`.
-Any mismatch (no marker, stale, different command, HEAD moved since the check)
+The marker is written by harness-submit M5 after a green `npm run check` and
+records `git write-tree`. This remains valid after commit because the new HEAD
+has the same tree. Any mismatch (no marker, stale, command or tree changed)
 forces a full re-run — the safe default. This is a local convenience only;
 non-harness pushes have no marker and always run the check.
 
@@ -28,10 +29,10 @@ MAX_AGE_S = 600  # 10 minutes
 EXPECTED_CMD = "npm run check"
 
 
-def _current_head() -> str | None:
+def _git_output(args: list[str]) -> str | None:
     try:
         r = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
+            ["git", *args],
             cwd=str(ROOT),
             capture_output=True,
             text=True,
@@ -42,20 +43,27 @@ def _current_head() -> str | None:
     return r.stdout.strip() if r.returncode == 0 else None
 
 
+def _current_index_tree() -> str | None:
+    return _git_output(["write-tree"])
+
+
+def _current_head_tree() -> str | None:
+    return _git_output(["rev-parse", "HEAD^{tree}"])
+
+
 def write_marker() -> int:
-    """Write a check-ok marker for the current HEAD (called by harness-submit M5
-    after a green npm run check). Pre-push gate reads it to skip a re-run."""
-    head = _current_head()
-    if head is None:
+    """Record the verified index tree so the marker survives the next commit."""
+    tree = _current_index_tree()
+    if tree is None:
         return 1
     MARKER.parent.mkdir(parents=True, exist_ok=True)
-    payload = {"ts": time.time(), "commitHash": head, "command": EXPECTED_CMD}
+    payload = {"ts": time.time(), "treeHash": tree, "command": EXPECTED_CMD}
     MARKER.write_text(
         json.dumps(payload, ensure_ascii=False) + "\n",
         encoding="utf-8",
         newline="\n",
     )
-    print(f"check-ok marker written for HEAD {head[:7]}")
+    print(f"check-ok marker written for tree {tree[:7]}")
     return 0
 
 
@@ -84,17 +92,17 @@ def main(argv: list[str] | None = None) -> int:
         return 1
     if data.get("command") != EXPECTED_CMD:
         return 1
-    marker_commit = data.get("commitHash")
-    if not isinstance(marker_commit, str):
+    marker_tree = data.get("treeHash")
+    if not isinstance(marker_tree, str):
         return 1
-    head = _current_head()
-    if head is None or head != marker_commit:
+    tree = _current_head_tree()
+    if tree is None or tree != marker_tree:
         return 1
     # All three checks passed: a green npm run check ran on this exact HEAD
     # within the last 10 minutes. Safe to skip.
     print(
         f"pre-push: skipping npm run check (verified {int(time.time() - ts)}s ago "
-        f"at HEAD {head[:7]})"
+        f"for tree {tree[:7]})"
     )
     return 0
 

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "0e63599ac74b7033"
+  "coreHash": "31546eadb30f5fdf"
 }

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

@@ -135,12 +135,12 @@
 
 ## 执行日志与结构化事件机制
 
-每个关联具体变更的 skill 都必须同时维护两类事实源：
+每个关联具体变更的 skill 只维护一个实时事实源：
 
-- `.harness/changes/<change-name>/logs/execution-log.md`：人类审计日志，保留上下文、降级原因、解释性文字。
-- `.harness/changes/<change-name>/events.ndjson`：程序化事件层，供 `harness_archive.py finalize` 生成 `summary-data.json`。
+- `.harness/changes/<change-name>/events.ndjson`：程序化事件层；人类可读上下文、降级原因和解释性文字写入事件 `note`。
+- `.harness/changes/<change-name>/logs/execution-log.md`：由 `harness_events.py` 在 `phase.end` 自动重建的人类审计投影，禁止 Write/Edit。
 
-`execution-log.md` 中记录开始和结束，格式统一：
+渲染后的 `execution-log.md` 阶段格式统一：
 
 ```markdown
 ### [<序号>] harness-<skill> — YYYY-MM-DD HH:MM
@@ -152,16 +152,17 @@
 - **摘要**: <一两句话描述主要产出或问题>
 ```
 
-- harness-plan 创建变更目录时初始化日志文件和 `events.ndjson`
-- 后续每个 skill 开始时追加开始条目和 `phase.start` 事件，结束时追加结束/耗时/结果和 `phase.end` 事件
-- **任何代码修改前必须先追加开始条目**（不得等执行完才补记录）
+- harness-plan 确定 change-name 后先追加 `phase.start`，脚本自动建立事件文件
+- 后续每个 skill 开始时追加 `phase.start` 事件，结束时追加包含耗时/结果的 `phase.end` 事件
+- **任何代码修改前必须先追加 `phase.start`**（不得等执行完才补记录）
 - **降级时必须记录明确原因**（如"Agent 不可用，降级为主会话只读探索"），不可仅写"完成"
-- **禁止末尾一次性补写**——每个阶段开始和结束都用 Edit 追加
+- **禁止末尾一次性补写**——各阶段实时 append 结构化事件，渲染日志不得直接编辑
 - **Bash 拒绝、PowerShell 重试、降级、跳过、用户确认都必须记录**
 - 日志状态统一使用 `✅OK / 🟡WARN(原因) / ❌FAIL(原因)`
 - harness-archive 归档时从日志汇总：时间线、总用时、Skill 调用统计
 - `harness_archive.py finalize/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
 - sync 默认不关联具体变更目录，仅在已有变更目录时追加日志和 events
+- archive 是例外：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加阶段边界
 
 ## Skill 目录结构
 
@@ -259,10 +260,10 @@ harness-skills/
 | 阶段 | 强制检查 |
 |------|---------|
 | **plan 阶段 0** | 检查工作区是否有未提交业务代码变更，已有则询问用户处理方式（继续/暂存/回滚/取消），不得假装"编码前规划" |
-| **plan 阶段 3** | 委派前 `harness_preflight.py check-agents --agent harness-explorer`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
+| **plan 阶段 3** | 委派前 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
 | **plan 阶段 4/6** | 原生规划协议必须记录风险/复用/替代方案/推荐方案/关键决策，以及任务拆分摘要 |
 | **plan 阶段 5** | 设计文档自审结果必须展示给用户；测试场景表未覆盖维度必须标记为 ⚠️ 缺口，不得全部 ✅ |
-| **run 步骤 0** | 任何代码修改前必须先追加执行日志开始记录和 `events.ndjson` 的 `phase.start` |
+| **run 步骤 0** | 任何代码修改前必须先向 `events.ndjson` 追加 `phase.start`；执行日志由阶段结束事件自动渲染 |
 | **run 轻量验证** | `/harness-run` 默认只做开发反馈：TDD RED/GREEN + REFACTOR + 构建命令增量编译（Java 的 `mvn compile -pl <module>` 等）+ 关门检查 + 写 verification-ledger；除非改了公共模块/数据访问层/sql/权限认证/接口层/数据契约 或用户要求 full-run-validation 或不打算继续 `/harness-test`，否则不默认跑全量测试命令（Java 的 `mvn test` 等）。若跑了全量测试必须写入 ledger 供 test/submit 复用 |
 | **run TDD 降级** | 输出必须写"🟡 静态逻辑验证通过，未执行真实单元测试"，**禁止写"测试全部通过"**；降级标注写在执行日志和覆盖报告中，**不污染业务代码注释**；记录三项：降级原因、静态验证场景列表、待部署后验证场景列表 |
 | **test ledger 复用** | Phase 1 单元测试前先读 `verification-ledger.json`：若 run 阶段已对同一 diffHash/module/profile 跑过单元测试命令（Java 的 `mvn test` 等）且测试通过（Java 的 `Tests run: N, Failures: 0, Errors: 0` / 前端 N passing），可跳过重跑并标记"✅ 复用 harness-run 单元测试结果"；diffHash 不一致 / profile 不一致 / 命令范围更窄 / run 后有行为性修改则不得复用 |
@@ -276,7 +277,7 @@ harness-skills/
 | **submit 步骤 4** | 提交前必须展示四项：实际 staged 文件列表、diff stat、commit message、是否 push |
 | **submit push 前** | `git fetch` 后检查远程是否有新提交；有则**不得直接 pull 后 push**，必须 pull/rebase + 重新 compile/test |
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
-| **archive 阶段 1** | 必须先 append `phase.start` 事件，**不得等归档完成后才补**；归档前确认：commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态 |
+| **archive 阶段 1** | 归档前确认 commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
 | **archive final-summary.html** | 默认运行 `harness_archive.py finalize`：由 events/ledger/log/manifest 生成 `summary-data.json`，再由 `templates/render-summary.mjs` 渲染 `final-summary.html`，内嵌 validate。无测试或无 review 时必须在 JSON 中标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。必须真实展示状态演进（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 

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

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -82,11 +82,9 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 
 ### Phase 3：执行归档
 
-1. append `phase.start` 事件。
-2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（移动、collect、render、validate、manifest 比对）。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。
-4. 模型补写 `meta/archive-meta.md` 的维护者结论 / knownRisks / manualActions（脚本占位字段）。
-5. append `phase.end` 事件。**finalize 失败或 validate 报错时不删除原目录**。
+1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
+2. 如需维护者结论，在移动前补全 `meta/archive-meta.md`；不得在 finalize 后修改已校验的归档文件。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（事件、移动、collect、render、validate、manifest 比对）。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 报错时不删除原目录**。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构
@@ -153,9 +151,9 @@ API 测试 `USER_SKIPPED` 或 DB 兼容 `BLOCKED_BY_DBA` 时，最终状态必
 
 未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/` 并在 final-summary 中展示。
 
-### 十一、phase.start 事件前置
+### 十一、归档事件单一所有权
 
-阶段 0 之前必须先 append `phase.start` 事件（`harness_events.py append`）；不得等归档完成才补。归档后 events.ndjson 与自动渲染的 execution-log.md 一起移入 archive。
+finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，并在移动后继续向归档目录中的同一事件流追加。调用者不得在 finalize 前后重复追加阶段边界，否则会造成重复阶段或在原 changes 路径生成幽灵目录。归档后 events.ndjson 与自动渲染的 execution-log.md 一起位于 archive。
 
 ### 十二、Shell 安全 / 敏感信息 / 证据化报告
 
@@ -187,7 +185,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/codebuddy/harness-archive/checklist.md

@@ -16,12 +16,12 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 ## 归档前检查（Phase 1）
 
-> ⚠️ **phase.start 前置**：在归档前检查的第一项前，必须先 append `phase.start` 事件（见 SKILL.md `## 执行日志`）。不得等归档完成才补。
+> ⚠️ **单一所有权**：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。
 
-- [ ] 已 append `phase.start` 事件（`harness_events.py append --change-dir ".harness/changes/<change-name>"`）
+- [ ] 未在调用 finalize 前手工追加 archive 阶段边界
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
 - [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
-- [ ] `logs/execution-log.md` 存在（需要追加归档记录；新路径缺失时兼容根目录 `execution-log.md`）
+- [ ] `events.ndjson` 存在；执行日志允许由 finalize 从事件流重新渲染（旧 archive 才兼容根目录 `execution-log.md`）
 - [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）
 - [ ] 准备生成 `summary-data.json`（业务目标、阶段状态、验证、产物、维护者结论）
 - [ ] git status 无未提交的重要变更（归档应对应已提交的代码）
@@ -40,7 +40,7 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - [ ] `.harness/archive/YYYY-MM-DD-<change-name>/` 目录存在（通过 Glob 实际扫描确认）
 - [ ] 所有子目录（plans/, tests/, reviews/, sqls/）已完整移入（通过 Glob 实际扫描确认，不仅看预期路径）
 - [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
-- [ ] archive-meta.md 已创建，frontmatter 字段完整
+- [ ] 如需 archive-meta.md，已在 finalize 前创建且 frontmatter 字段完整；finalize 后未再改动归档文件
 - [ ] summary-data.json 已生成，且为合法 JSON
 - [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
 - [ ] **final-summary.html 真实性检查**：

package/harness/bundles/general/codebuddy/harness-archive/reference.md

@@ -10,11 +10,9 @@ description: harness-archive 的归档流程、manifest、summary-data、final-s
 - **Phase 1 确认归档对象**：Glob `.harness/changes/*/plans/*-plan.md`（排除 archive），展示概要；多变更让用户选择或终止。
 - **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
 - **Phase 3 执行归档**：
-  1. append `phase.start` 事件（`harness_events.py append`）。
-  2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
-  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。
-  4. 模型补写 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`（脚本留空占位）。
-  5. append `phase.end` 事件。**finalize 报错或 validate 失败时不删除原 changes 目录**。
+  1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
+  2. 需要维护者结论时，在移动前补全 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`；finalize 后不再修改归档内容。
+  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 报错或 validate 失败时不删除原 changes 目录**。
 - **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
 
 ## manifest 生成

package/harness/bundles/general/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=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -85,7 +85,7 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/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=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -232,7 +232,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/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=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
@@ -25,13 +25,7 @@ description: 根据新需求、设计任务、代码修改请求或问题排查
 
 当用户提出新功能、改造、排查、设计方案、继续历史任务，且项目存在 `.harness/archive` 或 `.harness/knowledge` 时，AI 应主动运行本 skill，不需要等用户提醒。
 
-如果 `.harness/knowledge/index.json` 不存在或已过期，先运行：
-
-```powershell
-powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>' --update"
-```
-
-然后再查询。
+不在 query 前单独执行 sync。`query` 命令内部执行一次 ensure-current：建立一次当前快照，索引新鲜时无操作，过期或缺失时只构建一次，然后在同一调用内完成查询。
 
 ## Commands
 
@@ -59,12 +53,10 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 ## Workflow
 
 1. 确认项目根目录。
-2. 运行 `sync --project <root>`。
-3. 如果 `upToDate=false`，运行 `sync --update`。
-4. 用用户原始需求作为 `--query` 查询。
-5. 如已知道相关文件，追加 `--file` 过滤。
-6. 读取 JSON 输出中的 `contextPack`。
-7. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
+2. 用用户原始需求执行一次 `query`；query 命令内部执行一次 ensure-current。
+3. 如已知道相关文件，在同一次查询中追加 `--file` 过滤。
+4. 读取 JSON 输出中的 `contextPack`。
+5. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
 
 ## Output Contract
 
@@ -96,6 +88,8 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 ## Forbidden Actions
 
 - rebuild_index_without_need
+- pre_sync_before_query
+- query_then_sync_then_query_again
 - treat_candidate_as_current_fact
 - treat_stale_as_current_fact
 - skip_context_pack_before_planning
@@ -124,7 +118,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 - `matchCount` 与按状态分组的命中数（active/candidate/stale/superseded/conflicted）。
 - `contextPack` 路径与 `latest.json` 指针。
 - 命中 stale/superseded/conflicted 时显式提示风险。
-- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；索引过期 → 先 `sync --update`）。
+- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；ensure-current 失败 → 报告具体 issue，不重复同步或查询）。
 
 ## 渐进披露
 
@@ -136,7 +130,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -48,18 +48,19 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 ## Subagent 委派
 
-- **阶段 3 探索**：`check-agents --agent harness-explorer` → 可用则委派，否则主会话探索；无效返回不 retry
-- **阶段 7.5**：仅 `--adversarial`；`check-agents --agent harness-evaluator` → `reports/plan-review/`
+- **阶段 3 探索**：先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`；可用则委派，否则主会话探索；无效返回不 retry
+- **阶段 7.5**：仅 `--adversarial`；先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-evaluator --json`；可用才委派到 `reports/plan-review/`
 
 ## Workflow 概要
 
 | 阶段 | 动作 |
 |------|------|
 | 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
-| 0.5 | `harness-knowledge-query`（失败记 `issue`） |
-| 1 | 自动生成 change-name + 初始化 logs/events |
-| 2–3 | 代码探索 + 需求澄清（高风险 → 交互白名单 ②） |
-| 4 | **设计审批包** AskUserQuestion → 写 `spec/*-design.md` + `meta/worktree.json` |
+| 0.5 | 先初始化 change-name + `phase.start`，从第一条知识查询起保留事件证据 |
+| 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
+| 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
+| 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
+| 4 | **设计审批包** AskUserQuestion；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
 | 8 | 产物完整性必检 → `checklist.md` |
@@ -81,6 +82,9 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
+| 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |
+| 简单修复探索预算 | 预计不超过 2 个代码文件、且不涉及认证/安全/迁移/并发/API 契约重设时，最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个用户澄清问题；无关发现只记非阻断说明 |
+| 精简产物 | 简单修复只保留实现所需的设计、任务、边界和测试；禁止在 spec/plan/detail/scenarios 中重复同一背景和结论 |
 | state snapshot | 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol §state-snapshot.json）了解 project/worktree root、HEAD/base、profile/rules/map/knowledge 指纹；失效由脚本刷新，**不得仅凭缓存跳过代码探索或验证门禁**（design §3.6） |
 | 协议 | sensitive-info / evidence-based-reporting / state-layout |
 
@@ -95,11 +99,11 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 ## 交互白名单
 
 1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
-2. **decision-grilling**（阶段 3 澄清）：高风险业务裁决（一次一问）
+2. **decision-grilling**（阶段 2/3 澄清）：语义歧义或高风险业务裁决（一次一问）
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"

package/harness/bundles/general/codebuddy/harness-plan/checklist.md

@@ -12,9 +12,22 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 **判定**：stdout 为空 → ✅ 继续；stdout 非空 → baseline 隔离 + `decision`（note 含变更文件列表）；Bash 被拒 → PowerShell 重试。
 
-## 阶段 2：Worktree 决策（并入设计审批包）
+## 阶段 0.5：事件初始化与知识查询
 
-> worktree 不再单独询问。阶段 5 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
+- [ ] 先确定 change-name，并立即用 `harness_events.py append` 追加 `phase.start`
+- [ ] 再执行一次 knowledge `query`；由 query 内部 ensure-current，不另跑前置 sync
+- [ ] 查询失败追加 `issue`，不得重跑“sync + query”循环或假装已读取历史
+
+## 阶段 2：歧义优先检查与复杂度分级
+
+- [ ] 否定、对比、动作对象、范围或保留/删除关系不存在未确认的多义解释
+- [ ] 若存在歧义，仅完成最小取证后一次一问，并给出推荐理解
+- [ ] 简单修复探索预算：最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个澄清问题
+- [ ] 无关发现只记非阻断 `issue`，未扩展当前方案或问题列表
+
+## 设计审批包字段：Worktree
+
+> worktree 不再单独询问。阶段 4 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
 
 - [ ] 审批包确认后写入 worktree.json（`requested` true/false）
 - [ ] 阶段 8 检查 worktree.json 存在
@@ -26,7 +39,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 ```
 □ 是通过 Agent 工具委派 subagent 执行的（不是主会话直接调用 codegraph）
 □ subagent 返回了结构化设计概要（涉及模块、接口变更、关键决策）
-□ 委派前已运行 `harness_preflight.py check-agents --agent harness-explorer`
+□ 委派前已运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`
 □ `usable=false` 或未返回有效输出 → 主会话探索，**不 retry 委派**
 □ 主会话未被代码探索的中间结果污染
 □ 在执行日志中记录了 Agent 调用状态：
@@ -38,13 +51,13 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 ```
 
 > 如果 Agent 工具不可用，或子代理被委派但未返回有效输出（0 tool uses / 空返回 / 仅 "Done"），必须显式降级并记录：
-> - 在执行日志中写明降级原因：🟡 阶段3降级：Agent 不可用 / 子代理未返回有效输出，改为主会话只读探索
+> - 追加 `issue` 事件并在 note 写明降级原因：Agent 不可用 / 子代理未返回有效输出，改为主会话只读探索
 > - 主会话直接使用 codegraph MCP 工具（`mcp__codegraph__codegraph_explore`）和 Read 探索代码（只读，不执行写操作）
 > - 不得在主会话中执行任何写操作
 > - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
 > - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
 
-## 阶段 5：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
+## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
 
 > 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。
 
@@ -58,6 +71,8 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 确认后写入 `spec/<change>-design.md`（含 frontmatter）和 `meta/worktree.json`。
 
+- [ ] 确认事件早于 approved 设计文档；未获确认时不得先落盘 `status: approved`
+
 设计文档必须包含 frontmatter：
 ```yaml
 ---
@@ -155,11 +170,11 @@ source: harness-plan
 
 ```
 □ 已读取 protocols.md，并按 clarification-protocol / decision-grilling-protocol 执行
-□ 输入包含需求摘要 + 阶段0.5 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
-□ 已在 execution-log 中记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
+□ 输入包含需求摘要 + 阶段1 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
+□ 已用 decision / issue 事件 note 记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
 □ 已叠加项目架构约束（分层规范、数据模型、接口规范）
-□ 需求澄清结论已写入 .harness/changes/<change-name>/logs/execution-log.md，并在 events.ndjson 记录 decision
-□ 用户问题未超预算：普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
+□ 需求澄清结论已追加到 events.ndjson，阶段结束后执行日志由渲染器生成
+□ 用户问题未超预算：简单修复 0-1 问，普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
 □ 提问遵循"一次一问、等答再继续"；能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
 □ 每个需要用户决策的问题，AI 先给出了推荐答案、理由和取舍，用户仅确认或修正
 □ 高风险/业务语义决策（范围、权限、安全、支付、迁移、删除、API契约、用户可见行为）已显式等待用户确认
@@ -173,8 +188,8 @@ source: harness-plan
 
 ```
 □ 已读取 protocols.md，并按 implementation-planning-protocol 执行
-□ 输入为阶段5已审核设计文档
-□ 已生成基础任务列表，并在 execution-log 记录任务拆分摘要
+□ 输入为阶段4已审核设计文档
+□ 已生成基础任务列表，并用 artifact 事件 note 记录任务拆分摘要
 □ 已叠加项目层序依赖（数据/契约→业务层→接口层）
 □ 已生成 4 维度场景表（单元/接口/数据兼容/集成）
 □ 已确定变更名（kebab-case）
@@ -223,7 +238,7 @@ source: harness-plan
 
 - **产物路径唯一性**：`.harness/changes/<change-name>/` 是唯一真相源，plan 产物必须直接写入此目录
 - **原生规划协议**：阶段 4/6 使用 clarification、decision-grilling、implementation-planning 三段内置协议，不运行时依赖 Superpowers/grill-me/writing-plans
-- **阶段 2 是强制阻断检查点**——必须停下来问用户，收到回复后才能继续。不要跳过
+- **阶段 4 是强制阻断检查点**——展示设计审批包后必须停下来问用户，收到回复后才能写 approved 设计文档。不要跳过
 - 代码探索只读不写——这个阶段的目标是理解，不是修改
 - 场景表是后续所有步骤的真相源——宁可多花时间打磨，不要草草了事
 - 如果需求不明确，优先提问而不是猜测后继续设计
@@ -233,7 +248,7 @@ source: harness-plan
 ## 事件记录（前置规则）
 
 - [ ] 确定 change-name 后立即 append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
-- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 1 确定 change-name 后必须开始记录
+- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 0.5 确定 change-name 后必须开始记录
 
 ## 需求范围缩减后的 change-name 检查 ⚠️