hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/general/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: harness-knowledge-ingest
+description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
+  knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
+---
+<!-- generated by harness_deploy.py; core=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+# harness-knowledge-ingest
+
+从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
+
+当前实现是本地、离线、无 LLM、无外部服务的 SQLite FTS MVP，已经支持基础生命周期：`candidate`、`stale`、`active`、`superseded`、`conflicted`。按新需求查询历史由独立的 `harness-knowledge-query` 负责。
+
+## Triggers
+
+- ingest knowledge
+- sync knowledge
+- rebuild knowledge index
+- promote knowledge
+- 确认知识条目
+- 从归档生成知识索引
+- 刷新项目知识库
+- 检查知识库是否过期
+
+## Required context
+
+- AGENTS.md / CLAUDE.md
+- `.harness/archive/**/reports/final/summary-data.json`
+- `.harness/knowledge/index.json`
+- `.harness/codebase/map-summary.md`（如存在）
+- design.md
+
+## Purpose
+
+解决两个问题：
+
+1. **整理知识库内容**：把归档里的 `businessGoal`、`changedFiles`、`maintenanceNotes`、`knownRisks`、`manualActions`、`verification`、`reviewSummary` 抽成知识条目。
+2. **维护知识生命周期**：检查索引是否过期，保留 active 条目；高价值 candidate 可经人工确认提升，也可由 `auto` 首次写入的 `autoPromote` 配置按置信度门槛自动提升。
+
+## Outputs
+
+```text
+.harness/knowledge/index.json
+.harness/knowledge/index.sqlite
+.harness/knowledge/entries/candidate/*.json
+.harness/knowledge/entries/active/*.json
+.harness/knowledge/entries/stale/*.json
+.harness/knowledge/entries/superseded/*.json
+.harness/knowledge/entries/conflicted/*.json
+.harness/knowledge/cache/archive-entries/*.json
+.harness/knowledge/reports/ingest-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/verification-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/validator-suggestions-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/audit-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/views/knowledge-dashboard.md
+.harness/knowledge/views/by-file.md
+.harness/knowledge/views/stale-items.md
+.harness/knowledge/views/superseded-items.md
+.harness/knowledge/views/conflicted-items.md
+.harness/knowledge/views/active-review.md
+.harness/knowledge/views/knowledge.base
+.harness/knowledge/context-packs/*.md
+```
+
+## Commands
+
+`<skill-dir>` 指本 skill 目录。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行。完整命令示例与 config.json 配置见 `reference.md`「Commands 详细」。
+
+| 命令 | 用途 |
+|---|---|
+| `auto` | 一键防腐：首建 config、sync --update、suggest-validators、verify、audit；首次自动写 autoPromote 配置并提升高 confidence 条目 |
+| `ingest` | 重建/刷新知识索引，抽取 candidate；`--no-incremental` 强制全量重抽取 |
+| `sync` | 检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
+| `promote` | candidate→active（人工确认或 autoPromote 触发） |
+| `demote` | active→stale/candidate（人工复核后） |
+| `audit` | 生成 Candidate/Stale/Superseded/Conflict/Active Review 报告 |
+| `verify` | 执行 entry validators，刷新 lifecycle.validation，生成 verification-report |
+| `suggest-validators` | 生成 file_exists/file_contains validator 建议；`--apply` 写回 entry |
+| `mcp` | FastMCP stdio 入口，暴露 9 个工具（见 reference.md） |
+
+config.json 配置项（autoPromote / confidence / activeLifecycle / knowledgeValidation）详见 `reference.md`「Commands 详细」。
+
+## Workflow
+
+### Phase 0：确认项目根目录
+
+项目根目录必须包含 `.harness/`。如果 `.harness/archive/` 不存在或没有 `summary-data.json`，报告当前项目暂无可索引归档，不要伪造知识。
+
+### Phase 1：重建本地知识索引
+
+运行：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<project-root>'"
+```
+
+生成：
+
+- `index.json`：人类可读 manifest。
+- `index.sqlite`：SQLite FTS5 检索索引。
+- `entries/candidate/`：自动抽取、待确认知识。
+- `entries/stale/`：来源 commit 缺失、无法比较，或来源 commit 后相关文件变化的知识。
+- `entries/active/`：人工确认后可长期引用的知识。
+- `views/`：Obsidian 友好的浏览视图。
+- `reports/`：本次 ingest 报告。
+
+### Phase 2：同步检查
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>'"
+```
+
+当 `upToDate=false` 时，应优先运行 `sync --update` 或 `ingest`，再交给 `harness-knowledge-query` 查询。
+
+### Phase 3：人工确认高价值知识
+
+如果某条 candidate 已确认仍然有效，并且会反复影响后续需求，可运行 `promote` 将其提升为 active。
+
+active 条目适合保存：
+
+- 需求约束
+- 架构决策
+- API contract
+- 反复踩坑点
+- 测试或发布前置条件
+
+不要把一次性实现细节、过期临时方案、未验证结论提升为 active。
+
+### Phase 4：解释同步结果
+
+回复用户或交给后续 skill 前，应说明：
+
+- 索引是否最新。
+- 如需刷新，具体原因是 archive 增删、checksum 变化、sqlite 缺失，还是 HEAD 改变。
+- 本次是否自动刷新。
+- 当前 `active` / `candidate` / `stale` 的数量。
+
+## Knowledge extraction rules
+
+- Detect duplicate IDs, duplicate content, and conflicting active facts.
+- Keep project-local entries excluded from any global index unless explicitly selected.
+- Validate lifecycle relationships.
+- Default generated entries are `candidate`; only config-gated `autoPromote` may promote high-confidence long-lived entries to `active`.
+- Preserve provenance: every entry must include source archive, summary path, source commit, and source files when available.
+- Do not edit `.harness/archive/**` during ingest.
+- Do not copy secrets into `.harness/knowledge`.
+
+## Lifecycle rules
+
+- `candidate`：自动抽取但未人工确认。
+- `active`：人工确认、显式 promote，或配置允许的高置信度 autoPromote 后可用。
+- `stale`：来源 commit 缺失、来源 commit 后相关文件变化，或当前代码无法证明旧结论仍有效。
+- `superseded`：被后续归档/决策取代。
+- `conflicted`：与另一条 active/candidate 知识冲突。
+
+## Forbidden actions
+
+- auto_promote_candidate_knowledge_without_config_and_confidence_gate
+- erase_conflicts
+- include_project_local_by_default
+- mutate_archive_evidence
+- store_secrets
+- treat_stale_knowledge_as_current_fact
+
+## Allowed capabilities
+
+- read
+- search
+- write_candidate_knowledge
+- write_active_knowledge_after_manual_confirmation
+- write_confidence_scores
+- auto_promote_high_confidence_knowledge_when_configured
+- write_knowledge_index
+- write_obsidian_views
+
+## Verification
+
+本 skill 自带最小测试：
+
+```powershell
+powershell.exe -Command "python -m unittest '<skill-dir>\tests\test_harness_knowledge.py'"
+```
+
+完成脚本修改后必须至少运行该测试。若在真实项目中验证，还应运行：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' suggest-validators --project '<real-project-root>' --limit 20"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' verify --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<real-project-root>'"
+```
+
+并确认 `index.json`、`index.sqlite`、`views/knowledge-dashboard.md`、`reports/verification-report-*.md` 存在，且 sync 输出 `upToDate=true`。
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 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]]
+
+## Output Format
+
+执行完成后展示：
+
+- 本次命令（ingest/sync/promote）与目标项目根。
+- `upToDate` 及 `reasons`（sync）或新增/覆盖条目数（ingest/promote）。
+- 当前 `active` / `candidate` / `stale` 数量统计。
+- 产物路径（`index.json`、`index.sqlite`、`views/`、`reports/`）。
+- 下一步建议（`upToDate=false` → `sync --update`；有 candidate → 人工确认后 `promote`，或项目启用 `autoPromote` 后让高置信度长期知识自动提升；查询历史 → `/harness-knowledge-query`）。
+
+## 渐进披露
+
+- **Read `reference.md`** 仅在执行命令或查阅 config.json 配置时 — 含 Commands 详细示例（9 命令的 powershell 示例 + config.json 配置）与变更日志（v1.7–v1.13 补充能力）。
+
+## 交互白名单
+
+**仅当** `.harness/config/harness.json` 中 `knowledge.manualReview=true` 时，promote/demote 高价值条目需 AskUserQuestion；否则按 skill 默认策略 + `decision` 事件。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。

package/resources/harness/{java → bundles/general/codebuddy}/harness-knowledge-ingest/reference.md

@@ -4,7 +4,7 @@ description: harness-knowledge-ingest 的命令详细示例、config.json 配置
 
 # harness-knowledge-ingest 参考
 
-本文件为 `harness-knowledge-ingest` 的渐进披露支持文件，承载 Commands 详细示例与变更日志。SKILL.md 只保留概要 + 渐进披露引用。`<skill-dir>` 指本 skill 目录，即 `.claude/skills/harness-knowledge-ingest/` 或知识库源目录中的 `harness-knowledge-ingest/`。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行，避开 Bash 在 Windows 中文路径下的编码/参数问题。
+本文件为 `harness-knowledge-ingest` 的渐进披露支持文件，承载 Commands 详细示例与变更日志。SKILL.md 只保留概要 + 渐进披露引用。`<skill-dir>` 指本 skill 目录，即 `harness-knowledge-ingest/` 或知识库源目录中的 `harness-knowledge-ingest/`。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行，避开 Bash 在 Windows 中文路径下的编码/参数问题。
 
 ## Commands 详细
 

package/resources/harness/bundles/general/codebuddy/harness-knowledge-query/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: harness-knowledge-query
+description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
+  历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
+---
+<!-- generated by harness_deploy.py; core=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+# harness-knowledge-query
+
+根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
+
+此 skill 只负责查询和使用知识。整理、同步和 promote 条目由 `harness-knowledge-ingest` 负责。
+
+## Triggers
+
+- query knowledge
+- knowledge query
+- 查找相关历史需求
+- 根据历史归档理解这个需求
+- 结合之前做过的内容
+- 继续之前类似开发
+- 生成需求上下文包
+- 在规划前查历史
+
+## Automatic Use
+
+当用户提出新功能、改造、排查、设计方案、继续历史任务，且项目存在 `.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"
+```
+
+然后再查询。
+
+## Commands
+
+`<ingest-skill-dir>` 指同级 `harness-knowledge-ingest/` 目录；查询逻辑复用其脚本。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行，避开 Bash 在 Windows 中文路径下的编码/参数问题。
+
+### Query by requirement
+
+```powershell
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<project-root>' --query '<用户需求原文>'"
+```
+
+### Query with metadata filters
+
+```powershell
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<project-root>' --query '<需求或关键词>' --file '<source-file>' --status active"
+```
+
+可重复使用：
+
+- `--file <path>`：只返回关联到指定文件的知识。
+- `--status active|candidate|stale|superseded|conflicted`：按生命周期过滤。
+- `--type requirement|decision|implementation|risk|test-evidence|pitfall|api-contract`：按知识类型过滤。
+- `--limit <n>`：限制返回数量。
+
+## Workflow
+
+1. 确认项目根目录。
+2. 运行 `sync --project <root>`。
+3. 如果 `upToDate=false`，运行 `sync --update`。
+4. 用用户原始需求作为 `--query` 查询。
+5. 如已知道相关文件，追加 `--file` 过滤。
+6. 读取 JSON 输出中的 `contextPack`。
+7. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
+
+## Output Contract
+
+查询输出 JSON 包含：
+
+- `matchCount`
+- `contextPack`
+- `filters`
+- `planInput`
+- `matches`
+
+`planInput.kind` 必须为 `harness-knowledge-context-pack`。后续 `harness-plan` 应读取 `planInput.path`。
+
+每次查询还会更新稳定指针：
+
+```text
+.harness/knowledge/context-packs/latest.json
+```
+
+该文件包含最新 query、context pack 路径和 `matchIds`，供后续流程快速读取最近一次知识上下文。
+
+## Interpretation Rules
+
+- `active`：可优先采用，但仍要结合当前代码验证。
+- `candidate`：有参考价值，不是当前事实。
+- `stale`：只能作为历史线索，必须重新检查代码和归档。
+- `superseded` / `conflicted`：必须显式提示风险，不得静默采用。
+
+## Forbidden Actions
+
+- rebuild_index_without_need
+- treat_candidate_as_current_fact
+- treat_stale_as_current_fact
+- skip_context_pack_before_planning
+- copy_large_archive_content_into_prompt
+
+## Verification
+
+```powershell
+powershell.exe -Command "python -m unittest '<ingest-skill-dir>\tests\test_harness_knowledge.py'"
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<real-project-root>' --query '<真实需求>'"
+```
+
+确认输出中存在 `contextPack`、`planInput.kind=harness-knowledge-context-pack`，且 context pack 文件包含 `Before planning`。
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 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]]
+
+## Output Format
+
+执行完成后展示：
+
+- 用户需求原文与生效的过滤条件（`--file`/`--status`/`--type`/`--limit`）。
+- `matchCount` 与按状态分组的命中数（active/candidate/stale/superseded/conflicted）。
+- `contextPack` 路径与 `latest.json` 指针。
+- 命中 stale/superseded/conflicted 时显式提示风险。
+- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；索引过期 → 先 `sync --update`）。
+
+## 渐进披露
+
+- 本 skill 暂无 `checklist.md` / `reference.md` 支持文件，规则全部在 SKILL.md。若 Output Contract / Interpretation Rules 后续扩展变重，应拆到 `reference.md`。
+
+## 交互白名单
+
+**无** AskUserQuestion；`stale`/`conflicted` 命中记 `issue`，不阻断 query。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。

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

@@ -0,0 +1,109 @@
+---
+name: harness-plan
+description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
+---
+<!-- generated by harness_deploy.py; core=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+# harness-plan — 需求规划
+
+## Purpose
+
+需求 → 设计文档 → 任务拆分 → 测试场景表（编码/测试唯一真相源）。存在 `.harness/archive/` 或 `.harness/knowledge/` 时须先 `harness-knowledge-query`。
+
+## When to Use
+
+`/harness-plan`、新功能设计、技术方案、测试场景表规划。
+
+## 统一读取协议
+
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **spec** — 设计真相源：`spec/<change>-design.md`
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+
+## Worktree 门禁
+
+读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
+
+| 条件 | 行为 |
+|------|------|
+| `requested=false` | 主目录执行 |
+| `requested=true` + path 存在 | 切换 worktree 执行 |
+| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
+
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
+
+**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
+
+创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+
+## 原生规划协议
+
+内化为 `protocols.md`：`clarification-protocol`、`decision-grilling-protocol`、`implementation-planning-protocol`。不运行时调用 Superpowers/grill-me。
+
+## Subagent 委派
+
+- **阶段 3 探索**：`check-agents --agent harness-explorer` → 可用则委派，否则主会话探索；无效返回不 retry
+- **阶段 7.5**：仅 `--adversarial`；`check-agents --agent harness-evaluator` → `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` |
+| 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
+| 7.5 | 仅 `--adversarial` 对抗评审 |
+| 8 | 产物完整性必检 → `checklist.md` |
+
+change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 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]]
+
+## 关键规则
+
+| 规则 | 要点 |
+|------|------|
+| 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
+| 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
+| 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
+| Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
+| 知识查询 | 0.5 失败不得假装已读历史 |
+| 协议 | sensitive-info / evidence-based-reporting / state-layout |
+
+产出物表、frontmatter、legacy 兼容、结束输出模板 → `reference.md`
+
+## 渐进披露
+
+- **Read `checklist.md`** — 阶段检查与覆盖表
+- **Read `protocols.md`** — 阶段 4/6 原生协议
+- **Read `reference.md`** — 模板与 worktree JSON
+
+## 交互白名单
+
+1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
+2. **decision-grilling**（阶段 3 澄清）：高风险业务裁决（一次一问）
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。

package/resources/harness/bundles/general/codebuddy/harness-review/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: harness-review
+description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
+  .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
+---
+<!-- generated by harness_deploy.py; core=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+# harness-review — 代码审查
+
+## Purpose
+
+对 git diff 进行6维度审查，对照项目规则和测试场景表，输出分级报告。**审查结果仅供参考，默认不阻塞后续 submit/archive 流程。**
+
+## When to Use
+
+使用此 Skill 当：
+- 代码变更完成后需要审查
+- 提交前需要质量检查
+- 合并评审时需要系统性检查
+- 用户说"审查代码"、"review"、"检查代码质量"
+
+## Inputs
+
+- `$ARGUMENTS`：变更名（可选，留空时自动扫描 `.harness/changes/*/plans/` 确定）
+- 相关文件：`.harness/changes/*/plans/*-plan.md`、`项目规则（见 .harness/context-index.json）/`、测试场景表
+
+## 前置条件
+
+- `.harness/changes/<change-name>/plans/<change-name>-plan.md` 存在（任务真相源）
+- 必须读取 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 且 worktree 已创建 → 在 worktree 目录中执行审查；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录
+- **review 不阻塞后续流程**：test 报告缺失或未运行不阻止 review（review 是参考性阶段），但应在报告中标注 test 状态供参考
+
+## 统一读取协议
+
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **spec** — 设计真相源：`spec/<change>-design.md`
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+
+## Workflow
+
+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 -->
+### 2. 委派 harness-reviewer
+
+先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`。`usable=false` → **直接主会话审查**，记 `decision` 事件，**不委派**。`usable=true` 时用 Agent spawn `harness-reviewer`（只读, 6 维度）。返回空 / 无报告正文 → **不 retry**，降级主会话审查。
+
+3. **持久化报告（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`。未 Write → 🟡WARN，不得宣称 review 完成。
+4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`。若无 RED/YELLOW，记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。
+5. **收尾** — append `phase.end` / `artifact` 事件；控制台输出摘要
+
+## Review 定位（重要）
+
+**harness-review 是参考性代码审查阶段，不是硬门禁。**
+
+| 等级 | 含义 | 后续影响 |
+|:----:|------|----------|
+| RED | 高风险建议，强烈建议处理 | 不阻塞后续流程 |
+| YELLOW | 中低风险建议 | 不阻塞后续流程 |
+| OK | 无问题 | 不阻塞后续流程 |
+
+- 审查结果默认只作为参考，不阻塞 `/harness-submit`、`/harness-archive`
+- 除非用户显式要求"review 结果阻塞提交"，否则 review 不参与硬门禁
+- Review 报告中**禁止写**：阻塞 submit / 必须修复后才能继续
+- Review 报告中**应写**：建议优先处理 / 建议在 submit 前人工确认 / 建议补充测试 / 仅供参考，不阻塞后续 harness 流程
+
+### 可选 strict-review-gate 配置
+
+如果团队希望 review 结果阻塞提交，可在 `.harness/config/harness-test-config.md` 中设置：
+
+```yaml
+review:
+  strict-review-gate: true   # 默认 false
+```
+
+当且仅当 `strict-review-gate: true` 时，review RED 才阻塞 submit。默认行为是 `strict-review-gate: false`。
+
+## Output Format
+
+审查报告保存到 `.harness/changes/<change-name>/reports/review/review-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行），同时在控制台输出摘要。报告格式详见 `reference.md` 的「输出报告完整模板」。
+
+## 渐进披露
+
+- **Read `checklist.md`** 仅在执行完整6维度审查时 — 含6维度检查项详细列表 + 输出格式 + 执行日志记录模板
+- **Read `reference.md`** 仅在需要理解审查标准或生成详细报告时 — 含"为什么需要审查"概述 + 严重级别判定标准 + 输出报告完整模板
+- **Read `protocols.md`** 仅在 RED/YELLOW 问题需要转化为修复反馈时 — 含 `review-fixback-protocol` 的结构化 fixback 字段与落盘要求
+
+## 原生修复反馈协议
+
+`/harness-review` 不再运行时调用 Superpowers `receiving-code-review`。审查后的修复反馈能力内化为 `protocols.md` 的 `review-fixback-protocol`：
+
+1. RED/YELLOW 问题转成 fixback 条目：严重级别、位置、风险、建议、验证方式、对 submit 的影响。
+2. fixback 落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`。
+3. 无 RED/YELLOW 时记录跳过原因，不制造空修复任务。
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 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]]
+
+## 关键规则（硬门禁速查）
+
+> 每条规则的详细判定、检查项见 `checklist.md` 对应章节；Shell 执行安全见 `../protocols/powershell-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`，结构化报告事件见 `../protocols/report-pipeline-protocol.md`。
+
+### 一、只审查 git diff 变更部分
+
+只审查本次 `git diff` 中的变更，不审查已有代码；diff 为空 → 直接返回"无变更可审查"。每个问题给出具体修复建议（文件:行号 + 建议做法）。
+
+### 二、严重级别三态
+
+RED=高风险建议（强烈建议处理），YELLOW=中低风险建议，OK=无问题。6维度逐文件审查（架构/安全/规范/兼容/测试/性能）—— 检查项见 `checklist.md`。判定标准见 `reference.md`「严重级别判定标准」。
+
+### 三、review 结果仅供参考（不阻塞后续流程）
+
+review 结果默认只作参考，不阻塞 submit/archive；报告措辞遵循 `## Review 定位（重要）` 的“禁止写/应写”清单，不得出现“阻塞 submit / 必须修复后才能继续”。
+
+### 四、Shell 安全 / 敏感信息 / 证据化报告 / CodeGraph 探索
+
+git diff/log 命令通过 `powershell.exe -Command "..."` 执行；review-report 中如发现明文 token/密码/密钥，必须列入 RED 问题并在报告中以 `<TOKEN_REDACTED>` 等占位符引用；RED/YELLOW/OK 结论必须基于实际 diff 内容，不得凭印象判断。代码探索必须优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore`），不允许通过普通 Bash 调 codegraph 命令（已列入 `disallowed-tools`）；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
+
+## 交互白名单
+
+**无** AskUserQuestion（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。