hunter-harness 0.1.3 → 0.2.1

package/resources/harness/java/harness-codebase-map/reference.md

@@ -1,364 +0,0 @@
-# harness-codebase-map Reference
-
-## 1. 设计来源与迁移边界
-
-`harness-codebase-map` 参考 GSD `map-codebase` 的核心思想：
-
-- 使用多个 mapper focus 分别分析技术栈、架构、质量和风险。
-- 输出结构化代码库文档。
-- 主流程只收集确认和摘要，降低上下文占用。
-
-但它不是 GSD 原始 skill 的机械复制。
-
-必须移除的旧行为：
-
-| 旧行为 | 新行为 |
-|---|---|
-| 输出到 `.planning/codebase/` | 输出到 `.harness/codebase/map/` |
-| 自动 commit codebase map | 禁止自动 Git 写操作 |
-| `gsd-map-codebase` / `gsd-codebase-mapper` 命名 | `harness-codebase-map` / harness mapper focus |
-| GSD query intel | 不纳入本 skill MVP |
-| 依赖 GSD runtime | 不依赖，作为 hunter-harness 自有能力 |
-
-## 2. 输出文档职责
-
-| 文档 | document_type | Focus | 作用 |
-|---|---|---|---|
-| `STACK.md` | `stack` | tech | 技术栈、运行时、构建工具、关键依赖 |
-| `INTEGRATIONS.md` | `integrations` | tech | 外部系统、数据库、缓存、消息、第三方 API |
-| `ARCHITECTURE.md` | `architecture` | arch | 架构模式、分层、模块边界、数据流 |
-| `STRUCTURE.md` | `structure` | arch | 目录结构、关键文件位置、新代码应放哪里 |
-| `CONVENTIONS.md` | `conventions` | quality | 命名、编码风格、错误处理、日志、配置约定 |
-| `TESTING.md` | `testing` | quality | 测试框架、测试目录、运行方式、mock 和覆盖策略 |
-| `CONCERNS.md` | `concerns` | concerns | 风险、技术债、易错点、安全与迁移关注点 |
-| `map-summary.md` | `map-summary` | summary | AI 快速阅读入口，汇总代码库地图核心结论 |
-| `map-manifest.json` | `map-manifest` | metadata | 工具和 sync 使用的文档清单、hash、stale policy |
-
-## 2.1 模板文件规则
-
-`templates/` 中的模板是可直接落地的目标文件骨架，不是说明型代码块。
-
-- 生成 `STACK.md` 等 7 个主文档时，直接使用同名模板结构。
-- 生成 `.harness/codebase/map-summary.md` 时，使用 `templates/map-summary.md`。
-- 生成 `.harness/codebase/map-manifest.json` 时，参考 `templates/map-manifest.schema.json`。
-- 不得把 `# xxx Template`、外层 ```markdown 代码块或模板说明文字复制到最终产物中。
-
-## 3. 模式与刷新范围
-
-### full / --refresh
-
-刷新全部 7 个文档，适合首次生成或大型变更后使用。
-
-### --fast
-
-刷新：
-
-```text
-STACK.md
-STRUCTURE.md
-CONCERNS.md
-```
-
-适合依赖、目录、风险轻量更新。
-
-### --focus tech
-
-刷新：
-
-```text
-STACK.md
-INTEGRATIONS.md
-```
-
-### --focus arch
-
-刷新：
-
-```text
-ARCHITECTURE.md
-STRUCTURE.md
-```
-
-### --focus quality
-
-刷新：
-
-```text
-CONVENTIONS.md
-TESTING.md
-```
-
-### --focus concerns
-
-刷新：
-
-```text
-CONCERNS.md
-```
-
-### --paths
-
-增量扫描指定路径。
-
-安全规则：
-
-- 只允许 repo-relative path。
-- 禁止 `..`。
-- 禁止 `/` 开头或 Windows drive absolute path。
-- 禁止 shell 元字符：`;`、`` ` ``、`$`、`&`、`|`、`<`、`>`。
-- 路径值只作为扫描范围，不直接拼接到 shell 命令。
-
-Git 只允许只读查询：`status`、`diff --name-only`、`rev-parse`。禁止 `add`、`commit`、`pull`、`merge`、`push`、`reset`、`checkout`、`rebase`、`clean` 等写入或改变工作区状态的操作。
-
-## 4. Mapper Agent Prompt Contract
-
-并行 agent 可使用以下任务格式。
-
-### Tech Mapper
-
-```text
-你是 harness-codebase-map 的 tech mapper。
-
-目标：分析当前项目的技术栈和外部集成。
-
-范围：<full repo or path scope>
-
-必须直接写入：
-- .harness/codebase/map/STACK.md
-- .harness/codebase/map/INTEGRATIONS.md
-
-要求：
-- 使用 templates/STACK.md 和 templates/INTEGRATIONS.md 的结构。
-- 包含实际文件路径。
-- 不输出明文敏感信息。
-- 不执行 Git 写操作。
-- 完成后只返回文件路径、行数、warnings。
-```
-
-### Arch Mapper
-
-```text
-你是 harness-codebase-map 的 arch mapper。
-
-目标：分析当前项目的架构模式、模块边界和物理目录结构。
-
-必须直接写入：
-- .harness/codebase/map/ARCHITECTURE.md
-- .harness/codebase/map/STRUCTURE.md
-```
-
-### Quality Mapper
-
-```text
-你是 harness-codebase-map 的 quality mapper。
-
-目标：分析编码约定、测试框架、测试组织方式和验证命令。
-
-必须直接写入：
-- .harness/codebase/map/CONVENTIONS.md
-- .harness/codebase/map/TESTING.md
-```
-
-### Concerns Mapper
-
-```text
-你是 harness-codebase-map 的 concerns mapper。
-
-目标：分析风险、技术债、易错点、安全注意事项和后续开发关注点。
-
-必须直接写入：
-- .harness/codebase/map/CONCERNS.md
-```
-
-## 5. Manifest Schema
-
-`map-manifest.json` 建议结构：
-
-```json
-{
-  "schema_version": 1,
-  "generator": "harness-codebase-map",
-  "generated_at": "YYYY-MM-DD HH:mm:ss",
-  "mode": "full",
-  "profile": "general",
-  "project_root": ".",
-  "last_mapped_commit": "unknown",
-  "path_scope": {
-    "type": "full",
-    "paths": []
-  },
-  "documents": [
-    {
-      "document_type": "stack",
-      "path": ".harness/codebase/map/STACK.md",
-      "sha256": "sha256:<hash>",
-      "line_count": 120,
-      "focus": "tech",
-      "status": "generated"
-    }
-  ],
-  "summary": {
-    "path": ".harness/codebase/map-summary.md",
-    "sha256": "sha256:<hash>",
-    "line_count": 60
-  },
-  "warnings": [],
-  "stale_policy": {
-    "max_age_days": 7,
-    "changed_files_threshold": 10
-  }
-}
-```
-
-## 6. Summary Template
-
-`map-summary.md` 应简洁，面向 AI 快速加载：
-
-```markdown
-# Codebase Map Summary
-
-**Generated At:** YYYY-MM-DD HH:mm
-**Mode:** full
-**Profile:** <profile>
-**Commit:** unknown
-
-## Project Snapshot
-
-<项目一句话说明>
-
-## Key Stack
-
-- Language: ...
-- Framework: ...
-- Build: ...
-- Database: ...
-
-## Main Modules
-
-- `<path>` — <purpose>
-
-## Entry Points
-
-- `<path>` — <purpose>
-
-## Testing
-
-- Command: ...
-- Test location: ...
-
-## Concerns
-
-- ...
-
-## 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`
-```
-
-## 7. Freshness / Stale 判断
-
-建议供 `harness-sync` 使用的判断规则：
-
-| 条件 | 判定 | 状态 | 建议 |
-|---|---|---|---|
-| map 不存在 | missing | ❌FAIL(未生成) | 建议运行 full |
-| 7 个文档缺失 | incomplete | 🟡WARN(不完整) | 建议运行 full |
-| manifest 不存在 | unknown | 🟡WARN(元数据未知) | 建议运行 full 或 status 修复 |
-| 超过 7 天且变更文件 > 10 | stale | 🟡WARN(过期) | 建议运行 full 或 focus |
-| 超过 7 天且变更文件 ≤ 10 | aging | 🟡WARN(老化) | 可暂缓，提示用户 |
-| 关键配置变化 | stale | 🟡WARN(过期) | 建议 focus tech |
-| 目录结构变化明显 | stale | 🟡WARN(过期) | 建议 focus arch |
-| 测试目录/依赖变化 | stale | 🟡WARN(过期) | 建议 focus quality |
-
-关键配置包括：
-
-```text
-pom.xml
-build.gradle
-package.json
-pnpm-lock.yaml
-yarn.lock
-requirements.txt
-pyproject.toml
-Dockerfile
-docker-compose.yml
-application*.yml
-application*.properties
-```
-
-## 8. 敏感信息处理
-
-禁止写入：
-
-- token
-- password
-- secret
-- Authorization header
-- Cookie
-- API key
-- 私钥
-- 真实生产账号密码
-
-允许写入脱敏描述：
-
-```text
-配置文件 `<path>` 中存在数据库连接配置，敏感字段已脱敏。
-```
-
-## 9. CodeGraph 边界
-
-代码探索优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore` 等）；MCP 不可用时降级为 Glob/Grep 手动定位，并标注降级。`npx hunter-harness` 初始化阶段可检查 CodeGraph 是否安装，但不作为运行时探索手段。
-
-本 skill：
-
-- 不检查 CodeGraph 安装状态。
-- 不触发 CodeGraph sync。
-- 不修改 `.codegraph/`。
-- 不上传 `.codegraph/`。
-
-mapper 优先通过 CodeGraph MCP 探索代码；不得把本 skill 的成功建立在 CodeGraph 必须可用上——MCP 不可用时降级为 Glob/Grep 并标注降级。
-
-## 10. 报告模板
-
-```markdown
-# harness-codebase-map Report
-
-**Time:** YYYY-MM-DD HH:mm
-**Mode:** full
-**Scope:** full repo
-**Status:** ✅OK
-
-## Outputs
-
-| Document | Path | Lines | Status |
-|---|---|---:|---|
-| STACK | `.harness/codebase/map/STACK.md` | 120 | generated |
-
-## Manifest
-
-- `.harness/codebase/map-manifest.json`
-
-## Summary
-
-- `.harness/codebase/map-summary.md`
-
-## Context Index
-
-updated / skipped / failed
-
-## Warnings
-
-- none
-
-## Evidence
-
-- All output files readable.
-- Manifest JSON readable.
-- Document hashes calculated.
-```

package/resources/harness/java/harness-codebase-map/templates/ARCHITECTURE.md

@@ -1,57 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Architecture
-document_type: architecture
-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
----
-
-# Codebase Architecture
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## Architecture Style
-
-- <layered / modular / microservice / monolith / plugin / etc.>
-
-## Main Modules
-
-| Module | Path | Responsibility |
-|---|---|---|
-| <module> | `<path>` | <responsibility> |
-
-## Layering and Dependencies
-
-```text
-<layer or module dependency diagram>
-```
-
-## Request / Data Flow
-
-1. <entry>
-2. <service>
-3. <persistence/integration>
-
-## Key Entry Points
-
-- `<path>` — <purpose>
-
-## Extension Points
-
-- `<path>` — <how to add new feature>
-
-## Architectural Constraints
-
-- <constraint>
-
-## Notes for AI Agents
-
-- <how future skills should navigate architecture>

package/resources/harness/java/harness-codebase-map/templates/CONCERNS.md

@@ -1,49 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Concerns
-document_type: concerns
-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
----
-
-# Codebase Concerns
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## High Priority Concerns
-
-| Concern | Evidence | Impact | Suggested Handling |
-|---|---|---|---|
-| <concern> | `<path>` | <impact> | <guidance> |
-
-## Technical Debt
-
-- `<path>` — <issue>
-
-## Risky Areas
-
-- `<path>` — <why risky>
-
-## Security / Sensitive Data Risks
-
-- <redacted, evidence path only>
-
-## Testing Gaps
-
-- `<path>` — <gap>
-
-## Migration / Refactor Risks
-
-- <risk>
-
-## Notes for AI Agents
-
-- <warnings for plan/run/review>

package/resources/harness/java/harness-codebase-map/templates/CONVENTIONS.md

@@ -1,57 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Conventions
-document_type: conventions
-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
----
-
-# Codebase Conventions
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## Naming Conventions
-
-- Files: <pattern>
-- Classes / functions / modules: <pattern>
-- Tests: <pattern>
-
-## Code Organization
-
-- <layering / module / package rules>
-
-## Error Handling
-
-- <observed pattern with path evidence>
-
-## Logging
-
-- <logging pattern and path evidence>
-
-## Configuration
-
-- <configuration pattern and path evidence>
-
-## Database / Persistence Conventions
-
-- <if applicable>
-
-## API Conventions
-
-- <if applicable>
-
-## AI Agent Rules Derived from Conventions
-
-- <practical rule>
-
-## Evidence
-
-- `<path>` — <why it supports the convention>

package/resources/harness/java/harness-codebase-map/templates/INTEGRATIONS.md

@@ -1,52 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Integrations
-document_type: integrations
-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
----
-
-# Codebase Integrations
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## External Systems
-
-| System | Evidence | Usage | Notes |
-|---|---|---|---|
-| <system> | `<path>` | <purpose> | <risk/notes> |
-
-## Databases
-
-- Type: <database>
-- Config evidence: `<path>`
-- Access layer: `<path>`
-
-## Cache / Messaging / Search
-
-- <component>: <usage and path evidence>
-
-## HTTP / RPC Clients
-
-- `<path>` — <external service or API>
-
-## Auth / Security Integrations
-
-- <auth mechanism, redacted if sensitive>
-
-## Sensitive Information Handling
-
-- Do not copy credentials.
-- Mention only redacted config patterns.
-
-## Notes for AI Agents
-
-- <integration-specific cautions>

package/resources/harness/java/harness-codebase-map/templates/STACK.md

@@ -1,55 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Stack
-document_type: stack
-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
----
-
-# Codebase Stack
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## Runtime and Language
-
-- Language: <language and version>
-- Runtime: <runtime and version>
-- Package manager / build tool: <tool>
-
-## Frameworks
-
-- <framework>: <purpose>
-
-## Build and Run
-
-```bash
-<build command>
-<run command>
-<test command>
-```
-
-## Key Dependencies
-
-| Dependency | Evidence | Purpose |
-|---|---|---|
-| `<name>` | `<path>` | <why it matters> |
-
-## Configuration Files
-
-- `<path>` — <purpose>
-
-## Deployment / Runtime Environment
-
-- <container, server, cloud, local runtime notes>
-
-## Notes for AI Agents
-
-- <practical guidance for future plan/run/review>

package/resources/harness/java/harness-codebase-map/templates/STRUCTURE.md

@@ -1,69 +0,0 @@
----
-harness:
-  origin: generated
-  generator: harness-codebase-map
-  file_kind: generated_reviewable
-  push_policy: full-diff-proposal
-  update_policy: skip-if-local-dirty
-title: Codebase Structure
-document_type: structure
-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
----
-
-# Codebase Structure
-
-**Analysis Date:** <YYYY-MM-DD>
-
-## Directory Layout
-
-```text
-<project-root>/
-├── <dir>/          # <purpose>
-└── <file>          # <purpose>
-```
-
-## Directory Purposes
-
-### `<dir>/`
-
-- Purpose: <what lives here>
-- Contains: <file types>
-- Key files: `<path>`
-
-## Key File Locations
-
-### Entry Points
-
-- `<path>` — <purpose>
-
-### Configuration
-
-- `<path>` — <purpose>
-
-### Core Logic
-
-- `<path>` — <purpose>
-
-### Testing
-
-- `<path>` — <purpose>
-
-## Where to Add New Code
-
-| Need | Location |
-|---|---|
-| New feature | `<path>` |
-| New test | `<path>` |
-| New config | `<path>` |
-
-## Generated / Ignored Directories
-
-- `<path>` — <generated/cache/internal/external>
-
-## Notes for AI Agents
-
-- <navigation guidance>