hunter-harness 0.1.0 → 0.1.2

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

@@ -1,164 +1,164 @@
----
-name: harness-knowledge-query
-description: "根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge 历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。"
-argument-hint: "<需求文本> [--file <path>] [--status active|candidate|stale]"
-effort: medium
-allowed-tools: [Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]
-disallowed-tools:
-  - Bash(git *)
-  - Bash(mvn *)
-  - Bash(ls *)
-  - Bash(find *)
-  - Bash(grep *)
-  - Bash(cat *)
-  - Bash(cp *)
-  - Bash(mv *)
-  - Bash(rm *)
-  - Bash(mkdir *)
-  - Bash(touch *)
-  - Bash(sed *)
-  - Bash(awk *)
-  - Bash(curl *)
----
-<!-- generated by harness_deploy.py; core=63af4c482d21b6be; overlay=none; 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 边界保持最新。
+---
+name: harness-knowledge-query
+description: "根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge 历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。"
+argument-hint: "<需求文本> [--file <path>] [--status active|candidate|stale]"
+effort: medium
+allowed-tools: [Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]
+disallowed-tools:
+  - Bash(git *)
+  - Bash(mvn *)
+  - Bash(ls *)
+  - Bash(find *)
+  - Bash(grep *)
+  - Bash(cat *)
+  - Bash(cp *)
+  - Bash(mv *)
+  - Bash(rm *)
+  - Bash(mkdir *)
+  - Bash(touch *)
+  - Bash(sed *)
+  - Bash(awk *)
+  - Bash(curl *)
+---
+<!-- generated by harness_deploy.py; core=76dd32302df53f0b; overlay=none; 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/general/harness-plan/SKILL.md

@@ -1,127 +1,127 @@
----
-name: harness-plan
-description: "将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划"
-argument-hint: "需求描述 | --adversarial"
-effort: high
-allowed-tools: [Read, Glob, Grep, Edit, Write, Agent, Bash(powershell.exe:*)]
-disallowed-tools:
-  - Bash(git *)
-  - Bash(mvn *)
-  - Bash(ls *)
-  - Bash(find *)
-  - Bash(grep *)
-  - Bash(cat *)
-  - Bash(cp *)
-  - Bash(mv *)
-  - Bash(rm *)
-  - Bash(mkdir *)
-  - Bash(touch *)
-  - Bash(sed *)
-  - Bash(awk *)
-  - Bash(curl *)
----
-<!-- generated by harness_deploy.py; core=63af4c482d21b6be; overlay=none; 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 边界保持最新。
+---
+name: harness-plan
+description: "将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划"
+argument-hint: "需求描述 | --adversarial"
+effort: high
+allowed-tools: [Read, Glob, Grep, Edit, Write, Agent, Bash(powershell.exe:*)]
+disallowed-tools:
+  - Bash(git *)
+  - Bash(mvn *)
+  - Bash(ls *)
+  - Bash(find *)
+  - Bash(grep *)
+  - Bash(cat *)
+  - Bash(cp *)
+  - Bash(mv *)
+  - Bash(rm *)
+  - Bash(mkdir *)
+  - Bash(touch *)
+  - Bash(sed *)
+  - Bash(awk *)
+  - Bash(curl *)
+---
+<!-- generated by harness_deploy.py; core=76dd32302df53f0b; overlay=none; 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 边界保持最新。