hunter-harness 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "hunter-harness",
+  "version": "0.1.0",
+  "description": "Local-first, server-governed agent harness",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "hunter-harness": "./dist/bin.js"
+  },
+  "files": [
+    "dist/bin.js",
+    "resources"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run bundle && npm run copy-resources",
+    "bundle": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node24 --external:commander --external:yaml --external:zod --outfile=dist/bin.js",
+    "copy-resources": "node scripts/copy-resources.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "node ../../scripts/sync-harness.mjs && npm run build"
+  },
+  "dependencies": {
+    "commander": "15.0.0",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@hunter-harness/contracts": "*",
+    "@hunter-harness/core": "*",
+    "esbuild": "^0.25.12"
+  }
+}

package/resources/bootstrap-ir/manifest.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": 1,
+  "registry_version": "bootstrap-2026.06.20",
+  "compiler_version": "1.0.0",
+  "skills": [
+    "harness-sync",
+    "harness-plan",
+    "harness-run",
+    "harness-test",
+    "harness-review",
+    "harness-submit",
+    "harness-archive",
+    "harness-knowledge-ingest",
+    "harness-skill-optimizer",
+    "harness-codebase-map",
+    "harness-apidoc",
+    "harness-package"
+  ]
+}

package/resources/bootstrap-ir/skills/harness-apidoc.yaml

@@ -0,0 +1,24 @@
+name: harness-apidoc
+kind: workflow
+description: Analyze API changes and produce evidence-based documentation impact updates.
+triggers: [update API documentation, inspect API compatibility]
+inputs: [change_ref, api_contract]
+outputs: [api_impact_report, documentation_updates]
+forbidden_actions: [invent_api_behavior, hide_breaking_changes, publish_without_review]
+required_context: [AGENTS.md, .harness/context-index.json, .harness/knowledge/api]
+profiles:
+  general: { enabled: false }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Compare implementation and declared API contracts.
+  - Classify compatibility and documentation impact.
+  - Update only evidence-supported documentation.
+allowed_capabilities: [read, search, write_api_documentation, run_tests]
+source_provenance: user-provided validated Java API documentation workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-archive.yaml

@@ -0,0 +1,24 @@
+name: harness-archive
+kind: workflow
+description: Archive completed change evidence and extract unpromoted candidate Knowledge.
+triggers: [archive completed change, extract reusable knowledge]
+inputs: [change_documents, verification_evidence]
+outputs: [archive_summary, candidate_knowledge]
+forbidden_actions: [auto_promote_candidate_knowledge, discard_evidence, expose_sensitive_data]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Preserve the final summary and execution evidence.
+  - Extract reusable facts into the candidate area with source references.
+  - Never promote candidates to active Knowledge automatically.
+allowed_capabilities: [read, write_harness_archive, write_candidate_knowledge]
+source_provenance: user-provided validated archive workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-codebase-map.yaml

@@ -0,0 +1,24 @@
+name: harness-codebase-map
+kind: workflow
+description: Generate seven evidence-based codebase-map documents under the Harness workspace.
+triggers: [map the codebase, refresh codebase map]
+inputs: [project_root, optional_paths]
+outputs: [stack_map, integration_map, architecture_map, structure_map, convention_map, testing_map, concern_map]
+forbidden_actions: [copy_source_code_wholesale, manage_codegraph, automatic_execution_from_sync]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Analyze the requested scope using isolated mapper focuses.
+  - Write STACK, INTEGRATIONS, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, and CONCERNS.
+  - Record evidence, scan scope, time, and source revision without embedding source files.
+allowed_capabilities: [read, search, write_codebase_map]
+source_provenance: user-provided validated GSD map workflow and templates adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-knowledge-ingest.yaml

@@ -0,0 +1,24 @@
+name: harness-knowledge-ingest
+kind: governance
+description: Validate, deduplicate, index, and propose project Knowledge without bypassing review.
+triggers: [ingest knowledge, rebuild knowledge index]
+inputs: [knowledge_entries, candidate_entries]
+outputs: [knowledge_index, validation_report]
+forbidden_actions: [auto_promote_candidate_knowledge, include_project_local_by_default, erase_conflicts]
+required_context: [AGENTS.md, .harness/knowledge/index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Validate frontmatter and lifecycle relationships.
+  - Detect duplicate IDs, duplicate content, and conflicting active facts.
+  - Keep project-local entries excluded unless explicitly selected.
+allowed_capabilities: [read, search, write_knowledge_index, write_candidate_knowledge]
+source_provenance: Hunter Harness Knowledge governance contract

package/resources/bootstrap-ir/skills/harness-package.yaml

@@ -0,0 +1,24 @@
+name: harness-package
+kind: workflow
+description: Validate and prepare a reproducible project package without publishing it.
+triggers: [prepare package, validate package output]
+inputs: [project_root, build_configuration]
+outputs: [package_report, package_artifacts]
+forbidden_actions: [publish_artifact, expose_secrets, claim_unverified_build]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: false }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Validate the configured build and its required tests.
+  - Record exact artifact hashes and build evidence.
+  - Do not publish or upload package artifacts.
+allowed_capabilities: [read, run_builds, run_tests, write_package_reports]
+source_provenance: user-provided validated Java packaging workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-plan.yaml

@@ -0,0 +1,24 @@
+name: harness-plan
+kind: workflow
+description: Produce evidence-based designs, implementation plans, impact analysis, and test scenarios.
+triggers: [plan a change, design an implementation]
+inputs: [requirements, context_index]
+outputs: [design, implementation_plan, test_scenarios]
+forbidden_actions: [invent_evidence, expose_sensitive_data, automatic_source_control_write]
+required_context: [AGENTS.md, .harness/context-index.json, .harness/knowledge/index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Inspect relevant Knowledge and codebase-map evidence before proposing changes.
+  - Separate assumptions from verified facts.
+  - Define exact files, tests, risks, and rollback points.
+allowed_capabilities: [read, search, write_change_documents]
+source_provenance: user-provided validated planning workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-review.yaml

@@ -0,0 +1,24 @@
+name: harness-review
+kind: governance
+description: Review changes across correctness, security, compatibility, tests, maintainability, and evidence.
+triggers: [review a change, inspect implementation quality]
+inputs: [change_ref, context_index]
+outputs: [review_report, evidence_summary]
+forbidden_actions: [invent_findings, claim_unverified_success, mutate_reviewed_code_without_request]
+required_context: [AGENTS.md, .harness/context-index.json, .harness/knowledge/index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Inspect the actual diff and relevant project evidence.
+  - Rank actionable findings by impact and cite precise locations.
+  - Distinguish verified defects from risks and questions.
+allowed_capabilities: [read, search, run_tests, write_review_reports]
+source_provenance: user-provided validated six-dimension review workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-run.yaml

@@ -0,0 +1,24 @@
+name: harness-run
+kind: workflow
+description: Execute an approved implementation plan with test-first evidence and an execution log.
+triggers: [implement the plan, run approved tasks]
+inputs: [implementation_plan, test_scenarios]
+outputs: [implementation_changes, execution_log]
+forbidden_actions: [skip_red_green_verification, claim_unverified_success, automatic_source_control_write]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Execute one bounded task at a time.
+  - Record real command output and distinguish it from static inspection.
+  - Stop on unsafe or unexplained failures.
+allowed_capabilities: [read, search, write_project_files, run_tests]
+source_provenance: user-provided validated execution workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-skill-optimizer.yaml

@@ -0,0 +1,28 @@
+name: harness-skill-optimizer
+kind: migration
+description: Create, optimize, and migrate platform-neutral Skill IR with adapter-safe outputs.
+triggers: [create a skill, optimize a skill, migrate an agent skill]
+inputs: [skill_source, target_profiles, target_adapters]
+outputs: [skill_ir, validation_report, adapter_preview]
+forbidden_actions: [publish_canonical_skill, automatic_proposal_push, broaden_capabilities, automatic_source_control_write]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+  node: { enabled: true }
+  python: { enabled: true }
+  docs: { enabled: true }
+  personal-automation: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Convert source workflows and constraints into canonical Skill IR.
+  - Validate triggers, inputs, outputs, forbidden actions, and required context.
+  - Generate previews but never publish or push automatically.
+allowed_capabilities: [read, search, write_skill_ir, validate_adapter_outputs]
+source_provenance: user-provided validated skill optimizer adapted for cross-agent governance

package/resources/bootstrap-ir/skills/harness-submit.yaml

@@ -0,0 +1,24 @@
+name: harness-submit
+kind: workflow
+description: Prepare a submission summary, suggested message, and verification checklist without changing source control.
+triggers: [prepare submission, summarize completed change]
+inputs: [change_ref, verification_evidence]
+outputs: [submission_summary, suggested_message, submission_checklist]
+forbidden_actions: [source_control_write_without_explicit_confirmation, publish_without_review]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Summarize verified changes and remaining risks.
+  - Produce a suggested message and final checklist only.
+  - Require explicit user confirmation before any source-control mutation.
+allowed_capabilities: [read, search, write_submission_documents]
+source_provenance: user-provided validated submission workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-sync.yaml

@@ -0,0 +1,24 @@
+name: harness-sync
+kind: workflow
+description: Check Harness context, Knowledge indexes, managed blocks, rules, and codebase-map freshness.
+triggers: [sync harness context, check project context]
+inputs: [project_root, context_index]
+outputs: [sync_report, refresh_recommendations]
+forbidden_actions: [automatic_codebase_map_execution, manage_codegraph, install_external_tools]
+required_context: [AGENTS.md, .harness/context-index.json]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Validate managed blocks and local Harness structure.
+  - Rebuild deterministic indexes when their sources changed.
+  - Recommend codebase-map refresh when stale, but wait for explicit user confirmation.
+allowed_capabilities: [read, search, write_harness_metadata]
+source_provenance: user-provided validated Java workflow adapted to Hunter Harness

package/resources/bootstrap-ir/skills/harness-test.yaml

@@ -0,0 +1,24 @@
+name: harness-test
+kind: workflow
+description: Validate changes with real tests, explicit degradation reporting, and reproducible evidence.
+triggers: [test the change, validate behavior]
+inputs: [test_scenarios, change_ref]
+outputs: [test_report, evidence_summary]
+forbidden_actions: [claim_unrun_tests_pass, hide_test_failures, confuse_static_checks_with_tests]
+required_context: [AGENTS.md, .harness/context-index.json, .harness/knowledge/pitfalls]
+profiles:
+  general: { enabled: true }
+  java: { enabled: true }
+adapters:
+  claude-code: { enabled: true }
+  codex: { enabled: true }
+  cursor: { enabled: true }
+  generic: { enabled: true }
+  mcp: { enabled: true }
+version: 1.0.0
+instructions:
+  - Derive test cases from requirements and changed behavior.
+  - Run the narrow test first, then the complete relevant suite.
+  - Report skipped infrastructure and degraded validation explicitly.
+allowed_capabilities: [read, search, run_tests, write_test_reports]
+source_provenance: user-provided validated test workflow and pitfalls adapted to Hunter Harness

package/resources/bootstrap-ir/templates/claude-code-skill.md

@@ -0,0 +1,12 @@
+---
+name: {{name}}
+description: {{description}}
+version: {{version}}
+adapter: claude-code
+source_ir_hash: {{source_ir_hash}}
+compiler_version: {{compiler_version}}
+---
+
+# {{name}}
+
+{{body}}

package/resources/harness/general/.harness-build.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 1,
+  "overlay": "none",
+  "coreHash": "63af4c482d21b6be"
+}

package/resources/harness/general/CONTEXT.md

@@ -0,0 +1,65 @@
+# Harness Skills
+
+Harness Skills 是一组围绕本地变更治理的 agent 工作流。它把外部方法论吸收为原生协议，同时保持 `.harness/changes/<change-name>/` 作为变更过程的唯一真相源。
+
+## Language
+
+**原生协议**:
+Harness skill 内部直接执行的流程约束，作为正式行为契约。原生协议可以吸收外部方法论，但不依赖外部 skill 是否安装。
+_Avoid_: Adapter Mode, 外部 skill 调用
+
+**外部方法论来源**:
+为 harness 规则提供启发的外部 skill 或流程，例如 brainstorming、grill-me、writing-plans、test-driven-development、receiving-code-review。它们是设计来源，不是 harness 的运行时依赖。
+_Avoid_: 外部依赖, 必需插件
+
+**人工参考**:
+不进入正式流程状态机、只供人或后续规则维护者对标的方法、草稿或外部技能。人工参考缺失不产生降级项；若被采用，应先转写为 harness 原生协议或正式产物。
+_Avoid_: 运行时增强, 降级分支, 硬依赖
+
+**变更簇**:
+围绕同一业务行为或同一验证目标的一组任务。变更簇是 `/harness-run` 执行 RED→GREEN→REFACTOR 的基本单位。
+_Avoid_: 小任务, 单步任务
+
+**自适应执行参考**:
+`implementation-detail.md` 的定位。它按变更复杂度提供足够执行上下文，简单变更保持简洁，高风险变更写清顺序、接口、数据、风险和测试策略。
+_Avoid_: 超细步骤文档, 可选详细计划
+
+**Fixback**:
+由 review 阶段把 RED/YELLOW 问题转成的结构化修复反馈。Fixback 指向问题位置、推荐修复和验证方式，但默认不自动阻塞 submit。
+_Avoid_: 修复任务清单, blocking review
+
+**事件唯一源**:
+`events.ndjson` 是变更执行过程的唯一实时记录位置，由 `harness_events.py append` 写入。`execution-log.md` 是它的自动渲染产物，禁止手工编辑。
+_Avoid_: 日志双写, 手写执行日志
+
+**归档终结（finalize）**:
+`harness_archive.py finalize` 在单进程内完成 manifest、移动、collect、渲染、校验、比对、删除原目录的完整归档动作。取代旧的 collect/enrich/validate 三步编排；enrich 不再是有效概念。
+_Avoid_: enrich, 多步归档编排
+
+**知识裁决（judge）**:
+归档收尾时对知识条目的处置流程：脚本规则先消化机械部分（去重、时间序 supersede、stale 重验），模型批量裁决剩余的真语义冲突与 promote，写入可回滚的 decision log。人工退出常规循环。
+_Avoid_: 人工 promote 积压, candidate 待办
+
+**构建档案（build-profile）**:
+`.harness/config/build-profile.json`，项目级持久化的机读构建事实：可用命令模板、工具绝对路径、已知预存错误、服务启动模板。preflight 只做秒级校验，新坑由脚本回写。项目专属硬编码归此文件，不进 skill 文本。
+_Avoid_: 每次重新探测, skill 内硬编码项目参数
+
+**验证指纹（inputsHash）**:
+一项验证（compile/install/unitTest/apiTest）所依赖源文件集合的内容哈希。指纹一致且证据完整才允许 🔁REUSED；无法证明即保守重跑。
+_Avoid_: 仅凭 diffHash 复用, 无证据跳过
+
+**服务会话**:
+`runtime/service-session.json` 记录的 AI 启动服务生命周期。指纹匹配静默复用、不匹配自动重启、归档收尾统一停止；只有用户自启服务占端口才询问。
+_Avoid_: 每轮测试后必杀服务
+
+**交互白名单**:
+每个 skill 显式声明的允许 AskUserQuestion 场景清单。白名单外一律取默认值并记 decision 事件。
+_Avoid_: 逐决策点询问
+
+**部署合成**:
+`harness_deploy.py build` 把通用核心 + shared 片段 + overlay 合成为自包含 SKILL.md 后部署。Vault 源头 DRY，运行时单文件。
+_Avoid_: 运行时跨文件拼规则, fork 维护
+
+**Java overlay**:
+`overlays/java/` 中只含"任何 Java 项目通用"的差异段落与独有 skill（apidoc/package）。项目专属值写目标项目的 build-profile。
+_Avoid_: Java fork, UDP 硬编码进 overlay