@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/pi/harness-submit/reference.md

@@ -0,0 +1,152 @@
+---
+description: harness-submit 的提交格式、固定交互模板和中文 commit 文件流程。仅在执行提交流程时读取。
+---
+
+# harness-submit 参考
+
+## 提交方式 blocking user confirmation 固定模板
+
+问题标题：`请选择提交方式`
+
+选项：
+
+1. `commit + push 到当前 upstream`
+2. `仅本地 commit，不 push`
+3. `取消提交`
+
+不得临场增加复杂对象或嵌套参数，避免 blocking user confirmation 参数错误。
+
+> **worktree 模式（meta/worktree.json requested=true）**：固定选项 2「仅本地 commit」，不展示「commit+push」；commit 成功后 skill **自动接续** worktree 合并流程（`/harness-merge` 为别名）。push 只在主分支完成，产出 `mergeFinalHash`。
+
+## Commit Message 固定格式
+
+```text
+<type>(<scope>): <中文摘要>
+
+- 变更点 1
+- 变更点 2
+
+验证：
+- <复用 ledger / 重跑验证摘要>
+```
+
+禁止 footer：
+
+```text
+Co-Authored-By: ...
+Generated by ...
+AI generated ...
+```
+
+## 中文 commit 文件流程
+
+1. 创建 runtime 目录：
+
+```powershell
+powershell.exe -NoProfile -Command "New-Item -ItemType Directory -Force '.harness/changes/<change>/runtime'"
+```
+
+2. 写入 message 文件：
+
+```text
+.harness/changes/<change>/runtime/commit-message.txt
+```
+
+3. 用户确认后提交：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' commit -F '.harness/changes/<change>/runtime/commit-message.txt'"
+```
+
+禁止：
+
+- 命令行内联长中文 commit message；
+- 先英文 commit，再 amend 成中文；
+- 使用 `--no-verify`、`--no-gpg-sign`。
+
+## Commit Message 确认模板
+
+```markdown
+## 准备提交
+
+### 1. Staged 文件
+<git diff --cached --name-only 的实际输出>
+
+### 2. Diff Stat
+<git diff --cached --stat 的实际输出>
+
+### 3. Commit Message
+```text
+<commit message 完整内容>
+```
+
+### 4. Push 策略
+commit + push / 仅本地 commit
+
+确认提交吗？
+1. 确认提交
+2. 修改 message
+3. 取消
+```
+
+## 远端检查
+
+push 前必须执行：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' fetch"
+powershell.exe -NoProfile -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+```
+
+远端有新提交时，必须让用户选择：
+
+1. rebase 后重跑必要验证；
+2. 停止 push，保留本地 commit。
+
+## 输出示例
+
+```markdown
+## 提交完成 — <change-name>
+
+- Commit: `<final-hash>`
+- Push: ✅ 已推送 / ⏭️ 仅本地 commit
+- Commit message: `.harness/changes/<change>/runtime/commit-message.txt`
+- 验证策略: 🔁 复用 test ledger / 🔄 已重跑
+- 下一步: `/harness-archive`
+```
+
+## Worktree 清理兜底（Windows）
+
+`git worktree remove <path>` 在 Windows 下常因目录残留 `node_modules` 等深嵌套 gitignored 文件失败（报 "Directory not empty"，git 无法删空目录）。按顺序兜底：
+
+1. **先删 git 注册和本地分支**（分支须已推送 origin）：
+   ```powershell
+   powershell.exe -Command "git -C '<项目路径>' worktree remove '<worktree-path>' --force"
+   powershell.exe -Command "git -C '<项目路径>' branch -D <branch>"
+   ```
+
+2. **若目录仍残留**（git 注册已移除但磁盘目录还在）：用 robocopy 空 source 镜像清空（能处理长路径与 `node_modules` 深嵌套）：
+   ```powershell
+   powershell.exe -Command "$empty=Join-Path $env:TEMP ('emp-'+[Guid]::NewGuid()); New-Item -ItemType Directory -Force $empty | Out-Null; robocopy $empty '<worktree-path>' /MIR | Out-Null; Remove-Item -Recurse -Force $empty"
+   ```
+   ⚠️ **hook 误判规避**：不要把 `robocopy ... /MIR` 和 `Remove-Item` 写在同一条命令的参数位——PreToolUse hook 会把 `/MIR` 误判为 `Remove-Item` 的受保护路径（报 "system path '/MIR' is blocked"）。若遇此误判，按工具失败恢复策略**拆成两条命令**分别执行，不要重复同一条失败命令。
+
+3. **目录清空后删空目录本身**（用 .NET，规避 Remove-Item 对系统路径的 hook 拦截）：
+   ```powershell
+   powershell.exe -Command "[System.IO.Directory]::Delete('<worktree-path>', $true)"
+   ```
+
+4. **ExitWorktree 工具限制**：`ExitWorktree(remove)` 只删由 `EnterWorktree` 创建的 worktree。若本会话进入的是已存在 worktree（由 `harness-run` 创建），工具会拒绝删除。此时用 `action:keep` 返回主仓库，再按上述 1-3 步手动清理。
+
+5. **清理后更新 `meta/worktree.json`**：置 `created=false` + 追加 `removedAt`/`removedBy`/`removalNote`，记录产出保留待 `/harness-archive`。
+
+> 含 `$`/`[Guid]`/`@{}` 的复杂命令建议写入 `scripts/*.ps1` 后 `-File` 执行，避免内联转义问题（参见 `../protocols/powershell-protocol.md`）。
+
+## 工作树 clean + 已有 wip commit 场景
+
+若进入 `/harness-submit` 时工作树已 clean（`git status --porcelain` 为空），且 run/test 阶段已做 wip commit（HEAD 已是本次变更的提交），则：
+
+- 步骤 1（合并最新代码）：按无 upstream / 远端无新提交判定 N/A，在执行日志记录理由。
+- 步骤 5（commit-message.txt + `git commit -F`）N/A：无可暂存 diff，无新 commit 需生成。执行日志标注 `commit-message.txt / git commit -F: N/A（工作树 clean，无新 commit；N 个 wip 提交已存在，原样推送）`。
+- 步骤 4（提交方式选择）：固定三选项仍适用。但当 review 标了 RED 兼容性破坏等需人工确认项时，可在"commit + push"选项的描述中注明"并确认 <RED 项>"，**不得新增第四选项**、不得临场拼复杂 blocking user confirmation 参数。
+- push 仍按步骤 6：fetch 检查远端 → `git push -u`（无 upstream 则新建远端分支）→ 记录 pre-pull hash + final pushed hash。

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

@@ -0,0 +1,72 @@
+---
+name: harness-sync
+description: Use when the user asks to synchronize, refresh, or validate Harness
+  metadata, adapters, remote knowledge ownership, instruction entrypoints,
+  config origins, or CodeGraph status.
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-sync
+
+## Purpose
+
+通过一个有界入口刷新 Harness Adapter 与元数据、检查远端知识职责和项目指令状态，并在当前命令输出中给出组件结果。`sync` 是维护命令，不是 change 生命周期阶段：不追加 change 事件、不调用 `events-sync`、不上传运行监控。`sync` 不直接改写 AGENTS/CLAUDE/CODEBUDDY 或规则；文档优化使用远端审计提案。
+
+## Before running
+
+读取 `reference.md`。`sync` 自身会在任何重操作之前完成能力握手；不要另起一个
+`capabilities` 进程。工作流要求 `sync@2`、`rules-sync@1`、`rules-review@1`、
+`knowledge-sync@3`、`codegraph-status@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，
+不得降级为手工拼接旧流程。
+
+## Run
+
+```powershell
+npx hunter-harness sync --project <项目路径> --profile interactive --progress jsonl --json
+```
+
+CLI 负责 Python runtime 解析、Adapter 事务、远端知识职责、文档审计提示、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用旧知识 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。
+
+只读诊断使用 `--check`（`--dry-run` 为兼容别名）；它不得写 receipt 或投影。普通模式只允许执行用户请求的 Adapter 事务，不写入 `.harness/runtime/sync/`。长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。需要组件级证据时显式加 `--verbose`；`reportPath` 和 `reportSha256` 固定为 `null`。
+
+摘要中的 `remediations[]` 是稳定修复契约。先用对应 `previewCommand` 预览；低风险修复用
+`--apply safe`，指定修复用 `--fix <id>`。需覆盖受管投影的修复必须同时提供 `--yes`，
+并依赖 refresh 事务留下的 before snapshot；不允许绕过确认或无备份覆盖。指定修复时，
+无关组件只做只读评估，不得顺带写入。
+
+## Interpret
+
+- `OK`：所有可验证组件通过。
+- `ADVISORY`：例如需要运行中文指令审计提案；退出码仍为 0，且 `sync` 本身没有改写文档。
+- `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按组件的中文 `nextAction` 处理。
+- `FAIL`：组件执行失败；不得宣称同步完成。
+- `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。
+- `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。
+
+非交互或 CI 使用 `--check --profile general --progress jsonl --json`。交互式运行若报告 `INSTRUCTION_AUDIT_REQUIRED`，运行 `hunter-harness instructions audit`；规则候选只进入提案，永不自动应用。
+
+## 交互后续动作
+
+交互式宿主支持选择器时，必须使用**多选复选框**，保持用户熟悉的勾选形式；只显示与本次非 OK 组件对应的选项，再附加“保持现状”。不要改成自由输入或普通编号问答。选项标题和说明优先使用通俗中文，机器原因码只放在技术详情中。
+
+- **生成 Codebase Map**：仅在 `codebase-map` 缺失或过期时显示。说明它会扫描项目的技术栈、外部集成、架构、目录结构、编码约定、测试方式和风险，生成 `.harness/codebase/map/` 下的 `STACK.md`、`INTEGRATIONS.md`、`ARCHITECTURE.md`、`STRUCTURE.md`、`CONVENTIONS.md`、`TESTING.md`、`CONCERNS.md`，以及 `map-summary.md` 和 `map-manifest.json`；不会修改源码。
+- **运行指令审计**：仅在 `rules` 需要审计时显示。说明服务端会结合项目类型、现有指令文档、Codebase Map 和近期变更生成中文优化提案，不会直接修改项目文档；用户审阅后才可显式应用。
+- **检查 CodeGraph 后台同步**：仅在 watcher 未验证、停用或存在待同步源码时显示。若索引可用且待同步数为 0，应说明当前查询仍可用，检查 watcher 只是为了确认后续源码能否自动增量更新。
+- **保持现状**：接受本次提示，不执行任何后续动作。
+
+## Safety
+
+同步不得直接修改项目指令文档或规则。配置真源与生成投影存在漂移时只报告，不静默覆盖真源。change 清理先 dry-run，仅对已验证归档收据执行安全清理。知识查询和 ingest 均为远端职责，不创建 `.harness/knowledge`。
+
+无论结果如何，`sync` 都不写持久同步报告、不追加 change 事件、不调用 `events-sync`，也不上传监控；组件详情仅存在于本次 stdout。Adapter 事务本身的必要备份和回滚证据不属于 sync 日志，不得因此禁用。
+
+## 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

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

@@ -0,0 +1,176 @@
+---
+description: harness-sync 的能力契约、统一状态模型、报告收据和安全恢复参考。
+---
+
+# harness-sync 参考
+
+## 1. 能力握手
+
+工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。`sync` 在任何高成本
+阶段之前自行核对版本与能力；Skill 不要再运行独立的 `capabilities` 子进程。缺失时返回：
+
+```json
+{
+  "status": "BLOCKED",
+  "reasonCode": "BLOCKED_CAPABILITY_MISMATCH"
+}
+```
+
+不得通过直接运行内部脚本绕过该阻塞。打包 smoke 会从已发布 Skill 文档抽取所有 `hunter-harness` 命令，并验证安装后的 CLI 能力清单和 `--help`。
+
+## 2. Python runtime
+
+CLI 按以下顺序解析 Python，并在详细报告中记录来源：
+
+1. `HUNTER_HARNESS_PYTHON`
+2. 项目受管 runtime（`.harness/runtime/python`、`.venv`）
+3. `uv run python`
+4. Windows `py -3`
+5. `python3`
+6. `python`
+
+所有探测都必须有超时。完全不可用时返回 `PYTHON_RUNTIME_UNAVAILABLE`，并跳过仍依赖 Python 的变更状态阶段；远端知识和指令审计不允许回退到本地 Python 实现。
+
+## 3. 统一同步
+
+交互式：
+
+```powershell
+npx hunter-harness sync --project <项目路径> --profile interactive --progress jsonl --json
+```
+
+CI/非交互式：
+
+```powershell
+npx hunter-harness sync --check --project <项目路径> --profile general --progress jsonl --json
+```
+
+`--check` 是严格只读检查；`--dry-run` 是兼容别名。两者都不生成持久报告、receipt 或
+投影。普通模式可以执行明确请求的 Adapter 事务，但同样不写持久同步报告。每个长阶段
+通过 stderr 输出受限 heartbeat；stdout 默认只输出：
+
+```json
+{
+  "status": "WARN",
+  "runId": "<run-id>",
+  "components": {"ok": 7, "advisory": 1, "warn": 0, "fail": 0, "blocked": 0, "unknown": 0},
+  "versions": {
+    "cliVersion": "0.0.0",
+    "workflowBundleVersion": "0.0.0",
+    "adapterBundleVersions": {}
+  },
+  "remediations": [],
+  "reportPath": null,
+  "reportSha256": null
+}
+```
+
+所有模式的 `reportPath` 和 `reportSha256` 固定为 `null`。只有显式 `--verbose` 才把每个
+组件的 `status`、`reasonCode`、`observedAt`、`durationMs`、证据、是否自动修复及
+`nextAction` 写到 stdout。`sync` 不写 `.harness/runtime/sync/`，不追加 change 生命周期
+事件，不调用 `events-sync`，也不上传运行监控。
+
+### 结构化修复
+
+- `remediations[]` 含稳定 `id`、风险、写入范围、备份/回滚说明、预计耗时、是否需确认、
+  `previewCommand` 与 `applyCommand`。
+- `--apply safe` 只执行低风险、无需确认的修复。
+- `--fix <id>` 只执行该项；需要覆盖受管 Adapter 时必须加 `--yes`。
+- 指定修复时，其他组件仍参与诊断但保持只读。
+- Adapter 覆盖由 refresh 事务执行，before snapshot 位于最新 committed refresh
+  transaction；事务失败会自动回滚。预览永远不得产生写入。
+
+## 4. 组件状态
+
+| 组件 | 核心证据 | 失败/警告原则 |
+|---|---|---|
+| capability | CLI 版本、必需能力 | 不匹配立即 `BLOCKED` |
+| adapter projection | 事务后的实际文件 hash | 使用 post-transaction 校验；partial refresh 不得把未选 adapter 标成 stale |
+| knowledge | 远端职责声明 | 固定报告 `remote-only`、`fallback=false`、`localIndex=false`；不运行本地 ingest |
+| rules | 审计—提案—应用契约 | `sync` 只给出 `instructions audit` 下一步，不改写文档或自动应用候选 |
+| codebase map | manifest 文档清单、hash、生成时间 | 真实文件校验，不复用旧 display status |
+| instruction graph | 入口、include 边、环、主题可达性 | 缺失引用或循环为 `FAIL` |
+| config origins | canonical/projection 路径与 hash | 漂移 `WARN`，不静默覆盖 |
+| changes | 五态分类及归档收据 | `INVALID`/`ORPHAN` 不自动删除 |
+| CodeGraph | `codegraph status --json` 的 pending、数据库观察时间、watcher 可达性 | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；日志 mtime 只证明 watcher 活动，不证明索引完成；不自动全量 reindex |
+
+全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `ADVISORY` → `OK`。任一 `UNKNOWN`
+至少使全局结果为 `WARN`。远端知识可用性由实际 query/upload 收据判断，`sync` 不伪造本地 freshness。
+
+## 5. Git 与 CodeGraph
+
+增量基线只使用当前分支的 upstream merge-base；没有 upstream 时仅收集当前 HEAD 和有界文件统计。不得读取旧 `.harness/runtime/sync/last-success.json`，也禁止固定使用 `HEAD~5`。
+
+CodeGraph 状态探测优先读取 `codegraph status --json` 的权威 pending 列表；只有该 API
+不可用时才退回受限文件扫描，并把来源标成 `database-scan` 或 `unverified`。`.agents/`、
+`.cursor/`、`.claude/` 等 Adapter 投影和 Markdown 文档不计入源码 pending。daemon log
+mtime 只写入 `watcherObservedAt`，不能冒充 `indexObservedAt`。服务可达、watcher 已启用
+且权威 `pendingFileCount=0` 时为 `CURRENT`。如果 API 不可用，但本地索引存在且受限扫描
+确认 `pendingFileCount=0`，返回 `ADVISORY / INDEX_PRESENT_UNVERIFIED`：索引仍可用于查询，
+只是无法证明 watcher 正在持续运行。存在待同步源码，或已确认 watcher 停用/服务不可达，
+才返回 `WARN`。不要在 sync 内执行全量索引。
+
+## 6. Instruction graph
+
+只验证当前已启用 Agent 对应的入口文档及其引用图，而不是固定要求所有 Adapter 文件：
+
+- `AGENTS.md` 是共享入口，始终验证。
+- 仅启用 Claude Code 时验证 `CLAUDE.md`。
+- 仅启用 CodeBuddy 时验证 `CODEBUDDY.md`。
+- Codex 和 Cursor 不要求额外生成 `CLAUDE.md` 或 `CODEBUDDY.md`。
+
+- Claude 可单向引用 AGENTS，共享约束保持单一真源。
+- 禁止 AGENTS 反向引用 CLAUDE 形成环。
+- 最多读取 64 个文件、深度 8、总量 512 KiB。
+- 入口可以很薄；主题只需通过引用图可达，不要求复制到每个入口。
+
+## 7. Config origins
+
+典型 canonical 来源位于 `docs/ai/harness/`，`.harness/config/` 为生成投影。报告同时给出两侧路径、hash、来源类型与 drift，不把投影误判成真源。
+
+## 8. Change 五态与清理
+
+- `ACTIVE`：合法活动变更。
+- `ARCHIVED_LEFTOVER`：已由可验证 receipt 归档，但活动目录残留。
+- `RECOVERABLE`：残留可安全隔离恢复。
+- `ORPHAN`：缺少可信归档证据。
+- `INVALID`：结构或收据不合法。
+
+先预览：
+
+```powershell
+npx hunter-harness doctor --managed-blocks --json
+```
+
+change cleanup 由同步报告提供具体动作。只允许已验证的 `ARCHIVED_LEFTOVER` 进入删除路径；`RECOVERABLE` 只能移入隔离区；`ORPHAN`/`INVALID` 保持原状并提示人工处理。
+
+## 9. 中文指令与规则提案
+
+`sync` 只报告 `INSTRUCTION_AUDIT_REQUIRED`。需要优化时执行：
+
+```powershell
+npx hunter-harness instructions audit --json
+```
+
+服务端结合项目类型、现有文档、Codebase Map、近期变更总结和公开最佳实践生成中文提案。
+提案先保存到 `.harness/state/local/instruction-proposals/`，项目文件保持不变。审阅后显式执行：
+
+```powershell
+npx hunter-harness instructions apply --proposal <proposal.json> --yes --json
+```
+
+应用必须校验基线 hash 并使用事务；文件在审计后变化则返回 `INSTRUCTION_PROPOSAL_STALE`。
+近期变更中的经验只形成 rule candidates，`instructions apply` 也不得自动写入这些候选。
+
+## 10. 完成判定
+
+只有以下条件同时满足才能宣称同步成功：
+
+- stdout 摘要完整给出全局状态；使用 `--verbose` 时包含组件结果；
+- 没有 `FAIL` 或 `BLOCKED`；
+- 所有自动修复均有 post-transaction 证据；
+- knowledge 组件明确为 remote-only，且未创建或刷新本地索引；
+- 文档和规则组件未直接改写项目文件；
+- 未写持久 sync 报告、change 事件或监控上传记录；
+- 未把 `UNKNOWN` 描述成已验证；
+- 第二次无输入变化的运行不产生投影 churn。