npm - hunter-harness - Versions diffs - 0.1.3 → 0.2.0 - Mend

hunter-harness 0.1.3 → 0.2.0

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 (566) hide show

package/resources/harness/bundles/general/codex/harness-archive/templates/summary-data-template.json ADDED Viewed

@@ -0,0 +1,128 @@
+{
+  "schemaVersion": "2.2",
+  "changeName": "<change-name>",
+  "businessGoal": "本次变更为了做什么",
+  "finalStatus": "OK | WARN | CONDITIONAL_OK | FAIL",
+  "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"
+      }
+    ]
+  },
+  "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"
+    },
+    "dbCompatibility": "OK | BLOCKED_BY_DBA | NOT_RUN",
+    "coverageDisplay": "例如 29/29 或 USER_SKIPPED"
+  },
+  "timeline": [],
+  "changedFiles": [
+    { "path": "src/...", "summary": "说明", "insertions": 0, "deletions": 0 }
+  ],
+  "artifacts": [],
+  "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": [
+      {
+        "path": "reports/final/final-summary.html",
+        "kind": "final-report",
+        "phase": "archive"
+      }
+    ],
+    "validationIssues": []
+  },
+  "uncommittedTestEvidence": [],
+  "maintenanceNotes": [],
+  "knownRisks": [],
+  "manualActions": []
+}

package/resources/harness/bundles/general/codex/harness-codebase-map/SKILL.md ADDED Viewed

@@ -0,0 +1,95 @@
+---
+name: harness-codebase-map
+description: 分析现有代码库并生成 .harness/codebase/map/
+  下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
+---
+<!-- generated by harness_deploy.py; core=560f9757ad576d78; overlay=none; agent=codex; 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`
+- **禁止** `.planning/`、Git 写操作、修改 `.codegraph/`、自动 commit/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` 报告 |
+逐步细节、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]]
+## 关键规则
+| # | 规则 |
+|---|------|
+| 1 | 唯一输出 `.harness/codebase/map/` |
+| 2 | `generated_reviewable`，不建议手工改 map 正文 |
+| 3 | 不 Git 写操作、不改业务代码 |
+| 4 | 不管理 CodeGraph |
+| 5 | 敏感信息脱敏 → `sensitive-info-protocol` |
+| 6 | 证据化输出 → `evidence-based-reporting-protocol` |
+## Output Format
+模式、范围、7/7 文档路径与行数、manifest/summary、context-index 状态、WARN/FAIL → `reference.md` 报告模板
+## 渐进披露
+- **Read `checklist.md`** — 执行前后检查
+- **Read `reference.md`** — manifest、mapper、扫描模式
+- **Read `templates/*`** — 各文档模板
+## 交互白名单
+**无** 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 边界保持最新。

package/resources/harness/bundles/general/codex/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。