npm - @hunter-harness/workflow-harness - Versions diffs - 0.3.1 → 0.4.1 - Mend

@hunter-harness/workflow-harness 0.3.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (402) hide show

package/harness/bundles/java/pi/harness-archive/templates/summary-data-template.json ADDED Viewed

@@ -0,0 +1,218 @@
+{
+  "schemaVersion": "2.3",
+  "changeName": "<change-name>",
+  "businessGoal": "本次变更为了做什么",
+  "finalStatus": "OK | WARN | CONDITIONAL_OK | FAIL",
+  "archiveIntent": "release-candidate | record-only",
+  "archiveIntegrity": {
+    "ok": true
+  },
+  "candidateVerification": {
+    "ok": false,
+    "code": "PRODUCT_CANDIDATE_VERIFIED | PRODUCT_CANDIDATE_NOT_VERIFIED | PRODUCT_CI_GREEN | PRODUCT_CI_NOT_GREEN",
+    "assurance": "local-reproducible | remote-claimed | remote-attested",
+    "message": ""
+  },
+  "releaseDecision": {
+    "releaseEligible": false,
+    "code": "RELEASE_NOT_EVALUATED",
+    "checks": {},
+    "issues": []
+  },
+  "releaseEligible": false,
+  "projection": {},
+  "finalCommit": "<commit-hash>",
+  "finalCommitBranch": "<origin/branch>",
+  "baseCommit": "<base-commit-hash>",
+  "diffStat": {
+    "filesChanged": 0,
+    "insertions": 0,
+    "deletions": 0,
+    "range": "<base>..<head>"
+  },
+  "stageStatus": {
+    "plan": "OK",
+    "run": "OK | WARN",
+    "test": "OK | PARTIAL | USER_SKIPPED | BLOCKED_BY_DBA",
+    "review": "ADVISORY",
+    "submit": "OK",
+    "archive": "OK"
+  },
+  "durations": {
+    "totalLabel": "约 N 分",
+    "totalMinutes": 0,
+    "stages": [
+      {
+        "stage": "plan",
+        "skill": "harness-plan",
+        "startedAt": "YYYY-MM-DD HH:mm:ss",
+        "endedAt": "YYYY-MM-DD HH:mm:ss",
+        "minutes": 0,
+        "result": "OK | WARN | FAIL"
+      }
+    ]
+  },
+  "timing": {
+    "workflowWallClockMs": 0,
+    "attributedStageUnionMs": 0,
+    "externalWaitMs": 0,
+    "pausedMs": 0,
+    "agentOrToolUnattributedMs": 0,
+    "conservationDeltaMs": 0,
+    "attempts": [],
+    "sessions": []
+  },
+  "skillCalls": [
+    { "skill": "harness-plan", "count": 1, "result": "OK" }
+  ],
+  "verification": {
+    "unitTests": {
+      "run": 0,
+      "failures": 0,
+      "errors": 0,
+      "skipped": 0,
+      "passRate": "183/185",
+      "source": "committed | uncommitted-archived | not-run"
+    },
+    "apiTests": {
+      "status": "OK | PARTIAL | USER_SKIPPED | NOT_RUN",
+      "total": 0,
+      "passed": 0,
+      "failed": 0,
+      "blocked": 0,
+      "passRate": "34/35"
+    },
+    "browserE2E": {
+      "status": "OK | FAIL | PARTIAL | USER_SKIPPED | NOT_RUN",
+      "total": 0,
+      "passed": 0,
+      "failed": 0,
+      "skipped": 0,
+      "retries": 0
+    },
+    "dbCompatibility": "OK | BLOCKED_BY_DBA | NOT_RUN",
+    "coverageDisplay": "例如 29/29 或 USER_SKIPPED"
+  },
+  "timeline": [],
+  "changedFiles": [
+    { "path": "src/...", "summary": "说明", "insertions": 0, "deletions": 0 }
+  ],
+  "artifacts": [],
+  "artifactStorage": {
+    "schemaVersion": 1,
+    "artifactCount": 0,
+    "bytesAdded": 0,
+    "bytesReused": 0,
+    "bytesPruned": 0,
+    "largestItems": []
+  },
+  "retention": {
+    "schemaVersion": 1,
+    "mode": "audit-only",
+    "expiredCount": 0,
+    "bytesPrunable": 0,
+    "items": []
+  },
+  "remoteCost": {
+    "schemaVersion": 1,
+    "available": false,
+    "candidates": [],
+    "totals": {
+      "runCount": 0,
+      "runnerMinutes": 0,
+      "queueWaitMs": 0,
+      "artifactBytes": 0,
+      "duplicateRunCount": 0
+    }
+  },
+  "efficiency": {
+    "schemaVersion": 1,
+    "timing": {
+      "wallClockMs": 0,
+      "activeTimeMs": 0,
+      "resourceWaitMs": 0
+    },
+    "verificationAttempts": 0,
+    "statusCounts": {},
+    "failureClasses": {
+      "launcher": 0,
+      "environment": 0,
+      "test": 0,
+      "external": 0,
+      "unknown": 0
+    },
+    "invalidationReasons": {},
+    "environment": {
+      "prepare": 0,
+      "reuse": 0,
+      "reset": 0,
+      "cleanup": 0
+    },
+    "productIdentityCount": 0,
+    "repeatedCommandsWithoutNewEvidence": 0,
+    "manualWrapperCount": 0,
+    "notes": []
+  },
+  "reviewSummary": {
+    "status": "ADVISORY",
+    "red": 0,
+    "yellow": 0,
+    "redFixed": 0,
+    "redConfirmed": 0,
+    "yellowFixed": 0,
+    "yellowDeferred": 0,
+    "summary": ""
+  },
+  "archiveManifest": {
+    "movedFiles": 0,
+    "generatedFiles": 0,
+    "totalArchiveFiles": 0,
+    "checksumStatus": "OK | WARN | FAIL"
+  },
+  "reportPipeline": {
+    "schema_version": 1,
+    "generated_at": "YYYY-MM-DDTHH:mm:ss.sssZ",
+    "event_count": 0,
+    "sources": [
+      "events.ndjson",
+      "evidence/verification-ledger.json",
+      "logs/execution-log.md"
+    ],
+    "phases": {
+      "plan": { "duration_ms": null, "event_count": 0 },
+      "run": { "duration_ms": null, "event_count": 0 },
+      "test": { "duration_ms": null, "event_count": 0 },
+      "review": { "duration_ms": null, "event_count": 0 },
+      "submit": { "duration_ms": null, "event_count": 0 },
+      "archive": { "duration_ms": null, "event_count": 0 }
+    },
+    "commands": [
+      {
+        "command": "npm test",
+        "exit_code": 0,
+        "duration_ms": 0,
+        "phase": "run",
+        "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ"
+      }
+    ],
+    "verificationChecks": [
+      {
+        "name": "unit tests",
+        "status": "passed | failed | skipped | unknown",
+        "command": "npm test",
+        "source": "events.ndjson | evidence/verification-ledger.json"
+      }
+    ],
+    "artifacts": [],
+    "validationIssues": [],
+    "sourceConsistency": {
+      "ok": true,
+      "issues": []
+    }
+  },
+  "uncommittedTestEvidence": [],
+  "maintenanceNotes": [],
+  "knownRisks": [],
+  "decisions": [],
+  "manualActions": []
+}

package/harness/bundles/java/pi/harness-codebase-map/SKILL.md ADDED Viewed

@@ -0,0 +1,116 @@
+---
+name: harness-codebase-map
+description: 分析现有代码库并生成 .harness/codebase/map/
+  下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
+---
+<!-- generated by harness_deploy.py; core=45b278c44cd66b19; overlay=java; agent=pi; do not edit -->
+# harness-codebase-map — 代码库地图
+## Purpose
+生成 hunter-harness 自有代码库地图 → `.harness/codebase/map/`（7 类文档）+ `map-summary.md` + `map-manifest.json`。供 plan/run/review 快速理解项目结构。
+## 核心边界
+- **内容只写** `.harness/codebase/map/`、`map-summary.md`、`map-manifest.json`、`.harness/reports/codebase-map-*.md`；平台同步只更新 Harness 协议状态
+- **禁止** `.planning/`、Git 写操作、修改 `.codegraph/`、自动 commit 或 Git push
+- `harness-sync` 只**建议**刷新，不自动跑全量 map
+## When to Use
+首次接入、map 过期（sync 提示）、大型重构前、用户说「刷新 codebase map」。跳过：空项目（<5 源文件）、纯符号查询（用 CodeGraph）。
+## Arguments
+| 参数 | 含义 |
+|------|------|
+| （无） | 全量 7 文档 |
+| `--fast` | STACK + STRUCTURE + CONCERNS |
+| `--focus *` | tech / arch / quality / concerns / tech+arch |
+| `--paths p1,p2` | 增量路径（非法路径 → WARN，全非法须确认） |
+| `--status` / `--diff` | 只检查，不刷新 |
+| `--refresh` | 显式全量刷新 |
+## Workflow（薄编排）
+| Phase | 动作 |
+|-------|------|
+| 0 | 读 SKILL + `reference.md` / `checklist.md` / `templates/` + protocols |
+| 1 | 解析 `$ARGUMENTS` → 模式与扫描范围 |
+| 2 | 检查现有 map / manifest → `--status` 可在此结束 |
+| 3 | `New-Item` 确保输出目录（PowerShell，禁止 Bash mkdir） |
+| 4 | Glob/Grep/Read 扫描；git 只读查询经 PowerShell |
+| 5 | 写 7 文档（`templates/` + frontmatter）— 可并行 mapper agents |
+| 6 | 写 summary + manifest（schema → `templates/map-manifest.schema.json`） |
+| 7 | 更新 `.harness/context-index.json` codebase 入口（若存在） |
+| 8 | 控制台 + `.harness/reports/codebase-map-*.md` 报告 |
+| 9 | 项目已绑定平台时，运行 `npx hunter-harness push --yes --non-interactive --json` 上传受控规则与架构快照；失败只报告“平台同步待重试”，不回滚本地地图 |
+逐步细节、frontmatter 字段、git 允许列表 → `reference.md` / `checklist.md`
+## Mapper Agent 策略
+优先并行 mapper（tech/arch/quality/concerns）；Agent 直写文档，主会话汇总。不可用 → 主会话顺序扫描 + 🟡WARN。
+## 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 · map 额外：文件存在/行数/hash 为证据
+## 关键规则
+| # | 规则 |
+|---|------|
+| 1 | 唯一输出 `.harness/codebase/map/` |
+| 2 | `generated_reviewable`，不建议手工改 map 正文 |
+| 3 | 不做 Git 写操作、不改业务代码；受控平台上传不等于 Git push |
+| 4 | 不管理 CodeGraph |
+| 5 | 敏感信息脱敏 → `sensitive-info-protocol` |
+| 6 | 证据化输出 → `evidence-based-reporting-protocol` |
+| 7 | 扫描复用 `harness_profile` 的 `excludedRoots`（`DEFAULT_EXCLUDED_ROOTS`：node_modules/target/build/dist/cache 等）与 state snapshot 输入，不重复定义排除集；sync 只建议刷新，不自动触发全量 map（design §3.7） |
+## Output Format
+模式、范围、7/7 文档路径与行数、manifest/summary、context-index 状态、平台同步状态、WARN/FAIL → `reference.md` 报告模板
+## 渐进披露
+- **Read `checklist.md`** — 执行前后检查
+- **Read `reference.md`** — manifest、mapper、扫描模式
+- **Read `templates/*`** — 各文档模板
+## 交互白名单
+**无** blocking user confirmation；参数/默认值 + `decision` 事件
+## 执行日志
+`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=`codebase-map`；默认写 reports，有未归档变更时另写 change events

package/harness/bundles/java/pi/harness-codebase-map/checklist.md ADDED Viewed

@@ -0,0 +1,126 @@
+# harness-codebase-map 检查清单
+## 执行前检查
+| 检查项 | 必须 | 说明 |
+|---|:---:|---|
+| 当前目录是项目根或已给出项目路径 | 是 | 需要能定位源码、配置和 `.harness/` |
+| 参数已解析 | 是 | 识别 full / fast / focus / paths / status / diff |
+| `--paths` 已做安全校验 | 条件 | 拒绝 `..`、绝对路径、shell 元字符 |
+| 已读取 `.harness/project.yaml` | 否 | 不存在时 profile 记为 unknown |
+| 已读取 `.harness/context-index.json` | 否 | 不存在时可创建最小结构 |
+| 已检查旧 map 状态 | 是 | 判断首次、缺失、过期、部分刷新 |
+| 已确认输出路径为 `.harness/codebase/map/` | 是 | 禁止 `.planning/codebase/` |
+| 已确认不执行 Git 写操作 | 是 | 禁止 add/commit/pull/merge/push/reset/checkout/rebase/clean；只允许 status / diff --name-only / rev-parse |
+## 参数模式检查
+| 模式 | 需要生成/检查 |
+|---|---|
+| `--status` | 只检查 map 完整性、manifest、summary、stale 状态 |
+| `--diff` | 对比 manifest 与当前代码状态，输出可能过期范围 |
+| full / `--refresh` | 生成或刷新 7 个文档 |
+| `--fast` | 默认刷新 `STACK.md`、`STRUCTURE.md`、`CONCERNS.md` |
+| `--focus tech` | `STACK.md`、`INTEGRATIONS.md` |
+| `--focus arch` | `ARCHITECTURE.md`、`STRUCTURE.md` |
+| `--focus quality` | `CONVENTIONS.md`、`TESTING.md` |
+| `--focus concerns` | `CONCERNS.md` |
+| `--paths` | 只扫描合法 repo-relative 路径，仍按 focus 决定输出文档 |
+## 输出文件检查
+全量模式必须存在：
+```text
+.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
+.harness/codebase/map-summary.md
+.harness/codebase/map-manifest.json
+```
+模板目录必须包含：
+```text
+templates/STACK.md
+templates/INTEGRATIONS.md
+templates/ARCHITECTURE.md
+templates/STRUCTURE.md
+templates/CONVENTIONS.md
+templates/TESTING.md
+templates/CONCERNS.md
+templates/map-summary.md
+templates/map-manifest.schema.json
+```
+局部刷新模式中，未刷新文件如果已存在，可以保留；如果不存在，必须在报告中标记 WARN。
+## 文档质量检查
+每个生成文档必须满足：
+- 有 YAML frontmatter。
+- 标明 `generator: harness-codebase-map`。
+- 标明 `file_kind: generated_reviewable`。
+- 包含实际文件路径，路径使用反引号包裹。
+- 不包含明文 token、password、secret、Authorization、Cookie、API key。
+- 不把猜测写成事实；不确定内容用“推测 / 待验证”。
+- 至少包含 “Analysis Date” 或 “Mapped At”。
+## Manifest 检查
+`map-manifest.json` 必须包含：
+- `generator`
+- `generated_at`
+- `mode`
+- `profile`
+- `last_mapped_commit`
+- `path_scope`
+- `documents[]`
+- 每个文档的 `path` / `document_type` / `sha256` / `line_count`
+- `warnings[]`
+## Context Index 检查
+如果 `.harness/context-index.json` 存在：
+- 必须保留未知字段。
+- 只更新 `codebase.map` 相关字段。
+- 不得覆盖 rules、knowledge、skills 其他索引。
+如果不存在：
+- 可创建最小结构。
+- 报告中标记 `context-index: created-minimal`。
+## 失败判定
+以下情况必须标记 `❌FAIL`：
+- 无法写入 `.harness/codebase/map/`。
+- 全量模式下 7 个文档未全部生成，且不是用户明确选择局部模式。
+- manifest 无法生成或 JSON 不可读。
+- 写入后的文件无法 Read 验证。
+以下情况标记 `🟡WARN`：
+- Agent 工具不可用，降级为顺序扫描。
+- 部分路径非法，被剔除。
+- 无法获取 git commit，使用 `unknown`。
+- context-index 不存在并创建了最小结构。
+- 局部刷新导致部分文档仍缺失。
+- 检测到可能敏感信息并已脱敏。
+## 结束前必检
+- [ ] 输出目录是 `.harness/codebase/map/`。
+- [ ] 没有创建 `.planning/`。
+- [ ] 没有修改 `.codegraph/`。
+- [ ] 没有执行 Git 写操作。
+- [ ] 所有写入文件已通过 Read 或文件存在检查验证。
+- [ ] 最终回复中列出生成文件、行数、状态和 warnings。