@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/pi/harness-codebase-map/templates/TESTING.md

@@ -0,0 +1,64 @@
+---
+harness:
+  origin: generated
+  generator: harness-codebase-map
+  file_kind: generated_reviewable
+  push_policy: full-diff-proposal
+  update_policy: skip-if-local-dirty
+title: Testing Patterns
+document_type: testing
+profile: <profile-or-unknown>
+mapped_at: <YYYY-MM-DD HH:mm>
+last_mapped_commit: <sha-or-unknown>
+path_scope: <full|fast|focus|paths>
+status: active
+---
+
+# Testing Patterns
+
+**Analysis Date:** <YYYY-MM-DD>
+
+## Test Framework
+
+- Runner: <framework>
+- Config: `<path>`
+
+## Test Commands
+
+```bash
+<test command>
+<single test command if known>
+<coverage command if known>
+```
+
+## Test File Organization
+
+- Location: `<path or pattern>`
+- Naming: <pattern>
+
+## Unit Tests
+
+- Scope: <observed pattern>
+- Example path: `<path>`
+
+## Integration / API Tests
+
+- Scope: <observed pattern>
+- Example path: `<path>`
+
+## Mocking / Fixtures
+
+- <mock strategy>
+- Fixture location: `<path>`
+
+## Coverage / Quality Gates
+
+- <coverage rule or unknown>
+
+## Testing Gaps
+
+- <module or path lacking tests>
+
+## Notes for AI Agents
+
+- <how harness-test should use this map>

package/harness/bundles/general/pi/harness-codebase-map/templates/map-manifest.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Hunter Harness Codebase Map Manifest",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generator",
+    "generated_at",
+    "mode",
+    "profile",
+    "last_mapped_commit",
+    "path_scope",
+    "documents",
+    "summary",
+    "warnings",
+    "stale_policy"
+  ],
+  "properties": {
+    "schema_version": { "type": "integer", "const": 1 },
+    "generator": { "type": "string", "const": "harness-codebase-map" },
+    "generated_at": { "type": "string" },
+    "mode": { "type": "string" },
+    "profile": { "type": "string" },
+    "project_root": { "type": "string" },
+    "last_mapped_commit": { "type": "string" },
+    "path_scope": {
+      "type": "object",
+      "required": ["type", "paths"],
+      "properties": {
+        "type": { "type": "string" },
+        "paths": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "documents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["document_type", "path", "sha256", "line_count", "focus", "status"],
+        "properties": {
+          "document_type": { "type": "string" },
+          "path": { "type": "string" },
+          "sha256": { "type": "string" },
+          "line_count": { "type": "integer" },
+          "focus": { "type": "string" },
+          "status": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["path", "sha256", "line_count"],
+      "properties": {
+        "path": { "type": "string" },
+        "sha256": { "type": "string" },
+        "line_count": { "type": "integer" }
+      },
+      "additionalProperties": true
+    },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "stale_policy": {
+      "type": "object",
+      "required": ["max_age_days", "changed_files_threshold"],
+      "properties": {
+        "max_age_days": { "type": "integer" },
+        "changed_files_threshold": { "type": "integer" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/harness/bundles/general/pi/harness-codebase-map/templates/map-summary.md

@@ -0,0 +1,64 @@
+---
+harness:
+  origin: generated
+  generator: harness-codebase-map
+  file_kind: generated_reviewable
+  push_policy: full-diff-proposal
+  update_policy: skip-if-local-dirty
+title: Codebase Map Summary
+document_type: map-summary
+profile: <profile-or-unknown>
+generated_at: <YYYY-MM-DD HH:mm>
+last_mapped_commit: <sha-or-unknown>
+mode: <full|fast|focus|paths|status|diff>
+status: active
+---
+
+# Codebase Map Summary
+
+**Generated At:** <YYYY-MM-DD HH:mm>
+**Mode:** <full|fast|focus|paths|status|diff>
+**Profile:** <profile-or-unknown>
+**Commit:** <sha-or-unknown>
+
+## Project Snapshot
+
+<项目一句话说明>
+
+## Key Stack
+
+- Language: <language and version>
+- Framework: <framework>
+- Build: <build tool>
+- Database: <database or none/unknown>
+
+## Main Modules
+
+- `<path>` — <purpose>
+
+## Entry Points
+
+- `<path>` — <purpose>
+
+## Testing
+
+- Command: <test command or unknown>
+- Test location: `<path or unknown>`
+
+## Concerns
+
+- <risk or concern>
+
+## Detailed Documents
+
+- `.harness/codebase/map/STACK.md`
+- `.harness/codebase/map/INTEGRATIONS.md`
+- `.harness/codebase/map/ARCHITECTURE.md`
+- `.harness/codebase/map/STRUCTURE.md`
+- `.harness/codebase/map/CONVENTIONS.md`
+- `.harness/codebase/map/TESTING.md`
+- `.harness/codebase/map/CONCERNS.md`
+
+## Notes for AI Agents
+
+- Read this summary first, then open the detailed document that matches the current task.

package/harness/bundles/general/pi/harness-execute/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: harness-execute
+description: 执行阶段：按变更簇执行 TDD
+  编码循环（RED→GREEN→REFACTOR→编译验证），随后完成单元/接口/数据兼容验证并输出测试报告。仅当用户显式调用
+  /harness-execute 时使用；不得因用户提到编码/实现/测试就自动触发，也不得被其他阶段 skill 自动接续。
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-execute — 执行（编码 + 验证）
+
+> 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段。
+> `/harness-run` 与 `/harness-test` 保留为别名入口，语义与本 skill 相同。
+
+## Purpose
+
+基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），随后在同一阶段内完成单元测试、接口测试与数据兼容验证，写入 verification-ledger 并输出测试报告。负责 worktree 创建/切换。
+
+## When to Use
+
+仅当用户显式调用 `/harness-execute`（或别名 `/harness-run`、`/harness-test`）时执行；plan 完成后**不自动**进入本阶段。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
+
+**单阶段原则**：execute 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动开始其他阶段。
+
+## 前置条件
+
+- 设计文档（`plans/*-design.md` 优先，回退 `spec/*-design.md`）与 `plans/*-plan.md`（含 frontmatter）存在且已审批
+- `plans/*-test-scenarios.md` 存在（测试真相源）
+- 读 `meta/worktree.json`：`requested=true` 时 worktree 须存在或 execute 负责创建；worktree 已创建则在 worktree 中执行测试，不得静默回到主目录
+
+## Worktree 门禁
+
+读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
+
+| 条件 | 行为 |
+|------|------|
+| `requested=false` | 主目录执行 |
+| `requested=true` + path 存在 | 切换 worktree 执行 |
+| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
+
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
+
+**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
+
+创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+> 片段：worktree-gate · 创建命令 → `harness-run/reference.md`
+
+## 统一读取协议
+
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol
+
+## Workflow 概要
+
+0. 加载上下文：先 `harness_context.py prepare --project . --change <id> --phase execute --executor <tool> --json`（`--project` 必填），再 `harness_context.py begin --project . --change <id> --phase execute --executor <tool> --json` 校验交接，最后运行 **`harness_gate.py begin --phase execute --change <id>`**。旧名 `--phase run` / `--phase test` 仍被接受并归一为 execute。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → execute` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。<br>**Fixback** 不得拼装底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`；返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告并停止。禁止手写 `events.ndjson` / `phase.end`。
+0.5. **测试基础设施探测**与**命令执行模式 preflight** → `harness-test/reference.md`「命令执行模式 preflight」；测试基线已由 gate begin 内部建立，不得再次执行 guard begin
+1. **变更簇 TDD** — `harness-run/protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`
+2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；profile 缺失或陈旧时先 `harness_preflight.py detect --project . --json`；`record --project . --profile-input <key>` 从同一 target 推导 scope、coverage、规范命令与输入闭包
+3. **验证执行**：单元测试可复用则跳过（`harness_ledger.py can-reuse`）；接口测试**强制批量执行器**一次跑完全部场景；数据兼容验证按场景表执行 → `harness-test/reference.md`
+4. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
+5. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 必须取返回的 `nextPhases` 或 `plannedPhases` 中 execute 的真实后继（fixback 时为 execute 自身）。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
+
+**阶段归属规则**：只用 `ownerPhase=execute` 的任务和场景判定本阶段结果。`ownerPhase=review`/`submit` 的场景按计划留给后续阶段属于正常移交，出现在关门返回值的 `deferred` 里，不阻断 execute。合并前 `ownerPhase=run`/`test` 的旧清单经别名表归一为 execute，在 execute 关门时一并到期。
+
+> 关门脚本与本规则一致：`harness_gate.py close --phase execute` 的 C9 场景覆盖要求全部 `ownerPhase=execute` 的必需场景有通过 receipt——包括本属原 run 半段的编码验证与原 test 半段的接口/兼容验证，这正是两阶段合并的语义。
+
+**构建/测试执行入口**：所有构建与测试命令（mvn / gradle / npm test / pytest 等）必须经 `harness_test_runner.py exec` 发起，**禁止**用 `powershell.exe -Command` 直接裸跑：
+
+```text
+python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
+```
+
+资源档位是硬合同（`safe` 默认；`system`/`full` 需用户明确授权或 `--confirm-resource-intensive`）；Python `unittest` 必须逐模块隔离模式（`harness_test_runner.py unittest --profile safe --tests-dir <目录>`）。返回 `TEST_RUN_ALREADY_ACTIVE` 说明已有构建在跑：等待或查明持有者，不得绕开锁另起并行构建。完整约束 → `harness-test/checklist.md`「0.0-A 资源安全档位」。
+
+**长阶段租约**：`gate begin` 的租约默认 TTL 3600 秒，execute 阶段常常跑得更久。租约过期不会中断执行，**也不再阻断收尾**：`gate close` 发现租约过期而 run-id 仍是本阶段的，会自动用原 run-id 重取并照常关门，只在返回体的 `leaseLapsed` 里记录。不需要定期续租；报 `LEASE_ABSENT`/`LEASE_INVALID` 时先确认 begin 真的跑过，**不要**重跑 `gate begin`。
+
+**接口测试执行器优先级**：接口测试执行器（默认首选）> PowerShell batch `.ps1` > Playwright MCP `browser_evaluate`（仅前两者不可用或用户明确选择）> curl + UTF-8 JSON body file（兜底）。执行器在 PowerShell 可用时**禁止**用 Playwright MCP 逐条执行。→ `harness-test/reference.md`「接口测试工具优先级」
+
+**陈旧测试安全修复**：只有当前生产代码、已批准计划或可验证历史能唯一确定新契约时，才允许仅修改测试并立即重跑，然后记录：
+
+```text
+python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
+```
+
+新建或正常更新测试分别使用 `tdd-created` / `test-updated`；存在业务歧义时记录 `BLOCKED_PREEXISTING` 并停止。**禁止临时排除测试**（`.bak`/改名/移出目录/禁用注解/exclude/`skipTests` 充当通过证据）。
+
+**Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
+
+## 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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust
+
+## 关键规则（硬门禁速查）
+
+> 编码侧细则 → `harness-run/reference.md`、`harness-run/protocols.md`；验证侧细则 → `harness-test/reference.md`、`harness-test/checklist.md`、`harness-test/pitfalls.md`
+
+| 域 | 要点 |
+|----|------|
+| **文档输入** | 只读 `.harness/changes/<cn>/`；禁止 `docs/superpowers/` |
+| **变更簇 TDD** | 一簇一次 RED/GREEN；低价值项豁免；新分支必须 RED |
+| **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过 |
+| **探测/ledger** | 基础设施先探测；每次构建/测试经 `harness_ledger.py record`；禁止手写 ledger JSON |
+| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin`；阶段门禁统一用 `harness_gate.py begin/close`；gate 内部负责 guard begin/close（`harness_test_guard.py begin` / `harness_test_guard.py close` 仅由 gate 调用，不构成模型执行步骤），模型只在需要记录测试来源或修复时调用 guard 的 `record/stage/mark` |
+| **关门/状态** | 10 项关门检查；仅 execute-owned P0 静态-only 导致 WARN；review/submit-owned 待办正常移交 |
+| **Worktree** | `requested=true` 时代码只写 worktree |
+| **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
+| **租约** | 阶段超 TTL 由 close 自动用原 run-id 重取，无需续租；`LEASE_ABSENT`/`LEASE_INVALID` 才需人工 `harness_change.py claim`，一律不重跑 begin |
+| **报告** | 区分"产品测试"与"工具维护"；API 维度 `OK`/`PARTIAL`/`BLOCKED`/`NOT_RUN`/`FAIL` 五态 |
+
+## Output Format
+
+变更文件表 + 构建/测试证据 + 场景覆盖摘要 + 最终状态（✅OK / 🟡WARN / ❌FAIL）。测试报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`。
+
+## 渐进披露
+
+- **Read `harness-run/protocols.md`** — run-tdd + change-cluster-review
+- **Read `harness-run/reference.md`** — Step 0–5 细节、TDD/RED/ledger/迁移/安全矩阵
+- **Read `harness-test/checklist.md`** — 验证前各项强制检查、preflight、服务生命周期清单
+- **Read `harness-test/reference.md`** — API 测试执行方法、执行器模板、运行时配置叠加
+- **Read `harness-test/pitfalls.md`** — 测试踩坑规则
+
+## 交互白名单
+
+1. **预存变更**：保留 / 暂存 / 终止
+2. **数据库迁移**：展示审查清单并确认（**永不自动执行**）
+3. **worktree 创建失败**：是否改主目录
+4. **Service Gate**：仅当 `harness_service.py ensure` 返回 `needs-user-decision` 时询问处理方式
+5. **资源密集型测试确认**：仅当发布/验收确实需要 `system` 或 `full` 档位，且用户尚未明确授权时询问；获得授权后传入 `--confirm-resource-intensive`
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`execute`

package/harness/bundles/general/pi/harness-knowledge-ingest/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: harness-knowledge-ingest
+description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-knowledge-ingest
+
+知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；
+服务端收到后保存原包、安全解包、发布核心文件，并根据其中的 Markdown 与摘要重建
+项目语义索引。
+
+客户端不得生成 `.harness/knowledge`、SQLite 索引、候选条目、视图、报告或本地裁决。
+本地知识处理脚本已从分发包移除；历史版本数据只由升级兼容逻辑识别，不再执行。
+
+## 归档包边界
+
+允许上传的核心内容只有：
+
+- `reports/final/summary-data.json`
+- `spec/**/*.md`
+- `plans/**/*.md`
+- `archive-meta.md`
+- `change-context.json`
+- 包内 `archive-manifest.json`（由 CLI 生成）
+
+日志、测试报告、审查报告、HTML、缓存、备份、凭据和临时文件不得进入归档包。
+
+## Normal Workflow
+
+1. 先读取最近归档操作记录中的 `archiveRemote`，以及本地状态目录
+   `.harness/state/local/archive-packages/<change-key>.remote.json`。若 `archiveStatus=durable` 且
+   `knowledgeStatus=ready`，直接报告已完成，禁止重新打包或上传。
+2. 若存在 `.harness/state/local/archive-packages/<change-key>.zip`，只重试该包；
+   禁止搜索实现源码、调用 Python 内部函数或手工重新拼包。
+3. 只有旧归档没有 ZIP/回执时，调用公开命令重新生成并上传；`harness-archive`
+   的 finalize 正常情况下会生成确定性 ZIP，并调用：
+
+```powershell
+powershell.exe -Command "npx hunter-harness archive upload --file '<archive.zip>' --change-key '<change-key>' --yes --non-interactive --json"
+```
+
+4. 检查响应中的包哈希、服务端保存状态和 `knowledge_status`。
+5. 只有服务端确认原 ZIP 已持久保存且知识状态为 ready，才删除本地待上传 ZIP。
+6. 上传或 ingest 失败时保留 ZIP 与失败收据；修复连接后重试同一个 ZIP，不重新拼散文件。
+
+## Ownership Rules
+
+- 客户端：选择核心文件、生成稳定 manifest/ZIP、校验包哈希、上传与保留失败重试材料。
+- 服务端：敏感信息扫描、ZIP 安全校验、原包持久化、解包、制品发布、知识 ingest、状态查询和下载恢复。
+- 远端不可用：知识不可用；不得启动本地替代索引。
+- 面向人的知识、提案、规则和说明默认使用中文。
+
+## Forbidden Actions
+
+- build_or_refresh_local_knowledge
+- write_dot_harness_knowledge
+- upload_logs_reviews_tests_or_temp_files
+- call_legacy_python_ingest
+- treat_upload_acceptance_without_durable_status_as_success
+- delete_pending_zip_after_failed_upload
+
+## Verification
+
+确认归档命令的 JSON 结果同时包含：服务端 package 哈希、保存状态和知识状态。
+若失败，确认 `.harness/state/local/archive-packages/` 中仍保留可重试 ZIP；若成功，确认
+ZIP 已按收据策略清理，且平台下载接口可以恢复原包。
+
+## 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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust · 只有服务端持久化与 ingest 收据可证明知识已入库
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`knowledge-ingest` · 记录 package hash、服务端状态与失败重试路径

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

@@ -0,0 +1,97 @@
+---
+name: harness-knowledge-query
+description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-knowledge-query
+
+项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：
+
+- 不创建或读取 `.harness/knowledge`；
+- 不运行本地 Python ingest、SQLite、FTS 或 context-pack 脚本；
+- 不在网络或服务不可用时回退到本地归档；
+- 查询失败只记录“本轮无远端知识”，后续工作必须依靠当前代码和用户提供的信息。
+
+所有面向人的总结默认使用中文，代码标识符和原始路径保持原样。
+
+## Triggers
+
+- query knowledge / knowledge query
+- 查询历史需求、决策或实现经验
+- 结合之前做过的内容
+- 规划或排查前读取项目知识
+
+## Command
+
+在项目根目录执行一次：
+
+```powershell
+powershell.exe -Command "npx hunter-harness knowledge query '<用户需求原文>' --limit 10 --json"
+```
+
+只允许通过 CLI 访问平台，不得直接拼接 HTTP 请求，也不得调用旧的
+本地知识查询脚本（该脚本已从当前分发包移除）。
+
+## Workflow
+
+1. 原样保留用户的需求或问题作为查询文本；已知范围较大时可将关键模块名一并放入文本。
+2. 执行一次远端查询，不在查询前重建或同步知识。
+3. 读取 JSON 中的命中项、来源路径、变更键和相关度。
+4. 把命中内容作为历史线索；涉及当前行为时仍以当前代码和验证结果为准。
+5. 若命令返回远端不可达、未绑定或未认证，记录明确 issue 后继续，不重试本地方案。
+
+## Output Contract
+
+必须说明：
+
+- 查询文本与 limit；
+- 是否成功访问远端；
+- 命中数量及最相关来源；
+- 远端不可用时，明确写“未使用本地回退”；
+- 下一步是进入规划/实现，还是先核对当前代码。
+
+## Forbidden Actions
+
+- create_local_knowledge_index
+- query_local_sqlite_or_archive_as_fallback
+- generate_local_context_pack
+- retry_with_legacy_python_knowledge_script
+- treat_remote_history_as_current_code_fact
+- copy_secrets_into_query
+
+## 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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust · 远端查询成功必须有 CLI JSON 证据；失败不得伪装为已读取历史
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`knowledge-query` · 成功记录命中摘要，失败记录远端错误码且不做本地回退