hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/java/codex/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/resources/harness/bundles/java/codex/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/resources/harness/bundles/java/codex/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/resources/harness/bundles/java/codex/harness-knowledge-ingest/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: harness-knowledge-ingest
+description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
+  knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
+---
+<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
+# harness-knowledge-ingest
+
+从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
+
+当前实现是本地、离线、无 LLM、无外部服务的 SQLite FTS MVP，已经支持基础生命周期：`candidate`、`stale`、`active`、`superseded`、`conflicted`。按新需求查询历史由独立的 `harness-knowledge-query` 负责。
+
+## Triggers
+
+- ingest knowledge
+- sync knowledge
+- rebuild knowledge index
+- promote knowledge
+- 确认知识条目
+- 从归档生成知识索引
+- 刷新项目知识库
+- 检查知识库是否过期
+
+## Required context
+
+- AGENTS.md / CLAUDE.md
+- `.harness/archive/**/reports/final/summary-data.json`
+- `.harness/knowledge/index.json`
+- `.harness/codebase/map-summary.md`（如存在）
+- design.md
+
+## Purpose
+
+解决两个问题：
+
+1. **整理知识库内容**：把归档里的 `businessGoal`、`changedFiles`、`maintenanceNotes`、`knownRisks`、`manualActions`、`verification`、`reviewSummary` 抽成知识条目。
+2. **维护知识生命周期**：检查索引是否过期，保留 active 条目；高价值 candidate 可经人工确认提升，也可由 `auto` 首次写入的 `autoPromote` 配置按置信度门槛自动提升。
+
+## Outputs
+
+```text
+.harness/knowledge/index.json
+.harness/knowledge/index.sqlite
+.harness/knowledge/entries/candidate/*.json
+.harness/knowledge/entries/active/*.json
+.harness/knowledge/entries/stale/*.json
+.harness/knowledge/entries/superseded/*.json
+.harness/knowledge/entries/conflicted/*.json
+.harness/knowledge/cache/archive-entries/*.json
+.harness/knowledge/reports/ingest-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/verification-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/validator-suggestions-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/audit-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/views/knowledge-dashboard.md
+.harness/knowledge/views/by-file.md
+.harness/knowledge/views/stale-items.md
+.harness/knowledge/views/superseded-items.md
+.harness/knowledge/views/conflicted-items.md
+.harness/knowledge/views/active-review.md
+.harness/knowledge/views/knowledge.base
+.harness/knowledge/context-packs/*.md
+```
+
+## Commands
+
+`<skill-dir>` 指本 skill 目录。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行。完整命令示例与 config.json 配置见 `reference.md`「Commands 详细」。
+
+| 命令 | 用途 |
+|---|---|
+| `auto` | 一键防腐：首建 config、sync --update、suggest-validators、verify、audit；首次自动写 autoPromote 配置并提升高 confidence 条目 |
+| `ingest` | 重建/刷新知识索引，抽取 candidate；`--no-incremental` 强制全量重抽取 |
+| `sync` | 检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
+| `promote` | candidate→active（人工确认或 autoPromote 触发） |
+| `demote` | active→stale/candidate（人工复核后） |
+| `audit` | 生成 Candidate/Stale/Superseded/Conflict/Active Review 报告 |
+| `verify` | 执行 entry validators，刷新 lifecycle.validation，生成 verification-report |
+| `suggest-validators` | 生成 file_exists/file_contains validator 建议；`--apply` 写回 entry |
+| `mcp` | FastMCP stdio 入口，暴露 9 个工具（见 reference.md） |
+
+config.json 配置项（autoPromote / confidence / activeLifecycle / knowledgeValidation）详见 `reference.md`「Commands 详细」。
+
+## Workflow
+
+### Phase 0：确认项目根目录
+
+项目根目录必须包含 `.harness/`。如果 `.harness/archive/` 不存在或没有 `summary-data.json`，报告当前项目暂无可索引归档，不要伪造知识。
+
+### Phase 1：重建本地知识索引
+
+运行：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<project-root>'"
+```
+
+生成：
+
+- `index.json`：人类可读 manifest。
+- `index.sqlite`：SQLite FTS5 检索索引。
+- `entries/candidate/`：自动抽取、待确认知识。
+- `entries/stale/`：来源 commit 缺失、无法比较，或来源 commit 后相关文件变化的知识。
+- `entries/active/`：人工确认后可长期引用的知识。
+- `views/`：Obsidian 友好的浏览视图。
+- `reports/`：本次 ingest 报告。
+
+### Phase 2：同步检查
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>'"
+```
+
+当 `upToDate=false` 时，应优先运行 `sync --update` 或 `ingest`，再交给 `harness-knowledge-query` 查询。
+
+### Phase 3：人工确认高价值知识
+
+如果某条 candidate 已确认仍然有效，并且会反复影响后续需求，可运行 `promote` 将其提升为 active。
+
+active 条目适合保存：
+
+- 需求约束
+- 架构决策
+- API contract
+- 反复踩坑点
+- 测试或发布前置条件
+
+不要把一次性实现细节、过期临时方案、未验证结论提升为 active。
+
+### Phase 4：解释同步结果
+
+回复用户或交给后续 skill 前，应说明：
+
+- 索引是否最新。
+- 如需刷新，具体原因是 archive 增删、checksum 变化、sqlite 缺失，还是 HEAD 改变。
+- 本次是否自动刷新。
+- 当前 `active` / `candidate` / `stale` 的数量。
+
+## Knowledge extraction rules
+
+- Detect duplicate IDs, duplicate content, and conflicting active facts.
+- Keep project-local entries excluded from any global index unless explicitly selected.
+- Validate lifecycle relationships.
+- Default generated entries are `candidate`; only config-gated `autoPromote` may promote high-confidence long-lived entries to `active`.
+- Preserve provenance: every entry must include source archive, summary path, source commit, and source files when available.
+- Do not edit `.harness/archive/**` during ingest.
+- Do not copy secrets into `.harness/knowledge`.
+
+## Lifecycle rules
+
+- `candidate`：自动抽取但未人工确认。
+- `active`：人工确认、显式 promote，或配置允许的高置信度 autoPromote 后可用。
+- `stale`：来源 commit 缺失、来源 commit 后相关文件变化，或当前代码无法证明旧结论仍有效。
+- `superseded`：被后续归档/决策取代。
+- `conflicted`：与另一条 active/candidate 知识冲突。
+
+## Forbidden actions
+
+- auto_promote_candidate_knowledge_without_config_and_confidence_gate
+- erase_conflicts
+- include_project_local_by_default
+- mutate_archive_evidence
+- store_secrets
+- treat_stale_knowledge_as_current_fact
+
+## Allowed capabilities
+
+- read
+- search
+- write_candidate_knowledge
+- write_active_knowledge_after_manual_confirmation
+- write_confidence_scores
+- auto_promote_high_confidence_knowledge_when_configured
+- write_knowledge_index
+- write_obsidian_views
+
+## Verification
+
+本 skill 自带最小测试：
+
+```powershell
+powershell.exe -Command "python -m unittest '<skill-dir>\tests\test_harness_knowledge.py'"
+```
+
+完成脚本修改后必须至少运行该测试。若在真实项目中验证，还应运行：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' suggest-validators --project '<real-project-root>' --limit 20"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' verify --project '<real-project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<real-project-root>'"
+```
+
+并确认 `index.json`、`index.sqlite`、`views/knowledge-dashboard.md`、`reports/verification-report-*.md` 存在，且 sync 输出 `upToDate=true`。
+
+## 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
+
+执行完成后展示：
+
+- 本次命令（ingest/sync/promote）与目标项目根。
+- `upToDate` 及 `reasons`（sync）或新增/覆盖条目数（ingest/promote）。
+- 当前 `active` / `candidate` / `stale` 数量统计。
+- 产物路径（`index.json`、`index.sqlite`、`views/`、`reports/`）。
+- 下一步建议（`upToDate=false` → `sync --update`；有 candidate → 人工确认后 `promote`，或项目启用 `autoPromote` 后让高置信度长期知识自动提升；查询历史 → `/harness-knowledge-query`）。
+
+## 渐进披露
+
+- **Read `reference.md`** 仅在执行命令或查阅 config.json 配置时 — 含 Commands 详细示例（9 命令的 powershell 示例 + config.json 配置）与变更日志（v1.7–v1.13 补充能力）。
+
+## 交互白名单
+
+**仅当** `.harness/config/harness.json` 中 `knowledge.manualReview=true` 时，promote/demote 高价值条目需 AskUserQuestion；否则按 skill 默认策略 + `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 边界保持最新。